Skip to main content

API Key Types

Where keys come from​

Key issuance depends on mode:

  • Test keys (vp_sk_test_*, vp_pk_test_*) come from your business's sandbox. Activate it from Developers and create them there. Asking for test keys on the live business is refused with 403 test_keys_are_sandbox_only.
  • Live keys (vp_sk_live_*, vp_pk_live_*) are created on the live business, never on a sandbox (403 live_keys_not_on_sandbox). They are issued once your merchant application is approved and a payment processor is connected to your account. Both are required, and they are checked in that order:
    • Not approved yet: 403 merchant_not_onboarded (Error Codes).
    • Approved, but nothing connected: 403 live_keys_need_processor (Error Codes).
    • We could not confirm your payment setup: 503 processor_check_unavailable (Error Codes). This one is temporary and is not a problem with your request; retry shortly.

These refusals gate creating a new key. Keys you already hold keep working, and rotating one is never refused for these reasons.

A business can hold up to 20 active keys in each mode. Live and test keys count separately. The old key of a rotation stays active, and counts, until its grace period ends. At 20, creating or rotating a key is refused until you revoke one. Revoking frees the slot at once, so a leaked key can still be replaced: revoke a spare key first, or keep a slot free.

Key types at a glance​

KeyPrefixWhere to use itRotation
Test secret keyvp_sk_test_Server-side code, test mode onlyGrace window (default 24h)
Live secret keyvp_sk_live_Server-side code, production onlyGrace window (default 24h)
Test publishable keyvp_pk_test_Browser-exposed client code, test mode onlyGrace window (default 24h)
Live publishable keyvp_pk_live_Browser-exposed client code, production onlyGrace window (default 24h)
Restricted keyvp_sk_test_ / vp_sk_live_Server-side code that needs only part of the API: it can do only what you chose (Restricted keys)Grace window (default 24h); keeps its permissions and limits
Legacy secret keyvp_key_⚠ Older accounts only. Still accepted, and treated as a full secret key — server-side only, never in a browserRotate to a vp_sk_ key
Legacy session secret

Older accounts may hold an ss_test_ / ss_live_ session secret. It is no longer issued and verifies nothing — in particular it is not how you confirm a payment when the buyer is redirected back. Read the outcome from sessions.get and fulfill on the charge.succeeded webhook instead; see Handle the return.

Webhook signing secrets (whsec_*) are separate — see Webhook Signing Secrets.

