/v1/customers/{customerId}/accounts/{accountId}/cards….
Every call needs the programId query parameter — ?programId=abc — on top of the
operator’s bearer token. Your operator role bounds which programs you may act on; the
program itself is chosen by the request. The environment comes from your token — an
operator session picks it at sign-in (x-sandbox: true on login), a service user’s
credential is fixed to one — and a sandbox query parameter here is ignored.
These are the
/v1 routes. An older, unprefixed surface
(/customers/{customerId}/accounts/{accountId}/cards…, with GET-based status actions)
still answers, but it is being retired — build against /v1.The lifecycle
1
Issue
POST …/cards.The accepted body depends on the program’s card setup, and the schemas are
strict — an unrecognised field is a 400, not a silent ignore. Two shapes exist:GET …/cards/options lists the products the account can issue. If limitGroupId,
prepaid or forCustomerId come back as a 400, the program’s card setup does not
accept them — do not retry with them.forCustomerId has a second meaning on programs with
cardholders on a corporate: when the customer you name is a
cardholder of the corporate in the path, the card becomes theirs — embossed with
their name and visible only to them (see Issue cards).
For any other customer it keeps the cardholder meaning above; nothing changes for existing
integrations.Send an Idempotency-Key header so a retry can’t issue a second
card — issuing is the one card operation you cannot cheaply undo.{ id, customerId, accountId, cardType, status, provider, nickName }.2
Activate
POST …/cards/{cardId}/activate — some providers want the last
four digits as a truncatedPan query parameter.3
Fund (managed cards only)
POST /v2/…/balance — see Balance below.Idempotency
Two card endpoints accept an idempotency key, and they behave differently — the distinction matters, so don’t assume the second one protects you the way the first does. Send it as theIdempotency-Key header (preferred) or as an idempotencyKey field
in the body. Keys are scoped to the customer, so two customers reusing the same key never
collide.
POST …/cards — full replay protection
The key must be a UUID; anything else is rejected with 400 Idempotency-Key must be a UUID. The card’s id is derived from the key, so:
POST …/balance — replay-safe
Load/unload claims the key before it calls the card provider, so a retry with the same
key returns the original result rather than moving the funds a second time. The key must
be a UUID (a non-UUID is a 400), and it is scoped to the customer the account belongs to.
Failures split on whether the money could possibly have moved:
- Rejected before the provider is called — a validation error, an inactive account, not enough balance. Nothing happened, so the key is released and is immediately reusable: fix the request and retry with the same key.
- Failed in any way we can’t prove happened before that — a timeout, a dropped
connection, a rejection from the provider itself, or any error we don’t recognise. Only
the pre-dispatch rejections above release the key; everything else fails closed. The
outcome is genuinely unknown, so the claim is pinned and every retry under that key
returns
409 IDEMPOTENT_REQUEST_IN_PROGRESS. On this path that is not transient: it persists until the movement is reconciled, or until the key expires — expiry is best-effort and takes at least 48 hours. The two409cases look identical on the wire, so retry with backoff for ~30s and then treat the key as pinned.
Read
All of a program’s card products
GET /v1/cards/options?programId=abc lists every card product configured for the
program, not just the ones a single account can issue. Use it to build a product
picker or a configuration view, then filter on the client.
optionshas one entry per product per tier, region, provider and account type, so the samenamecan appear more than once.filterslists the distinct values of each of those fields, sorted, for building filter controls.provideridentifies the card provider that issues the product. Treat it as an opaque value: filter on it, do not hard-code the set.regionis the region the product applies to (todayUKorEU).tier: "default"is the fallback: an account whose tier has no products of its own is offered thedefaultones.descriptionisnullwhen the product has none.configis the card provider’s configuration for the product: the identifiers a card is issued under whenPOST …/cardsnames this product ascardName(alimitGroupIdon the request takes precedence). A card ordered bycardTypealone uses the program’s default configuration, which can differ. Its keys depend onprovider. Every product from the same provider has the same keys, and a key the product doesn’t set isnull. Values may be strings, numbers or objects (an object maps names to ids), and a key’s type can differ between providers.configitself can benullon any product, so handle that case. Use it for display and support. Don’t build logic on its keys.- On programs with named products,
nameis whatPOST …/cardstakes ascardName. - A program with no card products returns empty
options. A program outside your operator role is a404. Custodian (guardian-bound) roles can’t use this route.
Secure details and PIN
The dedicated reveal endpoints, each separately permissioned:GET …/secure-key— the encryption key for the secure-details response. Note this hangs off the account, not a card.POST …/cards/{cardId}/secure/passkey-challengethenPOST …/cards/{cardId}/secure— the step-up + reveal pair for full card details.GET …/cards/{cardId}/pin— the card PIN.
Status actions
All four arePOST with no body. Each returns the card’s new status.
PIN and limits
-
POST …/cards/{cardId}/pin/reset— body{ "newPin": "1234" }, 4 to 6 digits. -
POST …/cards/{cardId}/pin/unblock— clears a PIN-retry block. -
PATCH …/cards/{cardId}/limits— the fields depend on the program’s card provider: sendlimitGroupId+cardTypeto move the card to an existing limit group, orlimit+type(DAY,WEEK,MONTH,YEAR,LIFETIME) to set an amount directly.
Balance
Only on programs whose card provider holds a separate card balance (the managed / prepaid flow — see Issuing cards for your users). Both operations are account-scoped: they act on the account’s balance at the card provider, which exists from account provisioning and can hold funds with no cards issued. Load/unload has no card id in the path because there is nothing for one to identify.- v2 (recommended)
- v1
POST /v2/customers/{customerId}/accounts/{accountId}/balance— body{ "amount": "100.00", "action": "LOAD" };UNLOADmoves funds back to the account.amountmust be exact in the account’s currency: more decimals than it allows is a400, never rounded. Returnssuccess,availableBalance,transactionId,message, withavailableBalanceas a decimal string ("100.00") in the account’s currency.POST /v2/customers/{customerId}/accounts/{accountId}/cards/{cardId}/balance/sync— re-reads the balance from the provider and reconciles it. Returnssuccess,availableBalance,message, withavailableBalanceas a decimal string.
Shared cards and cardholders
For programs that let a second person hold a card on the account:3DS
GET /v2/customers/{customerId}/3ds— recent 3DS challenges for the customer, withamountas a decimal string and an alpha-3currency./v1/…/3dsstill works unchanged, withamountin the card provider’s own unit.POST …/cards/3ds/confirm— confirm a challenge.