Skip to main content
Scopes: cards:issue, cards:read, cards:topup, cards:freeze (or cards:*). Cards are issued for your end customers. You pass KYC in cardholder. One create = one card. Correlate with your ext_id, then card_id. List responses expose only metadata and number_masked. PAN / CVV / card_encrypted are available only on POST /api/partner/card_get.

Catalog

Returns only products enabled for your tenant. This list is availability and the informative USDT quote. There is no separate /availability or /quote. Unknown / foreign card_product → 409 / product_unavailable (no leak of other tenants’ catalogs).
Catalog fees are informative decimal strings from the live catalog. These docs do not publish the amounts. The charge at issue time follows the live tariff for that product. Products hidden from the retail catalog can remain active for an explicitly allowlisted B2B tenant. A fully off product or an inactive issuing program cannot be issued. Check the returned status before ordering. Optional quantity (1..20) on POST /api/partner/card_issue issues multiple cards with ext_id, ext_id#2, … Response 202 includes items[]. Mixed cart: POST /api/partner/batch.

Issue a card

Flat aliases address_line1 / city / region / postal_code on cardholder are accepted and normalized into nested address.*. Prefer nested address. ban_rus products (non-RU risk): phone must not be +7…, country ≠ RU, and names must be Latin. Russian phone/country are rejected for those products.

Response 202

Issue statuses

Other intermediate status strings may appear while the order is open — treat anything other than card_issued / failed as in progress. Prefer webhook card_issue.status_changed and document polling. Synchronous create failures return a JSON error body (error + message) — not an empty HTTP 500. Examples include invalid_customer_data, kyc_rejected, insufficient_balance, product_unavailable, cardholder_create_failed.

Stuck issue → failed / issue_timeout

If a card_issue document stays in processing with no card / charge progress for too long (default about 15 minutes), IMBA closes it as failed with error=issue_timeout (HTTP 504 recorded in the document response). You receive webhook card_issue.status_changed and a terminal POST /api/partner/document_get. Funds were not charged.
  • Retry with a new ext_id. Replaying the same ext_id returns the stored failed document.
  • Documents are not deleted on timeout.
  • A late provider callback after failed does not issue a second card.
One cardholder per new order: every new card issue creates a separate registration, including repeated KYC. Send the customer’s real cardholder.email. If that address is already registered, IMBA may give the issuer a different internal address so the new registration stays unique. The 3-D Secure code is still mailed to the cardholder.email you submitted, and the same code is sent on webhook card.otp. Replaying the same ext_id returns the existing order.

List cards

Scope: cards:read. Keyset pagination by opaque cursor — no offset, no total / count.
  • Stable order: ascending internal link id. Next page: id > cursor.
  • Issuing stub (link exists, card not ready): issue_status=card_issuing; card_id / status / number_masked / currency may be null.
  • No PAN / CVV / card_encrypted on the list — use Get card below.
  • next_cursor: null — last page.

Get card (secrets)

Default mode is JWE (card_encrypted). See Card encryption.
While issuance is in progress, the response can have card_id: null, issue_status: card_issuing, and status: issuing. Track the order with document_get; read the balance separately with card_balance. Card statuses: issuing, active, frozen, closed, failed.
There is no separate activation step after issue.
Do not log PAN/CVV/JWE plaintext.
card_id is IMBA’s hex id. It is not a payment-network token. PAN, expiry (expiration, typically MM/YYYY), and CVV are inside card_encrypted / card after you decrypt — see Card encryption. Only cards linked to your tenant are returned (404 otherwise). Webhooks carry status and ids — fetch secrets via this call, not from webhooks or the list endpoint.

3-D Secure codes

cardholder.email is a working address: the 3-D Secure code for a payment is mailed there. The same code is also delivered to you as webhook card.otp in the otp field, so your support can read it out to the buyer. There is no pull endpoint for the code, and it lives about 2 minutes — handle the webhook immediately.

Billing address only

Requires cards:read. Returns only the structured billing address provided by the issuer for a card owned by your tenant:
Fields may be omitted. Phone, email, name, birth data, cardholder objects, PAN, and CVV are never returned by this method. If the issuer does not supply a structured address, the response is 200 {"billing_address":null}; an address submitted in KYC is not substituted. Unknown or foreign cards return 404. Temporary issuer failure returns 502 billing_address_unavailable.

Card balance

Top up

Debit is in USDT from your settlement balance (amount + fee). amount is what you send. fee is a decimal string from the live tariff. These docs do not publish it.
Terminal result: webhook card_topup.status_changed or document poll. Card must be active.

