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
| Type | Holds its own balance? | Create with |
|---|---|---|
| Prepaid card | Yes. You move money onto it and back. | Create prepaid card |
| Budget card | No. 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:
- List card BINs under maintenance lists BINs to avoid issuing from for now.
- Get the recommended card BIN shows which BIN does best for some well-known merchants.
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"
}'
{
"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
| Status | Meaning |
|---|---|
ACTIVE | Ready to use. |
PENDING | Waiting for activation. Physical cards start here. |
FROZEN | Frozen by you. New authorisations are declined. |
CONTROL | Restricted by NAS for compliance or risk reasons. Contact NAS. |
INACTIVE | Deleted 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.
transactionLimitsType | Limit applies to |
|---|---|
DAY, WEEK, MONTH, QUARTER, YEAR | The current calendar period. It resets at 00:00 (GMT+8), and it is not a rolling window. |
TRANSACTION | A single purchase. |
LIFETIME | The 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.
- List card transaction scenarios lists the named scenarios (for example specific merchants) you can use.
- Set card transaction scenarios allows or blocks scenarios on one card, with
WHITE_LISTorBLACK_LIST. - Set card BIN spend controls allows or blocks merchant category codes (MCC), scenarios or currencies 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
| Event | When |
|---|---|
CARD.UPDATED | A card changed, for example its status. |
CARD.DELETED | A card was deleted. |
CARD.SETTING.UPDATED, CARD.SCENE.UPDATED | Limits or merchant controls changed. |
CARD.BALANCE.NEGATIVE | A card or budget balance went below zero. Move money onto it. |
CARD.3DS.OTP | A purchase needs a one-time code. See Webhooks. |
Errors
| Code | HTTP status | What happened |
|---|---|---|
NB40001 | 400 | The call needs an accountId. |
NB40302 | 403 | The card, cardholder or budget is not yours. |
NB40303 | 403 | This endpoint is not open to your client. Reading a full card number or a PIN is never open. |
| other | 400 | A validation message, for example a cardholder who is not yet ACTIVE, or a card beyond the five-card limit. |
See Errors.