Skip to main content
Vestrapay has two environments, sandbox and live. They share one API design and one set of docs, but they are separate systems. Each has its own dashboard, API host, checkout host, credentials, transactions, webhooks and configuration. Understanding that separation, and which credential belongs to which call, prevents most integration mistakes.

​
Environments

The sandbox moves no money. Use it to build and test everything, including failure paths. Live moves real money and is only available after your business has passed KYB. See Go live. The checkout URL returned by initialise always points at the checkout host of the environment you called, in the form https://checkout.vestrapay.com/<accessCode> on live and https://checkout.sandbox.vestrapay.app/<accessCode> in the sandbox. You never build it yourself.

​
Environment isolation

Everything is scoped to the environment of the credential you authenticate with.
  • A transaction created with a sandbox key cannot be verified with a live key, and the reverse. Verifying the wrong way round returns transaction.not_found.
  • Webhook endpoints are registered per environment. A live endpoint does not receive sandbox events. You must register an endpoint in each environment you use. Payment deliveries are signed with that environment’s secret API key; see Webhooks.
  • Services, splits and payment links are configured per environment. Set them up in the sandbox to rehearse, then repeat them in live. After you go live, open the live dashboard and confirm each one is there.
  • A key used against the wrong host is rejected with invalid_key_environment.
Keep the key and the base URL in the same configuration block, switched together by one setting such as VESTRAPAY_ENV. Two settings that can drift apart is the usual cause of “works in test, fails in live”.

​
Key types

Every environment has a pair of keys. Treat the secret key like a password. Keep it in a secrets manager or environment variable, never in source control, front-end bundles, mobile apps or logs. If a secret key leaks, rotate it immediately.

​
Where to find your keys

  1. Sign in to the dashboard for the environment you need.
  2. Open Settings → Developers.
  3. Copy the key pair. The full secret key is shown only when it is created or rotated. Afterwards the dashboard shows a masked value.
Live keys appear only after KYB approval and live activation. Until then the live pair is empty.

​
Rotating a secret key

Rotate from Settings → Developers. The new secret key is displayed exactly once, so store it before you leave the page. The previous secret key keeps working for a 30-minute grace period, which gives you time to deploy the new value without dropping requests. After the grace period the old key stops working.

​
How to authenticate

The API uses three kinds of credential. Which one applies depends on who is calling. Secret key example:
Authorization: Bearer sk_test_yourkey carries the same value and is equally valid. Send one or the other, not both. Checkout calls use the access code from the initialise response:
The code is also accepted as an access_code query parameter, which is useful for server-sent event connections that cannot set headers.
Merchant session tokens belong to people, not systems. They are the credential behind the dashboard, expire like any login session, and are subject to the signed-in user’s team permissions. Do not embed one in a long-lived service. For collection, use the secret key.

​
Access codes

An access code authorises checkout calls for exactly one payment. It is created by initialise and expires after 60 minutes. When it expires, further checkout calls fail with session.expired and the customer must start again with a fresh initialise.
  • An access code cannot initialise or verify anything, and it cannot touch any other payment.
  • It is safe to hand to your own front end so that it can drive the pay screen. Do not log it or share it publicly while the payment is open.
  • If the customer comes back after 60 minutes, initialise a new payment. Do not try to extend or reuse the old code.

​
Quick reference

API responses explains the matching JSON envelope, and Errors lists what each credential failure looks like.