Выпуск карты

POST /cards/request

Заголовок Idempotency-Key обязателен — при одинаковом ключе повторный вызов вернёт результат первого запроса и не потратит сток.

Тело запроса необязательно. Единственное поле — externalId, ваш идентификатор карты (см. Привязка к своему id).

curl -X POST 'https://b2b.lumowallet.io/cards/request' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000'

С привязкой к своему идентификатору:

curl -X POST 'https://b2b.lumowallet.io/cards/request' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  -d '{"externalId": "user-42-card-1"}'

{
  "status": "assigned",
  "card": {
    "id": "8c7f1823-0d43-4618-86ee-fa0c77643cb2",
    "externalId": "user-42-card-1",
    "status": "assigned",
    "maskedPan": "4466 ** ** 1234",
    "expiry": "03/29",
    "assignedAt": "2026-04-23T12:00:00Z",
    "createdAt": "2026-04-23T12:00:00Z"
  }
}

{
  "status": "pending",
  "request": {
    "id": "2077f4ef-a03d-4001-82e3-1965e44036e8",
    "externalId": "user-42-card-1",
    "status": "pending",
    "cardId": null,
    "createdAt": "2026-04-23T12:00:00Z"
  }
}

Когда карта выпустится, вы получите webhook card.assigned и поле cardId заполнится. Также можно опрашивать GET /cards/requests/{requestId}.

externalId — необязательное поле в теле запроса: ваш идентификатор карты (id пользователя, номер заказа, что угодно до 128 печатаемых ASCII-символов без пробелов). Дальше он ездит вместе с картой:

• возвращается в POST /cards/request, GET /cards, GET /cards/{id} и GET /cards/requests/{requestId};
• приходит в webhook card.assigned — так отложенный выпуск связывается с вашей сущностью без хранения маппинга на нашей стороне;
• по нему можно искать карту: GET /cards?externalId=user-42-card-1.

Если заявка ушла в очередь, externalId хранится на ней и переезжает на карту в момент выдачи.

Уникальность — в рамках вашей компании. Второй выпуск с тем же значением вернёт 409 CARD_EXTERNAL_ID_TAKEN, а в details придёт cardId (или requestId) того, кто уже занял значение:

{
  "statusCode": 409,
  "error": "Conflict",
  "errorCode": "CARD_EXTERNAL_ID_TAKEN",
  "message": "externalId \"user-42-card-1\" уже занят картой 8c7f1823-0d43-4618-86ee-fa0c77643cb2",
  "details": {
    "externalId": "user-42-card-1",
    "cardId": "8c7f1823-0d43-4618-86ee-fa0c77643cb2"
  }
}

У разных компаний значения не пересекаются — свой user-42-card-1 может быть у каждой. Карты, выпущенные без externalId, приходят с null, и задним числом поле не проставляется.

Пока карта по заявке не выпущена, заявку можно отменить — например, если она надолго зависла в очереди, а деньги под неё нужны на другое.

POST /cards/requests/{requestId}/cancel

curl -X POST 'https://b2b.lumowallet.io/cards/requests/2077f4ef-.../cancel' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "id": "2077f4ef-a03d-4001-82e3-1965e44036e8",
  "externalId": "user-42-card-1",
  "status": "cancelled",
  "cardId": null,
  "createdAt": "2026-04-23T12:00:00Z"
}

Резерв под заявку возвращается в доступный баланс, а externalId снова освобождается — его можно использовать в новой заявке.

Отменить можно только заявку в статусе pending. Если карта уже выпущена, придёт CARD_REQUEST_NOT_CANCELABLE: выданную карту не отменяют, её закрывают через POST /cards/{id}/retire.

Повторная отмена не ошибка — вернётся та же заявка, и ничего не изменится. Поэтому запрос безопасно повторять, если ответ не дошёл.

Заявку может отменить и наша сторона — например, если карту по ней выдать не удалось. Тогда придёт webhook card.request_cancelled, а резерв так же вернётся на баланс.

На момент POST /cards/request:

1. Проверяется, что availableBalance >= openingFee + minInitialDeposit, иначе — 400 INSUFFICIENT_FUNDS.
2. Сумма openingFee + minInitialDeposit переводится в frozenBalance.
3. При выдаче (статус assigned): openingFee списывается с balance, minInitialDeposit возвращается в доступный баланс.
4. При ошибке моста: вся сумма размораживается.

Одна заявка за раз для заданного Idempotency-Key. Чтобы выпустить 10 карт — сделайте 10 вызовов с разными ключами.