Required access
Usecards:read, cards:write, and operations:read. Select a card from GET /api/v1/cards; its id and productId belong to your company and environment.
Quote and submit
CallPOST /api/v1/quotes with:
total into the operation:
POST /api/v1/operations with a unique Idempotency-Key. Reuse that key only for retries of this exact request.
Track completion
Track the operation ID or process its webhook.completed confirms the operation; an accepted request only reserves funds. The resulting card balance can differ from the top-up amount because the card may already have funds or spending activity.
Avoid overlapping top-ups on the same card. If an earlier result is unknown, reconcile it first. Never infer success from a timeout, and never turn manual_review into a fresh top-up.
Pricing changes and failures
QUOTE_CHANGED means the submitted total no longer matches current pricing. Fetch a new quote and obtain your customer’s approval for the new total. INSUFFICIENT_BALANCE means available company funds cannot cover the operation, including fees.
Live top-ups require an enabled live card integration. Sandbox top-ups do not move real money.