Cards

What they are

Cards are the funded payment instruments issued to cardholders. Each card has a Card Account that holds balance, status, and display attributes (e.g., last4, expiry). Cards can be created for a cardholder, frozen/unfrozen for risk control, and cancelled if needed.

Lifecycle

1. Create a card for an existing cardholder with an initial amount.

2. Use & manage: check balance, fund/unfund via the Card Account APIs.

3. Control status: freeze/unfreeze for security; cancel to permanently disable.

Key capabilities / endpoints

• POST /card – Create a card

• PUT /card/{cardId}/freeze, PUT /card/{cardId}/unfreeze, DELETE /card/{cardId}/cancel – Status controls

• Accounts:

  • GET /accounts/card-account, GET /accounts/card-account/{cardId}

  • GET /accounts/card-account/{cardId}/balance

  • POST /accounts/card-account/{cardId}/add-funds, POST /accounts/card-account/{cardId}/remove-funds

  • GET /accounts/card-account/{cardId}/transactions

Statuses ACTIVE, FROZEN, CANCELLED, EXPIRED, plus transitional states (PENDING_CARD_STATUS_CHANGE, UNFREEZING, CANCELLING) and outcomes (FAILED, UNKNOWN).

Events Card created/cancelled and freeze/unfreeze requests, as well as account funding/defunding, are emitted as webhook events.