Card Issuance
Card Issuance
The complete lifecycle of virtual and physical cards: products and BINs, issuance, top-ups, withdrawals, spending controls, secure card details, closure and replacement.
Guides
Card Issuance OverviewIssue cards upstream using members' L1 profiles, fund them from asset balances, and enable worldwide spending.Card Products and BINsCard products determine the BIN, currency, form factor, and maximum limits. Available products depend on merchant authorization.Issue CardsApply, review, then issue. Physical cards also require binding and activation; activation is irreversible.Card Top-ups and WithdrawalsCard top-ups are asynchronous in two stages. A successful order does not mean the funds have reached the card.Spending ControlsLimits, merchant/MCC lists, and billing addresses provide three kinds of control. Allowlists and blocklists cannot be switched in place.Freeze, Report Lost, and Close CardsFreezing and unfreezing have separate transitional states. Closure is irreversible; `POST /close` returns the remaining balance.View Card CredentialsAfter ownership verification, card number, CVV, and expiry are returned in plaintext. We ensure these details are not stored in our databases or logs.ChargebacksChargeback penalties are a risk-control measure between you and your members. We monitor your overall chargeback rate.State Machines and ValuesApplication, card, shipping, and supplementary-document states advance independently. This page lists all four state axes.
Webhook
Card Issuance ResultsEmitted when issuance succeeds, execution fails, the cardholder is approved or a physical card becomes ready to bind. Cardholder approval or readiness to bind does not mean the card is ready to use.3DS Verification CodesEmitted when the issuing provider sends us a 3DS / OTP verification code callback.Card Status ChangesEmitted when a card is frozen, unfrozen, reported lost or closed.Card Top-Up CreditedEmitted when the top-up funds **actually reach the card**, not when the order is accepted.Card Withdrawal CreditedEmitted when card funds have been returned to the member wallet and ledger settlement is complete.Card Transaction UpdatesEmitted after a transaction callback, automatic reconciliation or query-based backfill is processed, with the public transaction and card IDs and their actual status.Merchant Funding LevelsLow-balance alerts, top-up and withdrawal suspension, and recovery notifications after replenishment.
API Reference · 42 endpoints
Card Products Products
GET
/v1/cards/products
Available card products (filtered by the merchant's authorized BINs)
GET
/v1/cards/products/{id}/quote
Card issuance invoice: pricing and eligibility for this product and member
Card Applications Applications
POST
/v1/cards/applications
Submit a card application (virtual or physical, selected by form_factor)
Moves funds
GET
/v1/cards/applications/{id}
Application status
GET
/v1/cards/applications/{id}/recovery
Query a failed application's reason, refund, and separate KYC review progress
POST
/v1/cards/applications/{id}/recovery
Submit corrected KYC directly, independently of the old application and refund
GET
/v1/cards/applications/{id}/cancel-preview
Cancellation preview (eligibility and refund amount)
POST
/v1/cards/applications/{id}/cancel
Cancel an application (the only self-service way to stop further loss)
Moves funds
POST
/v1/cards/applications/{id}/supplement-sessions
Document supplements: obtain a hosted-screen link for the end user
GET
/v1/cards/applications/{id}/shipment
Physical card shipping (one of four independent status axes)
Cards Cards
GET
/v1/cards
Card list (first four and last four digits; never full card numbers)
GET
/v1/cards/{id}
Card details (first four and last four digits; never the full card number)
PATCH
/v1/cards/{id}
Change a card nickname
GET
/v1/cards/{id}/transactions
Card transactions (cursor pagination)
Card Funding Funding
POST
/v1/cards/{id}/topup-quotes
Estimate a card top-up (no upstream call)
POST
/v1/cards/{id}/topups
Top up a card (two asynchronous stages; the webhook confirms credit)
Moves funds
POST
/v1/cards/{id}/withdrawals
Transfer funds from a card to the wallet (not an on-chain withdrawal)
Moves funds
Spending Controls Controls
POST
/v1/cards/{id}/freeze
Freeze a card (transitional state: freezing)
POST
/v1/cards/{id}/unfreeze
Unfreeze a card (transitional state: unfreezing; separate endpoint from freezing)
PATCH
/v1/cards/{id}/limits
Set user-defined limits (0 means unset; the product maximum applies)
GET
/v1/cards/{id}/merchant-rules
Read the card's merchant / MCC list
PUT
/v1/cards/{id}/merchant-rules
Replace the entire merchant / MCC list (either an allowlist or a blocklist)
DELETE
/v1/cards/{id}/merchant-rules
Clear the card's list (restore unrestricted use)
PATCH
/v1/cards/{id}/billing-address
Change the billing address (used for AVS checks by US online merchants)
Lifecycle Lifecycle
GET
/v1/cards/{id}/replacement
Replacement progress or replacement quote (mutually exclusive sections)
POST
/v1/cards/{id}/lost
Report a lost / stolen card (irreversible; physical cards only)
GET
/v1/cards/{id}/close-check
Card closure precheck
POST
/v1/cards/{id}/close
Close a card (irreversible; we return the remaining balance)
POST
/v1/cards/{id}/replacements
Request a card replacement (no direct balance transfer between old and new cards)
Physical Cards Physical Cards
POST
/v1/cards/bind
Bind a physical card (three card details; no step-up authentication)
POST
/v1/cards/{id}/activate
Activate a physical card (irreversible; call directly after your own user verification)
POST
/v1/cards/{id}/pin
Change / reset a PIN (use the CVV branch if the old PIN is forgotten)
Shipping Addresses Shipping Addresses
GET
/v1/shipping-addresses
Shipping address book
POST
/v1/shipping-addresses
Add a shipping address
GET
/v1/shipping-addresses/{id}
Get an address
PATCH
/v1/shipping-addresses/{id}
Update an address
DELETE
/v1/shipping-addresses/{id}
Delete an address
POST
/v1/shipping-addresses/{id}/default
Set the default address
Secure Card Details Secure Details
POST
/v1/cards/{id}/secure-session
Retrieve the card number, CVV, and expiry date in real time
POST
/v1/cards/{id}/cvv/unblock
Unblock CVV