Physical cards
A physical card is a plastic card that is posted to the cardholder. It is created like a virtual card, then shipped, then activated.
You cannot order or ship a physical card in the sandbox. The sandbox answers the fee lookup, but an order is refused. Build and test the ordering flow against the reference and these notes, and run it for the first time in production.
What the sandbox can and cannot do
| Step | Sandbox | Production |
|---|---|---|
| Find a BIN that supports physical cards | Works | Works |
| Look up shipping fees | Works | Works |
| Create a physical card | Production only | Works |
| Order shipping | Production only | Works |
| Read shipping information | Production only | Works |
| Identity check and activation | Production only | Works |
Before you order
- Use a BIN with
supportPhysicalCardset totrue. See Cards. - The cardholder must be fully verified. Physical cards need the complete KYC details. See KYC.
- If you want your own card design, ask NAS. A custom design needs approval and production time that is counted in weeks, and NAS gives you a
physicalCardDesignIdwhen it is ready. Without one, the card is a plain blank card.
Step 1 — Check the fees
Shipping fees depend on the destination zone and on how many cards you send.
curl "https://sandbox-api.nas.cards/open-api/v3/physical-cards/fees?accountId=$ACCOUNT_ID&binId=<bin-id>&toMailCardCount=1" \
-H "x-access-token: $ACCESS_TOKEN"
Add zone (a country code, province or region) to see the fees for one destination. List physical card fees describes the fields.
Step 2 — Create the card
Create the card with cardMode set to PHYSICAL_CARD. Use Create prepaid card or Create budget card, with physicalCardDesignId if NAS gave you one.
curl -X POST "https://sandbox-api.nas.cards/open-api/v3/prepaid-card" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Idempotency-Key: 0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d" \
-H "Content-Type: application/json" \
-d '{
"accountId": "<account-id>",
"binId": "<bin-id>",
"cardMode": "PHYSICAL_CARD",
"cardholderId": "<cardholder-id>",
"referenceId": "plastic-0001"
}'
The card starts as PENDING. It cannot be used online or in a shop until it is activated.
Step 3 — Order shipping
Give the delivery details. All the cards in one order must be on the same BIN.
curl -X POST "https://sandbox-api.nas.cards/open-api/v3/physical-cards/bulk-ship" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"accountId": "<account-id>",
"cardIds": ["<card-id>"],
"firstName": "Alex",
"lastName": "Example",
"email": "alex@example.com",
"phoneCountryCode": "1",
"phoneNumber": "2025550123",
"shippingAddress": {
"addressLine1": "1 Example Street",
"city": "New York",
"state": "NY",
"country": "US",
"postalCode": "10001"
}
}'
The answer holds a taskId. Follow it with Get the progress of a task.
A shipping address in Brazil or Mexico also needs taxId. For Brazil it is an 11-digit CPF number. cardPackage chooses the packing: p_0 for cards only in a tray box, or p_1 for card, carrier and envelope.
Step 4 — Follow the shipment
Read the courier and the tracking number once the card has shipped.
curl "https://sandbox-api.nas.cards/open-api/v3/physical-cards/<card-id>/shipping-info?accountId=$ACCOUNT_ID" \
-H "x-access-token: $ACCESS_TOKEN"
Until the card ships, data is an empty object. You also receive PHYSICAL_CARD.SHIPPING when the shipment status changes.
Step 5 — Check the cardholder and activate
When the card arrives, activate it. What you must do first depends on the type of cardholder.
NAMED_INDIVIDUALcardholder. The cardholder was already verified, so call Activate physical card directly.CORPORATE_MANAGEDcardholder. Verify the person who holds the card first. Either generate an identity link and send it to the cardholder, or confirm their identity by sending images of their ID. You are told the result in aPHYSICAL_CARD.VERIFYevent. Then activate the card.
curl -X POST "https://sandbox-api.nas.cards/open-api/v3/physical-cards/<card-id>/activate" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"accountId": "<account-id>"}'
The card moves to ACTIVE and you receive PHYSICAL_CARD.ACTIVATED. The cardholder can then set a PIN with Update PIN and use the card in a shop and online.
Events
| Event | When |
|---|---|
PHYSICAL_CARD.SHIPPING | The shipment status changed. |
PHYSICAL_CARD.VERIFY | The result of a cardholder identity check. |
PHYSICAL_CARD.ACTIVATED | The card was activated. |
Errors
| Code | HTTP status | What happened |
|---|---|---|
NB40302 | 403 | A card in the order is not yours. |
NB40001 | 400 | The accountId is missing. |
| other | 400 or 403 | A validation message, or a refusal because physical cards are not available for your client. In the sandbox an order is refused. |
See Errors.