Freeze

Returns 202. Result via webhook card_freeze.status_changed / documents.

Unfreeze

Same scope as freeze: cards:freeze. You can unfreeze only a card you (or the cardholder) froze. A freeze by IMBA or by the bank stays frozen.
Returns 202. Result via webhook card_unfreeze.status_changed / documents. Replaying the same ext_id and body returns HTTP 202 with the stored body: status moves from processing to active or failed. Do not treat HTTP 202 on a retry as still in progress. The document is done when the card is active. If the issuer already reported the card active, the result is still success. A reported success does not unfreeze the card while it is still frozen. If IMBA or the issuer freezes the card again before the issuer answers, the card stays frozen and the document ends failed with error=unfreeze_not_confirmed (not a second 409). card_id hex is case-insensitive. ext_id is 1..128 characters (400 ext_id_too_long; missing ext_id is 400 ext_id_required). reason is optional, defaults to user_request, and is at most 200 characters (400 reason_too_long). Card numbers in reason are removed and are not returned; if nothing remains, the stored reason is user_request. A body that is not JSON, or is larger than 8 KiB, is 400 invalid_json. Another tenant’s card and an unknown card return the same 404 not_found. An in-flight status change returns 409 order_in_progress. An active card returns 409 card_not_frozen. A closed card returns 400 card_closed. Another tenant’s card returns 404, the same error as an unknown card. A status or freeze_kind field in the body does not change the decision. IMBA checks the freeze again when the unfreeze is sent to the issuer. If IMBA or the issuer froze the card in the meantime, the unfreeze is not sent and the document fails with unfreeze_not_confirmed. A reported success does not clear a card that is still frozen.

Authorizations

Requires cards:read. Only cards owned by your tenant. Another tenant’s card, a retail card, and an unknown card return the same 404 not_found. from / to accept RFC 3339 or unix seconds. status filter is pending, approved, or declined. An item may show unknown for an unrecognized issuer type; filtering by unknown returns 400 invalid_status. limit is 1..100 (default 50). Zero, negative, fractional, and non-numeric values return 400 invalid_limit; values above 100 are capped. Pages are newest first. Pass next_cursor as cursor to read older rows. A foreign or malformed cursor returns 400 invalid_cursor. Non-JSON bodies and bodies above 8 KiB return 400 invalid_json. Amounts are exact signed decimal strings. A missing amount and its currency are omitted. A repeat can fill missing amount, merchant, or fee data without sending another status change. ext_id identifies the card issuance order. Card numbers, CVV, and supplier names are removed from public text. Unsafe raw issuer ids are never exposed: a program may omit an unusable authorization id or return an opaque public transaction id.
History is available for all card programs enabled for B2B. Reading an issued card’s history does not require the product to remain enabled or visible in the catalog. Hexadecimal identifiers keep their case-insensitive behavior; other identifiers are case-sensitive and must be used exactly as returned by the API. For programs that report them, auth_type also includes authorization, authorization_decline, expense, reversal, refund, verification, verification_decline, verification_expense, and maintenance_fee. Authorizations and verifications are pending; declined attempts are declined; completed expenses, refunds, reversals, and maintenance fees are approved. approved describes completion, so use auth_type to distinguish a refund from a purchase. Unknown types remain visible with status=unknown. An optional entry_type distinguishes transaction from fee. A fee entry is an additional fee charged to the card; its amount is that fee. Company-funded provider costs are excluded. fee_amount on a transaction is an attribute of that transaction, not an instruction to create another settlement debit. An optional original_transaction_id links a refund, reversal, or fee to an original event when that event is known. New transaction and fee identifiers and cursors use random UUIDs. Identifiers and cursors are opaque; save them without parsing them. Existing transaction identifiers and cursors keep working. The payload has no PAN, CVV, issuer name, or supplier name. New events also arrive as webhooks card_transaction.created and card_transaction.status_changed. card_transaction.updated reports a transaction type change that keeps the same normalized status. Exact callback repeats do not create another event. Updates keep the original pagination position. History contains events persisted by IMBA from issuer callbacks and supported history synchronization. It does not make a live request for a full issuer archive on every page. If an event has no usable issuer timestamp, receipt time is used (the stored receipt for legacy records). Orders across products are listed by document_list; card transactions and settlement entries are separate histories.

Not in v1 (cards)

Automated delivery of PAN/CVV after card_issued: yes, via this GET (not webhook). You show credentials in your UI. See FAQ.