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

# Overview

> Issue payment cards to your users.

Cards in Reap API are payment cards you issue to your users. Each card is linked to an account that holds the spending balance.

***

## Card types

| Type       | Description                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| `VIRTUAL`  | Digital-only card. Ready to use immediately after creation.                                                  |
| `PHYSICAL` | Mailed to the cardholder's address. Usable digitally right away; activate the physical card when it arrives. |

<Note>
  You choose `type` once, at creation, and it is fixed. A `PHYSICAL` card is a single card that works digitally right away, exactly like a virtual card, and can additionally be shipped as plastic. You do not create a separate virtual card for it, and there is no separate card ID for its digital and physical forms. Pick `VIRTUAL` for a digital-only card, `PHYSICAL` when the cardholder also needs plastic.
</Note>

***

## Card statuses

| Status    | Meaning                                                                             |
| --------- | ----------------------------------------------------------------------------------- |
| `ACTIVE`  | Card is active and can be used for transactions.                                    |
| `FROZEN`  | Card is temporarily suspended. You or the cardholder can unfreeze it.               |
| `BLOCKED` | Card is blocked by Reap for risk or compliance reasons. Contact support to unblock. |
| `EXPIRED` | Card has reached its expiration date and can no longer be used.                     |

`status` tracks whether the card can be used. It is independent of where a physical card is in production or delivery. A physical card is `ACTIVE` and usable online from creation, while its production and shipping progress is tracked separately on the `physicalCardStatus` field (and through shipment webhooks). So a physical card that is still in transit reports `status: ACTIVE` with a `physicalCardStatus` such as `IN_TRANSIT`. See [Physical Card Shipping](/cards/physical-shipping).

### Simulating card statuses in sandbox

In sandbox, use [Simulate card status](/api-reference/simulation/simulate-card-status) to force a card into a status that is otherwise hard to trigger. Reap also emits a [`CARD_STATUS_UPDATED`](/api-reference/card-status-updated) webhook with the new status.

The main use cases are statuses you cannot reach through standard endpoints:

* `BLOCKED`: simulates a Reap security block (e.g. too many failed PIN attempts). Normally requires real fraud or compliance triggers.
* `EXPIRED`: simulates a card reaching its expiry date without waiting for it.

`FROZEN` and `ACTIVE` are also accepted here, but you can reach those through the standard [Freeze](/api-reference/cards/freeze-card) and [Unfreeze](/api-reference/cards/unfreeze-card) endpoints.

***

## Issue your first card

<Note>
  Before issuing a card, the user must have `application.status: APPROVED` and the account must be `ACTIVE`. See the [KYC overview](/compliance/kyc/overview) if you haven't onboarded the user yet.
</Note>

<Steps>
  <Step title="Create a card">
    Call [Create a card](/api-reference/cards/create-card) with the user's ID, account ID, and `type`.

    * `VIRTUAL`: the card is created with `status: ACTIVE` and is ready to use immediately.
    * `PHYSICAL`: available for digital use immediately. The physical card is mailed to the cardholder and must be activated on arrival.
  </Step>

  <Step title="Display card details">
    The PAN, CVV, and expiry date are never returned by the API. To show them to the cardholder, call [Create reveal session](/api-reference/cards/reveal-card-details) from your backend. It returns a short-lived `revealUrl`. Pass this to your frontend and load it in an `<iframe>` or `WebView`.

    See [Displaying Card Details](/cards/secure-display) for the full integration guide.
  </Step>

  <Step title="Handle card status changes">
    Reap sends a [`CARD_STATUS_UPDATED`](/api-reference/card-status-updated) webhook whenever a card's status changes. Listen for this event to keep your UI and internal records in sync.

    Key statuses to handle:

    * `FROZEN`: cardholder or your app froze the card
    * `BLOCKED`: Reap blocked the card for risk or compliance reasons. Unblocking requires a support request.
    * `EXPIRED`: card has reached its expiration date

    Do not poll for status changes. Webhooks are the source of truth.
  </Step>

  <Step title="Set a PIN (optional)">
    If your card program includes ATM withdrawals or chip-and-PIN transactions, call [Update PIN](/api-reference/cards/update-card-pin) before the cardholder uses the card at a terminal. See [Update PIN](/cards/virtual-cards#update-pin) for PIN requirements.
  </Step>
</Steps>

***

## Adding a card to a mobile wallet

Cardholders can add their card to Apple Pay or Google Pay, either by entering the card details manually or, if you build it, with a one-tap button in your app. See [Digital Wallets](/cards/digital-wallets/overview) for both methods and how card verification works.