VoltPay integration guide

Merchant model: one merchant account can own many websites. API keys and the webhook secret stay shared at the merchant level.

API key rotation: rotate one selected key in API Keys. The previous key remains valid for up to 24 hours (or its earlier expiry). Update every integration using it, verify authentication, then revoke the previous key. Existing permissions and website bindings are preserved.

What separates your websites: the websiteId you send with each request, not the credential. The key authenticates the account; the websiteId decides which website owns the payment, and each website keeps its own webhook URL, checkout configuration, and reporting on that basis. Send the correct value from every website you integrate.

Where to manage websites: add or rename websites in Dashboard → Websites.

Where to get websiteId: every website card and edit panel on the Websites page shows a copyable websiteId. Use that exact UUID in payment creation requests.

Where to configure webhook URLs: set each website's webhook URL in Developers → Webhooks.

What websiteId does: it assigns the payment to a website, controls which webhook URL receives status updates, and powers dashboard filters for payments, customers, subscriptions, and stats.

Without websiteId: the payment is attached to your oldest active website, and its webhooks go to that website's webhook URL. Older integrations may still identify the website through the reserved customData keys listed below, but this is a compatibility path only. Always send websiteId, even if you have only one website today.

Checkout redirect: send the customer to redirectUrl to continue payment. The link stays valid for 24 hours.

No return URL: there is no success or return URL. After paying, the customer stays on the payment page. Open redirectUrl in a new tab, or keep your own "check payment" page, and grant access only from the webhook or the status endpoint. A redirect alone never proves payment.

Checkout expiry: expiresAt is 60 minutes after creation by default, and 6 hours once the customer chooses a card payment. An expired payment can still become PAID later, so always credit a late PAID.

Duplicate protection: if the same website already has a payment for the same customer email and amount that is in progress (PENDING or PROCESSING) and was created within the last 10 minutes, the API returns that payment instead of creating a new one. The response then has "reusedExistingPayment": true and the existing paymentId, so always store the paymentId from the response against your order.

Website routing: when you send websiteId, the payment is attached to that website and later status webhooks are delivered to that website's configured webhook URL. Without it, the payment goes to your oldest active website.

Direct provider intent: providerCode values are provided by your account manager; the code in the example is a placeholder. The code is checked against global, merchant, and website switches when the link is created. Final country, amount, currency, risk, capacity, and session eligibility is checked after buyer capture. A merchant required checkout flow has higher priority, so always inspect directProvider.eligible and keep the standard checkout fallback.

Recurring billing: automatic renewals are currently not available. The "paymentType": "RECURRING" and intervalDays fields (whole days, required together with RECURRING) are still accepted, but do not build on renewals. Treat every payment as one-time, and read paymentType from the webhook as the final value.

Refunds keep status PAID. A refund or chargeback never changes status — integrations treat PAID as final, so it stays PAID. Detect money that went back to the buyer with refundStatus: null (not refunded), PARTIALLY_REFUNDED (part of amount), REFUNDED (all of it) or CHARGEBACK (the buyer's bank reversed it; takes precedence over a refund). refundedAmount is the amount reversed so far, in currency, and 0 when refundStatus is null.

There is no refund webhook yet. If you need to revoke access or stop a renewal after a refund, check this endpoint — for example before each renewal or when a buyer contacts support. Both fields are additive; clients that ignore unknown fields keep working.

Rate limits (per API key): POST /api/payments/create 300 requests per minute; GET /api/payments/:paymentId/status 300 requests per minute. Every response on these endpoints reports that limit in X-RateLimit-Limit-api-key, X-RateLimit-Remaining-api-key and X-RateLimit-Reset-api-key.

A 429 response carries Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Wait at least Retry-After seconds before retrying.

Only PAID is final: a PAID event can arrive after FAILED or CANCELLED, hours and sometimes days later. Always credit it, and never drop an event because the order was already marked failed or expired. FAILED and CANCELLED mean "not paid yet", not a final outcome, and FAILED can be sent more than once for the same payment when the customer retries.

Successful delivery: only HTTP 200, 201, 202 or 204. Redirects are not followed and count as failures. A 2xx response whose JSON body contains "success": false, "ok": false, "acknowledged": false or a status of error, failed, failure or rejected also counts as a failure. Respond within 20 seconds; slower responses time out.

Retries: failed deliveries are retried automatically with increasing delays for up to 72 hours (about 20 attempts). A Retry-After header on your response is honoured. Your handler must be idempotent.

Deduplication: X-Webhook-Id stays the same across automatic retries, but a manual resend from the dashboard gets a new X-Webhook-Id. Deduplicate business actions on paymentId + newStatus (for subscription.canceled, on subscriptionId), not only on X-Webhook-Id.

Pausing an endpoint: events that occur while a website's webhook is paused are queued, not dropped, and pending retries wait with them. When you resume, queued events are delivered in occurredAt order to the endpoint's current URL, each keeping its X-Webhook-Id. Events queued for more than 7 days are not delivered automatically; resend them from the dashboard if you still need them. A manual resend goes to the website's current webhook URL.

Ordering: compare paymentId, newStatus, and occurredAt instead of assuming events arrive in order.

Recurring: renewals are currently not available. If paymentType is present, read the webhook value as the final outcome.

Shared secret: all website webhook deliveries are signed with the same merchant webhook secret. URLs are website-specific; signature verification remains merchant-scoped.