> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reap.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Physical Card Activation

> Activate a physical card once it reaches the cardholder.

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.

```mermaid theme={null}
stateDiagram-v2
  direction LR
  IN_TRANSIT --> OUT_FOR_DELIVERY
  OUT_FOR_DELIVERY --> DELIVERED
  DELIVERED --> ACTIVATED : activate
  IN_TRANSIT --> ACTIVATED : activate
  OUT_FOR_DELIVERY --> ACTIVATED : activate
  ACTIVATED --> [*]
```

***

## Activation flow

<Steps>
  <Step title="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.
  </Step>

  <Step title="Submit the code">
    Call [Activate physical card](/api-reference/cards/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`.
  </Step>

  <Step title="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](/cards/3d-secure) for the e-commerce flow.
  </Step>
</Steps>

***

## 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.

<Warning>
  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.
</Warning>

Call [Get activation code for a physical card](/api-reference/cards/get-activation-code) 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`.