Skip to main content
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

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.

​
Card statuses

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.

​
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 a 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 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 overview if you haven’t onboarded the user yet.
1

Create a card

Call Create a 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.
2

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

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

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, either by entering the card details manually or, if you build it, with a one-tap button in your app. See Digital Wallets for both methods and how card verification works.