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. Test-mode keys (vp_sk_test_*, vp_pk_test_*) only hit the sandbox; live-mode keys (vp_sk_live_*) only hit production. They are hard-segregated — a test key cannot accidentally charge a real card.

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.