# Request a new card

Reserves `cardOpeningFeeUsdt + cardMinInitialDepositUsdt` on the
company balance (`frozenBalance += reserve`). If the bridge has
a card in stock — returns `status: assigned` and immediately
debits `openingFee` from balance. Otherwise returns
`status: pending` and the request gets fulfilled asynchronously
via `card.assigned` webhook.
Необязательный `externalId` в теле привязывает карту к идентификатору
в вашей системе: он возвращается в `GET /cards`, `GET /cards/{id}` и в
webhook `card.assigned`, по нему же можно искать карту
(`GET /cards?externalId=…`). Значение уникально в рамках компании —
повторная заявка с занятым `externalId` вернёт `409 CARD_EXTERNAL_ID_TAKEN` (у разных компаний значения не пересекаются).

Endpoint: POST /cards/request
Version: 1.0.0
Security: apiKeyAuth

## Header parameters:

  - `Idempotency-Key` (string, required)
    UUID or any unique value per request attempt.

## Request fields (application/json):

  - `externalId` (string)
    Идентификатор карты в вашей системе. Уникален в рамках компании.
Допустимы печатаемые ASCII-символы без пробелов.
    Example: user-42-card-1

## Response 200 fields (application/json):

  - `status` (string, required)
    Enum: "assigned"

  - `card` (object, required)

  - `card.id` (string, required)

  - `card.externalId` (string | null)
    Идентификатор карты в вашей системе, если был передан при выпуске
    Example: user-42-card-1

  - `card.status` (string, required)
    - `requested` — заявка в очереди, карта будет выпущена позже
- `assigned` — активна, можно пополнять и использовать
- `closing` — запрошено закрытие, идёт обработка
- `closed` — закрыта, остаток возвращён на баланс компании
- `retired` — устаревший статус закрытых карт (эквивалентен `closed`)
- `failed` — эквайер не смог выпустить карту
    Enum: "requested", "assigned", "closing", "closed", "retired", "failed"

  - `card.maskedPan` (string | null)
    Example: 4466 ** ** 1234

  - `card.expiry` (string | null)
    MM/YY
    Example: 03/29

  - `card.assignedAt` (string | null)

  - `card.createdAt` (string, required)

  - `request` (object, required)

  - `request.id` (string, required)

  - `request.externalId` (string | null)
    Идентификатор из заявки; переезжает на карту при выдаче
    Example: user-42-card-1

  - `request.status` (string, required)
    Enum: "pending", "fulfilled", "cancelled", "failed"

  - `request.cardId` (string | null)

  - `request.createdAt` (string, required)

## Response 400 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code.
    Example: 400

  - `error` (string, required)
    HTTP reason phrase (legacy `PERMISSION_DENIED` for permission errors).
    Example: Bad Request

  - `errorCode` (string, required)
    Stable machine-readable code — always present. New codes may be
