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. |
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. |
Simulating card statuses in sandbox
In sandbox, use Simulate card status to force a card into a status that is otherwise hard to trigger. Reap also emits aCARD_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 and Unfreeze endpoints.
Issue your first card
Before issuing a card, the user must have
application.status: APPROVED and the account must be ACTIVE. See the KYC quickstart if you haven’t onboarded the user yet.Create a card
Call Create a card with the user’s ID, account ID, and
type.VIRTUAL: the card is created withstatus: ACTIVEand 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.
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 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 for the full integration guide.Handle card status changes
Reap sends a
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 cardBLOCKED: Reap blocked the card for risk or compliance reasons. Unblocking requires a support request.EXPIRED: card has reached its expiration date
Set a PIN (optional)
If your card program includes ATM withdrawals or chip-and-PIN transactions, call Update PIN before the cardholder uses the card at a terminal. See Update PIN for PIN requirements.
Adding a card to a mobile wallet
Cardholders can add their card to Apple Pay or Google Pay by entering the card details manually. During this flow, the wallet provider requires the cardholder to verify the card with a one-time passcode. Reap delivers that passcode directly to the cardholder, using theemail and phoneNumber captured when the user was created. Make sure both values are accurate and reachable by the cardholder, otherwise they will not be able to complete verification and the card cannot be added to the wallet.