Skip to main content

​
Hosts and transport

Auth and Partner paths share the same host. There is no partner staging URL and no /v1 prefix on /partner/….
  • 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 /partner/cards, /partner/esims, /partner/gift-cards: 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 /partner/batch with items: [{ "op", "body" }] (op = gift_purchase | esim_purchase | card_issue | card_topup | card_freeze | withdraw_create). Max 20 items.

​
Async pattern

Most money and product creates return 202 (or idempotent 200/202 on replay). Track progress with:
  1. Webhooks (terminal statuses)
  2. GET /partner/documents/{ext_id}
  3. Product GET endpoints (cards, esims, gift-cards)

​
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 unfreeze, card replacement, card merchant transaction history, network token vaults. Details: FAQ.