Skip to main content

Test mode

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

Your keyA request goes toWhat decides the outcome
Test (vp_sk_test_*, vp_pk_test_*)Your sandbox account's processor test environmentThe order total, for declines
Live (vp_sk_live_*, vp_pk_live_*)The processor itself, moving real moneyThe processor. A live key on a sandbox account is refused with auth_key_type_forbidden; it is never simulated.

GET /v1/capabilities reports the connection your account actually runs on. Read it if you are unsure what you are pointed at.

Test cards​

Sandboxes run 3-D Secure on every card payment, so only these cards work. Common test numbers such as 4242 4242 4242 4242 and 4111 1111 1111 1111 are declined. Use expiry 03/30 and CVC 100 (1000 for American Express). If the dashboard shows different test cards for your sandbox, use those.

CardResult
4111 1111 1110 1203 (Visa) / 5200 0000 0000 1203 (Mastercard)Verified with no challenge: approves
4111 1111 1118 1072 (Visa) / 5240 0000 0000 1072 (Mastercard)Challenge: the test page lets you pass or fail it

A card payment can pause while the buyer completes the bank check, so always send a return URL. See 3-D Secure.

Testing a decline​

With one of the cards above, the processor's test environment decides a decline by the order total, and an ordinary total such as 25.00 approves. To test a decline, set the total, including shipping and tax, to this one:

Order totalamountResultdecline_codeaction
2,000.12200012Declined by the card's bankdo_not_honorhard

decline_code is the field on the payment intent; the charge.failed webhook carries the same value as failure_code.

Because the total decides the outcome, the same totals work on hosted checkout and on Embedded Fields.

Rules in every test mode​

  • A test key never reaches a live processor account. The credentials resolved for a test key are that processor's sandbox credentials, and there is no fallback to live ones: a missing sandbox configuration throws rather than reaching the live account.
  • Mode is a property of the key, not the host. Test and live keys are served by the same host. See Which environment am I talking to?.
  • Test and live objects never mix. A vp_pmt_test_* token used with a live key is rejected with 400 payment_method_mode_mismatch. (Not payment_method_inactive, which is 422 and means the token was revoked.)

Webhooks in test mode​

Test mode fires the same events as live, from the same place: your processor's notification arrives and we emit. Nothing about the event set or its payloads changes with the key's mode. Every event and its payload is on Webhook events.