Skip to main content

Sandbox testing

The sandbox at https://sandbox-api.nas.cards has simulators that stand in for the outside world: a merchant, and a KYC reviewer. They exist only in the sandbox. A simulator call to production is refused.

All simulators are in the Testing group of the reference.

SimulatorUse it to
Simulate card authorizationMake a merchant ask the card to authorise a purchase.
Simulate card refundRefund an earlier purchase.
Simulate card reversalCancel a purchase before it clears.
Simulate KYC reviewPass or fail a KYC review.

Simulate a purchase​

curl -X POST "https://sandbox-api.nas.cards/open-api/v3/vcc/simulate/auth" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"cardId": "<card-id>", "amount": "5", "merchantName": "Example Store", "mcc": "5999"}'
Response POST /open-api/v3/vcc/simulate/auth
{ "reasonCode": "APPROVE", "responseCode": "APPROVE" }
  • amount is in US dollars, as text.
  • merchantName and mcc are optional. Use them to test merchant controls. See Cards.
  • The answer is the authorisation result. It does not use the standard envelope.
  • The card needs enough balance. See Wallets and funding.

The purchase appears in List card transactions as a consumption transaction (type 1), and you receive CARD_TRANSACTION.CREATED.

Simulate a refund​

Pass the card, the amount and the id of the purchase to refund. Take the id from the transaction list.

curl -X POST "https://sandbox-api.nas.cards/open-api/v3/vcc/simulate/refund" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"cardId": "<card-id>", "amount": "5", "relatedTransactionId": "<transaction-id>"}'

A refund is a credit (type 0). The original purchase keeps its status.

Simulate a reversal​

A reversal cancels a purchase that has not yet cleared. It takes the same fields as a refund.

curl -X POST "https://sandbox-api.nas.cards/open-api/v3/vcc/simulate/reversal" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"cardId": "<card-id>", "amount": "5", "relatedTransactionId": "<transaction-id>"}'

A reversal is type 14, and relatedCardTransactionId links it to the purchase. See Transactions.

Simulate a KYC review​

Use Passed for a pass and Canceled for a fail. Add a message to set the reason you will see.

curl -X POST "https://sandbox-api.nas.cards/open-api/v3/vcc/simulate/kyc/review" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"accountId": "<account-id>", "status": "Canceled", "message": "Document is not readable"}'

You can only simulate a review for an account that belongs to your client. Any other account is refused. See KYC.

What to test​

Work through this list before you go live.

  1. Get a token, let it expire or refresh it, and see that your client renews it.
  2. Submit KYC and handle PASSED, and also CANCELED.
  3. Create a cardholder and a card. Repeat the create with the same key, and check you get the same card.
  4. Fund the card and check the balance.
  5. Simulate a purchase, a refund and a reversal. Check each transaction and each event.
  6. Freeze the card, simulate a purchase, and check it is declined.
  7. Answer webhooks slowly or with an error on purpose, and check that your endpoint copes with the retry.
  8. Send a webhook with a wrong signature to your endpoint and check it is refused.
  9. Cause a 429 and check that your client waits for Retry-After.

What the sandbox cannot do​

AreaSandboxNotes
Register a new accountNot available (production only)The sandbox does not register accounts.
Order physical cardsNot available (production only)The fee lookup works. See Physical cards.
Simulated depositsNot availableA deposit needs a real transfer of test funds on a test network. See Wallets and funding.
Real moneyNeverAll funds in the sandbox are test funds.

Look at the test data page for the cases NAS has checked and their outcomes.