imbawallet-com Cards API

openapi: 3.2.0
info:
  title: IMBA Partner Cards API
  version: 1.2.0
  summary: B2B Partner API for USDT settlement, cards, eSIM, gift cards, and KYT
  description: 'B2B Partner API. Production host `https://imbawallet.com` (no sandbox).


    - Human docs: `https://api-docs.imbawallet.com` (guides + FAQ)

    - Authenticate with `POST /auth/v1/partner/token` (assertion JWT), then call

    `POST /api/partner/` with `Authorization: Bearer `

    and a JSON body. Resource ids are body fields, not URL segments.

    - Amounts are decimal strings.

    - Response timestamps are UTC RFC 3339 with `Z`.

    - Request time fields accept RFC 3339 or unix seconds (not milliseconds).

    - Catalog calls (`/api/partner/gift_offers`, `/api/partner/esim_offers`,

    `/api/partner/card_products`) are live availability and the live USDT price.

    There is no `/quote` or `/availability` path.

    - Order lookup: `POST /api/partner/document_get`. Secrets via product calls

    after fulfillment (card JWE, gift `epin`, eSIM LPA) — not in webhooks

    except `card.otp`.

    - Card authorizations: `POST /api/partner/card_transactions`.

    Unfreeze: `POST /api/partner/card_unfreeze` (only a freeze by you or the cardholder).

    - Not in v1: purchase refund/cancel, card unload, card replacement.'
  contact:
    name: IMBA Partner Support
    email: support@imbawallet.com
  license:
    name: Proprietary
    url: https://imbawallet.com
servers:
- url: https://imbawallet.com
  description: Production
tags:
- name: Cards
  description: Card catalog, issue, list, secrets, topup, freeze
paths:
  /api/partner/card_products:
    post:
      operationId: listPartnerCardProducts
      tags:
      - Cards
      summary: List card products allowed for this partner
      description: 'Tenant allowlist. This response is live availability and an informative

        USDT quote (`issue_fee_usdt` / `issue_topup_usdt`). There is no separate

        `/quote` or `/availability`. Charge at issue follows the live tariff.'
      responses:
        '200':
          description: Tenant card product catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardProductsResponse'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
  /api/partner/card_list:
    post:
      operationId: listPartnerCards
      tags:
      - Cards
      summary: List cards (keyset pagination; masked PAN only)
      description: 'Scope `cards:read`. Keyset pagination by opaque cursor — no `offset`,

        no `total`/`count`. List items never include PAN, CVV, or

        `card_encrypted` — use POST `/api/partner/card_get` for secrets.

        Foreign or malformed `cursor` → `400` / `invalid_cursor`.'
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: cursor
        in: query
        description: Opaque decimal id from previous next_cursor
        schema:
          type: string
      responses:
        '200':
          description: Card list page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardListResponse'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
  /api/partner/card_issue:
    post:
      operationId: issuePartnerCard
      tags:
      - Cards
      summary: Issue a card
      description: 'Async issue. On stuck `processing` with no progress, IMBA closes the

        document as `failed` with `error=issue_timeout` and sends webhook

        `card_issue.status_changed`. Retry with a new `ext_id` (documents are

        not deleted). Synchronous failures return JSON `{error,message}`.

        For `ban_rus` products: phone must not be `+7…`, `country` ≠ `RU`,

        Latin names.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardIssueRequest'
      responses:
        '202':
          description: Card issue accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardIssueResponse'
        '409':
          $ref: '#/components/responses/Error'
        '422':
          $ref: '#/components/responses/Error'
  /api/partner/card_get:
    post:
      operationId: getPartnerCard
      tags:
      - Cards
      summary: Get card details (secrets via JWE or plaintext mode)
      description: 'Only cards linked to this partner. Default `card_payload=jwe` returns

        `card_encrypted` and `card: null`. Decrypt for PAN (`number`),

        `expiration`, and `cvv`. Secrets are never stored in list, webhooks, or

        document payloads. Authorizations are `POST /api/partner/card_transactions`.

        Unfreeze is `POST /api/partner/card_unfreeze`. This resource does not

        refund, unload, or replace a card.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - card_id
              properties:
                card_id:
                  type: string
                  example: 00112233445566778899aabb
      responses:
        '200':
          description: Card details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardGetResponse'
        '404':
          $ref: '#/components/responses/Error'
  /api/partner/card_balance:
    post:
      operationId: getPartnerCardBalance
      tags:
      - Cards
      summary: Get card balance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - card_id
              properties:
                card_id:
                  type: string
                  example: 00112233445566778899aabb
      responses:
        '200':
          description: Card balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardBalanceResponse'
        '404':
          $ref: '#/components/responses/Error'
  /api/partner/card_topup:
    post:
      operationId: createPartnerCardTopup
      tags:
      - Cards
      summary: Top up a card (USDT debit from partner balance)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - card_id
              - amount_usdt
              - ext_id
              properties:
                card_id:
                  type: string
                  example: 00112233445566778899aabb
                amount_usdt:
                  $ref: '#/components/schemas/DecimalString'
                ext_id:
                  $ref: '#/components/schemas/ExtId'
      responses:
        '202':
          description: Topup accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardTopupResponse'
        '409':
          $ref: '#/components/responses/Error'
        '422':
          $ref: '#/components/responses/Error'
  /api/partner/card_freeze:
    post:
      operationId: freezePartnerCard
      tags:
      - Cards
      summary: Freeze a card
      description: 'Async freeze (`202`). Unfreeze is `POST /api/partner/card_unfreeze`

        and only succeeds when this te'
components:
  schemas:
    CardTopupResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    CardProductsResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    CardListResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    CardIssueRequest:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    CardIssueResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    CardBalanceResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    DecimalString:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    CardGetResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    ExtId:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
  responses:
    Error:
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true