Справочник APIКарты
Пополнить карту
POST
/api/partner/v1/cards/{id}/topup- Scope
cards:write- Idempotency-Key
- обязателен
Резервирует средства и запускает пополнение. Как и выпуск, пополнение асинхронное: в ответе операция, а не новый баланс. Дождитесь card.topped_up или опрашивайте GET /operations/{id}.
Цена считается по тарифу, на котором карта была ВЫПУЩЕНА, а не по тарифу, который вы назовёте, — стоимость пополнения не зависит от того, по какому тарифу вы запрашивали котировку.
Пополнить можно только карту в состоянии active. Карта, которая ещё создаётся, отклоняется с card_not_active — сначала дождитесь card.issued.
Параметры пути
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
id | string (uuid) | да | Идентификатор карты |
Тело запроса
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
amount | string (decimal) | да | Десятичная строка в USD, см. amount_type |
amount_type | string | нет | credit (по умолчанию) — amount придёт на карту. debit — amount спишется с баланса. |
Пример запроса
BODY='{"amount":"100","amount_type":"credit"}'
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/topup" "$BODY" "$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/topup" \
-H "X-Key-Id: $PP_KEY_ID" \
-H "X-Timestamp: $TS" \
-H "X-Signature: $SIG" \
-H "Idempotency-Key: $IDEM" \
-H "Content-Type: application/json" \
-d "$BODY"import { randomUUID } from "node:crypto";
const res = await pp("POST", "/cards/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/topup", {
"amount": "100",
"amount_type": "credit"
}, { idempotencyKey: randomUUID() });import uuid
res = pp("POST", "/cards/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/topup", body={
"amount": "100",
"amount_type": "credit",
}, idempotency_key=str(uuid.uuid4()))$res = pp('POST', '/cards/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/topup', [
'amount' => '100',
'amount_type' => 'credit',
], uuid4());pp() — функция-обёртка с подписью из раздела Аутентификация и подпись.
Ответ
202 Accepted — 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": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f7a",
"kind": "topup",
"status": "processing",
"card_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"hold_amount": "103.5928",
"net_amount": "100",
"created_at": "2026-10-07T10:01:15Z"
}{
"title": "Unprocessable Entity",
"status": 422,
"detail": "card_not_active: card is creating and cannot be topped up",
"errors": [
{
"message": "card_not_active",
"location": "error.code",
"value": "card_not_active"
}
]
}Ошибки
| HTTP | Код | Когда |
|---|---|---|
| 402 | balance_exhausted | Доступного баланса (available) не хватает на операцию. Пополните счёт. |
| 404 | not_found | Карты нет или она выпущена не вашим аккаунтом. |
| 422 | card_not_active | Карта не в состоянии active: ещё выпускается, заморожена или закрыта. |
| 422 | amount_below_limit | Сумма на карту ниже минимума тарифа (min_topup). |
| 422 | amount_above_limit | Сумма выше максимума тарифа (max_topup) или лимита на одну операцию для вашего аккаунта. |
| 503 | maintenance | Технические работы на этом направлении. Деньги не двигались — повторите позже с тем же Idempotency-Key. |
Плюс общие ошибки подписи и лимитов — см. Ошибки.