Skip to main content

Quick start

This guide takes you from your credentials to a virtual card with a simulated purchase on it. Every call goes to the sandbox, https://sandbox-api.nas.cards. Nothing here touches production or real money.

Step 1 — Create your account​

NAS sets up your client for you during onboarding and sends you its sandbox client id and the id of your programme account. See Environments for how production access is granted later.

note

In production you register one account for each customer, and each account is verified for one person only. The sandbox does not register accounts, so this guide uses the single account id NAS gave you. Use the same test person's details every time you submit KYC on it.

Some steps cannot be run in the sandbox. The guide marks them production only.

Step 2 — Get your API credentials​

NAS gives you these during onboarding:

  • a sandbox client id;
  • the account id of your programme account;
  • confirmation of the IP addresses your calls will come from. The allow-list is optional in the sandbox, but if NAS registered addresses for you, call from them.

Set the first two in your shell:

export CLIENT_ID="<client-id>"
export ACCOUNT_ID="<account-id>"

Authentication explains how the client id is used to get a token.

Step 3 — Choose an environment​

This guide calls the sandbox, https://sandbox-api.nas.cards. Nothing here touches production or real money. Production uses the same paths on https://api.nas.cards, with its own credentials. See Environments for the full comparison.

Step 4 — Get an access token​

Ask for a one-time code, then exchange it for a token. Authentication explains both calls and how to renew the token.

curl "https://sandbox-api.nas.cards/open-api/v3/oauth/authorize?clientId=$CLIENT_ID"

curl -X POST "https://sandbox-api.nas.cards/open-api/v3/oauth/access-token" \
-H "Content-Type: application/json" \
-d '{"clientId": "<client-id>", "code": "<code-from-the-first-call>"}'

Keep the accessToken from the answer:

export ACCESS_TOKEN="<access-token>"

Step 5 — Make a first call: list card BINs​

A BIN is a card product. You need a BIN id to create a cardholder and a card. This call also proves your token and your account id work.

curl "https://sandbox-api.nas.cards/open-api/v3/card/bins?accountId=$ACCOUNT_ID" \
-H "x-access-token: $ACCESS_TOKEN"
Response GET /open-api/v3/card/bins
{
"code": "000000",
"message": "success",
"data": {
"list": [
{
"id": "1926684703962181633",
"bin": "559666",
"type": 1,
"currencies": ["USD"],
"network": "Master",
"countryRegion": "US",
"verification": { "avs": true, "threeDs": false },
"purchaseLimit": { "day": "1000000", "single": "1000000", "lifetime": "1000000" },
"supportPhysicalCard": false
}
],
"total": 1
}
}

Pick a BIN and note its id. For a virtual card, any BIN works. supportPhysicalCard tells you whether physical cards are available on it.

Step 6 — Upload the customer's ID images​

Verification needs a photo of the ID document and a selfie. Upload each image first. The answer holds a file id for the image.

curl -X POST "https://sandbox-api.nas.cards/open-api/v3/files/upload" \
-H "x-access-token: $ACCESS_TOKEN" \
-F "accountId=$ACCOUNT_ID" \
-F "files=@id-front.jpg"
Response POST /open-api/v3/files/upload
{
"code": "000000",
"message": "success",
"data": [
{ "id": "1234567890", "accountId": "ba0a5c6d-ee96-4c44-82f1-dc306d325d8e", "createTime": "1754994030000" }
]
}

Repeat for the back of the ID and for the selfie. Upload one image per call, because the answer does not say which id belongs to which file. See KYC for file limits and image rules.

Step 7 — Submit KYC​

Submit the customer's details with the file ids from step 6. NAS does not accept verification share tokens from other providers. Send the real data and the real images.

curl -X POST "https://sandbox-api.nas.cards/open-api/v3/accounts/$ACCOUNT_ID/kyc" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"firstName": "Alex",
"lastName": "Example",
"dateOfBirth": "1990-01-01",
"gender": "M",
"nationality": "US",
"nationalId": "X1234567",
"idType": "PASSPORT",
"issueDate": "2020-05-10",
"expiryDate": "2030-05-10",
"address": {
"addressLine1": "1 Example Street",
"city": "New York",
"state": "NY",
"country": "US",
"postalCode": "10001"
},
"idFrontId": "1234567890",
"selfie": "1234567892",
"phoneCountryCode": "1",
"phoneNumber": "2025550123",
"sourceType": "api"
}'
Response POST /open-api/v3/accounts/{accountId}/kyc
{
"code": "000000",
"message": "success",
"data": {
"caseId": "cae9efe2-b577-4632-8c57-8822ddb8542a",
"accountId": "053b4288-7f47-4dc5-bf59-402a5bebf44c",
"createTime": "1755498145103",
"status": "PENDING",
"reason": ""
}
}

