Cards

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 GET /partner/cards/{card_id}.

Catalog

GET https://api.imbawallet.com/partner/card-products
Authorization: Bearer <access_token>

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).

{
  "products": [
    {
      "card_product": 12,
      "name": "Partner Virtual USD Card",
      "currency": "USD",
      "issue_fee_usdt": "5.00",
      "issue_topup_usdt": "10.00",
      "status": "active"
    }
  ]
}

Catalog fees are informative. The charge at issue time follows the live tariff for that product. Optional quantity (1..20) on POST /partner/cards issues multiple cards with ext_id, ext_id#2, … Response 202 includes items[]. Mixed cart: POST /partner/batch.

Issue a card

POST https://api.imbawallet.com/partner/cards
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "ext_id": "card-issue-20260710-003",
  "card_product": 12,
  "cardholder": {
    "first_name": "IVAN",
    "middle_name": "IVANOVICH",
    "last_name": "IVANOV",
    "birth_date": "1990-05-17",
    "phone": "+79991234567",
    "email": "ivan@example.com",
    "country": "RU",
    "address": {
      "line1": "Ulitsa Pushkina, d. 1, kv. 12",
      "line2": null,
      "city": "Moskva",
      "region": "Moskva",
      "postal_code": "101000"
    }
  }
}

Field	Required	Notes
`ext_id`	yes	Your order id
`card_product`	yes	From your catalog
`cardholder.*`	yes*	KYC; some fields are product-conditional (`birth_date`, `address`, `middle_name`)

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`

{
  "ext_id": "card-issue-20260710-003",
  "order_id": "019d0127-fd3c-78cc-ac8e-e36927c03535",
  "card_id": null,
  "card_product": 12,
  "status": "accepted",
  "created_at": "2026-07-10T09:25:00.000Z"
}

Issue statuses

`status`	Meaning
`accepted`	Accepted; funds reserved
`card_issuing`	Issuing in progress
`card_issued`	Card ready — fetch secrets via GET
`failed`	Failed; reserve released

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 GET /partner/documents/{ext_id}. 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.

Cardholder reuse: if you previously issued a card for the same email+phone with matching KYC under your tenant, IMBA may reuse that cardholder (anti-fraud). A different person with the same email+phone gets a new cardholder.

List cards

GET https://api.imbawallet.com/partner/cards?limit=50&cursor=12345
Authorization: Bearer <access_token>

Scope: cards:read. Keyset pagination by opaque cursor — no offset, no total / count.

Query	Notes
`limit`	Default `50`, clamp `1..100`
`cursor`	Opaque decimal id from previous `next_cursor`. Foreign / malformed → `400` / `invalid_cursor`

{
  "items": [
    {
      "card_id": "00112233445566778899aabb",
      "ext_id": "card-issue-20260710-003",
      "card_product": 12,
      "issue_status": "card_issued",
      "status": "active",
      "currency": "USD",
      "number_masked": "411111******1111",
      "created_at": "2026-07-10T09:25:00.000Z"
    }
  ],
  "next_cursor": "12345"
}

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)

GET https://api.imbawallet.com/partner/cards/{card_id}
Authorization: Bearer <access_token>

Default mode is JWE (card_encrypted). See Card encryption.

{
  "card_id": "00112233445566778899aabb",
  "ext_id": "card-issue-20260710-003",
  "card_product": 12,
  "issue_status": "card_issued",
  "status": "active",
  "currency": "USD",
  "number_masked": "411111******1111",
  "card_encrypted": "<compact JWE>",
  "card": null,
  "balance": {
    "available": "100.00",
    "pending": "0.00",
    "cached_at": "2026-07-10T09:31:00.000Z"
  },
  "created_at": "2026-07-10T09:25:00.000Z",
  "updated_at": "2026-07-10T09:31:00.000Z"
}

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 GET, 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.

Card balance

GET https://api.imbawallet.com/partner/cards/{card_id}/balance

{
  "card_id": "00112233445566778899aabb",
  "currency": "USD",
  "available": "100.00",
  "pending": "0.00",
  "as_of": "2026-07-10T09:31:00.000Z"
}

Top up

Debit is in USDT from your settlement balance (amount + fee).

POST https://api.imbawallet.com/partner/cards/{card_id}/topups
Content-Type: application/json

{
  "amount_usdt": "250.00",
  "ext_id": "topup-20260710-009"
}

{
  "ext_id": "topup-20260710-009",
  "topup_id": "019d0128-aaaa-7bbb-8ccc-ddddeeeeffff",
  "card_id": "00112233445566778899aabb",
  "amount": "250.00",
  "fee": "1.25",
  "status": "accepted"
}

Terminal result: webhook card_topup.status_changed or document poll. Card must be active.

Freeze

POST https://api.imbawallet.com/partner/cards/{card_id}/freeze
Content-Type: application/json

{
  "ext_id": "freeze-20260710-001",
  "reason": "user_request"
}

Returns 202. Result via webhook card_freeze.status_changed / documents.
Unfreeze is not available in v1 of Partner API (contact support / ops).

Not in v1 (cards)

Capability	Status
Merchant transaction / authorization history	No Partner endpoint. Settlement USDT lines: Reconciliation
Unfreeze	No — support / ops
Refund, unload, or reverse a completed top-up via API	No. Failed issue releases the reserve. BIN/program shutdown is a bank refund via ops
Replace a card (new PAN, same holder)	No — `POST /partner/cards` with a new `ext_id`
Network token / Apple Pay / Google Pay token APIs	No — wallets may still work on the product; Partner API does not return wallet tokens

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

Get started

Money

Products

Operations

Catalog

Issue a card

Response `202`

Issue statuses

Stuck issue → `failed` / `issue_timeout`

List cards

Get card (secrets)

3-D Secure codes

Card balance

Top up

Freeze

Not in v1 (cards)

​Catalog

​Issue a card

​Response 202

​Issue statuses

​Stuck issue → failed / issue_timeout

​List cards

​Get card (secrets)

​3-D Secure codes

​Card balance

​Top up

​Freeze

​Not in v1 (cards)

Catalog

Issue a card

Response `202`

Issue statuses

Stuck issue → `failed` / `issue_timeout`

List cards

Get card (secrets)

3-D Secure codes

Card balance

Top up

Freeze

Not in v1 (cards)