Перейти к содержимому
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.

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

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

Тело запроса

ПолеТипОбяз.Описание
amountstring (decimal)даДесятичная строка в USD, см. amount_type
amount_typestringнет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_idstringнетКарта, созданная или изменённая операцией; у выпуска появляется, когда карта создана
created_atstringдаКогда операция принята, UTC
error_codestringнетПочему операция не удалась. Все значения и что с ними делать — в разделе Ошибки.
hold_amountstring (decimal)даЗарезервировано на балансе, пока операция в процессе
idstringдаИдентификатор операции
kindstringдаissue | topup | close | cashout
net_amountstring (decimal)даЗачислено на карту (для закрытия — возвращено с неё)
refundRefundDTOнетТолько для закрытия: остаток карты, возвращённый вам
refund.amountstring (decimal)нетЗачислено на ваш баланс: residual − fee
refund.feestring (decimal)нетУдержано по close_refund_fee_pct тарифа
refund.residualstring (decimal)нетСколько было на карте при закрытии
refund.statusstringдаrefunded | zero (карта была пустой) | unknown (баланс прочитать не удалось; ничего не зачислено, урегулируем вручную)
settled_atstringнетКогда операция пришла в конечный статус, UTC
statusstringда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КодКогда
402balance_exhaustedДоступного баланса (available) не хватает на операцию. Пополните счёт.
404not_foundКарты нет или она выпущена не вашим аккаунтом.
422card_not_activeКарта не в состоянии active: ещё выпускается, заморожена или закрыта.
422amount_below_limitСумма на карту ниже минимума тарифа (min_topup).
422amount_above_limitСумма выше максимума тарифа (max_topup) или лимита на одну операцию для вашего аккаунта.
503maintenanceТехнические работы на этом направлении. Деньги не двигались — повторите позже с тем же Idempotency-Key.

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