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 the card’s own state. It does not reflect the state of the account the card is issued on: a restricted account declines every authorization while its cards stay ACTIVE. Read both values when showing a cardholder whether a card can be used.

​
Freeze and block are separate

A freeze and a block are two independent states a card can be in, and a card can be in both at once. status reports the block when both are set, so a frozen card that is then blocked reports BLOCKED, and the boolean frozen field is how you know the freeze is still there. Lifting the block returns that card to FROZEN, not to ACTIVE. Each state is lifted on its own, in any order. Unfreezing a blocked card is allowed and clears the freeze; the card stays BLOCKED and goes to ACTIVE when the block lifts. Expose freeze in your app as a cardholder-facing switch. Reserve block for cases where you want the card stopped and a deliberate decision made before it is used again. Either state stops the card everywhere. A physical card stops working at the terminal and the ATM alongside online payments, and so does the card in any mobile wallet it has been added to.

​
Blocked cards

blockReason.type names the cause and blockLiftable tells you what you can do about it, so you never need to hardcode a list of reasons. When blockLiftable is false, Unblock returns 409 CARD_BLOCK_NOT_LIFTABLE and the block stays in place. Surface that to your support team rather than retrying. Blocking a card that is already blocked never weakens the block: a card blocked by Reap keeps that reason and stays non-liftable even if you call Block on it afterwards. For a card blocked because fraud was confirmed, prefer deleting the card and issuing a new one over unblocking it. The card number is compromised, and unblocking puts the same number back into circulation. status is also 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 block placed by Reap, which in production needs a real fraud or compliance trigger. Defaults to SUSPECTED_FRAUD_PIN, which you can lift. Pass blockReason: OTHER to produce a block you cannot lift and exercise the 409 CARD_BLOCK_NOT_LIFTABLE path.
  • 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, and a CLIENT_REQUESTED block through Block.

​
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.
Pass cardDesignId to pick a design from those assigned to your project (List card designs); omit it to use the project default. The card returns the design it was issued with as cardDesignId.Pass preferredCardName to choose the name printed on the card; omit it and Reap prints the user’s verified name. See Name on the card.
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 Secure Display 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: the cardholder or your app froze the card
  • BLOCKED: read blockReason.type for the cause and blockLiftable for whether you can lift it
  • 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.

​
Name on the card

The name on a card must match the identity the user was verified with. By default Reap prints the user’s verified first and last name, dropping middle names to fit the 27-character limit. The card returns the printed name as cardholderName. To print a different form of the name, such as a shorter one when the full name does not fit, pass preferredCardName to Create a card. Reap compares it with the user’s verified first and last name. Write the first and last name in either order, each in full or as an initial, or give one of them alone. For a user verified as Jane Smith: The rules for the name:
  • Length. At most 27 characters.
  • Characters. Letters (A-Z, a-z), digits, the letters äöüÄÖÜ, spaces, and /, -, ^, ., ', ). Write JOSE, not JOSÉ. A name outside this set returns 422 VALIDATION_FAILED on the request, or 400 PREFERRED_CARD_NAME_INVALID when card issuance rejects it.
  • What the check ignores. Case, punctuation, and a leading title such as MR or DR.
  • What it rejects. A name made only of initials, or only of numbers.
  • How strict it is. The check measures how closely the name resembles the verified name, so a close variant, such as a longer form of the first name or one short extra word, can be accepted. Build the name from the verified first and last name rather than relying on the check to catch every variant.
A name that does not match returns 400 PREFERRED_CARD_NAME_MISMATCH and no card is created. Send the request again with a corrected name, or without preferredCardName to use the default.
preferredCardName is not supported on corporate employee projects, where the card is issued under the employee’s company. Sending it there returns 400 PREFERRED_CARD_NAME_NOT_SUPPORTED.

​
Fraud monitoring

When fraud monitoring flags a transaction, or when a cardholder reports a past transaction as fraud, use Fraud Alerts to confirm or decline. Confirming or reporting blocks the card and emits CARD_STATUS_UPDATED with blockReason.type: FRAUD_ALERT_CONFIRMED.

​
Challenging a charge

Blocking a card stops further damage but does not recover money already spent. To challenge a cleared charge and take it to the card network, file a dispute. This covers unauthorised charges as well as everyday merchant problems such as goods never arriving or a subscription billed after cancellation.

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