Primer Sandbox Processor

Primer provides a Sandbox Processor that can be used in the Sandbox environment to make test payments and validate your integration.

This processor comes with:

  • a set of test card numbers to trigger various scenarios
  • a set of mocked payment methods to create your first payments on the checkout

Keep in mind:

  • For PCI-compliance reasons, only test card numbers are allowed in Sandbox. A payment will fail if a non-test card number is used.
  • No error will be raised in production for using a test card number

Test card payments

For test card payments, you can use the following test cards to simulate scenarios:

Successful authorization

Use the following test cards to simulate a successful authorization.

Card NetworkCard NumberCVVExpiry dateAccount Funding Type
Visa4111 1111 1111 1111
Click to copy
Any 3 digit numberAny future expiry dateDebit
Visa4242 4242 4242 4242
Click to copy
Any 3 digit numberAny future expiry dateCredit
Mastercard5252 5252 5252 5258
Click to copy
Any 3 digit numberAny future expiry dateDebit
Mastercard5555 5555 5555 4444
Click to copy
Any 3 digit numberAny future expiry dateCredit
Visa / Cartes Bancaires4035 5000 0000 0000
Click to copy
Any 3 digit numberAny future expiry date
Mastercard / Cartes Bancaires5132 0000 0000 0000
Click to copy
Any 3 digit numberAny future expiry date
Cartes Bancaires4970 0000 0000 0008
Click to copy
Any 3 digit numberAny future expiry date
Failed and declined authorization

Use the following test cards to simulate a failed or declined authorization.

ScenarioCard NetworkCard Number
Generic declineVisa4000 0000 0000 0002
Click to copy
Generic declineMastercard5100 0000 0000 0008
Click to copy
Generic failVisa4000 0000 0000 0010
Click to copy
Generic failMastercard5100 0000 0000 0016
Click to copy

Test mocked payment methods

The Primer Sandbox Processor bundles a mocked version of PayPal, Sofort and Klarna.

For each of these payment methods, you can trigger the desired outcome of the “Authorization” using the Drop-In Checkout.

Testing PM Cards Web UI

Dummy APM

Third-party processors & payment methods

Some payment methods and processors feature a sandbox/test environment. View the public documentation of these services to learn how to best leverage their environment.

We need to add third-party processor test cards to an allow-list. If you experience any issues using third-party processor test cards, it may be because they are not on this list so please contact us to resolve.

Testing 3D Secure

The Client Session fields customer.billingAddress and customer.emailAddress are required to trigger 3D Secure in Sandbox. Add these fields when you create a Client Session or create a manual Payment.

For testing 3DS, you can use the following test cards to simulate scenarios:

ScenarioCard NetworkCard NumberCVVExpiry dateAmount
Manual Challenge (iOS & Android)Other9120 0000 0000 0006
Click to copy
Any 3 digit numberAny future expiry dateAny
Manual Challenge (Web)Visa4111 1111 1111 1111
Click to copy
Any 3 digit numberAny future expiry dateAny (except ones below)
Frictionless & Successful (Web)Visa4111 1111 1111 1111
Click to copy
Any 3 digit numberAny future expiry date20001
Frictionless & Unsuccessful (Web)Visa4111 1111 1111 1111
Click to copy
Any 3 digit numberAny future expiry date20002
Manual Challenge (Web)Mastercard5252 5252 5252 5258
Click to copy
Any 3 digit numberAny future expiry dateAny (except ones below)
Frictionless & Successful (Web)Mastercard5252 5252 5252 5258
Click to copy
Any 3 digit numberAny future expiry date20001
Frictionless & Unsuccessful (Web)Mastercard5252 5252 5252 5258
Click to copy
Any 3 digit numberAny future expiry date20002

The challenge screen will present options for you to choose your test response.

Web

iOS

Testing fallbacks

To test fallbacks, you need:

  • a test card that will decline or fail with your primary processor under one of the conditions outlined above
  • a fallback processor that will authorize the payment based on the test card used to decline or fail with the first processor

Example fallback configuration

If the fallback processor doesn't accept the test card, the payment will be declined and you'll see both authorization requests declined in the payment details page.

Primer test processor

In sandbox, set the Primer test processor as the primary processor and an alternative processor as the fallback processor, such as Braintree, Stripe or Worldpay.

Failed and declined authorization

Use the following test cards to simulate a failed or declined authorization.

Use any 3-digit CVV and future expiry date to trigger the test scenario.

ScenarioCard NetworkCard Number
Generic declineVisa4000 0000 0000 0002
Click to copy
Generic declineMastercard5100 0000 0000 0008
Click to copy
Generic failVisa4000 0000 0000 0010
Click to copy
Generic failMastercard5100 0000 0000 0016
Click to copy

Using one of Primer's test cards for generic decline and fail authorizations above, the authorization request will decline or fail (depending on the card used) and trigger a fallback. The fallback authorization request should then be sent and be authorized.

Example test fallback with Primer test processor

Other sandbox processors

