Skip to main content

Cards

A card belongs to a cardholder and sits on a card BIN. You can issue virtual cards in the sandbox and in production. Physical cards are covered in Physical cards.

Card types​

TypeHolds its own balance?Create with
Prepaid cardYes. You move money onto it and back.Create prepaid card
Budget cardNo. It draws on a shared budget.Create budget card

Both come as VIRTUAL_CARD or PHYSICAL_CARD. A virtual card cannot be turned into a physical card later. Order a physical card separately.

A cardholder holds at most five cards. Active and frozen cards count, whether virtual or physical. Deleting a card frees its place.

Step 1 — Choose a BIN​

A BIN is a card product. It fixes the network, the currency, the checks that apply (address check and 3-D Secure) and whether physical cards are available.

curl "https://sandbox-api.nas.cards/open-api/v3/card/bins?accountId=$ACCOUNT_ID" \
-H "x-access-token: $ACCESS_TOKEN"

Each BIN has a type: 1 for prepaid cards and 0 for budget cards. supportPhysicalCard says whether you can order plastic on it. purchaseLimit shows the limits on spending per day, per purchase and over the card's life.

Two related calls help you plan:

Step 2 — Create a card​

Send an Idempotency-Key header and a referenceId that is unique to the card. See Idempotency, pagination and limits.

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": "Travel 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": "Travel card",
"balanceId": "0d13f168-339b-4b74-a412-07a6ababcd9c",
"cardholderId": "1963922322985988097",
"referenceId": "card-0001",
"createTime": "1710813276127"
}
}

The card is ready to use when status is ACTIVE. For a prepaid card you can send an amount to fund it as you create it, or fund it afterwards with Card transfer in.

To issue many cards in one call, use Batch create prepaid cards. It returns a taskId at once. Follow it with Get the progress of a task until the status is DONE, and read failedNum and failedReason for any that failed.

Card statuses​

StatusMeaning
ACTIVEReady to use.
PENDINGWaiting for activation. Physical cards start here.
FROZENFrozen by you. New authorisations are declined.
CONTROLRestricted by NAS for compliance or risk reasons. Contact NAS.
INACTIVEDeleted or expired. The card is closed.

Find cards​

List cards filters by cardholderId, status, label, budgetId, referenceId and batchNo. It never returns the full card number.

curl "https://sandbox-api.nas.cards/open-api/v3/card-list?accountId=$ACCOUNT_ID&status=ACTIVE&limit=20" \
-H "x-access-token: $ACCESS_TOKEN"

Get card summary returns the status, balance, spending so far and limits of one card.

Freeze and unfreeze​

Freeze a card to stop new authorisations at once. Unfreeze it to use it again. Freeze is the right first response to a lost device or a suspected leak.

curl -X POST "https://sandbox-api.nas.cards/open-api/v3/cards/<card-id>/freeze" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"accountId": "<account-id>"}'

Unfreeze takes the same body.

Spending limits​

Set card velocity controls caps how much a card can spend over a period. Velocity limits fit best on budget cards, where several cards share one pool of money.

transactionLimitsTypeLimit applies to
DAY, WEEK, MONTH, QUARTER, YEARThe current calendar period. It resets at 00:00 (GMT+8), and it is not a rolling window.
TRANSACTIONA single purchase.
LIFETIMEThe whole life of the card.

Only one limit type applies at a time. Setting a new one replaces the old one.

curl -X PUT "https://sandbox-api.nas.cards/open-api/v3/cards/<card-id>/velocity-control" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"accountId": "<account-id>", "transactionLimitsType": "DAY", "amountLimit": "500"}'

What a card can still spend is the limit minus what it has already spent. For a budget card the remaining budget balance also caps it.

Merchant controls​

Spend controls allow or block groups of merchants, either on a single card or on a BIN.

A blocked purchase is declined and shows as a failed transaction.

Set a PIN​

Update PIN sets or changes the PIN of a card. The PIN is six digits.

curl -X PUT "https://sandbox-api.nas.cards/open-api/v3/cards/<card-id>/pin" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"accountId": "<account-id>", "pin": "123456"}'

123456 is an example. Use the PIN your cardholder chose. You can write a PIN and you can never read it back. Do not log it.

Delete a card​

Delete card closes a card for good. Any balance goes back according to your programme rules. A deleted card cannot be restored, and the status becomes INACTIVE.

Events​

EventWhen
CARD.UPDATEDA card changed, for example its status.
CARD.DELETEDA card was deleted.
CARD.SETTING.UPDATED, CARD.SCENE.UPDATEDLimits or merchant controls changed.
CARD.BALANCE.NEGATIVEA card or budget balance went below zero. Move money onto it.
CARD.3DS.OTPA purchase needs a one-time code. See Webhooks.

Errors​

CodeHTTP statusWhat happened
NB40001400The call needs an accountId.
NB40302403The card, cardholder or budget is not yours.
NB40303403This endpoint is not open to your client. Reading a full card number or a PIN is never open.
other400A validation message, for example a cardholder who is not yet ACTIVE, or a card beyond the five-card limit.

See Errors.