Card issuing APIs look straightforward from the documentation. Create a cardholder, create a card, read transactions. The parts that consume the schedule are rarely the endpoints — they are the timing assumptions, and they surface late.
The core objects
Almost every issuing API models the same four things:
- Cardholder — the person or entity the card belongs to. Carries the KYC state.
- Card — virtual or physical, tied to a cardholder, with its own status and controls.
- Authorisation — a real-time hold when the card is presented. Not yet money moved.
- Transaction — the settled record, which arrives later and may differ from the authorisation.
That last distinction causes more bugs than anything else on this list.
Authorisations are not transactions
An authorisation is a request asking whether a card may be used, right now, for an amount. It may settle for a different amount, or never settle at all.
Concretely:
- A hotel authorises $500, settles $380.
- A fuel pump authorises $1, settles $90.
- A cancelled order authorises, then reverses with no settlement.
If your ledger treats authorisations as spend, balances will be wrong for a subset of users, every day. Track both states and reconcile on settlement.
Design webhook-first
The single biggest architectural difference from a payments API: the interesting events do not happen inside your request/response cycle. Authorisations arrive while a cardholder is standing at a terminal. Settlements arrive hours later. Status changes arrive whenever the issuer decides.
Build for it:
POST /v1/cards → 201, card created
webhook: authorization → arrives seconds to days later
webhook: transaction → arrives after settlement
webhook: card.status → arrives whenever it changes
Three properties your handler needs from day one:
- Idempotency. Webhooks retry. The same event will arrive twice. Key on the event ID and make reprocessing a no-op.
- Ordering tolerance. A settlement can arrive before you finished processing its authorisation. Do not assume sequence.
- Fast acknowledgement. Return 200 immediately and process asynchronously. Slow handlers get retried, which compounds the problem.
Spending controls are policy, not code
Most platforms let you express limits declaratively — per-transaction caps, daily and monthly ceilings, merchant category restrictions, geographic rules. Use them rather than approving in your own logic. They are enforced at authorisation time by the processor, which is faster and does not depend on your service being up.
Reserve custom authorisation logic for genuinely business-specific rules, and understand the latency budget before you take it on: a slow response means a declined card at a checkout.
The edge cases that only appear in production
Every one of these will happen. Decide the policy before launch:
- Partial reversals — authorised $100, settled $60, reversal for the difference.
- Force posts — a transaction settling with no matching authorisation, typically from offline terminals.
- Currency conversion — the settled amount in your currency differs from the amount the cardholder saw.
- Disputes — a chargeback arrives weeks later. Who is liable, and how does your ledger represent it?
- Card replacement — a lost card gets a new number. Wallet tokens, subscriptions and stored credentials all need to follow.
A sane build order
- Sandbox, everything. Never test against real value.
- Cardholder creation and KYC state — the gate on everything downstream.
- Virtual card issuance — fastest path to something real.
- Webhook handling with idempotency, before any traffic.
- Ledger and reconciliation — authorisations and settlements as distinct states.
- Controls and freeze/unfreeze — your support team will need these on day one.
- Physical cards, once the virtual flow is proven.
Two to four weeks is a realistic range for a competent team with clear requirements. Teams that skip step 4 and retrofit it typically lose that time twice over.
Before you start
Ask for sandbox credentials, the webhook event catalogue, the retry policy, and the authorisation timeout budget. Those four answers determine most of your design.
If you want to walk through the integration for your stack, book a technical call.