It's possible to test fallbacks without using the Primer test processor. You will need to review the testing guides for your processors and ensure:

  • you can decline or fail a payment with your primary processor for the conditions outlined above
  • the test card or test scenario can lead to a successful authorization request with your fallback processor

See below for some example processors and how to test fallbacks using them.

Braintree

Braintree enable authorization responses to be determined by the authorization amount. You can test fallbacks using Braintree as your primary processor.

If the amount is set to 3000.00-3000.99, then this will trigger a fallback.

Set Braintree as the primary processor and configure your fallback processor.

Then, create a test payment with the amount set to 3000.00-3000.99 and use any test card from your fallback processor that will result in an authorized payment.

The authorization will decline and trigger a fallback. The fallback request should then be sent and be authorized.

You can test fallbacks with 3DS using Braintree as your primary processor as the authorization response is determined by the amount, not the test card. You will also need a fallback processor, such as the Primer test processor, that will accept Primer's 3DS test card which is required to trigger 3DS in sandbox.

Example test fallback with 3DS

Worldpay

Worldpay enable authorization responses to be determined by the cardholder name. You can test fallbacks using Worldpay as your primary processor.

If the cardholder name is set to "ERROR", then this will trigger a fallback.

Set Worldpay as the primary processor and configure your fallback processor.

Then, create a test payment with the cardholder name set to "ERROR" and use any test card from your fallback processor that will result in an authorized payment.

The authorization will decline and trigger a fallback. The fallback request should then be sent and be authorized.

You can test fallbacks with 3DS using Worldpay as your primary processor as the authorization response is determined by the cardholder name, not the test card. You will also need a fallback processor, such as the Primer test processor, that will accept Primer's 3DS test card which is required to trigger 3DS in sandbox.

Example test fallback with 3DS using Worldpay as primary processor and Nuvei as fallback processor

Stripe

Stripe enable authorization responses to be determined by the card number. You can test fallbacks using Stripe as your primary processor.

If the card number is set to 4000000000000119, then this will trigger a fallback.

Set Stripe as the primary processor and configure your fallback processor.

Then, create a test payment with the card number 4000000000000119 and ensure this card will result in an authorized payment with your fallback processor.

The authorization will decline and trigger a fallback. The fallback request should then be sent and be authorized.

Example test fallback with 3DS using Worldpay as primary processor and Nuvei as fallback processor

You can't test fallbacks with 3DS using Stripe as your primary processor as the authorization response is determined by the card number. This clashes with Primer's 3DS test card which is required to trigger 3DS in sandbox.

Testing fraud checks

To test fraud checks in sandbox, you will need to pass the right data to trigger the specific fraud check outcome you want to test. This will vary per fraud detection provider so ensure you check their documentation and our fraud provider specific documentation on what needs passing.

Testing network tokens

Before testing network tokens in sandbox, make sure your account is fully enrolled to network tokenization.

Speak to your Customer Success Manager or raise a ticket on our JIRA Service Desk.  If you don’t have access, please contact your account administrator for assistance.

Visa's testing environment is frequently reset, which makes testing Visa network tokens extremely unreliable.

As a result, testing Visa network tokenization is not available on Primer sandbox. We encourage you to only test Mastercard network tokenization in sandbox, and to test Visa network tokenization in production.

Provisioning network tokens

On sandbox, Primer attempts to provision a network token whenever a card is added to the vault of a customer ID starting with primer-nt-testing.

The best way to vault a card is to use Universal Checkout. Make sure to call POST/client-session with a customerId and vaultOnSuccess set to true. This automatically vaults the card if the payment is successfully authorized.

This first payment is processed using the raw card data. Once vaulted, it usually takes a few seconds for the network token to be provisioned and available for subsequent payments.

Use the following test cards to simulate scenarios:

ScenarioCard NetworkCard NumberCVVExpiry date
Eligible cardMastercard2222 6904 2006 4590
Click to copy
Any 3 digit numberAny future expiry date
Eligible cardMastercard2222 6904 2006 4574
Click to copy
Any 3 digit numberAny future expiry date
Eligible cardMastercard2222 6904 2006 4590
Click to copy
Any 3 digit numberAny future expiry date
Eligible cardMastercard5120 3501 0006 4594
Click to copy
Any 3 digit numberAny future expiry date
Non-eligible cardMastercard5460 1261 2820 0800
Click to copy
Any 3 digit numberAny future expiry date

To validate that the card was properly network tokenized, call GET/payment-instruments to list the saved payment methods for a specific customerId. The field paymentMethod.isNetworkTokenized is set to true when the network token was successfully provisioned and attached to the vaulted card.

Processing payments with network tokens

When a payment is created with a vaulted card that has been network tokenized, Primer automatically attempts to pass the network token to the processor, if the processor is supported.

You can test this by creating a payment with:

  • the Payments API by following this guide
  • or with the vault section of Universal Checkout, by selecting a vaulted card that was network tokenized

To validate that the payment used a network token, call GET/payments/{paymentId} with the payment ID to retrieve the payment object. The field cardTokenType is set to:

  • NETWORK_TOKEN if the payment was processed with a network token
  • CARD_PAN if the payment was processed with the raw credentials