Skip to main content

Sandbox & Test Mode

Every Von Payments account has a sandbox environment with its own API keys, merchant data, and payment routing. Mode is decided by your key prefix, on every request: test-mode keys (vp_sk_test_*, vp_pk_test_*) run in test mode; live-mode keys (vp_sk_live_*) run in live mode. A single account holds both and flips per request.

A test key never moves real money — but what it actually talks to depends on your setup, and the two paths behave differently.

Your setupA test charge goes toWhat decides the outcome
Sandbox account (what Activate VORA Sandbox creates — the default)A Von-owned emulator. No payment processor is contacted at all.The session amount, or the test card number — see below
Boarded onto a real processor's sandboxThat processor's sandbox environment, using its sandbox credentialsThe processor

On the second path the credentials are selected by your key's mode with no fallback — if the sandbox credentials are missing, the request fails rather than reaching the live account.

This distinction matters more than it looks: the two paths do not honour the same test card numbers. See Test cards before assuming a card behaves the same way on both.

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 in 3 steps​

  1. Land on vonpay.com/developers and click Get sandbox keys — or, if you're already signed in, deep-link straight to app.vonpay.com/dashboard/developers. OTP sign-in (any email), no ops-side approval queue.
  2. Click Activate VORA Sandbox on the developer dashboard. This atomically creates a sandbox merchant record, attaches a mock gateway config (so sessions route immediately without boarding a real processor), and issues your test keys (vp_sk_test_*, vp_pk_test_*, ss_test_*). Grab them at /dashboard/developers/api-keys.
  3. Trigger the outcome you need by setting the session amount: 200 in minor units for a declined charge, any other amount for approved. See the table below.

No approval queue for sandbox — you can be creating test sessions within a minute of sign-up. Live keys are separate and require merchant application approval; see API Keys → Self-service vs. gated issuance.

Test-mode behavior​

  • Test transactions never touch a real processor. The mock gateway produces synthetic session payloads with deterministic outcomes (see table below).
  • Webhooks still fire. Point them at webhook.site (easiest — no local setup) or ngrok for a tunnel into your dev machine. Sandbox webhook delivery is enabled by default.
  • 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.

Sandbox outcomes — deterministic by amount​

Session amount (in minor units — cents, pence, etc.) picks the outcome.

AmountOutcomeWhat your integration should handle
200Declined — charge.failed webhook with data.failure_code: card_declined; session status → failed; signed redirect URL carries status=failedRendering the decline path in your UI; reading failure_code from the webhook payload
Any otherApproved — charge.succeeded webhook; session status → succeeded; signed redirect URL carries status=succeededThe happy path

Need to exercise 3DS, issuer-specific declines, timeouts, or other edge cases? Board a real-processor sandbox account onto your merchant — it ships a full test-card catalog without touching real funds. The checkout-local sandbox deliberately keeps one decline trigger; richer decline simulation belongs with the real processor's sandbox.

Two sandbox surfaces

The amount-based outcomes above apply to the hosted Checkout sandbox (vora-hosted.js). The Embedded Fields sandbox (vora.js) is keyed to the test card number instead, and exercises the specific declines, 3DS, and the capture / void / refund lifecycle — see Test cards.

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 environment: boarding a separate sandbox merchant record (one per environment) keeps webhook noise cleanly segregated. Dashboard → "Create sandbox" per environment.
  • CI integration tests: call the API with a test-mode key, assert on the deterministic mock outcomes, purge session IDs after the run (or rely on the nightly cleanup).
  • Want real cards on a real processor? Any sandbox merchant can be re-boarded onto a real-processor sandbox. You'll get real tokenization without real funds movement.

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.