In the sandbox, finish the review yourself with the simulator. Use Passed to pass and Canceled to fail.

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": "Passed"}'

Step 8 — Create a cardholder​

curl -X POST "https://sandbox-api.nas.cards/open-api/v3/cardholders" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"accountId": "<account-id>",
"binId": "<bin-id>",
"cardholderTier": "NAMED_INDIVIDUAL",
"cardholderRelationship": "EMPLOYEE",
"firstName": "Alex",
"lastName": "Example",
"email": "alex@example.com",
"dob": "1990-01-01",
"gender": "M",
"nationality": "US",
"nationalId": "X1234567",
"idType": "PASSPORT",
"issueDate": "2020-05-10",
"expiryDate": "2030-05-10",
"address": {
"addressLine1": "1 Example Street",
"city": "New York",
"state": "NY",
"country": "US",
"postalCode": "10001"
},
"idFrontId": "1234567890",
"selfie": "1234567892",
"phoneCountryCode": "1",
"phoneNumber": "2025550123",
"referenceId": "customer-0001"
}'

Keep the cardholder id from the answer. A cardholder starts as PENDING. Read it again, or wait for the CARDHOLDER.UPDATED event, until it is ACTIVE.

Step 9 — Create a virtual card​

Send a unique Idempotency-Key and a unique referenceId. If the call times out, repeat it with the same two values and you get the same card, not a second one.

curl -X POST "https://sandbox-api.nas.cards/open-api/v3/prepaid-card" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Idempotency-Key: 6f0a8b0e-3f6a-4c7e-9a1d-2b5c8d7e9f10" \
-H "Content-Type: application/json" \
-d '{
"accountId": "<account-id>",
"binId": "<bin-id>",
"cardMode": "VIRTUAL_CARD",
"cardholderId": "<cardholder-id>",
"referenceId": "card-0001",
"label": "Quick start card"
}'
Response POST /open-api/v3/prepaid-card
{
"code": "000000",
"message": "success",
"data": {
"id": "d8eda079-6ba7-409e-99c8-ab5f83566fbd",
"accountId": "78ad30f2-5794-47c7-b413-62cc599ab203",
"userName": "Alex Example",
"currency": "USD",
"bin": "411111",
"status": "ACTIVE",
"cardLastFour": "4567",
"label": "Quick start card",
"balanceId": "0d13f168-339b-4b74-a412-07a6ababcd9c",
"cardholderId": "1963922322985988097",
"referenceId": "card-0001",
"createTime": "1710813276127"
}
}

The answer never holds the full card number. You get cardLastFour. To show the full details to the cardholder, see Card details.

Step 10 — Put money on the card​

Move money from your account balance onto the card. Send a unique clientTransactionId.

curl -X POST "https://sandbox-api.nas.cards/open-api/v3/cards/transfer-in" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"accountId": "<account-id>",
"cardId": "<card-id>",
"clientTransactionId": "5b1e3f0c-8d2a-4e7b-9c1f-0a6d4b2e8f31",
"amount": "10"
}'

The transfer needs a balance on your card account. NAS confirms how your card account balance is funded during onboarding. See Wallets and funding for deposits and conversion, and for what the sandbox can and cannot do.

Step 11 — Simulate a purchase and read it back​

The simulator acts as a merchant. It asks the card to authorise a purchase, exactly as a real merchant would.

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"}'
Response POST /open-api/v3/vcc/simulate/auth
{ "reasonCode": "APPROVE", "responseCode": "APPROVE" }

The simulator answers with the authorisation result only. The purchase itself shows up as a transaction and as a webhook event.

Read the transaction​

curl "https://sandbox-api.nas.cards/open-api/v3/cards/transaction-list?accountId=$ACCOUNT_ID&cardId=<card-id>" \
-H "x-access-token: $ACCESS_TOKEN"

You should see a transaction with type 1 (consumption) and status PENDING until it clears. Your webhook URL also receives CARD_TRANSACTION.CREATED. See Transactions and Webhooks.

What is production only​

StepSandboxProduction
Register a separate account for each customer (POST /open-api/v3/accounts/register)Not availableAvailable
Order a physical cardNot availableAvailable
DepositsTest network only. See Wallets and funding.Real deposits

Next steps​