Cards

You order a card by sending the cardholder's printed name and contact details. The card is created at the card processor, stored against your account, billed for its first month straight away, and returned in full. Card issuance draws on a finite lifetime allowance, so send an Idempotency-Key on every call.

• The card is created with a zero balance. Fund it with a separate top-up.
• card_holder_name takes letters, digits, äöüÄÖÜ, space, and / - ^ . ' ), 26 characters at most. Send the name as the user wrote it: O'Brien works as is, José converts to Jose automatically, Müller keeps its umlaut. Only ß, Ø, Æ and non-Latin scripts are rejected; send an ASCII form for those.
• This is where 3-D Secure codes are sent, so collect a real, reachable number. It can be changed later with PUT /cards/{id}/phone if the cardholder switches SIM.

Returns the cards your account owns, ordered by creation time with the newest first. Closed cards are left out, so a card disappears from this list once you close it. Page through the results with limit and offset.

• Closed cards are excluded from this list. Read one back by id to see its final state.
• count is the number of rows on this page, not a total. Keep paging while count equals your limit, and stop when it comes back smaller.
• limit and offset are clamped, never rejected. Asking for limit=500 returns 100 rows and a 200.

Returns a single card you own, together with the balance read from the card processor at the moment of the call. The card object is the same shape as a list row, and this operation also serves cards you have closed. When the balance read fails you still get 200, with balance_usd set to null.

• The balance is read from the card processor on every call, so each request costs a round trip. Poll it deliberately rather than on every page render.
• A failed balance read returns null, never 0, and the rest of the card still comes back. Treat null as unknown and retry. Zero is a real answer.
• balance_usd sits beside card in the envelope, not inside the card object.

Answers instantly for any number of cards because it reads from our balance model rather than calling the card processor per card. Omit card_ids to page through your whole fleet, or send up to 1000 specific ids. Every row carries as_of, the moment that balance was last read from the processor: the model is written through whenever a balance is fetched and refreshed continuously in the background, stalest first. Send refresh true with at most 25 ids to force live processor reads for cards where the display must be exact right now.

• Reads come from our balance model, so fleet-wide calls are instant at any size. as_of on each row is when that balance was last read from the processor; recently active cards are freshest because every money movement writes through.
• refresh: true is for the handful of cards where a display must be exact right now. It is capped at 25 because each one is a live processor call.
• For live tracking prefer the event stream. Every top-up, unload and transaction carries its amount, so polling this in a loop is the slow way to learn what you were already told.

You move money from your prepaid float onto one of your cards, one dollar for one dollar. The debit is written to your ledger before the card processor is called, so any failure after that point says something about money that has already left your float. The Idempotency-Key you send is the only way to find out which outcome you got, so send one on every call.

• amount_usd must be a JSON number with at most two decimal places. More precision is rejected with 400 rather than rounded, because rounding would move money you did not ask to move.
• There is no per-call maximum. The binding figure is float.available_usd, and exceeding it returns 402 rather than clamping.
• Your balance is debited before the card processor is called, so any failure after validation concerns money that has already left it. A definite rejection is refunded automatically. A timeout is not, and is reconciled by hand.

The inverse of topup: takes amount_usd off the card and returns it to your balance, one dollar for one dollar, without closing the card. The order of operations is reversed from topup because the risk is reversed. A durable intent row is written first, then the processor subtracts from the card, then your balance is credited. A failure between the last two steps leaves an intent row that support is alerted on, so the money is reconciled rather than lost.

• No fee in either direction: the load fee was charged once when you funded your balance, and moving money between your balance and your cards is free both ways.
• Emits a card.unloaded webhook once the credit has committed. A replay under the same Idempotency-Key emits nothing.
• Asking for more than the card holds is refused with 402 and nothing moves in either direction.

The card's configured daily, weekly and monthly spending limits, read live from the card processor. null means no limit of that kind is set, in which case only the program-level per-transaction ceiling applies.

• The per-transaction ceiling in the response is program-level and informational. It cannot be changed per card.
• null for a limit means only the per-transaction ceiling applies.

Send any of daily_limit, weekly_limit and monthly_limit. Each is a positive USD amount. Fields you omit keep their current value; removing a limit is not yet supported. The response reads the limits back from the processor, so it shows what actually took effect rather than echoing your input.

• Fields you omit keep their current value. Removing a limit is not yet supported, and zero is refused; freeze the card instead.
• A purchase that breaches a limit is declined at the point of sale and arrives as a card.declined event with decline_reason.code naming which limit.

You block or restore spending on a card without touching its balance. Freezing is reversible, the card keeps its number and expiry, and any money already loaded stays on it. A frozen card still attracts the monthly card fee.

• The response returns only card_id and the frozen value you sent. Read the resulting status from GET /cards/{cardId}.
• Freezing leaves the balance on the card and does not stop the monthly fee. Only closing does.
• A successful freeze or unfreeze emits a card.status_changed event with reason set to partner_freeze or partner_unfreeze, so a webhook-driven card store stays in sync without polling.

Updates the mobile number held on this card. Cardholders change numbers; before this existed the only remedy was closing the card and issuing a new one. 3-D Secure codes for purchases do not go to this number: they are delivered to your webhook as card.3ds_challenge events. Keep it current anyway, since the card keeps it on record.

• Applies to cards in sms 3DS mode. On webhook mode the code goes to your endpoint instead, but keep the number current in case you switch back.
• The number is not echoed back. It is cardholder data you just sent us.

Ends a card permanently and returns whatever balance is left on it to your prepaid float. The balance is read and returned before the card is deleted, so a card whose balance cannot be read stays open and you get 503. Closing is irreversible, and it stops the monthly card fee from the following month.

• Closing sweeps the remaining balance back to your account and stops the card permanently. Replaying a close returns 200 with the amount already returned.
• Closing does not return card allowance. Your lifetime cap counts every card you have ever issued.
• The month in which you close is billed in full. There is no proration.

One time 3-D Secure codes for your cards are delivered by webhook only: the code arrives on your registered webhook as a card.3ds_challenge event and you deliver it to the cardholder yourself, by email, in-app message or push. Every card is set to webhook delivery when it is created, so you do not need to call this. A method of sms is refused.

• Webhook delivery of 3DS codes is enabled per program. Contact us to switch it on before you build on it: until it is enabled for your program only sms mode is live, and putting a card in webhook mode early would leave its 3-D Secure purchases unable to complete.
• webhook mode is refused unless you already have an active registered endpoint, and that is checked only at the moment you set it. If your endpoint later goes down, 3-D Secure purchases on this card stop completing.
• The setting lives at the card processor and there is no endpoint that reads it back, so record what you set. sms sends the code to the number the card was ordered with; update it with PUT /cards/{id}/phone if it changes.