> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sakawave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cards introduction

> What card issuance is for, the two tier gates in front of it, and why one of them cannot currently be satisfied.

Cards let your customers spend the balance you hold for them, at any merchant that takes Mastercard, in USD. They are the only part of the API where money leaves without you naming a destination — the merchant decides, and you set the boundaries in advance.

## The gates

Two tier checks stand in front of issuance, and they apply to different parties.

| Gate | Who | Requirement | Failure |
| - | - | - | - |
| `card_issuance` feature | Your **business** | Tier 2 | `403` with `reason: feature_not_available` |
| Holder eligibility | The **customer** | Tier 2, individual, with name, email, and phone | `404 card_holder_not_found` |

<Warning>
  The second gate cannot currently be satisfied. Every customer is created at tier 1, and [no endpoint in the API raises a customer's tier](/services/customers/identity-and-verification#tiers). A business client must name a customer as holder, so **every issuance attempt fails**.

  This is recorded as the first open decision for this service. Nothing in your integration will fix it; it needs either a customer verification path or a change to the holder rule.
</Warning>

The rest of this documentation describes the service as built, so that when the gate opens you are not starting from scratch. Read it as a specification.

## What a card is, structurally

A card is a balance plus a set of rules.

* **The balance** lives in a hidden USD account Sakawave opens for the card. You cannot reach it except through funding and withdrawal.
* **The rules** are spending controls — a per-transaction cap, a daily cap, and a daily count — enforced at authorisation.

Funding moves money from your account to that balance. Spending moves it out to merchants. Withdrawal brings it back. Termination sweeps whatever is left.

## Cards are not transfers

They look similar and behave differently in ways worth knowing before you start.

| | Transfer | Card operation |
| - | - | - |
| Destination | You name it | The merchant decides |
| Retry after failure | Needs a **new** reference | The **same** reference re-drives it |
| Currency | Seven fiat, four crypto | USD only |
| Approval policy | Can apply | Does not apply |
| Idempotency scope | Transfers | **All** card operations share one namespace |

The second row is the important one. A transfer that fails keeps its `externalReference` and resending returns the failure; a **card issuance that fails is re-driven** by resending the same reference. The two services have opposite retry semantics.

## Who holds a card

Only a customer, through this API. The service also supports issuing to a dashboard user, and an individual client gets a holder created for it automatically, but neither is reachable from a business client's API key — issuance takes a `customerId` and nothing else.

## The shape of the API

Eleven operations, split into three groups.

**Lifecycle**

| Operation | Notes |
| - | - |
| [`POST /v1/cards`](/api-reference/cards/issue-a-card) | Issue and fund in one call. |
| [`GET /v1/cards`](/api-reference/cards/list-cards) | Page through them. |
| [`GET /v1/cards/{cardId}`](/api-reference/cards/get-a-card) | One card, with its operations. |
| [`POST /v1/cards/{cardId}/terminate`](/api-reference/cards/terminate-a-card) | Irreversible. Sweeps the balance. |

**Money**

| Operation | Notes |
| - | - |
| [`POST /v1/card-fx-quotes`](/api-reference/cards/create-a-card-fx-quote) | Funding or withdrawing on a non-USD account. Issuance quotes for itself. |
| [`POST /v1/cards/{cardId}/fund`](/api-reference/cards/fund-a-card) | Account to card. |
| [`POST /v1/cards/{cardId}/withdraw`](/api-reference/cards/withdraw-from-a-card) | Card to account. |

**Control and visibility**

| Operation | Notes |
| - | - |
| [`POST /v1/cards/{cardId}/freeze`](/api-reference/cards/freeze-a-card) | Stops merchants, not funding. |
| [`POST /v1/cards/{cardId}/unfreeze`](/api-reference/cards/unfreeze-a-card) | Back to active. |
| [`POST /v1/cards/{cardId}/details`](/api-reference/cards/reveal-card-credentials) | The full PAN and CVV. Handle with care. |
| [`GET /v1/cards/{cardId}/transactions`](/api-reference/cards/list-card-transactions) | Spending history. Not paginated. |

There is no endpoint to change a card's label or its spending controls after issuance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.