Card Operations

Creating a Card

Two prerequisites: your business must have completed KYB verification, and the target cardholder must have kycStatus: ACCEPTED before a card can be issued to them.

POST /cards
{
  "cardholderId": "CH1a2b3c4d5e6f",
  "amount": 100.00,
  "name": "JOHN DOE",        // optional, defaults to cardholder name
  "productId": "MCUSD1"  // optional, defaults to default product
}

Fund

Add money to a card from your business wallet:

POST /cards/{cardId}/fund
{ "amount": 50.00 }

A funding fee (percentage-based) may apply — see Card Fees
Full amount is added to the card balance; fee is debited from your wallet separately
Can fund a frozen card

Unload

Withdraw balance from a card back to your wallet:

POST /cards/{cardId}/unload
{ "amount": 25.00 }

Cannot unload more than the available card balance
An unloading fee may apply based on your pricing

Freeze / Unfreeze

Temporarily disable a card without losing its balance:

POST /cards/{cardId}/freeze    // disable transactions
POST /cards/{cardId}/unfreeze  // re-enable transactions

Frozen cards cannot make purchases but retain their balance
You can still fund or unload a frozen card

Terminate

Permanently close a card:

DELETE /cards/{cardId}
{
  "reason": "Customer requested closure",  // optional
  "reference": "REF123456"                  // optional
}

Balance refund: any remaining card balance is automatically returned to your business wallet on termination — no fee is charged.

{
  "status": true,
  "message": "Card terminated successfully",
  "data": {
    "id": "CRD678E4F2A1B3C9",
    "status": "TERMINATED",
    "reason": "Customer requested closure",
    "refundedBalance": 25.00,
    "terminatedAt": "2026-01-15T10:30:00+00:00",
    "reference": "REF123456"
  }
}

Card cannot be reactivated after termination
Cardholder can still have other active cards
Provide a reason for record-keeping (visible in webhooks and logs)

Replace

Issue a replacement card for a terminated card. The balance is transferred automatically:

POST /cards/{cardId}/replace

If the original product has canIssue: false, the default product is used as a fallback.

Transactions

Transaction Types

Type	Description
`debit`	Purchase or payment (money leaves card)
`credit`	Refund or cashback (money added to card)
`funding`	Card funding operation
`unload`	Card unloading operation

Transaction Statuses

Status	Description
`PENDING`	Authorization hold
`COMPLETED`	Successfully settled
`DECLINED`	Transaction rejected
`REVERSED`	Refunded or reversed

GET /cards/{cardId}/transactions?page=1

Webhook Events

Card Lifecycle

Event	Trigger
`card.created`	New card issued and ready to use
`card.failed`	Card issuance failed; any hold is released
`card.funded`	Funds added
`card.funding_failed`	Funding was rejected; the debited amount is returned
`card.unloaded`	Funds withdrawn
`card.unloading_failed`	Unload was rejected; the card keeps the balance
`card.frozen`	Card frozen
`card.unfrozen`	Card unfrozen
`card.terminated`	Card permanently closed. Delivered twice: `PROCESSING` then `COMPLETED`
`card.termination_refund`	The balance left on a terminated card has been returned
`card.replaced`	Card replaced; the balance moves to the new card
`card.negative_balance`	Card settled below zero and owes a balance

Transaction Events

Event	Trigger
`card.transaction.approved`	Transaction approved
`card.transaction.declined`	Transaction declined
`card.transaction.reversed`	Transaction reversed
`card.transaction.cross_border_fee`	A cross-border fee was charged
`card.transaction.decline_fee_domestic`	A fee was charged for a domestic decline
`card.transaction.decline_fee_international`	A fee was charged for an international decline

Error Codes

Code	Cause	Resolution
`INSUFFICIENT_BALANCE`	Wallet balance too low	Top up business wallet
`INSUFFICIENT_CARD_BALANCE`	Card balance too low	Fund the card
`CARD_NOT_ACTIVE`	Card is frozen, suspended, or terminated	Check status; unfreeze if frozen
`CARD_INACTIVE`	Physical card not yet activated	Activate with activation code
`CARD_SUSPENDED`	System suspension	Fund the card (decline suspension) or contact support
`CARD_TERMINATED`	Card permanently closed	Issue a new card
`CARDHOLDER_INACTIVE`	Cardholder not active	Activate the cardholder first
`BUSINESS_KYB_REQUIRED`	Business verification incomplete	Complete KYB verification
`ALREADY_FROZEN`	Card already frozen	No action needed
`ALREADY_ACTIVE`	Card already active	No action needed
`DECLINE_LIMIT_REACHED`	15 insufficient funds declines	Fund the card to reset and reactivate

Endpoints

POST /cards — Create card
GET /cards — List cards
GET /cards/{id} — Get card details
DELETE /cards/{id} — Terminate card
POST /cards/{id}/fund — Fund card
POST /cards/{id}/unload — Unload card
POST /cards/{id}/freeze — Freeze card
POST /cards/{id}/unfreeze — Unfreeze card
POST /cards/{id}/replace — Replace card
GET /cards/{id}/transactions — Get transactions

Getting Started

Payments

Cardholders

Cards

Card Operations

Card Operations

Creating a Card

Fund

Unload

Freeze / Unfreeze

Terminate

Replace

Transactions

Transaction Types

Transaction Statuses

Webhook Events

Card Lifecycle

Transaction Events

Error Codes

Endpoints

​Card Operations

​Creating a Card

​Fund

​Unload

​Freeze / Unfreeze

​Terminate

​Replace

​Transactions

​Transaction Types

​Transaction Statuses

​Webhook Events

​Card Lifecycle

​Transaction Events

​Error Codes

​Endpoints

Card Operations

Creating a Card

Fund

Unload

Freeze / Unfreeze

Terminate

Replace

Transactions

Transaction Types

Transaction Statuses

Webhook Events

Card Lifecycle

Transaction Events

Error Codes

Endpoints