> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.imbawallet.com/llms.txt > Use this file to discover all available pages before exploring further. # FAQ > Integrator answers for Partner API hosts, catalogs, orders, cards, money, and what v1 does not expose. Short answers for B2B integrators. Endpoint detail lives in the guides and [API overview](/api-reference/overview). This is **Partner API** (`https://api.imbawallet.com`). Prepaid agents are a different product: [Agent API](/agent). ## Documentation and hosts **Where is the full Partner API documentation?** | | | | ----------------------- | ------------------------------------------------------------------ | | Guides (this site) | [https://api-docs.imbawallet.com](https://api-docs.imbawallet.com) | | OpenAPI / API reference | [API overview](/api-reference/overview) | | API host | `https://api.imbawallet.com` | | Support | [support@imbawallet.com](mailto:support@imbawallet.com) | Access is [manual onboarding](/guides/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](/guides/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](/guides/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](/guides/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?** 1. Webhook `*.status_changed` (terminal) 2. `GET /partner/documents/{ext_id}` (poll every few seconds) 3. 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](/guides/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](/guides/money-and-idempotency). ## Errors, retries, refunds **Error format?** `{ "error": "", "message": "…" }`. No `request_id`. See [Errors](/guides/errors). **Timeouts and retries?** See [Rate limits](/guides/rate-limits#timeouts-and-retries). 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](/guides/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](/guides/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.