Skip to main content
Physical cards arrive locked. The cardholder activates the card with a 6-digit code printed on the mailer. After activation the card can be used at physical terminals.

​
When to activate

Activate once the cardholder has the card in hand. The activate endpoint accepts cards in DELIVERED, IN_TRANSIT, or OUT_FOR_DELIVERY status — couriers report delivery on different schedules, and the cardholder often holds the card before our physicalCardStatus updates to DELIVERED. The 6-digit code in the mailer is the security boundary; no one can activate without it. You cannot activate a card that has not been shipped, has been canceled, or is already active.

​
Activation flow

1

Cardholder enters the code

Prompt the cardholder for the 6-digit activation code from the card mailer. Authenticate them in your app first (login, biometric, in-app PIN) so a stolen mailer alone cannot activate a card.
2

Submit the code

Call Activate physical card with the cardId and activationCode. The endpoint requires an Idempotency-Key header, so retries are safe.On success the endpoint returns 204 No Content and the card’s physicalCardStatus flips to ACTIVATED on the next GET /cards/:id.
3

Confirm to the cardholder

The card is ready for physical terminals. ATM withdrawals and contactless payments work immediately. The card’s online (ECOMMERCE) usage is independent of activation, see 3D Secure for the e-commerce flow.

​
Lost activation codes

The mailer carries the only copy of the code the cardholder ever sees. If they lose it, retrieve the same code through the API and forward it via your own secure channel.
The retrieved code is the same dedicated code originally assigned to the card. It does not rotate. Treat it as sensitive: verify the cardholder’s identity yourself before sharing, and deliver it over a channel you control (in-app message, verified email, SMS to a verified phone). Do not store the code in your application logs.
Call Get activation code for a physical card with the cardId. The response is the same 6-digit string the cardholder originally received. Use this endpoint only for lost-code recovery. The standard flow is for the cardholder to read the code off the mailer.

​
Best practices

  • Authenticate the cardholder before activation. The mailer code alone is not strong enough. Combine it with your own login or biometric check.
  • Gate GET /cards/:id/activation-code carefully. This endpoint returns the secret with no cardholder verification on our side. Verify identity through your own channel before calling it, and deliver the code only over channels you control.
  • Retry safely. Activation is naturally idempotent — physicalCardStatus = ACTIVATED is sticky. A retry of a successful activate returns 400 CARD_CANNOT_BE_ACTIVATED with reason: 'ALREADY_ACTIVATED', which is still an unambiguous “card is active” signal. Partners may pass an Idempotency-Key for their own bookkeeping, but it is not required.
  • Treat the code as a secret. Never log activation codes, never expose them in URLs, and never echo them back in error responses.
  • Do not poll for activation. The 204 response is authoritative. The card’s physicalCardStatus flips to ACTIVATED on the next GET /cards/:id.