document:read, or any ops scope that creates documents (cards:issue / cards:read / cards:topup / cards:freeze / withdraw / gift:purchase / esim:* / reconciliation:read).
Every create that uses ext_id can be polled:
List orders
POST /api/partner/document_list requires document:read.
items with ext_id, type, ref_id, status, created_at, and
updated_at, plus next_cursor and as_of. It includes successful, failed,
and pending orders for your tenant across all product programs, even after a
product is disabled. It does not include Wallet referrals or another tenant’s
clients. Product secrets and internal client identifiers are not returned.
Use document_get for a particular order’s details.
Optional from and to accept RFC 3339 or unix seconds and filter order creation
time (from inclusive, to exclusive). The default upper bound is the current
time, returned as as_of. Pass that as_of as to on subsequent pages, along
with the returned next_cursor as cursor. Orders are sorted newest first,
with a stable order for equal timestamps. Status updates do not move an order
between pages. limit is 1–100 (default 50; higher values are capped).
Malformed or foreign cursors return the same 400 invalid_cursor.
Orders, card transactions, KYT checks,
and settlement ledger entries are separate histories.
A card purchase does not create another charge to your settlement balance.
Document types
Document
status moves from processing toward terminal values (done / failed / card_issued / … by type). Operation details live in response (for example card_id, business status, error).
How to check status
- Polling: call this endpoint until
statusis terminal (a few seconds between polls; respect rate limits). - Webhook: on terminal
ext_doc, IMBA sends*.status_changed(at-least-once; idempotent byevent_id). Keep polling as a fallback. - Secrets (PAN/CVV, LPA, gift code) are not required in webhooks or
document_get— use the product GET (/cards/{card_id},/esims/{esim_id},/gift-cards/{purchase_id}).
Stuck card_issue
A card_issue that remains processing with no card / charge progress is closed by IMBA as failed with error=issue_timeout (see Cards). You get a webhook and a terminal document. Funds were not charged. Retry with a new ext_id — the same ext_id replays the stored failed result. Documents are not deleted.
Use documents for in-flight work keyed by your ext_id (this is the order / reference lookup). Card merchant authorizations are a separate list: POST /api/partner/card_transactions. Product secrets stay on the product GET endpoints (step 3 above).