Panel — Cards
- Base path
/api/panel/v1/wallet/cards (+ /card-events)- Identity
- Panel session (JWT). The issuer webhook endpoints under
/card-eventspass an additional issuer signature check — on top of the panel session, not instead of it. - Authorization
- RBAC permission:
wallet:card:read·wallet:card:operate·wallet:card:authorize - Cross-surface
- The endpoints on this page have NO equivalent in the s2s API; you cannot call them from your own panel. These capabilities exist only in the merchant panel, behind a panel session.
Issuing virtual or physical cards linked to a wallet balance.
Card lifecycle, authorization processing, limit reservation and settlement flows are built. Running in production requires an issuer-processor connection and a BIN allocation.
This category mints real card numbers (PANs); with no connected issuer no card is ever produced — the system does not silently fall back to a simulator, the request is rejected. Status: Roadmap.
Issuing a card
POST /api/panel/v1/wallet/cards| Field | Required | Description |
|---|---|---|
programId | ✅ | |
endUserId | ✅ | Cardholder |
sourceWalletAccountId | ✅ | Account the card spends from |
currency | ✅ | |
cardType | — | Virtual / physical |
cardholderNameRef | — | Reference for the name on the card |
spendLimitScheme | — | Card-specific spend limit scheme |
Lifecycle
Because a card is bound to a wallet account, it spends the balance directly: a card purchase debits the linked account.
| Action | What it does |
|---|---|
| Freeze / unfreeze | Temporarily makes the card unusable |
| Cancel | Permanently closes the card |
| Reissue | Produces a new card and closes the old one |
Authorization and settlement
When an authorization arrives, the amount is blocked on the wallet account; on capture the block is committed, on reversal it is released.
Limit reservation at authorization time is fail-closed: if the limit service cannot answer within a short deadline the authorization is declined. This is deliberate — it prevents spending with no funds behind it.
On partial capture the limit counter charges the captured amount; the difference is returned to the amount counter. See Limits.
Expired authorizations are released automatically and the block lifts.
Issuer events
Events from the card issuer (authorization, capture, reversal) arrive on a signed webhook surface and are reflected onto card state.
Go-live prerequisites
Card issuing is the wallet capability with the most external dependencies:
- Issuer-processor agreement
- BIN allocation
- Card production and distribution process (for physical cards)
- PCI and compliance sign-off
- Card spend limit schemes
- Lost/stolen card operational process
- Settlement and chargeback processes
Once these are in place, the issuer and BIN sponsor are declared in the sponsor policy (Panel — Programs), and this section activates.