Skip to main content
Short answers for B2B integrators. Endpoint detail lives in the guides and API overview. This is Partner API (https://imbawallet.com). Prepaid agents are a different product: Agent API.

Documentation and hosts

Where is the full Partner API documentation? Access is manual onboarding after a business review. How do I authenticate? Ed25519 assertion JWT → POST /auth/v1/partner/token → Bearer access token (900 seconds, no refresh). Wallet / client HS256 tokens are rejected. See Authentication. What is the environment structure? Auth is POST /auth/v1/partner/token. Product calls are POST /api/partner/<function> with a JSON body (ids in the body, not in the URL). Same host, no /v1 prefix. See Conventions.

Catalog, availability, and price

Which catalog endpoints exist? Gift/eSIM catalogs are off until IMBA enables them on your tenant (offers: [], purchase → 503 / catalog_disabled). Is there a product availability endpoint? No separate /availability. The catalog call is availability: if the offer or card_product is in the response, you may buy it. Missing / inactive SKU → 422 / unknown_offer or 409 / offer_unavailable / product_unavailable. Stale gift catalog → 503 / catalog_stale (refresh the list, then create with a new ext_id if the previous document is already terminal). Is there a quote endpoint? No POST /quote. The catalog call is the live USDT price you will be charged (after any agreed tenant discount). Do not cache gift/eSIM prices across long windows; respect catalog rate limits.

Orders, status, and lookup

How do I purchase? Creates are async (202). ext_id is required. Insufficient available_balance → 409 / insufficient_balance and no document. How do I check order status?
  1. Webhook *.status_changed (terminal)
  2. POST /api/partner/document_get (poll every few seconds)
  3. Product calls (card_get, esim_get, gift_get)
How do I look up a transaction or reference? There is no other universal transaction-search API. Card merchant authorizations are POST /api/partner/card_transactions. Reconciliation is your USDT settlement ledger, not the card’s spend feed. Webhooks? HMAC-SHA256 header X-IMBA-Signature over the raw body; at-least-once; idempotent by event_id. Secrets are not in webhooks except card.otp. See Webhooks. Idempotency for purchases? Stable ext_id per partner. Same body → replay 200/202. Different body → 409 / ext_id_conflict. Terminal failed replays the stored failure — retry with a new ext_id. See Money and idempotency.

Errors, retries, refunds

Error format? { "error": "<code>", "message": "…" }. No request_id. See Errors. Timeouts and retries? See Rate limits. Short version: HTTP create timeout 30–60s; retry creates with the same ext_id; 429 exponential backoff; after terminal failed / issue_timeout use a new ext_id. Refund / cancel? There is no Partner refund, void, or cancel-purchase endpoint in v1. Chargeback webhooks are not in v1.

Money

Balance? POST /api/partner/balance with {"currency":"USDT"} — ledger fields ledger_balance, reserved, available_balance, pending_credit. Spend available_balance. See Balance and deposit. USDT settlement / deposit? Only USDT TRC-20. POST /api/partner/deposit_address with currency and network returns a sticky address (same string every time). IMBA deposit fee is 0. Default confirmations: 19. Other tokens/networks do not credit the partner settlement balance. Withdraw: POST /api/partner/withdraw_create. Minimum operational balance? You can call the API with a zero balance; product and money creates that need funds return 409 / insufficient_balance. KYT screening uses 422 insufficient_balance. Keep headroom above in-flight reserved. Rate limits? Defaults: 300 calls / rolling minute; 60 catalog calls / minute; 1000 ms catalog cooldown; 40 open money documents / 24h; 50,000 USDT withdraw / 24h. See Rate limits. Expected fulfillment time? There is no published hard SLA in seconds. Typical: Product and money creates return 202 immediately — do not expect PAN / epin / LPA in that HTTP response. KYT screening returns 200 while processing; poll kyt_check_get. Does the API deliver voucher / card credentials after purchase? Yes, by pull after the order is ready. IMBA does not white-label-deliver to the end user; you show the data in your UI.

Virtual cards (lifecycle)

Reseller / embedded model (your Telegram bot or site, IMBA fulfills): yes. End users do not register with IMBA Wallet. Typical issuer contact rules for B2B cards: no .ru email, no +7 phone (ban_rus products also require Latin names and country ≠ RU). Simplified KYC: email, phone, address; no liveness / passport biometrics. Phone is not used for SMS OTP.

Product policy (onboarding)

Specific commercial figures are a matter of discussion and are written on the tenant. Live debit is always the Partner API price at purchase time.