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.
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
- TypeScript
- Python
- Java
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>"}'
// Node.js 22 or later. Save as token.ts and run it with: npx tsx token.ts
// Call 1: ask for a one-time code.
const authorize = await fetch(
`https://sandbox-api.nas.cards/open-api/v3/oauth/authorize?clientId=${process.env.CLIENT_ID}`,
);
console.log(await authorize.text());
// Call 2: exchange the code for a token.
const token = await fetch('https://sandbox-api.nas.cards/open-api/v3/oauth/access-token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ clientId: '<client-id>', code: '<code-from-the-first-call>' }),
});
console.log(await token.text());
# Python 3 with requests installed. Save as token.py and run it with: python token.py
import os
import requests
# Call 1: ask for a one-time code.
authorize = requests.get(
"https://sandbox-api.nas.cards/open-api/v3/oauth/authorize",
params={"clientId": os.environ["CLIENT_ID"]},
)
print(authorize.text)
# Call 2: exchange the code for a token.
token = requests.post(
"https://sandbox-api.nas.cards/open-api/v3/oauth/access-token",
headers={"Content-Type": "application/json"},
json={"clientId": "<client-id>", "code": "<code-from-the-first-call>"},
)
print(token.text)
// Java 17 or later. Save as Token.java and run it with: java Token.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Token {
public static void main(String[] args) throws Exception {
HttpClient http = HttpClient.newHttpClient();
// Call 1: ask for a one-time code.
HttpRequest authorize = HttpRequest.newBuilder(URI.create(
"https://sandbox-api.nas.cards/open-api/v3/oauth/authorize?clientId=" + System.getenv("CLIENT_ID")))
.GET()
.build();
System.out.println(http.send(authorize, HttpResponse.BodyHandlers.ofString()).body());
// Call 2: exchange the code for a token.
HttpRequest token = HttpRequest.newBuilder(URI.create(
"https://sandbox-api.nas.cards/open-api/v3/oauth/access-token"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("""
{"clientId": "<client-id>", "code": "<code-from-the-first-call>"}
"""))
.build();
System.out.println(http.send(token, HttpResponse.BodyHandlers.ofString()).body());
}
}
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"
{
"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"
{
"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"
}'
{
"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
- TypeScript
- Python
- Java
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"
}'
// Node.js 22 or later. Save as cardholder.ts and run it with: npx tsx cardholder.ts
const response = await fetch('https://sandbox-api.nas.cards/open-api/v3/cardholders', {
method: 'POST',
headers: {
'x-access-token': process.env.ACCESS_TOKEN!,
'Content-Type': 'application/json',
},
body: JSON.stringify({
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',
}),
});
console.log(await response.text());
# Python 3 with requests installed. Save as cardholder.py and run it with: python cardholder.py
import os
import requests
response = requests.post(
"https://sandbox-api.nas.cards/open-api/v3/cardholders",
headers={
"x-access-token": os.environ["ACCESS_TOKEN"],
"Content-Type": "application/json",
},
json={
"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",
},
)
print(response.text)
// Java 17 or later. Save as Cardholder.java and run it with: java Cardholder.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Cardholder {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder(URI.create(
"https://sandbox-api.nas.cards/open-api/v3/cardholders"))
.header("x-access-token", System.getenv("ACCESS_TOKEN"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("""
{
"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"
}
"""))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
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
- TypeScript
- Python
- Java
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"
}'
// Node.js 22 or later. Save as card.ts and run it with: npx tsx card.ts
const response = await fetch('https://sandbox-api.nas.cards/open-api/v3/prepaid-card', {
method: 'POST',
headers: {
'x-access-token': process.env.ACCESS_TOKEN!,
'Idempotency-Key': '6f0a8b0e-3f6a-4c7e-9a1d-2b5c8d7e9f10',
'Content-Type': 'application/json',
},
body: JSON.stringify({
accountId: '<account-id>',
binId: '<bin-id>',
cardMode: 'VIRTUAL_CARD',
cardholderId: '<cardholder-id>',
referenceId: 'card-0001',
label: 'Quick start card',
}),
});
console.log(await response.text());
# Python 3 with requests installed. Save as card.py and run it with: python card.py
import os
import requests
response = requests.post(
"https://sandbox-api.nas.cards/open-api/v3/prepaid-card",
headers={
"x-access-token": os.environ["ACCESS_TOKEN"],
"Idempotency-Key": "6f0a8b0e-3f6a-4c7e-9a1d-2b5c8d7e9f10",
"Content-Type": "application/json",
},
json={
"accountId": "<account-id>",
"binId": "<bin-id>",
"cardMode": "VIRTUAL_CARD",
"cardholderId": "<cardholder-id>",
"referenceId": "card-0001",
"label": "Quick start card",
},
)
print(response.text)
// Java 17 or later. Save as Card.java and run it with: java Card.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Card {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder(URI.create(
"https://sandbox-api.nas.cards/open-api/v3/prepaid-card"))
.header("x-access-token", System.getenv("ACCESS_TOKEN"))
.header("Idempotency-Key", "6f0a8b0e-3f6a-4c7e-9a1d-2b5c8d7e9f10")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("""
{
"accountId": "<account-id>",
"binId": "<bin-id>",
"cardMode": "VIRTUAL_CARD",
"cardholderId": "<cardholder-id>",
"referenceId": "card-0001",
"label": "Quick start card"
}
"""))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
{
"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"}'
{ "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
| Step | Sandbox | Production |
|---|---|---|
Register a separate account for each customer (POST /open-api/v3/accounts/register) | Not available | Available |
| Order a physical card | Not available | Available |
| Deposits | Test network only. See Wallets and funding. | Real deposits |
Next steps
- NAS API: Authentication, Notifications, Status codes, and Idempotency, pagination and limits.
- Basic concepts: Account hierarchy, Environments and the Glossary.
- Card issuing: Overview, then KYC, Cards, Card details, Physical cards and Transactions.
- Wallets: Wallets and funding.
- Testing: Sandbox testing and Test data.
- Going live: Going live, the checklist for production.