Cards overview

A card is a USD Mastercard your business issues to one of its customers. It carries its own balance, funded from one of your accounts, and it spends at merchants like any other card. Everything here is USD. There is no other card currency, and no physical card.

A business client cannot currently issue a card through this API. A customerId is required, and that customer must be at tier 2 — but every customer is created at tier 1 and nothing raises it. Every issuance attempt ends in 404 card_holder_not_found. The rest of this service is documented as built; read the issuance pages as a specification of intent rather than something you can exercise today.

Two types

	`virtual`	`disposable`
Reusable	Yes	No — moves to `used` after its first payment
Spending controls	Supported	Rejected at creation
Typical use	A subscription card, a team card	A single online purchase

The object

{
  "id": "01K2Z3AB4S5T6V7W8XYZABCDEF",
  "label": "Ada travel card",
  "type": "virtual",
  "brand": "mastercard",
  "currency": "USD",
  "status": "active",
  "maskedPan": "•••• •••• •••• 4242",
  "expiryMonth": 8,
  "expiryYear": 2028,
  "holder": { "type": "customer", "id": "01K2Z3AB4C5D6E7F8G9HJKMNPQ", "name": "Ada Okafor" },
  "balance": "5000",
  "balanceFormatted": "50.00",
  "spendingControls": { "transactionAmountLimit": "2000", "dailyAmountLimit": "5000", "dailyTransactionCount": 10 },
  "operations": []
}

balance is USD minor units as a string — "5000" is $50.00. Cards expire two years after issuance.

Statuses

Status	Can spend	Can fund or withdraw	Terminal
`creating`	No	No	No
`active`	Yes	Yes	No
`frozen`	No	Yes	No
`funding_failed`	No	No	No — retry issuance
`used`	No	No	Yes
`terminating`	No	No	Yes
`terminated`	No	No	Yes
`failed`	No	No	Yes
`fraud`	No	No	Yes

The row worth noticing is frozen: a frozen card refuses merchants but still accepts funding and withdrawal. Freezing is a spending control, not a lock on the money.

Operations and payments

Two different records, easily confused.

	Operation	Payment
What	Something you did to the card	Something the card did at a merchant
Kinds	`issuance`, `funding`, `withdrawal`, `termination`	A purchase, refund, or reversal
Where	`operations` on the card, from `GET /v1/cards/{cardId}`	`GET /v1/cards/{cardId}/transactions`
Statuses	`created`, `submitting`, `pending`, `completed`, `failed`	`pending`, `completed`, `failed`, `reversed`, `refunded`

Operations are how you track your own instructions asynchronously. Payments are the card’s spending history.

The hidden account

Every card gets its own USD balance account, opened by Sakawave and marked invisible. It will never appear in GET /v1/accounts, and you cannot transfer to or from it directly — funding and withdrawal are the only doors. That is why a card balance is read from the card, not from the accounts service.

Events

Event	When
`card.created`	A card was issued
`card.updated`	Its status or controls changed
`card.transaction.created`	A payment was authorised
`card.transaction.completed`	A payment settled
`card.transaction.failed`	A payment failed
`card.transaction.reversed`	An authorisation was reversed

Introduction

What cards are for, and the tier gates in front of them.

Get started

Issue, fund, and read a card.

Setup and configuration

Feature gates, limits, and idempotency.

Card programs and PAN handling

Spending controls, credentials, and what never to store.

Getting Started

Platform Guides

Currencies and countries

Customers

Accounts

Recipients and destinations

Transfers

Cards

Bill payments

eSIM

Tutorials

Webhooks

Two types

The object

Statuses

Operations and payments

The hidden account

Events

Next

Introduction

Get started

Setup and configuration

Card programs and PAN handling

​Two types

​The object

​Statuses

​Operations and payments

​The hidden account

​Events

​Next

Introduction

Get started

Setup and configuration

Card programs and PAN handling

Two types

The object

Statuses

Operations and payments

The hidden account

Events

Next