Жизненный цикл карты

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

Состояния

            POST /cards
                │
                ▼
           ┌──────────┐   выпуск не удался   ┌────────┐
           │ creating │ ───────────────────▶ │ failed │
           └────┬─────┘                      └────────┘
                │ card.issued
                ▼
           ┌──────────┐ ◀──────────────────▶ ┌────────┐
           │  active  │                      │ frozen │
           └────┬─────┘                      └───┬────┘
                │ POST /cards/{id}/close         │
                ▼                                │
        ┌────────────────┐                       │
        │ wait_for_close │ ◀─────────────────────┘
        └───────┬────────┘
                ▼
           ┌──────────┐           ┌─────────┐
           │  closed  │           │ expired │  истёк срок действия
           └──────────┘           └─────────┘

`state`	Что значит	Пополнить	Закрыть	Реквизиты
`creating`	Карта создаётся у эмитента	нет	нет	нет
`active`	Работает	да	да	да
`frozen`	Заблокирована эмитентом или ждёт проверки (см. ниже)	нет	да	да
`wait_for_close`	Закрывается	нет	—	да
`closed`	Закрыта, остаток возвращён	нет	без эффекта	да
`expired`	Истёк срок действия	нет	да	да
`failed`	Выпуск не удался, резерв снят	нет	нет	нет

Пополнение карты не в active отклоняется с 422 card_not_active.

Выпуск

POST /cards → 202 и операция issue в статусе processing, сумма в резерве.
Мы создаём карту у эмитента и пополняем её. Обычно это секунды.
Первая карта нового держателя ждёт проверки личности у эмитента — это заметно дольше. Следующие карты того же external_id её пропускают.
Итог — событие card.issued (или card.issue_failed) и операция в succeeded / failed. В card_id операции — идентификатор новой карты.

Пока операция в processing, карту не пополнить: ответ 422 card_not_active.

Карта, которую эмитент перестал отдавать

Иногда эмитент перестаёт возвращать карту — обычно её закрыли или удалили на его стороне. Тогда GET /cards/{id} возвращает provider_missing: true:

{
  "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "state": "frozen",
  "provider_missing": true,
  "holder_external_id": "cust-42",
  "masked_number": "**** **** **** 4821",
  "currency": "USD",
  "created_at": "2026-10-07T09:13:02Z"
}

Карта показывается как frozen, balance не отдаётся, пополнения отклоняются.
Закрыть её можно — так случай и разрешается. Реквизиты по-прежнему доступны: они нужны держателю для спора с мерчантом.
Если эмитент снова начнёт отвечать, флаг снимется сам.

Баланс карты

GET /cards/{id} читает баланс у эмитента в момент запроса.

Ответ	Как трактовать
`"balance": "50"`	Живое значение
`"balance": "50", "balance_stale": true`	Последнее известное значение — эмитент сейчас не ответил. Число настоящее, но необратимую операцию на нём не стройте
поля `balance` нет	Неизвестен. Не ноль

POST /cards/{id}/close синхронный: в ответе уже итоговая операция. Комиссия close_fee списывается, остаток карты возвращается на ваш баланс (за вычетом close_refund_fee_pct), следом приходят события card.closed и card.balance_reclaimed.

CARD=9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
IDEM=$(uuidgen)
TS=$(date +%s)
SIG=$(printf '%s\n%s\n%s\n%s\n%s' "$TS" "POST" "/api/partner/v1/cards/$CARD/close" "" "$IDEM" \
  | openssl dgst -sha256 -hmac "$PP_SECRET" -hex | awk '{print $NF}')

curl -sS -X POST "https://api.plativputi.com/api/partner/v1/cards/$CARD/close" \
  -H "X-Key-Id: $PP_KEY_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Idempotency-Key: $IDEM"

const op = await pp("POST", `/cards/${cardId}/close`, undefined, {
  idempotencyKey: randomUUID(),
});

op = pp("POST", f"/cards/{card_id}/close", idempotency_key=str(uuid.uuid4()))

$op = pp('POST', "/cards/$cardId/close", null, uuid4());

{
  "id": "f6a7b8c9-d0e1-4f2a-9b3c-4d5e6f7a8b9c",
  "kind": "close",
  "status": "succeeded",
  "card_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "hold_amount": "1",
  "net_amount": "0",
  "refund": { "status": "refunded", "residual": "37.4", "fee": "0", "amount": "37.4" },
  "created_at": "2026-10-08T14:20:00Z",
  "settled_at": "2026-10-08T14:20:01Z"
}

Закрытие уже закрытой карты — успех без эффекта. Карту может закрыть и не ваш запрос — например, эмитент. Тогда вы получите card.closed с полем closed_by и card.balance_reclaimed с возвращённым остатком.

Состояния

Выпуск

Карта, которую эмитент перестал отдавать

Баланс карты

Закрытие

На этой странице