Закрыть карту — API Плати в Пути

POST/api/partner/v1/cards/{id}/close

Scope: cards:write
Idempotency-Key: обязателен

Закрывает карту и списывает комиссию закрытия по тарифу.

В отличие от выпуска и пополнения, закрытие синхронное: операция возвращается уже в статусе succeeded или failed, а комиссия списывается, только если закрытие действительно произошло.

Остаток на карте возвращается на ваш баланс в том же вызове, за вычетом close_refund_fee_pct тарифа (по умолчанию 0 — возвращается целиком). Ответ несёт его в refund, следом приходит событие card.balance_reclaimed. refund.status — refunded, zero (карта была пустой) или unknown: баланс прочитать не удалось, ничего пока не зачислено, урегулируем вручную.

Закрытие уже закрытой карты — успешная операция без эффекта.

Параметры пути

Параметр	Тип	Обяз.	Описание
`id`	string (uuid)	да	Идентификатор карты

Пример запроса

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

curl -sS -X POST "https://api.plativputi.com/api/partner/v1/cards/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/close" \
  -H "X-Key-Id: $PP_KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -H "Idempotency-Key: $IDEM"

import { randomUUID } from "node:crypto";

const res = await pp("POST", "/cards/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/close", undefined, { idempotencyKey: randomUUID() });

import uuid

res = pp("POST", "/cards/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/close", idempotency_key=str(uuid.uuid4()))

$res = pp('POST', '/cards/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/close', null, uuid4());

pp() — функция-обёртка с подписью из раздела Аутентификация и подпись.

Ответ

200 OK — OperationDTO

Поле	Тип	Обяз.	Описание
`card_id`	string	нет	Карта, созданная или изменённая операцией; у выпуска появляется, когда карта создана
`created_at`	string	да	Когда операция принята, UTC
`error_code`	string	нет	Почему операция не удалась. Все значения и что с ними делать — в разделе Ошибки.
`hold_amount`	string (decimal)	да	Зарезервировано на балансе, пока операция в процессе
`id`	string	да	Идентификатор операции
`kind`	string	да	`issue` \| `topup` \| `close` \| `cashout`
`net_amount`	string (decimal)	да	Зачислено на карту (для закрытия — возвращено с неё)
`refund`	RefundDTO	нет	Только для закрытия: остаток карты, возвращённый вам
`refund.amount`	string (decimal)	нет	Зачислено на ваш баланс: `residual` − `fee`
`refund.fee`	string (decimal)	нет	Удержано по `close_refund_fee_pct` тарифа
`refund.residual`	string (decimal)	нет	Сколько было на карте при закрытии
`refund.status`	string	да	`refunded` \| `zero` (карта была пустой) \| `unknown` (баланс прочитать не удалось; ничего не зачислено, урегулируем вручную)
`settled_at`	string	нет	Когда операция пришла в конечный статус, UTC
`status`	string	да	`processing` \| `succeeded` \| `failed` \| `needs_review`

Примеры ответа

{
  "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"
}

Ошибки

HTTP	Код	Когда
402	`balance_exhausted`	Доступного баланса не хватает на комиссию закрытия (`close_fee`).
404	`not_found`	Карты нет или она выпущена не вашим аккаунтом.
503	`maintenance`	Технические работы на этом направлении. Деньги не двигались — повторите позже с тем же `Idempotency-Key`.

Плюс общие ошибки подписи и лимитов — см. Ошибки.