Hosts and transport
Auth and Partner calls share
https://imbawallet.com. There is no partner staging URL. Partner calls are POST with a JSON body. Resource ids (card_id, esim_id, purchase_id, ext_id) are fields in that body, not URL segments. There is no /v1 prefix.
- HTTPS only (TLS 1.2+)
Content-Type: application/jsonfor bodiesAuthorization: Bearer <access_token>on Partner endpoints
Amounts and time
Identity and correlation
There is no
request_id in Partner API responses. Correlate request and response in your own logs; IMBA does the same on its side.
There is no separate “end-customer id” in the API. Correlate your users with ext_id, card_id, holder fields, etc. on your side.
Isolation
- You only see your own funds, documents, cards, eSIMs, and gift purchases
- Another tenant’s resource →
404(no existence leak) - Missing scope →
403 - Wallet end-user tokens are rejected
Versioning
The API evolves per capability, not as a single global rewrite.- Prefer additive changes and dual-read inputs (old and new formats both work).
- If a breaking change to a method is unavoidable, the version is signaled in a request header or body (same URL); IMBA serves the matching contract. Path schemes like
/v1→/v2are not used for piecemeal evolution. - Deprecated behavior stays available until a documented sunset when applicable.
Bulk (quantity / batch)
- On
POST /api/partner/card_issue,/api/partner/esim_purchase,/api/partner/gift_purchase: optionalquantity(1..20). Same body repeated;ext_idbecomesext_id,ext_id#2, … Response202includesitems[](best-effort per item). - Mixed cart:
POST /api/partner/batchwithitems: [{ "op", "body" }](op=gift_purchase|esim_purchase|card_issue|card_topup|card_freeze|card_unfreeze|withdraw_create). Max 20 items.
Async pattern
Compatibility entry pointscards, card_issue_one, esim_purchase_one, and gift_purchase_one remain available. Prefer card_list and the main create methods shown in the guides. The _one methods create one item; they do not interpret quantity as a bulk request.
KYT uses a separate pattern: kyt_check returns 200 even when the screening is still processing. Poll kyt_check_get; see KYT.
Most money and product creates return 202 (or idempotent 200/202 on replay). Track progress with:
- Webhooks (terminal statuses)
POST /api/partner/document_getwithext_id- Product calls (
card_get,esim_get,gift_get)
Lookup vs endpoints that do not exist (v1)
Not in v1 (do not call these — they are not Partner paths):
/quote, /availability, purchase refund/cancel, card unload, card replacement, network token vaults. Details: FAQ.