FAQ

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

Documentation and hosts

Where is the full Partner API documentation?


Guides (this site)	https://api-docs.imbawallet.com
OpenAPI / API reference	API overview
API host	`https://api.imbawallet.com`
Support	support@imbawallet.com

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?

Environment	URL	Notes
Production	`https://api.imbawallet.com`	The Partner API host
Docs	`https://api-docs.imbawallet.com`	This site (not an API)
Sandbox / staging for partners	—	None. There is no partner sandbox

Auth and /partner/… share the same production host. There is no /v1 path prefix. See Conventions.

Catalog, availability, and price

Which catalog endpoints exist?

Catalog	Call	Live debit field
Cards	`GET /partner/card-products`	`issue_fee_usdt` / `issue_topup_usdt` (informative; charge follows the live tariff at issue)
eSIM	`GET /partner/esim-offers`	`price_usdt`
Gift cards	`GET /partner/gift-offers`	`price_usdt`

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 list is availability: if the offer or card_product is in the GET 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 GET 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?

Product	Create
Card	`POST /partner/cards`
eSIM	`POST /partner/esims`
Gift	`POST /partner/gift-cards`
Card top-up	`POST /partner/cards/{card_id}/topups`
eSIM top-up	`POST /partner/esims/{esim_id}/topups`
Mixed cart	`POST /partner/batch`

Creates are async (202). ext_id is required. Insufficient available_balance → 409 / insufficient_balance and no document. How do I check order status?

Webhook *.status_changed (terminal)
GET /partner/documents/{ext_id} (poll every few seconds)
Product GET (/cards/{card_id}, /esims/{esim_id}, /gift-cards/{purchase_id})

How do I look up a transaction or reference?

You have	Call
Your `ext_id`	`GET /partner/documents/{ext_id}`
`card_id`	`GET /partner/cards/{card_id}` or list `GET /partner/cards`
`purchase_id`	`GET /partner/gift-cards/{purchase_id}`
`esim_id`	`GET /partner/esims/{esim_id}`
Settlement USDT lines	`GET /partner/reconciliation`

There is no other universal transaction-search API. Card merchant authorization history is not in Partner API v1. 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.

Case	What happens
Sync refuse (`409` / `422` / `400`)	No document, no debit
Async provider failure	Reserve released; settlement balance restored
Gift delivered (`completed`)	No refund of the code
eSIM provisioning failed	Settlement balance returned
eSIM works / unused	No refund
Card issue failed / `issue_timeout`	No charge (or reserve released)
Card program / BIN discontinued	Bank refund via IMBA ops — not self-serve API
Withdrawal	May reach `failed` or `cancelled`; there is no partner cancel-withdraw call

Chargeback webhooks are not in v1.

Money

Balance? GET /partner/balance?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. GET /partner/deposit-address?currency=USDT&network=TRON 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 /partner/withdrawals. Minimum operational balance?

Rule	Value
Commercial minimum first deposit	1,000 USDT
Minimum monthly volume	None
Technical floor	The account cannot go negative; IMBA does not extend credit

You can call the API with a zero balance; creates that need funds return 409 / 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:

Flow	Expect
Gift / eSIM	Seconds to a few minutes until `completed` (examples often under a minute)
Card issue	Async until `card_issued`; stuck with no progress is closed after about 15 minutes (`issue_timeout`)
USDT deposit	After `confirmations_required` (default 19 TRON blocks)
3-D Secure `card.otp`	Usually sub-second after the acquirer asks; the code lives about 2 minutes
Human support	Usually less than 1 hour

Creates return 202 immediately — do not expect PAN / epin / LPA in that HTTP response. 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.

Product	When	Where
Gift	`completed`	`GET /partner/gift-cards/{purchase_id}` → `receipt.epin`
eSIM	after purchase	`GET /partner/esims/{esim_id}` → `activation.lpa` (`qr_available`)
Card	`card_issued`	`GET /partner/cards/{card_id}` → JWE `card_encrypted` or plaintext `card`
3-D Secure	acquirer ask	webhook `card.otp` only (no GET)

Virtual cards (lifecycle)

Reseller / embedded model (your Telegram bot or site, IMBA fulfills): yes. End users do not register with IMBA Wallet.

Topic	Partner API v1
Create	`POST /partner/cards` → `202`; then webhook / document until `card_issued`
Card id	Hex `card_id` from IMBA. Not a network token (Apple/Google Pay token APIs are not exposed)
PAN / expiry / CVV	`GET /partner/cards/{card_id}` after issue. Decrypt JWE (`number`, `expiration` as `MM/YYYY`, `cvv`). List/webhooks have `number_masked` only
Balance	`GET /partner/cards/{card_id}/balance` (card currency, usually USD) — not your USDT settlement
Top-up	`POST /partner/cards/{card_id}/topups` (`amount_usdt` + `ext_id`); card must be `active`
Status	`issuing` / `active` / `frozen` / `closed` / `failed`. No separate activation step
Freeze	`POST /partner/cards/{card_id}/freeze`
Unfreeze	Not in v1 — contact support
Merchant transaction history	Not in v1
Refund / unload	Not in v1
Replacement	Not in v1 — issue a new card with a new `ext_id`
3-D Secure	Email to `cardholder.email` + webhook `card.otp`. No SMS

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)

Question	Answer
End customer stays in our UI?	Yes. They never log into IMBA Wallet for these products
White-label delivery of QR / codes by IMBA?	No. API returns data to you; you deliver
Russian residents as cardholders?	Yes, if contacts pass issuer rules (not `.ru`, not `+7`)
Russian customers buying travel eSIM via Partner API?	No
Own retail markup?	Yes. You set the price you charge; IMBA debits the agreed B2B catalog / card tariff

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.

Get started

Money

Products

Operations

Documentation and hosts

Catalog, availability, and price

Orders, status, and lookup

Errors, retries, refunds

Money

Virtual cards (lifecycle)

Product policy (onboarding)

​Documentation and hosts

​Catalog, availability, and price

​Orders, status, and lookup

​Errors, retries, refunds

​Money

​Virtual cards (lifecycle)

​Product policy (onboarding)

Documentation and hosts

Catalog, availability, and price

Orders, status, and lookup

Errors, retries, refunds

Money

Virtual cards (lifecycle)

Product policy (onboarding)