Skip to main content

Sandbox & Test Mode

Mode is decided by your key prefix, on every request: a test-mode key (vp_sk_test_*, vp_pk_test_*) never moves real money. Test payments run on a sandbox account, against its processor's test environment, and that environment decides the outcome: Test mode. A test key on a live merchant account, or on a sandbox with no processor attached, is refused with sandbox_account_required.

Mode is not the same thing as which host you call, and your key does not select a host — see Which environment am I talking to? below.

Start a sandbox integration​

A test sandbox belongs to a business, so you set up the business first. Nothing has to be approved before you can test.

  1. Sign up from vonpay.com/developers (Get sandbox keys), or go straight to app.vonpay.com/merchant/developers if you already have a login.
  2. Start your application at app.vonpay.com/merchant/apply. Starting it sets up your business. Approval is needed for live keys, not for the sandbox.
  3. Click Activate Evaluation Sandbox in Developer Tools. You get test keys straight away (the secret key is shown once), and the sandbox is set up with its own processor test account for test payments. If that account cannot be set up at the time, you still get your keys, and Developer Tools says test payments are not ready yet; until they are, a test payment is refused with sandbox_account_required.
  4. Create a session or a payment intent with a test key and pay with a sandbox test card, at a total from Test mode to test a decline.

Each business has one test sandbox, and only an admin of the business can create it; activating again takes you back to the one you have. If you have no business yet, activating is refused with 409 sandbox_needs_a_business, and Developer Tools points you to the application instead. Live keys are created on your live business, never on a sandbox, and require merchant application approval; see API Keys → Where keys come from.

Test-mode behavior​

  • Webhooks still fire. Point them at webhook.site (easiest — no local setup) or ngrok for a tunnel into your dev machine.
  • Rate limits apply but are more generous than in production.
  • Data is ephemeral. Test sessions are purged by a nightly retention job. Don't rely on a test session ID surviving past the next day.

Common developer setups​

  • Local dev, no public URL: use ngrok → ngrok http 3000 → paste the forwarding URL as successUrl and as your webhook endpoint in the dashboard.
  • Staging and local development: each business has one test sandbox, so every environment you run shares its test keys and test data. Tell your environments' test orders apart with your own metadata or order references.
  • CI integration tests: call the API with a test-mode key, assert on the outcomes for your account's path, purge session IDs after the run (or rely on the nightly cleanup).

Which environment am I talking to?​

The vora.js script URL is identical in every environment. Two independent things decide where your calls land:

Set byDecides
Modeyour key prefix — _test_ / _live_whether the charge is a test charge or a real one
HostapiBaseUrl on new Vora({ … })which deployment serves the request

apiBaseUrl defaults to the production host (https://checkout.vonpay.com) and is not inferred from your key. Test and live keys are served by the same host — using a test key does not point you somewhere else.

Your server and your browser must name the same host. If they disagree, your server calls succeed and every browser call fails with 401 auth_invalid_key_publishable, because the key was never issued by the host the browser is calling. That asymmetry — server fine, browser 100% failing — is the tell. See the troubleshooting entry.