Skip to main content

Security

Authentication​

API requests use Bearer token authentication:

Key Types​

Authorization: Bearer vp_sk_live_xxx

Von Payments issues two kinds of API key you authenticate with and two kinds of signing secret you never send in a request. Older accounts may also hold a fifth, legacy key — see the note below the list:

  • Secret key (vp_sk_test_… / vp_sk_live_…) — server-side only, authenticates every API call. A live key presents your provider's production credentials and moves real money.
  • Publishable key (vp_pk_test_… / vp_pk_live_…) — the browser-side counterpart, safe to ship in a bundle.
  • Session signing secret (ss_…) — older accounts only; it is no longer issued, and nothing in the integration asks you for it. In particular it does not confirm a return redirect: the return link carries no signature.
  • Webhook signing secret (whsec_…) — verifies the webhooks we send you. Per endpoint, and not your API key. See Webhook signing secrets.

⚠ Older accounts may also hold a vp_key_… key. It predates the current prefixes and is still accepted — as a full secret key. If you find one in a bundle or a config, treat it as live credentials and rotate it to a vp_sk_ key; do not assume it is inert because it is not in the list above.

Prefixes, which key each route accepts, rotation and expiry: API keys. Mode is decided by the key prefix on every request — one account holds both and flips per request; a test key never moves real money (Test mode). The prefix picks the mode, not the host: the same host serves both, and a browser whose apiBaseUrl names a different host than your server gets 401 auth_invalid_key_publishable on every call (troubleshooting). A compromised secret key is revoked, with no grace window, from the dashboard: Compromise — skip the grace.

Restricted keys​

A restricted key is a secret key that holds only the permissions you choose when you create it, with money limits (a key that can take payments or issue refunds must have one). Use one for a system that needs a small part of the API, such as a reporting job. Permissions, limits and examples: Restricted keys.

Key Rotation​

Secret keys can be rotated without downtime. When a key is rotated, the previous key enters a grace window that is caller-configurable — 1h, 24h or 7d, defaulting to 24h — during which both keys authenticate. After the grace window closes, the previous key returns 401 with code: auth_key_expired — distinct from auth_invalid_key so SDKs can detect rotation and refresh instead of failing the payment.

  • A revoked key (no rotation metadata) returns auth_invalid_key; a key deactivated mid-rotation returns auth_key_expired

Rotate keys via /dashboard/developers/api-keys. The UI shows the new plaintext exactly once — store it immediately.

Client secret​

Each checkout session has its own client secret. The browser sends it to prove that it renders this one checkout. Your server gets it, and your page passes it to vora.js in place of the session id.

  1. Read clientSecret from POST /v1/sessions or GET /v1/sessions/{sessionId}. Only a secret key gets it. A create repeated with the same Idempotency-Key returns the same value. A session created with a publishable key has none, and neither has an older session. Treat clientSecret as optional: when it is absent or null, your page passes the session id instead, as before.
  2. Give it to the one page that renders this checkout.
  3. On that page, pass it to vora.sessions.retrieve() in place of the session id:
const session = await vora.sessions.retrieve(clientSecret); // vp_cs_live_…_secret_…

vora.js sends the client secret only as the X-Vonpay-Client-Secret header, and only to the Von Payments checkout API. It keeps the value in memory and never puts it in a URL. session.id is the session id, never the secret. Use vora.js 1.45.1 or later: an older vora.js puts the value it is given into the URL path, which is refused with 400 client_secret_in_path. If your page pins an older version, upgrade it first. If you call the browser API yourself, send the same header on every call for the session.

vora.js sends a client secret only to https://checkout.vonpay.com. A page with a custom apiBaseUrl cannot send one: retrieve() refuses it with frame_client_secret_invalid. Such a page can pass the session id instead, but only while the session does not require its client secret.

It is a secret. It belongs to one checkout session. Do not log it, do not put it in a link, an email or a URL, and do not keep it after the checkout ends. The server SDKs keep it out of their logs: from 4.3.0 the Node SDK leaves clientSecret out of JSON.stringify() and console.log() (read it as session.clientSecret; logging that value still logs it), and the Python SDK leaves client_secret out of the session's repr(). Older versions log it like any other field. The CLI's --json output shows only the session id part, unless you add --show-secrets (CLI 0.16.0 and later).

Two calls need it whenever the session has one, whatever your account's setting: reading the store order (GET /v1/public/sessions/{sessionId}/mirror-order) and closing a wallet's bank check (POST /v1/public/sessions/{sessionId}/wallet_challenge/cancel). Without it, they answer 401 client_secret_required. The embedded card form needs it too when the session declares a save (setupForFutureUse, storedCredentialUse or mode: "setup") for a buyerId: without it the form is refused with 401 client_secret_required and nothing is charged.

