API Reference
The complete Von Payments Checkout API is documented in OpenAPI 3.1 format.
OpenAPI Spec
openapi.yaml — import into Postman, Insomnia, Redocly, or any OpenAPI tool.
Two front-end integration paths
Hosted Checkout (POST /v1/sessions → redirect the buyer to checkoutUrl) and Embedded Fields (the browser SDK on your own page, in embed or elements mode) both vault a vp_pmt_* and settle through Payment Intents, the server-side engine for authorization, capture, refund and void. On an Embedded Fields charge-and-save session submit() has already charged — do not also call POST /v1/payment_intents for it. Side-by-side comparison: Choose your integration.
Endpoints Summary
Get session status
GET /v1/sessions/{id} returns the full status of a previously-created session. Requires a secret key (vp_sk_*); publishable keys are rejected with auth_key_type_forbidden. See Session Object for the response shape.
Close a session so you can charge another way
POST /v1/sessions/{sessionId}/expire closes an open, unpaid session so no payment can start on it afterwards. Call it before you take payment for the same order another way, such as when a buyer whose card was declined on the payment form switches to a card you saved earlier.
Reading the session first is not enough. GET /v1/sessions/{sessionId} tells you what has been recorded so far, but a payment the buyer's browser sent before giving up can still arrive after your read. Expiring the session closes that window: the check and the change happen in one atomic step, and payment attempts take the same step, so an expire and a payment racing for one session can never both succeed.
Closing a declined session. A failed session created with integrationMode: "elements" and chargeAtSubmit: true can also be closed (expiredFrom: "failed"): when no payment is recorded, paymentStatus is unpaid, no payment attempt on it is still in progress (such as a card waiting on the buyer's bank check), no hold from it is waiting to be released, and its hosted checkout page was never opened. A decline known to belong to the session's latest payment attempt is closed immediately. Otherwise the session must be unchanged for 10 minutes: the wait covers a payment that can still finish shortly after a decline it cannot be tied to, such as a wallet payment on the same session. If the decline allowed another card on the same session (retry.allowed: true), the session is back to pending and closes immediately.
200means the session is closed and no payment attempt that goes through our servers was in progress or can start. Expiring an already-expiredsession whoseexpiredFromispending,failedorauthentication_cancelled(a session closed while its payment waited on the bank's security check) also returns200, so the call is safe to retry.409 session_not_expirablemeans nothing changed. On a declined session it carries areason:recent_activitycomes withretryAfterSecondsand aRetry-Afterheader, so call again after that many seconds;payment_may_be_in_flightmay never clear. Treat an unrecognisedreasonaspayment_may_be_in_flight. Without arecent_activityreason, a payment may exist on the session that has not been reported, which is also what you get whenexpiredFromisprocessingornull. Do not take payment for the order another way. For those two states, do not rely on polling the session or on a webhook either: there is no session-expiry event, and otherwise a payment that lands on an already-expired session is not reported today. On anelements+chargeAtSubmitsession,expiredFrom: "processing"can later change tofailedonce the provider confirms the payment was never authorized after a timed-out bank check, and that attempt'spayment_intent.failed/charge.failedwebhooks announce it. Contact support with the session id.
One exception, on embed sessions. The buyer's browser pays the processor directly there, using a credential issued when the form loaded. That credential stays valid for up to an hour and cannot be recalled, so expiring the session stops new forms loading and refuses everything that goes through our servers, but it cannot stop a payment the buyer had already submitted. Remove or disable the payment form on your page and confirm the buyer is not mid-submission before you expire it. If a payment completes anyway it is not reported to you today, and it carries no payment intent, so it cannot be refunded through this API; contact support with the session id. Reporting for that case is being built. Sessions in elements mode, hosted checkout and wallet payments all go through our servers, where the guarantee holds.
Change an open session's total or metadata
PATCH /v1/sessions/{sessionId} changes the total, the metadata, or both, of an open, unpaid checkout session. Change the total when the buyer picks a delivery address or a shipping option inside the Apple Pay or Google Pay sheet and your store re-prices the order. Change the metadata to add something you only know after creating the session, such as your order number for the statement descriptor ending. It can also give a guest checkout the shopper's email, or name the customer once the shopper signs in, after the page opened (Name a guest). Requires a secret key.
curl -X PATCH https://checkout.vonpay.com/v1/sessions/vp_cs_live_k7x9m2n4p3 \
-H "Authorization: Bearer $VON_PAY_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "amount": 5498 }'
| Field | Required | Notes |
|---|---|---|
amount | To change the total | The new total in minor units (5498 = $54.98), from 1 to 99,999,999. |
currency | No | ISO 4217 code, only with amount. Omit it to keep the session's currency. |
lineItems | No | Same shape as on POST /v1/sessions, only with amount. When sent, it replaces the displayed line items. |
card_form_group | To set the group | The session's card-form group, when your server learns it after creating the session. Applied first and on its own, on an open session only. Write-once: the same value again changes nothing, a different value is refused with 400 validation_error (param: "card_form_group") and nothing is changed, and it can never be cleared. It lets a buyer keep the card they typed when your checkout replaces its session. |
metadata | To change the metadata | Keys to merge into the session's metadata, with the same rules as on create (at most 50 keys, string values up to 500 characters, and the reserved keys are dropped). Keys you send are added or overwrite the stored value; keys you leave out are kept; none are removed. The merged map is capped at 8 KB, and mirror cannot be set. See Session metadata merges too. |
Send amount, a non-empty metadata, card_form_group, or a combination of them. Guest details go in a request of their own (below). A request with none of these is a 400 validation_error. An empty metadata sent with amount is ignored.
Restricted keys. Under a restricted key with charge limits, a new total must fit those limits, as at create. Otherwise the answer is 422 api_key_limit_exceeded and nothing is changed. A metadata-only change is never capped. A restricted key can change the total only of a session it created. Any other session answers 404 session_not_found.
curl -X PATCH https://checkout.vonpay.com/v1/sessions/vp_cs_live_k7x9m2n4p3 \
-H "Authorization: Bearer $VON_PAY_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "metadata": { "order_id": "ORD-1234" } }'
A 200 returns the same object as GET /v1/sessions/{sessionId}. The server SDKs' sessions.update() changes the total from 2.11.0, the metadata from 4.2.0, the card-form group from 4.3.0 (cardFormGroup in Node, card_form_group in Python) and the guest details from 4.9.0; an update with none of them is refused by the SDK before anything is sent. The call sends no webhook, and an Idempotency-Key is optional because every change is idempotent on its own.
Only elements payment sessions can be changed. Anything else returns 409 session_not_modifiable with a reason, and nothing is changed:
reason | What it means | What to do |
|---|---|---|
integration_mode | Hosted checkout and the embedded payment form fix the total and the metadata when the form loads. | Create a new session. |
setup_session | A no-charge setup session has no total. | Nothing to change. |
store_order | Total changes only. The session is linked to a connected-store order (mirror or order), so the total is the store's. Its metadata can still be changed. | Change the order in the store instead. |
in_page_bank_check | Total changes only. Your account runs the buyer's bank check (3-D Secure) on the page before paying. The bank checks the amount, and the charged total must match the checked one. Its metadata can still be changed. | Create a new session with the new total. |
not_open | A payment is in progress, the session is paid, held, declined or expired, it was created to forward the card to another processor, or it has passed its time limit (it can still read pending and unpaid for a short while after). | Read session.status and session.paymentStatus in the response. Do not take payment for the same order another way while a payment is in progress. |
409 session_update_conflict means retry the same request. Other changes to the session kept landing while this one was applied, so nothing was changed (reason: "concurrent_update", with the session object). The session is still open and payable: wait a moment, send the same request again, and send updates for one session one after another rather than in parallel. See session_update_conflict.
A change can never land under a payment already in progress. The check and the change are one atomic step, and payment attempts go through the same step. The payment form also tells the server which total the buyer approved: the express-checkout element sends it for you, and a bring-your-own-button integration sends it as expected_amount. If the session no longer holds that total, the payment is refused with 409 expected_amount_mismatch and the buyer is not charged. A total that changes while a payment request is being processed is refused the same way, even when no expected_amount was sent.
Name a guest after the page opened
On a guest checkout, your store can learn the shopper's email after the payment page opened, or the shopper can sign in or create an account. Send the email, or your customer reference, to the session with PATCH /v1/sessions/{sessionId}. The card field does not need to be built again: the charge reads these values from the session when the shopper pays.
| Field | Notes |
|---|---|
buyerId | Your own customer reference, as on POST /v1/sessions, when the shopper signs in or creates an account after the page opened. Set once (Name the customer). |
buyerEmail | The guest's email. If the shopper changes it, send it again. The last value wins until the session names a customer. |
setupForFutureUse | on_session only, as on POST /v1/sessions. |
storedCredentialUse | unscheduled. recurring and installment are declared only at create: sent here, they are refused with 400 validation_error unless the session already holds that value. |
curl -X PATCH https://checkout.vonpay.com/v1/sessions/vp_cs_live_k7x9m2n4p3 \
-H "Authorization: Bearer $VON_PAY_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "buyerEmail": "shopper@example.com" }'
Send one of them or more, in a request of their own. With amount, metadata or card_form_group in the same request, the answer is 400 validation_error and nothing changes. The server SDKs take buyerEmail, setupForFutureUse and storedCredentialUse from 4.9.0 (buyer_email, setup_for_future_use and stored_credential_use in Python). They take buyerId from 4.13.0 (buyer_id in Python).
This works only on a payment session created with integrationMode: "elements" and chargeAtSubmit: true, before any payment attempt. Otherwise the answer is 409 session_not_modifiable with a reason, and nothing changes:
reason | Why |
|---|---|
integration_mode | The session is not an elements session that charges at submit. |
setup_session | The session saves a card without a payment. |
stored_credential_declared | The session was created with storedCredentialUse recurring or installment, and the request sends another value. A declared schedule never changes. |
customer_named | The session already names a customer, and the request changes a value. A request that sends only values the session already holds answers 200 and changes nothing. |
subscription_signup | The session starts a subscription. |
forwarded_gateway | The session was created to forward the card to another processor. |
store_order | The session is linked to a connected-store order. |
card_form_group | The session has a card_form_group. |
payment_attempted | A payment was already attempted on the session. |
not_open | The session is paid, ended or past its time limit. |
You can ignore this 409. The payment goes ahead on what the session already holds, and the card is not kept. With buyerId, the card is not kept under that customer.
Name the customer
buyerId is set once. Leave it out to keep the session's customer. A different buyerId is refused. Once the session names a customer, buyerEmail, setupForFutureUse and storedCredentialUse cannot change either. Send buyerId before the shopper pays: after any payment attempt, even a declined one, the answer is payment_attempted. buyerId alone does not keep the card. The card is kept only with reuse consent, as on a session created with buyerId. The 200 carries the session's id, integrationMode, chargeAtSubmit and buyerId, so you can check it is the session you meant to change.
A change that lands as the shopper pays. If your change arrives as the shopper presses Pay, the charge answers 409 session_update_conflict with reason: "concurrent_update". Nothing was charged and the session is still open. The shopper submits the same card again. Do not ask for a different card, and do not create a new session. A wallet payment answers the same way: nothing was charged, and the shopper pays again.
Session statuses
A checkout session has one of five statuses: pending, processing, succeeded, failed, or expired. The normal flow is pending → processing → succeeded (or → failed / → expired); a session may also move directly pending → succeeded/failed/expired. Not all transitions are one-way: a processing session can revert to pending, and a failed session can later converge to succeeded on a successful retry (success takes precedence). Only succeeded and expired are terminal. See Session Object — Status Lifecycle.
Payment intent statuses
Payment intents progress through a discrete lifecycle of seven statuses: requires_action → authorized → captured → succeeded (or voided / failed, or cancelled when a payment still waiting on the bank's security check is cancelled with nothing taken). On the manual-capture path, authorized → captured → succeeded runs as three discrete steps; on the automatic-capture path, an authorized intent can move straight to succeeded when settlement is synchronous. See the Payment Intents guide for the full state machine, transition rules, and error envelope.
Endpoints
This lists the merchant endpoints in the published contract. API error responses carry a docs link that points into this table. Where an endpoint is operator-enabled rather than always available, the row says so — being in the contract is not the same as being switched on for your account.
| Method | Path | Auth | Description |
|---|---|---|---|
POST | /v1/sessions | Secret | Create a checkout session (Hosted Checkout). A price can only be set with a secret key, so a publishable key cannot create a session (403 auth_key_type_forbidden). The /v1/public/* routes below require a publishable key instead; API Key Types lists them with what each one does |
POST | /v1/sessions?dry_run=true | Secret | Validate params without creating a session |
GET | /v1/sessions/{sessionId} | Secret | Get session status |
PATCH | /v1/sessions/{sessionId} | Secret | Change the total, merge metadata or name a guest on an open, unpaid elements session: the total typically after the buyer picks a shipping address or option in the Apple Pay / Google Pay sheet, the metadata to add your order number once you have it. Also sets the session's write-once card_form_group. Refused with 409 session_not_modifiable (nothing changed) on hosted and embedded-form sessions and setup sessions; a total change is also refused on sessions linked to a store order and sessions with an in-page bank check. Sends no webhook. See Change an open session's total or metadata |
POST | /v1/sessions/{sessionId}/expire | Secret | Close an open, unpaid session so no payment can start on it afterwards. Call it before taking payment for the same order another way, such as when a buyer whose card was declined switches to a card you saved earlier. Reading the session does not claim it, and a payment the browser sent before the buyer gave up can still arrive after your read. Idempotent on an already-expired session whose expiredFrom is pending, failed or authentication_cancelled; any other state returns 409 session_not_expirable and changes nothing |
POST | /v1/payment_intents | Secret | Create a payment intent (auth or auth+capture) — see guide |
GET | /v1/payment_intents/{id} | Secret | Retrieve a payment intent's persisted state. This is where you read back the full metadata — the provider truncates long values on the charge itself, but the intent keeps what you sent. Because it comes back verbatim, keep card numbers, bank details and government IDs out of metadata |
GET | /v1/payment_intents | Secret | List your payment intents, newest first, with filters (window of at most 31 days) — see Payment reports. A read-only restricted key (payment_intents.read) is enough |
GET | /v1/payment_intents/summary | Secret | Counts, amounts and approval and decline rates for a window, optionally grouped by time, store, tag, card brand, currency, outcome or decline code — see Payment reports |
POST | /v1/payment_intents/{id}/capture | Secret | Capture an authorized intent (full or partial via amount_to_capture) |
POST | /v1/payment_intents/{id}/client_read_secret | Secret | Mint a new read-only browser secret for a payment created with next_action_presentation: "in_page" that still waits on the bank's check, for a page that reloaded or a second browser. At most 3 work at once and 10 are minted per payment. See Show the check in a pop-up on your page. |
POST | /v1/payment_intents/{id}/void | Secret | Void an authorized intent (before capture) |
GET | /v1/payment_intents/{id}/mirror-order | Secret | Mirrored store-order reference for a discrete-flow intent — see Connected platforms |
GET | /v1/refunds | Secret | List one payment's refunds, newest first, with its refund totals — see Refunds |
POST | /v1/refunds | Secret | Refund a succeeded payment intent (full or partial via amount) |
POST | /v1/tokens | Secret | Mint a vp_pmt_* payment-method token from a provider vault reference (provider_reference) |
GET | /v1/payment_methods | Secret | List a buyer's saved cards by your own customer reference — see Tokens |
PATCH | /v1/tokens/{id} | Secret | Replace the billing address stored with a saved card, or clear it with null (see Tokens) |
POST | /v1/security_code_sessions | Secret | Open a short-lived session for the buyer to re-type a saved card's security code, then charge with security_code_session (see Saved card security code) |
DELETE | /v1/tokens/{id} | Secret | Revoke a stored payment method so it can never be charged again — see Tokens |
POST | /v1/buyers | Secret | Create or update a buyer record (upsert on external_id / email) — see Buyers |
GET | /v1/buyers | Secret | Exact buyer lookup by ?external_id= or ?email= (at least one required; no unfiltered listing) |
GET | /v1/buyers/{id} | Secret | Retrieve a buyer by vp_by_* id |
PATCH | /v1/buyers/{id} | Secret | Sparse buyer profile update (external_id not patchable) |
GET | /v1/capabilities | Publishable or Secret | Per-merchant capability matrix (supported_operations, settlement_currencies, rate_limits) |
GET | /v1/descriptor_config | Secret | Your statement-descriptor configuration — see Statement descriptors |
POST | /v1/mirror/quote | Secret | Price a basket against the connected store before charging — see Connected platforms |
GET | /v1/subscription_products | Secret | List your subscription products, newest first, each with the terms a sign-up on it states (see Subscriptions) |
POST | /v1/subscription_products | Secret | Create a subscription product, with the same rules as one made in your dashboard. Needs an Idempotency-Key (see Subscription products) |
GET | /v1/subscription_products/{product} | Secret | Read one subscription product by its id, or by the product_ref of an active product, with its routing profile, store links and number of live subscriptions (see Subscription products) |
PATCH | /v1/subscription_products/{product} | Secret | Change a subscription product's name, routing profile, schedule, store links or web page. A new schedule or routing applies to new sign-ups only. Needs an Idempotency-Key |
POST | /v1/subscription_products/{product}/price | Secret | Change a subscription product's renewal price. A raise is for new sign-ups only; a cut can also lower existing subscriptions on the old price. Needs an Idempotency-Key (see Subscription products) |
POST | /v1/subscription_products/{product}/archive | Secret | Archive a subscription product: no new sign-ups, while existing subscriptions keep renewing. Needs an Idempotency-Key |
POST | /v1/subscription_products/{product}/unarchive | Secret | Sell an archived subscription product again. Needs an Idempotency-Key |
GET | /v1/subscription_products/{product}/terms | Secret | Read a subscription product's price, schedule and default terms sentence, to show next to the order button before the sign-up charge (see Subscriptions) |
GET | /v1/subscriptions | Secret | List your subscriptions, newest first; filter by buyer_id, email or status (see Subscriptions) |
GET | /v1/subscriptions/{id} | Secret | Read one subscription |
GET | /v1/subscriptions/{id}/attempts | Secret | List a subscription's payment tries, newest first. See Payment tries |
POST | /v1/subscriptions/{id}/cancel | Secret | Cancel a subscription now, or at the end of the paid period with at_period_end. Never refunds. Needs an Idempotency-Key |
DELETE | /v1/subscriptions/{id}/scheduled_cancel | Secret | Withdraw a cancel scheduled for the end of the paid period. Needs an Idempotency-Key |
POST | /v1/subscriptions/{id}/pause | Secret | Pause renewals, optionally until a resumes_on date. Needs an Idempotency-Key |
POST | /v1/subscriptions/{id}/resume | Secret | Resume a paused subscription. Needs an Idempotency-Key |
POST | /v1/subscriptions/{id}/skip | Secret | Skip the next renewal: the next bill date moves one interval later, at once. Needs an Idempotency-Key |
POST | /v1/subscriptions/{id}/next_bill_date | Secret | Move the next charge to a date. A sooner date waits for a notice to the customer. Needs an Idempotency-Key |
POST | /v1/subscriptions/{id}/interval | Secret | Change how often a subscription renews. Billing more often waits for a notice to the customer. Needs an Idempotency-Key |
GET | /v1/webhook_subscriptions | Secret | List your webhook subscriptions — see Webhook verification |
POST | /v1/subscriptions/{id}/price | Secret | Set one subscription's renewal price. Needs an Idempotency-Key |
POST | /v1/subscriptions/{id}/discount | Secret | Set a discount on future renewals (one at a time). Needs an Idempotency-Key |
DELETE | /v1/subscriptions/{id}/discount | Secret | Remove a subscription's discount. Needs an Idempotency-Key |
POST | /v1/subscriptions/{id}/portal_links | Secret | Create a one-time link to the customer's subscription page, for a Manage subscription button (see Subscriptions) |
POST | /v1/webhook_subscriptions | Secret | Create a webhook subscription |
GET | /v1/webhook_subscriptions/{id} | Secret | Retrieve one subscription |
PATCH | /v1/webhook_subscriptions/{id} | Secret | Update a subscription's events, description or status (its URL cannot change) |
DELETE | /v1/webhook_subscriptions/{id} | Secret | Delete a subscription |
POST | /v1/webhook_subscriptions/{id}/rotate_signing_secret | Secret | Rotate a subscription's whsec_* signing secret — see Webhook secrets |
POST | /v1/webhook_subscriptions/{id}/send_test_event | Secret | Send a test event to a subscription |
GET | /v1/webhook_events/{id} | Secret | Retrieve a single webhook event |
GET | /v1/webhook_listen | Secret | Stream your webhook delivery attempts (Server-Sent Events) — what the CLI's listen command uses. Answers 501 when the feed is switched off: see Streaming endpoints below |
GET | /v1/wallet-domains | Secret | List your Apple Pay / Google Pay domain entries; see How domain entries work |
POST | /v1/wallet-domains | Secret | Register a domain for one wallet; see How domain entries work |
GET | /v1/wallet-domains/{id} | Secret | Retrieve one wallet-domain verification |
DELETE | /v1/wallet-domains/{id} | Secret | Remove a wallet-domain verification (soft delete) |
POST | /v1/wallet-domains/{id}/verify | Secret | Check one wallet domain again; see How domain entries work |
GET | /v1/wallet-domains/{id}/file | Secret | Download the Apple Pay domain-verification file to host on your site; see Apple Pay setup |
POST | /v1/sdk-telemetry | Secret | SDK telemetry (on by default with a test key, off with a live key or a local server). Your code does not call this — the server SDKs post to it for you when telemetry is enabled |
GET | /v1/public/sessions/{sessionId} | Publishable | Browser-safe session lookup — used by Embedded Fields SDK |
POST | /v1/public/binder-load | Publishable | Per-processor element capability map (Embedded Fields) |
GET | /v1/public/security_code_sessions/{id} | Publishable | Security-code field configuration, read by the browser SDK's vora.securityCode() (Embedded Fields) |
POST | /v1/public/security_code_sessions/{id} | Publishable | Records that the buyer entered a valid security code (no code or card data is sent), called by the browser SDK's vora.securityCode() submit() from vora.js 1.40.2 (Embedded Fields) |
GET | /v1/public/payment_intents/{id} | Publishable | Read the status of a payment your server created with next_action_presentation: "in_page", with its client_read_secret in the X-Vonpay-Intent-Secret header. vora.handleNextAction() calls it for you. Every refusal is the same 404, which does not mean unpaid. See the check in a pop-up. |
GET | /v1/public/payment_intents/challenge-return | None | The page the bank's check returns to on an in-page bank check. Not called by your code: in the pop-up it tells your page, and in a new tab it sends the shopper to your return_url with payment_intent=<id>. See the check in a pop-up. |
POST | /v1/public/tokens | Publishable | Browser-side vp_pmt_* minting (Embedded Fields) |
GET | /v1/public/payment_intents/{id}/events | Signed token | Live payment-status stream for the buyer's browser (Server-Sent Events). ⚠️ Not generally available — see Streaming endpoints below |
POST | /v1/public/payment_intents/{id}/stream_token | Signed token | Renew the token for the payment-status stream above, sending the current token as Authorization: Bearer. ⚠️ Not generally available: it is switched off together with the stream, see Streaming endpoints below |
GET | /api/health | None | Health check (add ?deep=true for deep variant) |
POST | /v1/public/sessions/{sessionId}/charge | Publishable | Charge the card the buyer just entered, from the browser, on an Embedded Fields elements-mode session — the charge-at-submit path. Your server never sees the card. See Custom layout; on this path do not also call POST /v1/payment_intents, or you charge twice. |
POST | /v1/public/sessions/{sessionId}/complete | Publishable | Resolve the outcome of an embedded payment after submit. The SDK calls this for you — you read the result it returns. A result here is a UX signal, not proof of payment: confirm from the webhook before fulfilling. |
POST | /v1/public/sessions/{sessionId}/wallet_challenge/cancel | Publishable | Close an Apple Pay or Google Pay bank check (3-D Secure) the buyer left unfinished, so the session can take another try. vora.js calls this for you. The response's outcome is reopened, succeeded, ended or pending. It is not proof of payment: fulfill from the webhook. |
GET | /v1/public/sessions/{sessionId}/embed-token | Publishable | Poll whether an embedded session is ready to mount. The SDK handles this during load(); you would only call it directly when diagnosing a card form that never appears — see Embedded Fields errors. |
GET | /v1/public/sessions/{sessionId}/mirror-order | Publishable | Read the connected-store order reference for a completed session — for showing an order number on your thank-you page. Safe from the browser; it returns the reference only, never buyer identity. |
POST | /v1/public/wallets/apple-session | Publishable | Apple Pay merchant validation, for a bring-your-own-button wallet integration. Not needed with the Express Checkout element, which handles validation itself — see Standalone wallets. |
POST | /v1/public/wallets/google-session | Publishable | Google Pay session setup for a bring-your-own-button wallet integration. Not needed with the Express Checkout element — see Standalone wallets. |
Streaming endpoints
Two endpoints in the contract stream over Server-Sent Events. For webhook delivery to your server, use webhook subscriptions; these streams do not replace them.
GET /v1/webhook_listen streams your webhook delivery attempts, one frame per attempt; the CLI's listen uses it. It takes a secret key.
- A test key sees only test-mode attempts and a live key only live-mode ones. A test event sent with
POST /v1/webhook_subscriptions/{id}/send_test_eventshows as one attempt on a test key's feed. - The stream opens with a
: connectedcomment frame, so the headers arrive at once. - When the feed is switched off, the answer is
501endpoint_not_implementedat once, with noRetry-After. Retrying will not change it: watch deliveries at your webhook subscription's URL instead. - An account can keep at most 5 feeds open on each server, and each server has its own limit too. Over either, the answer is a retryable
503service_unavailablewithRetry-After: 5: close a feed or wait, then retry.
GET /v1/public/payment_intents/{id}/events answers 503 to every caller, with no body, so code that parses every error as JSON throws instead of reading a code. The stream's token renewal, POST /v1/public/payment_intents/{id}/stream_token, is switched off with it and answers the same bare 503.
Authentication
Merchant-facing endpoints use Bearer token auth:
Authorization: Bearer vp_sk_live_xxx
Test keys use the vp_sk_test_ prefix. Live keys use vp_sk_live_.
Most endpoints require a secret key (vp_sk_*), including session creation (POST /v1/sessions and its dry_run variant): a price can only be set with a secret key, so a publishable-key create is refused with auth_key_type_forbidden (HTTP 403). The exceptions are GET /v1/capabilities, which accepts either key type, and the /v1/public/* endpoints, which require a publishable key (vp_pk_*). So a publishable key can read capabilities and call the public browser endpoints; it is rejected on every secret-only route with auth_key_type_forbidden (HTTP 403).
Request Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer API key. The accepted key type depends on the endpoint: secret (vp_sk_*) for most routes and for session creation, publishable (vp_pk_*) for the /v1/public/* endpoints, and either type for GET /v1/capabilities. |
Content-Type | Conditional | application/json on the browser/public POST endpoints (/v1/public/sessions/{id}/charge, /v1/public/tokens), which reject a missing or non-JSON type with HTTP 415 unsupported_media_type. The authenticated REST POST endpoints (/v1/sessions, /v1/payment_intents, /v1/refunds, /v1/tokens) parse the JSON body without a Content-Type check, but sending application/json is recommended for all POST requests. |
Von-Pay-Version | No | API version date string (e.g. 2026-04-14). If omitted, the request uses the current API version. Pin this header to avoid breaking changes when the API evolves. |
Idempotency-Key | Conditional | One key per logical operation, reused on every retry — a replay with the same key returns the original response. Required on every POST /v1/payment_intents from the 28 October 2026 cut-off, after which a keyless charge can be refused at any time; until the refusal starts, a keyless charge succeeds but its response carries Deprecation, Sunset and Link headers. Already required on POST /v1/refunds and POST /v1/payment_intents where the processor connection keeps no queryable record of its own (a keyless request is refused with 400 idempotency_key_required); optional elsewhere, but a keyless retry issues a second real refund or charge. Never mint a fresh key to get past a 409 charge_in_progress. Max 255 printable-ASCII characters. See Idempotency. |
Response Headers
Every response includes:
| Header | Description |
|---|---|
X-Request-Id | Unique request ID for debugging |
The three rate-limit headers X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset are returned on every rate-limited response — both successful responses and 429 responses. Retry-After is the only one that also appears outside rate limiting: a 503 carries it too, both during a maintenance write-freeze and on the disabled-/v1/webhook_listen state described above. Do not read Retry-After as "you were rate limited" — branch on the status code. See Rate Limits.
Idempotency
Idempotency-Key is enforced per-resource: a key is unique to (merchant_id, idempotency_key) on the resource it created (session, payment intent, refund). A replayed key with a matching request body returns the original response. A replayed key with a different request body returns HTTP 422 idempotency_replay_incompatible — the SDK surfaces this loudly so a buggy retry that changed amount, cart, or redirect URLs cannot silently inherit a prior resource.
Retention. On POST /v1/payment_intents we keep a key for at least 30 days after the request that first used it. After 30 days, do not rely on a key to detect a duplicate (How long a key lasts). Use one key per logical operation and reuse it across every retry of that operation — that reuse is what makes the retry safe. Use a different key only when the operation is genuinely different (a second, intentional refund of the same payment; a new order), not merely because it is a later attempt. One exception: a refund that came back 200 with status: "canceled" is terminal and returned no money, and reissuing it under the same key replays that response forever — see Refunds. Full rule: Idempotency.
Format. Max 255 characters, printable ASCII only (codepoints 0x20–0x7E). Whitespace-only keys are treated as no key.
The server SDKs retry an ambiguous failure (5xx, timeout) on a money-moving call (create, capture, void, refund) only when you sent a key — see Auto-retry.
Errors
session_already_completed is returned as HTTP 409 Conflict, distinct from session_expired's HTTP 410 Gone. It means the session's payment already finished: the buyer was charged once (authorized once on a captureMethod: "manual" session). It comes from the public completion and read endpoints, and from POST /v1/payment_intents when the session_id you pass already charged at submit, or that expired, or had a payment-provider transaction recorded without succeeding (the body then carries charged: false, plus expiredFrom: "processing" when the session ended while its charge was being decided; the outcome may not be final). On POST /v1/payment_intents, charged: false means only that your request charged nothing: on a captureMethod: "manual" session the session's own payment can be authorized and held, which sends only payment_intent.authorized until you capture it, so read GET /v1/payment_intents/{id} (status: "authorized") or wait for that webhook. It never comes from POST /v1/sessions itself. A payment that is still running answers a separate 409, session_payment_in_progress.
Branch on code: never create a new session for either 409, since that could charge the buyer twice. A 410 means the session ended; create a fresh one, unless the body carries expiredFrom: "processing", which means a charge may have been taken (see session_expired).
Rate Limits
Full bucket list and handling rules: Rate Limits.