Card Issuing Flow
End-to-end flow from BIN selection to a fund-ready virtual card.
This guide walks through the full happy-path for provisioning a virtual card. Use it as a checklist when wiring a new integration.
List available BINs
Call GET /card-bins. The response tells you which billing fields each BIN requires (mobile, email, supportPin, requireKycCardholder).
If the BIN requires KYC, create a cardholder
For BINs where requireKycCardholder: true, your end-user must clear KYC first.
- Hosted — call
POST /kyc/cardholders/auto, redirect the user toverificationUrl, then wait for theCARDHOLDER_KYC_STATUSwebhook. - Manual — upload documents via
POST /kyc/presignedUploads, then submit identity viaPOST /kyc/cardholders/manual.
Issuing a card under a non-APPROVED cardholder will fail.
Issue the card
POST /cards with cardBinId, initialAmount, and either name fields or a cardholderId.
The response returns immediately with status: "CREATING"; the card is provisioned asynchronously.
Wait for CARD_CREATED
Listen for the CARD_CREATED webhook. Once received, the card is usable. You can verify with GET /cards/{cardId} — status will be "ENABLE".
(Optional) Reveal sensitive details to the cardholder
GET /cards/{cardId}/sensitive returns the unmasked PAN, CVV, and expiry. This endpoint has stricter rate limits — only call it when the cardholder is actively viewing the card.
Funding & withdrawal
After creation, balance is managed with:
POST /cards/{cardId}/funding— top-up from your walletPOST /cards/{cardId}/withdrawal— pull funds back into your walletGET /wallet/balance— current wallet position
All amounts are integers in cents.
Lifecycle controls
| Action | Endpoint |
|---|---|
| Pause spending | POST /cards/{cardId}/freeze |
| Resume spending | POST /cards/{cardId}/unfreeze |
| Update PIN | POST /cards/{cardId}/pin (only when BIN supports PIN) |
| Update contact | POST /cards/{cardId}/contact |
| Permanently close | DELETE /cards/{cardId} |