Card Operations

Concepts behind issuing, recharging, and managing cards — including the asynchronous operation pattern used by createCard and rechargeCard. For full parameter and response details, see the Card section of the API Reference.

Why Card Operations Are Async

Issuing or funding a card involves downstream processing that doesn't complete instantly. Rather than holding your request open, createCard and rechargeCard return immediately with an operation ID and a status. You then poll a separate endpoint to find out when — and how — the operation finished.

The Pattern

1. Kick off the operation — call createCard (with a productId) or rechargeCard (with a cardId and amount). The response is a CardOperation object with an operation ID and status.
2. Check the status — if it's PROCESSING, the operation hasn't finished. Call getCardOperationStatus with the operation ID.
3. Poll until terminal — keep checking, with a delay between attempts, until the status is no longer PROCESSING. See the Card Reference for the full list of terminal statuses and what each means.

Implementation Notes

• Don't assume success from a 200 alone — that means the operation was accepted, not completed. Always check the status field.
• Use backoff when polling rather than a tight loop.
• Persist the operation ID so you can resume checking status after a client-side restart or timeout.
• Design for idempotency on your side — retrying createCard/rechargeCard after a network error, without knowing if the original request landed, risks a duplicate operation.

Other Card Endpoints

Once a card exists, the rest of the Card API is synchronous:

• getProducts — available card products (needed to choose a productId for createCard)
• getStatuses — possible card statuses
• getCards — list cards, optionally filtered by status
• getCardTransactions — paginated transaction history, filterable by cardId
• getCardInfo — details for a specific card
• getCardSensitive — sensitive card details (avoid logging this; limit how long it's held in memory)
• remarkCard — attach or update a label on a card