added over time, so treat unknown values as a generic failure for
the given `statusCode`.
    Enum: "VALIDATION_ERROR", "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "UNPROCESSABLE", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE", "BAD_GATEWAY", "AUTH_REQUIRED", "INVALID_API_KEY", "INVALID_CREDENTIALS", "SESSION_INVALID", "COMPANY_INACTIVE", "NO_COMPANY_MEMBERSHIP", "PERMISSION_DENIED", "ACCOUNT_ALREADY_EXISTS", "QR_AMOUNT_MISSING", "QR_INVALID", "QR_RESOLVE_FAILED", "AMOUNT_BELOW_MIN", "AMOUNT_ABOVE_MAX", "ST00012_SUM_MISSING", "ST00012_SUM_INVALID", "GIBDD_UIN_INVALID", "FINE_ALREADY_PAID", "FINE_NOT_FOUND", "QUOTE_NOT_FOUND", "QUOTE_EXPIRED", "INSUFFICIENT_BALANCE", "COMPANY_NOT_FOUND", "ORDER_NOT_FOUND", "UNSUPPORTED_CALLBACK_STATUS", "DRIVER_HELPER_TRANSIENT", "WALLET_BACKEND_ERROR", "DISPUTE_NOT_FOUND", "DISPUTE_NOT_ALLOWED", "IDEMPOTENCY_KEY_REQUIRED", "CARDS_NOT_ENABLED", "CARD_NOT_FOUND", "CARD_REQUEST_NOT_FOUND", "CARD_REQUEST_NOT_CANCELABLE", "CARD_NOT_ACTIVE", "CARD_NOT_OWNED", "CARD_RECHARGE_INVALID", "CARD_EXTERNAL_ID_TAKEN", "BRIDGE_ERROR", "MEMBER_NOT_FOUND", "CANNOT_CHANGE_OWN_ROLE", "ROLE_CHANGE_NOT_ALLOWED", "INVITE_NOT_FOUND", "INVITE_USED", "INVITE_EXPIRED", "INVITE_INVALID", "WEBHOOK_DELIVERY_NOT_FOUND", "WEBHOOK_URL_NOT_CONFIGURED", "INVALID_SIGNATURE", "PAYOUTS_NOT_ENABLED", "PAYOUT_NOT_FOUND", "PAYOUT_REQUISITE_INVALID", "PAYOUT_BANK_UNKNOWN", "PAYOUT_BANK_REQUIRED", "PAYOUT_ACTIVE_LIMIT", "PAYOUT_REQUISITE_COOLDOWN", "PAYOUT_OUTSIDE_WORKING_HOURS", "PAYOUT_NOT_CANCELABLE", "PAYOUT_DISPUTE_NOT_ALLOWED", "PAYOUT_SERVICE_REJECTED", "PAYOUT_SERVICE_UNAVAILABLE"

  - `message` (any, required)
    Human-readable message (RU). Array of strings for validation errors.

  - `required` (string)
    Present only for `PERMISSION_DENIED` — the permission the API key is missing.
    Example: orders:create

  - `path` (string)
    Request path that produced the error.
    Example: /orders/prepare

  - `timestamp` (string)
    When the error was produced (ISO 8601).
    Example: 2026-05-27T16:41:49.000Z

  - `requestId` (string)
    Correlation id, also returned in the `X-Request-Id` response header.
Quote it when contacting support.
    Example: 439436bd-201c-4084-9063-58cfa2cd40ad

## Response 401 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code.
    Example: 400

  - `error` (string, required)
    HTTP reason phrase (legacy `PERMISSION_DENIED` for permission errors).
    Example: Bad Request

  - `errorCode` (string, required)
    Stable machine-readable code — always present. New codes may be
added over time, so treat unknown values as a generic failure for
the given `statusCode`.
    Enum: "VALIDATION_ERROR", "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "UNPROCESSABLE", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE", "BAD_GATEWAY", "AUTH_REQUIRED", "INVALID_API_KEY", "INVALID_CREDENTIALS", "SESSION_INVALID", "COMPANY_INACTIVE", "NO_COMPANY_MEMBERSHIP", "PERMISSION_DENIED", "ACCOUNT_ALREADY_EXISTS", "QR_AMOUNT_MISSING", "QR_INVALID", "QR_RESOLVE_FAILED", "AMOUNT_BELOW_MIN", "AMOUNT_ABOVE_MAX", "ST00012_SUM_MISSING", "ST00012_SUM_INVALID", "GIBDD_UIN_INVALID", "FINE_ALREADY_PAID", "FINE_NOT_FOUND", "QUOTE_NOT_FOUND", "QUOTE_EXPIRED", "INSUFFICIENT_BALANCE", "COMPANY_NOT_FOUND", "ORDER_NOT_FOUND", "UNSUPPORTED_CALLBACK_STATUS", "DRIVER_HELPER_TRANSIENT", "WALLET_BACKEND_ERROR", "DISPUTE_NOT_FOUND", "DISPUTE_NOT_ALLOWED", "IDEMPOTENCY_KEY_REQUIRED", "CARDS_NOT_ENABLED", "CARD_NOT_FOUND", "CARD_REQUEST_NOT_FOUND", "CARD_REQUEST_NOT_CANCELABLE", "CARD_NOT_ACTIVE", "CARD_NOT_OWNED", "CARD_RECHARGE_INVALID", "CARD_EXTERNAL_ID_TAKEN", "BRIDGE_ERROR", "MEMBER_NOT_FOUND", "CANNOT_CHANGE_OWN_ROLE", "ROLE_CHANGE_NOT_ALLOWED", "INVITE_NOT_FOUND", "INVITE_USED", "INVITE_EXPIRED", "INVITE_INVALID", "WEBHOOK_DELIVERY_NOT_FOUND", "WEBHOOK_URL_NOT_CONFIGURED", "INVALID_SIGNATURE", "PAYOUTS_NOT_ENABLED", "PAYOUT_NOT_FOUND", "PAYOUT_REQUISITE_INVALID", "PAYOUT_BANK_UNKNOWN", "PAYOUT_BANK_REQUIRED", "PAYOUT_ACTIVE_LIMIT", "PAYOUT_REQUISITE_COOLDOWN", "PAYOUT_OUTSIDE_WORKING_HOURS", "PAYOUT_NOT_CANCELABLE", "PAYOUT_DISPUTE_NOT_ALLOWED", "PAYOUT_SERVICE_REJECTED", "PAYOUT_SERVICE_UNAVAILABLE"

  - `message` (any, required)
    Human-readable message (RU). Array of strings for validation errors.

  - `required` (string)
    Present only for `PERMISSION_DENIED` — the permission the API key is missing.
    Example: orders:create

  - `path` (string)
    Request path that produced the error.
    Example: /orders/prepare

  - `timestamp` (string)
    When the error was produced (ISO 8601).
    Example: 2026-05-27T16:41:49.000Z

  - `requestId` (string)
    Correlation id, also returned in the `X-Request-Id` response header.
