Skip to main content

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.

Production only

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​

StepSandboxProduction
Find a BIN that supports physical cardsWorksWorks
Look up shipping feesWorksWorks
Create a physical cardProduction onlyWorks
Order shippingProduction onlyWorks
Read shipping informationProduction onlyWorks
Identity check and activationProduction onlyWorks

Before you order​

  • Use a BIN with supportPhysicalCard set to true. 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 physicalCardDesignId when 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_INDIVIDUAL cardholder. The cardholder was already verified, so call Activate physical card directly.
  • CORPORATE_MANAGED cardholder. 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 a PHYSICAL_CARD.VERIFY event. 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​

EventWhen
PHYSICAL_CARD.SHIPPINGThe shipment status changed.
PHYSICAL_CARD.VERIFYThe result of a cardholder identity check.
PHYSICAL_CARD.ACTIVATEDThe card was activated.

Errors​

CodeHTTP statusWhat happened
NB40302403A card in the order is not yours.
NB40001400The accountId is missing.
other400 or 403A validation message, or a refusal because physical cards are not available for your client. In the sandbox an order is refused.

See Errors.