CARDS

Overview

Issue USD virtual cards to your customers, fund them from your business wallet, and manage them through their full lifecycle. Cards are issued by our card partner after a KYC review and activate async

/v1/cards

All Virtual Cards endpoints live under this base path.

Use this section to

Issue a USD virtual card to a customer with an initial prefund
Fund, withdraw from, freeze, unfreeze, or terminate a card
Retrieve full card details securely, and reconcile card spend

Response format

Success

{
  "status": "success",
  "message": "...",
  "data": { }
}

Error

{
  "status": "error",
  "code": "ERROR_CODE",
  "message": "..."
}

Currency

Cards are USD-only. Issuance fees, prefunds, and top-ups are debited from, and withdrawals are credited back to your business USD wallet. Fund the USD wallet before issuing or funding cards.

Customer identity

Cards belong to a customer created via the Customer Enrollment & KYC section. Use that customer's uuid as customer_id.

Card references

Every card has a stable tracking_id (EXTCARD…), use it in every path that takes :tracking_id. A card_id is also returned; it's the reference echoed in card webhook events.

Before you start: KYC

A card can only be issued to a customer who has all approvals:

Required	Notes
A government ID (passport, national ID, or driver's license)	With its document number
Proof of address	Utility bill or bank statement

Submit these through the Customer Enrollment & KYC section, and check the status until they read approved. A customer who already has an approved USD/EUR/GBP virtual account meets this bar.

Note: Document-type KYC is accepted on submission, but our card partner performs the authoritative review at issuance time and can still decline it, surfaced via the Card Issuance Status Update webhook.

The card object

Every card-returning endpoint uses this shape:

{
  "tracking_id": "EXTCARD…",
  "customer_uuid": "…",
  "card_id": "…",
  "label": "John Doe USD Card",
  "brand": "visa",
  "card_type": "virtual",
  "currency": "USD",
  "masked_pan": "539983******1234",
  "last4": "1234",
  "exp_month": "08",
  "exp_year": "2029",
  "cardholder_name": "JOHN DOE",
  "balance": 25.00,
  "status": "active",
  "date_created": "1782947655"
}

Status values:

Status	Meaning
`pending`	Issuance queued
`active`	Live and usable
`frozen`	Temporarily disabled
`terminated`	Permanently closed
`failed`	Issuance declined, any debit auto-refunded

Masked PAN and expiry are populated once the card reaches active.

Typical integration flow

Enroll the customer (if you haven't already) and get their KYC approved.
Issue a card for that customer, and it comes back pending.
Wait for the card-created webhook, the card is now active with its masked PAN and expiry.
Fetch secure card details when you need the full PAN/CVV to display to the customer.
Fund, withdraw, freeze, unfreeze, or terminate as needed.
Spend events arrive as transaction webhooks; reconcile any time via Get Card Transactions.

Questions? Email [email protected]. Also on GitBook.