Quote it when contacting support.
    Example: 439436bd-201c-4084-9063-58cfa2cd40ad

## Response 403 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code.
    Example: 400

  - `error` (string, required)
    HTTP reason phrase (legacy `PERMISSION_DENIED` for permission errors).
    Example: Bad Request

  - `errorCode` (string, required)
    Stable machine-readable code — always present. New codes may be
added over time, so treat unknown values as a generic failure for
the given `statusCode`.
    Enum: "VALIDATION_ERROR", "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "UNPROCESSABLE", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE", "BAD_GATEWAY", "AUTH_REQUIRED", "INVALID_API_KEY", "INVALID_CREDENTIALS", "SESSION_INVALID", "COMPANY_INACTIVE", "NO_COMPANY_MEMBERSHIP", "PERMISSION_DENIED", "ACCOUNT_ALREADY_EXISTS", "QR_AMOUNT_MISSING", "QR_INVALID", "QR_RESOLVE_FAILED", "AMOUNT_BELOW_MIN", "AMOUNT_ABOVE_MAX", "ST00012_SUM_MISSING", "ST00012_SUM_INVALID", "GIBDD_UIN_INVALID", "FINE_ALREADY_PAID", "FINE_NOT_FOUND", "QUOTE_NOT_FOUND", "QUOTE_EXPIRED", "INSUFFICIENT_BALANCE", "COMPANY_NOT_FOUND", "ORDER_NOT_FOUND", "UNSUPPORTED_CALLBACK_STATUS", "DRIVER_HELPER_TRANSIENT", "WALLET_BACKEND_ERROR", "DISPUTE_NOT_FOUND", "DISPUTE_NOT_ALLOWED", "IDEMPOTENCY_KEY_REQUIRED", "CARDS_NOT_ENABLED", "CARD_NOT_FOUND", "CARD_REQUEST_NOT_FOUND", "CARD_REQUEST_NOT_CANCELABLE", "CARD_NOT_ACTIVE", "CARD_NOT_OWNED", "CARD_RECHARGE_INVALID", "CARD_EXTERNAL_ID_TAKEN", "BRIDGE_ERROR", "MEMBER_NOT_FOUND", "CANNOT_CHANGE_OWN_ROLE", "ROLE_CHANGE_NOT_ALLOWED", "INVITE_NOT_FOUND", "INVITE_USED", "INVITE_EXPIRED", "INVITE_INVALID", "WEBHOOK_DELIVERY_NOT_FOUND", "WEBHOOK_URL_NOT_CONFIGURED", "INVALID_SIGNATURE", "PAYOUTS_NOT_ENABLED", "PAYOUT_NOT_FOUND", "PAYOUT_REQUISITE_INVALID", "PAYOUT_BANK_UNKNOWN", "PAYOUT_BANK_REQUIRED", "PAYOUT_ACTIVE_LIMIT", "PAYOUT_REQUISITE_COOLDOWN", "PAYOUT_OUTSIDE_WORKING_HOURS", "PAYOUT_NOT_CANCELABLE", "PAYOUT_DISPUTE_NOT_ALLOWED", "PAYOUT_SERVICE_REJECTED", "PAYOUT_SERVICE_UNAVAILABLE"

  - `message` (any, required)
    Human-readable message (RU). Array of strings for validation errors.

  - `required` (string)
    Present only for `PERMISSION_DENIED` — the permission the API key is missing.
    Example: orders:create

  - `path` (string)
    Request path that produced the error.
    Example: /orders/prepare

  - `timestamp` (string)
    When the error was produced (ISO 8601).
    Example: 2026-05-27T16:41:49.000Z

  - `requestId` (string)
    Correlation id, also returned in the `X-Request-Id` response header.
