Skip to main content

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/json for bodies
  • Authorization: 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 → /v2 are 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: optional quantity (1..20). Same body repeated; ext_id becomes ext_id, ext_id#2, … Response 202 includes items[] (best-effort per item).
  • Mixed cart: POST /api/partner/batch with items: [{ "op", "body" }] (op = gift_purchase | esim_purchase | card_issue | card_topup | card_freeze | card_unfreeze | withdraw_create). Max 20 items.

Async pattern

Compatibility entry points cards, 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:
  1. Webhooks (terminal statuses)
  2. POST /api/partner/document_get with ext_id
  3. 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.