Secret vs publishable — when to use which​

  • Secret keys (vp_sk_*) can create sessions, retrieve session status, and do everything through the API. A restricted key is a secret key that can do only what you chose. Never expose them to a browser or mobile app.

  • Publishable keys (vp_pk_*) are safe to embed in client code. They cannot create sessions: a price may only be set with a secret key, so POST /v1/sessions refuses a publishable-key request carrying amount, currency, lineItems, mirror or order with 403 auth_key_type_forbidden and reason: "price_requires_secret_key", and every session needs a currency. Create sessions on your server with your secret key. One read-only route accepts either key type: GET /v1/capabilities. Every other /v1/ merchant route rejects a publishable key with auth_key_type_forbidden (HTTP 403), including retrieving the full session details a secret key sees.

    A publishable key still reaches the browser-facing routes. The browser-facing /v1/public/* routes below require a publishable key and reject a secret one, so the reach of a publishable key is wider than the merchant surface suggests:

    RouteMethodWhat it does
    /v1/public/sessions/{id}GETRedacted public session view (id, expiry, amount, currency, routing — no PII, no merchant-internal metadata, no provider session id)
    /v1/public/sessions/{id}/embed-tokenGETShort-lived token for the embedded-fields frame
    /v1/public/sessions/{id}/mirror-orderGETMirrored store-order status for this session
    /v1/public/sessions/{id}/chargePOSTCharges the buyer — Embedded Fields charge at submit. 422 merchant_not_configured where your gateway does not support it; 501 endpoint_not_implemented while it is switched off platform-wide or not yet live-enabled for your gateway
    /v1/public/sessions/{id}/completePOSTCompletes the session after payment — the SDK calls it for you
    /v1/public/sessions/{id}/wallet_challenge/cancelPOSTCloses an Apple Pay or Google Pay bank check (3-D Secure) the buyer left unfinished, so the session can take another try. The SDK calls it for you
    /v1/public/security_code_sessions/{id}GET, POSTSecurity-code field configuration, and the record that the buyer entered a valid code (no code or card data is sent)
    /v1/public/binder-loadPOSTPer-processor element capability map
    /v1/public/tokensPOSTMints a vp_pmt_* payment-method token from the browser — and on a wallet request (instrument: "wallet") charges the buyer directly
    /v1/public/telemetry/browserPOSTBrowser telemetry ingest
    /v1/public/wallets/apple-sessionPOSTApple Pay merchant validation for standalone wallets, enabled per account
    /v1/public/wallets/google-sessionPOSTGoogle Pay session for standalone wallets, enabled per account

    The session routes are session-bound — each is scoped to one checkout session, and a cross-merchant, mode-mismatched, or unknown session collapses to an opaque 404. That scoping, not the key type, is what limits them. (/v1/public/telemetry/browser takes no session and is rate-limited per IP instead.)

Key type is derived authoritatively from the prefix: vp_pk_ ⇒ publishable, vp_sk_ ⇒ secret. The checkout API enforces key-type restrictions server-side. For example, calling sessions.get() (GET /v1/sessions/:id, the full secret-key view) with a publishable key returns auth_key_type_forbidden (HTTP 403). The SDK surfaces that 403; it does not reject the key at construction time — constructing a client with a publishable key is allowed.

Restricted keys​

A restricted key is a secret key that can do only what you chose when you created it. Give one to a system that needs a small part of the API, for example a script that issues refunds. It has the same prefix as any secret key (vp_sk_test_… / vp_sk_live_…) and you use it the same way, from your server only.

To create one:

  1. In the dashboard, open Developers and create a secret key. Test keys come from your sandbox and live keys from your live business, as for any key (above).
  2. Under What can this key do?, select Only what I choose (a restricted key).
  3. Tick the permissions the key needs (the table below).
  4. If the key can take payments, set at least one money limit (below).
  5. Create the key, and store it as you store any secret key.

You cannot change a key's permissions or limits later. To change them, create a new key. Rotating a key keeps its permissions and limits.

What each permission allows​

PermissionIn the dashboardEndpoints it opens
sessions.readCheckout sessions: ReadGET /v1/sessions/{id}
sessions.writeCheckout sessions: Create and changePOST /v1/sessions, PATCH /v1/sessions/{id}, POST /v1/sessions/{id}/expire
sessions.create_setupCheckout sessions: Save a card, no paymentPOST /v1/sessions, for a card-save session with no payment only
payment_intents.readPayments: ReadGET /v1/payment_intents/{id}, GET /v1/payment_intents/{id}/mirror-order, and the payment reports: GET /v1/payment_intents and GET /v1/payment_intents/summary
payment_intents.writePayments: Take paymentsPOST /v1/payment_intents, and capture, void and cancel on a payment intent
payment_intents.create_mit_recurringPayments: Take renewal payments from saved cardsPOST /v1/payment_intents, for a merchant-initiated recurring charge on a saved card only
refunds.readRefunds: ReadGET /v1/refunds
refunds.writeRefunds: RefundPOST /v1/refunds
payment_methods.readSaved cards and tokens: Read saved cardsGET /v1/payment_methods
tokens.writeSaved cards and tokens: Create card tokensPOST /v1/tokens, PATCH /v1/tokens/{id}, DELETE /v1/tokens/{id}
buyers.readCustomers: ReadGET /v1/buyers, GET /v1/buyers/{id}
buyers.writeCustomers: Create and changePOST /v1/buyers, PATCH /v1/buyers/{id}
webhooks.readWebhooks: ReadGET /v1/webhook_subscriptions, GET /v1/webhook_subscriptions/{id}, GET /v1/webhook_events/{id}, GET /v1/webhook_listen
webhooks.writeWebhooks: Create and changePOST /v1/webhook_subscriptions, PATCH and DELETE /v1/webhook_subscriptions/{id}, rotate_signing_secret, send_test_event
wallet_domains.readWallet domains: ReadGET /v1/wallet-domains, GET /v1/wallet-domains/{id}, GET /v1/wallet-domains/{id}/file
wallet_domains.writeWallet domains: Add and removePOST /v1/wallet-domains, DELETE /v1/wallet-domains/{id}, POST /v1/wallet-domains/{id}/verify
subscriptions.readSubscriptions: ReadGET /v1/subscriptions, GET /v1/subscriptions/{id}, GET /v1/subscription_products, GET /v1/subscription_products/{product}
subscriptions.writeSubscriptions: Cancel, pause, resume, skipPOST /v1/subscriptions/{id}/cancel, DELETE /v1/subscriptions/{id}/scheduled_cancel, /pause, /resume, /skip. Also reads subscriptions
subscriptions.write_billingSubscriptions: Change billingPOST /v1/subscriptions/{id}/next_bill_date, /interval, /price, POST and DELETE /v1/subscriptions/{id}/discount, and POST /v1/subscriptions/{id}/portal_links. Does not include subscriptions.write or subscriptions.read: add subscriptions.read if the key must also read subscriptions. A restricted key made before this permission existed does not have it: create a new key
subscription_products.writeSubscription products: Create, change, archivePOST /v1/subscription_products, PATCH /v1/subscription_products/{product}, /price, /archive, /unarchive, and the two product reads. Lowering what existing customers pay (apply_to_existing: true) or sending routing_profile also needs subscriptions.write_billing
capabilities.readOther: Read account capabilitiesGET /v1/capabilities
descriptor_config.readOther: Read statement name settingsGET /v1/descriptor_config
security_code_sessions.writeOther: Ask for a card's security code againPOST /v1/security_code_sessions
mirror.writeOther: Send your store's ordersPOST /v1/mirror/quote

A request the key holds no permission for is refused with 403 api_key_permission_denied. The error message names the permission the request needs. An endpoint not in this table is refused to every restricted key: use a full key for it. The browser endpoints under /v1/public/* take a publishable key and refuse a restricted key too.

Money limits​

A key that can take payments (Take payments or Take renewal payments from saved cards) must have at least one money limit. The limits are in one currency:

  • Most per payment: the largest single payment the key may make.
  • Most in 24 hours: the total of the key's payments over any rolling 24 hours. Approved payments and payments still in progress count, and so do the key's checkout sessions while they are under 24 hours old or still open for payment. Declined payments do not.

These limits also cap the payment checkout sessions the key creates. A session's total must be in the limits' currency, and no more than the per-payment maximum (or the 24-hour total, when that is lower or the only limit). Each payment session the key creates counts toward the 24-hour total while it is under 24 hours old or still open for payment, paid or not. Expiring an unused session frees its room. A session's total over the limits is refused with limit: "per_session".

A payment in another currency, above the per-payment maximum, or past the 24-hour total is refused with 422 api_key_limit_exceeded, and nothing is charged. The error's limit field says which limit refused it. Only a daily_total refusal clears by waiting. Refunds do not count against these limits.

A key that can refund (refunds.write) must have a refund limit: a per-refund maximum, a rolling 24-hour refund total, or both, in the same currency. A refund with no amount counts as the whole remaining balance. Requested and completed refunds count toward the total. Failed and canceled refunds do not.

A refund from a key with no refund limit, above the maximum, past the 24-hour total or in another currency is refused with 422 api_key_limit_exceeded, and nothing is refunded. Only a refund_daily_total refusal clears by waiting.

The two narrow permissions​

Two permissions allow one action only: Take renewal payments from saved cards (payment_intents.create_mit_recurring) and Save a card, no payment (sessions.create_setup). A key that holds one of them without the wider permission (payment_intents.write or sessions.write) may send only what that action needs.

  • Renewal payments: the request must be a merchant-initiated recurring charge, mit: { "initiator": "merchant", "reason": "recurring" }, on a saved card (payment_method: { "id": "vp_pmt_…" }). It may also send amount, currency, capture_method, metadata (but not metadata.mirror) and buyer_id.
  • Card-save sessions: the session must be a card-save session with no payment. Customer profile and contact fields, line items and store-order fields are refused.

A field that writes somewhere the permission does not cover is refused with 403 api_key_permission_denied, and the error's refused_fields lists the fields to remove. Nothing is charged or created.

Examples​

Three common keys. Tick only what the system needs: a key can never do more than its permissions allow.

A refund-only key​

For a system that only issues refunds, for example a bulk refund script, tick two permissions: Refunds: Read and Refunds: Refund. Add Payments: Read only if the script also reads payments.

The key can refund, so it must have a refund limit. Choose the Currency under the key's money limits; refund limits use it. Then, under Refund limits, set one or both:

  • Set Most per refund a little above your largest refund. A refund with no amount counts as the whole remaining balance, so a full refund of a payment above this limit is refused.
  • Set Most refunded in 24 hours above the total of a normal day's refunds. The total is rolling. Requested and completed refunds count against it; failed and canceled ones do not.

Choose limits that also stop a faulty script from refunding far more than you expect. A refund outside a limit, or in another currency, is refused with 422 api_key_limit_exceeded, and nothing is refunded.

Before you refund a payment, list its refunds, so that a run you start again does not refund it twice:

curl "https://checkout.vonpay.com/v1/refunds?payment_intent=vpi_live_EXAMPLE" \
-H "Authorization: Bearer vp_sk_live_YOUR_RESTRICTED_KEY"

Then refund it. Give every refund its own Idempotency-Key, made from your own record (an order and a refund number), never a random value made at send time:

curl https://checkout.vonpay.com/v1/refunds \
-H "Authorization: Bearer vp_sk_live_YOUR_RESTRICTED_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_1042_refund_1" \
-d '{ "payment_intent": "vpi_live_EXAMPLE", "amount": 500 }'

If the call gets no answer, send it again with the same key. A 202 with status: "requested" is not a failure: never refund it again (Refunds). A payment, a capture or a new checkout session with this key is refused with 403 api_key_permission_denied.

A read-only key for reporting​

For a reporting job or an internal dashboard, tick only read permissions, for example Payments: Read, Refunds: Read and Checkout sessions: Read. Add Customers: Read only if the report needs customer records. The key cannot take payments, so it needs no money limit, and every request that would change something is refused with 403 api_key_permission_denied.

Payments are read one at a time, by id:

curl https://checkout.vonpay.com/v1/payment_intents/vpi_live_EXAMPLE \
-H "Authorization: Bearer vp_sk_live_YOUR_RESTRICTED_KEY"

To record every payment as it happens, set up webhooks with a full key. Your receiver can then read each payment by id with this key.

A renewals-only key for a billing job​

For a job that charges your customers' saved cards on a schedule, tick Payments: Take renewal payments from saved cards, plus Payments: Read to read the results and Saved cards and tokens: Read saved cards to find a customer's card. This permission is narrow: the key can make only a merchant-initiated recurring charge on a saved card, and nothing else.

The key can take payments, so it must have a money limit:

  • Set Most per payment a little above your largest renewal amount. A charge above it is refused.
  • Set Most in 24 hours above the total of a normal day's renewals. The total is rolling. Approved payments and payments in progress count against it; declined payments do not.
  • Both limits are in one currency, chosen when you create the key. A renewal in another currency is refused, so bill each currency with its own key.

A charge outside a limit is refused with 422 api_key_limit_exceeded, and nothing is charged. Its limit field says which limit refused it, including unsupported when your account's payment connection cannot apply a 24-hour total: then set a per-payment maximum only. Choose limits that also stop a faulty job from charging far more than you expect.

Each charge names the saved card and the recurring reason, with one Idempotency-Key per renewal. A renewal sends no return_url: nobody is present to complete a 3-D Secure check.

curl https://checkout.vonpay.com/v1/payment_intents \
-H "Authorization: Bearer vp_sk_live_YOUR_RESTRICTED_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: renewal_cust42_2026_11" \
-d '{
"amount": 2999,
"currency": "USD",
"payment_method": { "id": "vp_pmt_live_EXAMPLE" },
"mit": { "initiator": "merchant", "reason": "recurring" }
}'

mit.original_transaction_id is optional here: the charge is linked to the card's first approved payment made with the customer present. If the card has none, the charge is refused with 422 mit_anchor_unknown and nothing is charged; send mit.original_transaction_id with the vpi_… of the payment where the customer agreed.

For a card saved to a customer, also send that customer's buyer_id: a buyer_id that does not match the card's owner is refused as if the card did not exist (payment_method_not_found). Leave capture_method out, so the renewal is captured at once: this key cannot capture, void or cancel a payment. Besides these, the key may send only metadata. Any other field, such as buyer_email or billing_address, is refused with 403 api_key_permission_denied, and refused_fields names it. For how a merchant-initiated charge is linked to the customer's first payment, see Payment intents: merchant-initiated charges.

Rotation grace​

When you rotate a secret or publishable key, the old key stays valid for a grace window so you can deploy the new key without downtime. The grace period is caller-configurable — 1h, 24h, or 7d — and defaults to 24h when you don't specify one. The old key keeps working until grace_ends_at, after which it rejects with auth_key_expired.

Rotation timeline (default 24h grace)​

t =State
t0Click Rotate in /dashboard/developers/api-keys. New key is created; old key enters grace.
t0UI shows the raw value of the new key once. Copy it to your secret manager immediately.
t0 → t0+24hBoth keys accepted. Deploy the new key across all your services during this window.
t0+24hOld key rejects with auth_key_expired (HTTP 401). Grace ends.

If you rotate with a 1h or 7d grace, the t0+24h row shifts to t0+1h or t0+7d accordingly.

You cannot re-rotate a key that is already in its grace window — that returns 404 ("not eligible for rotation"); rotate the current primary key instead. A predecessor already in grace stays active until its own grace_ends_at passes; rotating again does not deactivate it early. There is no per-window rotation rate limit (24h is the default grace period, not a cooldown), though each mode has a cap on the number of simultaneously-active keys (fresh + in-grace) — exceeding it returns 409.

Compromise — skip the grace​

If a key is exposed (leaked to a public repo, screenshot, shoulder-surf, etc.), do not initiate a normal rotation. Grace would keep the compromised key working for the duration of the grace window.

Instead, from /dashboard/developers/api-keys:

  1. Click Revoke on the compromised key (not Rotate). It is refused with no grace window.
  2. Create a fresh key.
  3. Move your deployed services to the fresh key.

A revoked key (one with no rotation metadata) rejects with auth_invalid_key. A key that simply ran out its rotation grace rejects with auth_key_expired.

Rotation-badge states (dashboard)​

Each key in /dashboard/developers/api-keys carries a badge: Active (the current primary), Grace: ends in <N>h (previous primary, accepted until grace_ends_at), Revoked (auth_invalid_key from now on) or Expired (grace passed — auth_key_expired). When a service starts failing authentication after a rotation, the badge on the key it holds says which.

Expiry behavior​

API keys do not have a baked-in TTL — they stay Active until rotated or revoked. The only paths to expiry are:

  • Normal rotation → previous key enters its grace window → rejects with auth_key_expired once grace_ends_at passes.
  • Revoke → immediate rejection with auth_invalid_key.
  • Merchant account suspension → all keys for that merchant immediately reject with auth_merchant_inactive (HTTP 401). This is an account-level state (the merchant account is suspended or no longer approved for the mode), separate from per-key rotation/revocation.
  • Revocation by Von Payments — e.g. in response to a breach report. Shows the same Revoked badge.

A freshly-rotated key needs no further activation step.