Quote it when contacting support.
    Example: 439436bd-201c-4084-9063-58cfa2cd40ad

## Response 409 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code.
    Example: 400

  - `error` (string, required)
    HTTP reason phrase (legacy `PERMISSION_DENIED` for permission errors).
    Example: Bad Request

  - `errorCode` (string, required)
    Stable machine-readable code — always present. New codes may be
added over time, so treat unknown values as a generic failure for
the given `statusCode`.
    Enum: "VALIDATION_ERROR", "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "UNPROCESSABLE", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE", "BAD_GATEWAY", "AUTH_REQUIRED", "INVALID_API_KEY", "INVALID_CREDENTIALS", "SESSION_INVALID", "COMPANY_INACTIVE", "NO_COMPANY_MEMBERSHIP", "PERMISSION_DENIED", "ACCOUNT_ALREADY_EXISTS", "QR_AMOUNT_MISSING", "QR_INVALID", "QR_RESOLVE_FAILED", "AMOUNT_BELOW_MIN", "AMOUNT_ABOVE_MAX", "ST00012_SUM_MISSING", "ST00012_SUM_INVALID", "GIBDD_UIN_INVALID", "FINE_ALREADY_PAID", "FINE_NOT_FOUND", "QUOTE_NOT_FOUND", "QUOTE_EXPIRED", "INSUFFICIENT_BALANCE", "COMPANY_NOT_FOUND", "ORDER_NOT_FOUND", "UNSUPPORTED_CALLBACK_STATUS", "DRIVER_HELPER_TRANSIENT", "WALLET_BACKEND_ERROR", "DISPUTE_NOT_FOUND", "DISPUTE_NOT_ALLOWED", "IDEMPOTENCY_KEY_REQUIRED", "CARDS_NOT_ENABLED", "CARD_NOT_FOUND", "CARD_REQUEST_NOT_FOUND", "CARD_REQUEST_NOT_CANCELABLE", "CARD_NOT_ACTIVE", "CARD_NOT_OWNED", "CARD_RECHARGE_INVALID", "CARD_EXTERNAL_ID_TAKEN", "BRIDGE_ERROR", "MEMBER_NOT_FOUND", "CANNOT_CHANGE_OWN_ROLE", "ROLE_CHANGE_NOT_ALLOWED", "INVITE_NOT_FOUND", "INVITE_USED", "INVITE_EXPIRED", "INVITE_INVALID", "WEBHOOK_DELIVERY_NOT_FOUND", "WEBHOOK_URL_NOT_CONFIGURED", "INVALID_SIGNATURE", "PAYOUTS_NOT_ENABLED", "PAYOUT_NOT_FOUND", "PAYOUT_REQUISITE_INVALID", "PAYOUT_BANK_UNKNOWN", "PAYOUT_BANK_REQUIRED", "PAYOUT_ACTIVE_LIMIT", "PAYOUT_REQUISITE_COOLDOWN", "PAYOUT_OUTSIDE_WORKING_HOURS", "PAYOUT_NOT_CANCELABLE", "PAYOUT_DISPUTE_NOT_ALLOWED", "PAYOUT_SERVICE_REJECTED", "PAYOUT_SERVICE_UNAVAILABLE"

  - `message` (any, required)
    Human-readable message (RU). Array of strings for validation errors.

  - `required` (string)
    Present only for `PERMISSION_DENIED` — the permission the API key is missing.
    Example: orders:create

  - `path` (string)
    Request path that produced the error.
    Example: /orders/prepare

  - `timestamp` (string)
    When the error was produced (ISO 8601).
    Example: 2026-05-27T16:41:49.000Z

  - `requestId` (string)
    Correlation id, also returned in the `X-Request-Id` response header.
