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
/availability or /quote. Unknown / foreign card_product → 409 / product_unavailable (no leak of other tenants’ catalogs).
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 sameext_idreturns the storedfaileddocument. - Documents are not deleted on timeout.
- A late provider callback after
faileddoes not issue a second card.
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
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/currencymay benull. - No PAN / CVV /
card_encryptedon the list — use Get card below. next_cursor: null— last page.
Get card (secrets)
card_encrypted). See Card encryption.
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
cards:read. Returns only the structured billing address provided by the issuer for a card owned by your tenant:
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.
card_topup.status_changed or document poll. Card must be active.
Freeze
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.
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
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.
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.