CodeWhereWhat it meansWhat to do
client_secret_invalidAPI, 401The header holds a value that is not this session's client secret. Nothing was done.Read clientSecret again on your server for this session. Never send a guess.
client_secret_requiredAPI, 401This session requires its client secret, and the call did not send it. Nothing was done.Pass the client secret to vora.sessions.retrieve().
client_secret_in_pathAPI, 400A client secret was put in the URL path where the session id belongs. Nothing was done, and the value was not recorded.Use vora.js 1.45.1 or later, or pass the session id.
frame_client_secret_invalidvora.jsThe value passed to retrieve() looks like a client secret but is not a valid one, or apiBaseUrl is not the Von Payments checkout API. Nothing was sent.Pass the clientSecret your server received for this session, unchanged.
frame_client_secret_requiredvora.jsThe checkout answered client_secret_required. Nothing was charged.Pass the client secret to retrieve().
frame_unexpected_redirectvora.jsA call that carried the client secret was answered with a redirect, which the API never sends. vora.js did not follow it.If it was a payment, check its outcome on your server before the buyer tries again. Then check apiBaseUrl and any proxy between the page and the API.

Confirming the return redirect​

The buyer returns to your successUrl with ?session=vp_cs_… whatever the outcome, through their own browser — treat everything on that URL as untrusted, and reaching the page proves nothing. Read the outcome from sessions.get with your secret key and fulfill on the charge.succeeded webhook: Handle the return. Signature checking belongs on webhooks, not on the redirect — a declined payment is signed exactly as validly as an approved one.

PCI Compliance​

Card number, expiry and CVC are entered in a secure iframe hosted by the payment processor and never touch Von Payments' servers or yours, on Hosted Checkout and on Embedded Fields in either mode — your PCI scope stays at SAQ-A.

elements mode puts billing-details fields in YOUR page

The card fields stay in the iframe in both modes, but in elements mode the SDK renders cardholder name, email, the save-card checkbox and (by default) the billing address as ordinary inputs in your own DOM — the cardholder-name input even carries autocomplete="cc-name", so the browser may autofill it from the buyer's saved card. A connection whose capability map declares the address native gets the processor's own address element instead, rendered in its isolated iframe; the capability matrix says which yours declares.

Any other script on that page can read those values. Your SAQ-A eligibility is unchanged, but your page-script hygiene (a tag manager, an analytics vendor, a compromised dependency) is now in scope for buyer identity data. If you cannot vouch for every script on your checkout page, prefer embed mode.

Data Encryption​

DataProtection
Card dataNever stored — entered in processor's iframe
Buyer nameAES-256-GCM encrypted at rest
Buyer emailAES-256-GCM encrypted at rest
API keysSHA-256 hashed in database
Checkout session IDsCryptographically random (vp_cs_<mode>_ + nanoid)

Transport Security​

  • Merchant-supplied URLs (such as successUrl and cancelUrl) must use HTTPS; localhost is exempt at the validation layer so you can test locally
  • Live-mode keys reject localhost/loopback redirect URLs — local redirects are permitted only with test-mode keys
  • HSTS header with 2-year max-age
  • TLS 1.2+ only (per the platform's information security policy)

Security Headers​

The checkout page serves these headers:

HeaderValue
Strict-Transport-Securitymax-age=63072000; includeSubDomains; preload
X-Frame-OptionsDENY
X-Content-Type-Optionsnosniff
Referrer-Policystrict-origin-when-cross-origin
Content-Security-PolicyRestrictive nonce-based policy allowing only required domains

Rate Limiting​

Every endpoint is rate-limited per IP, per API key, or both — buckets, limits and the 429 headers are on Rate Limits.

API Versioning​

The API is versioned by date through the Von-Pay-Version request header — API Versioning.

Webhook Signature Verification​

Webhooks are signed with HMAC-SHA256, keyed with a per-endpoint whsec_* signing secret. The signature ships in the x-vonpay-signature request header with both the timestamp and the HMAC inline:

x-vonpay-signature: t=1714406400,v1=abc123def456...

The exact bytes to sign, the replay window and working verifiers in Node, Python, Go, Ruby and PHP are on Webhook Signature Verification. The platform signs with exactly one secret and sends one v1= entry, so there is no rotation grace window on our side — Rotating a signing secret. Each endpoint's whsec_* is its own secret: not your API key, and not the ss_* session secret.

Reporting Vulnerabilities​

If you discover a security vulnerability, contact security@vonpay.com.