Quote it when contacting support.
    Example: 439436bd-201c-4084-9063-58cfa2cd40ad

## Response 502 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code.
    Example: 400

  - `error` (string, required)
    HTTP reason phrase (legacy `PERMISSION_DENIED` for permission errors).
    Example: Bad Request

  - `errorCode` (string, required)
    Stable machine-readable code — always present. New codes may be
added over time, so treat unknown values as a generic failure for
the given `statusCode`.
    Enum: "VALIDATION_ERROR", "BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "UNPROCESSABLE", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE", "BAD_GATEWAY", "AUTH_REQUIRED", "INVALID_API_KEY", "INVALID_CREDENTIALS", "SESSION_INVALID", "COMPANY_INACTIVE", "NO_COMPANY_MEMBERSHIP", "PERMISSION_DENIED", "ACCOUNT_ALREADY_EXISTS", "QR_AMOUNT_MISSING", "QR_INVALID", "QR_RESOLVE_FAILED", "AMOUNT_BELOW_MIN", "AMOUNT_ABOVE_MAX", "ST00012_SUM_MISSING", "ST00012_SUM_INVALID", "GIBDD_UIN_INVALID", "FINE_ALREADY_PAID", "FINE_NOT_FOUND", "QUOTE_NOT_FOUND", "QUOTE_EXPIRED", "INSUFFICIENT_BALANCE", "COMPANY_NOT_FOUND", "ORDER_NOT_FOUND", "UNSUPPORTED_CALLBACK_STATUS", "DRIVER_HELPER_TRANSIENT", "WALLET_BACKEND_ERROR", "DISPUTE_NOT_FOUND", "DISPUTE_NOT_ALLOWED", "IDEMPOTENCY_KEY_REQUIRED", "CARDS_NOT_ENABLED", "CARD_NOT_FOUND", "CARD_REQUEST_NOT_FOUND", "CARD_REQUEST_NOT_CANCELABLE", "CARD_NOT_ACTIVE", "CARD_NOT_OWNED", "CARD_RECHARGE_INVALID", "CARD_EXTERNAL_ID_TAKEN", "BRIDGE_ERROR", "MEMBER_NOT_FOUND", "CANNOT_CHANGE_OWN_ROLE", "ROLE_CHANGE_NOT_ALLOWED", "INVITE_NOT_FOUND", "INVITE_USED", "INVITE_EXPIRED", "INVITE_INVALID", "WEBHOOK_DELIVERY_NOT_FOUND", "WEBHOOK_URL_NOT_CONFIGURED", "INVALID_SIGNATURE", "PAYOUTS_NOT_ENABLED", "PAYOUT_NOT_FOUND", "PAYOUT_REQUISITE_INVALID", "PAYOUT_BANK_UNKNOWN", "PAYOUT_BANK_REQUIRED", "PAYOUT_ACTIVE_LIMIT", "PAYOUT_REQUISITE_COOLDOWN", "PAYOUT_OUTSIDE_WORKING_HOURS", "PAYOUT_NOT_CANCELABLE", "PAYOUT_DISPUTE_NOT_ALLOWED", "PAYOUT_SERVICE_REJECTED", "PAYOUT_SERVICE_UNAVAILABLE"

  - `message` (any, required)
    Human-readable message (RU). Array of strings for validation errors.

  - `required` (string)
    Present only for `PERMISSION_DENIED` — the permission the API key is missing.
    Example: orders:create

  - `path` (string)
    Request path that produced the error.
    Example: /orders/prepare

  - `timestamp` (string)
    When the error was produced (ISO 8601).
    Example: 2026-05-27T16:41:49.000Z

  - `requestId` (string)
    Correlation id, also returned in the `X-Request-Id` response header.
Quote it when contacting support.
    Example: 439436bd-201c-4084-9063-58cfa2cd40ad