Создать платёж
POST
/v1/payments
POST https://api.banka.bot/v1/payments.payment_url, ссылку наплатёжную страницу для плательщика.
idв запросе не передаётся.
Повтор запроса
Idempotency-Key, вашу уникальную строку накаждый платёж (подойдёт uuid4), сохранённую вместе с заказом. Повтор
с тем же ключом и тем же телом в течение 24 часов возвращает тот же
платёж с тем же ответом, второй платёж не создаётся. Тот же ключ с
другим телом отвечает
409 duplicate_external_id. Если первый запрос сэтим ключом ещё выполняется, ответ
409 invalid_request, повторитечерез несколько секунд.
Повторите тот же самый запрос с тем же
Idempotency-Key. Новый ключили запрос без ключа это новый платёж.
который потерялся, истечёт через час; если в запросе был
callback_url, по нему придёт payment.expired с payment_id,которого вы не видели. Поэтому сопоставляйте заказ по
payment_id,а не только по
order_id.Способ оплаты
method привязывает платёж к способу оплаты:платёжная страница открывается сразу в нём, без шага выбора, а
method в ответе, статусе и вебхуке заполнен с момента создания.Способ, недоступный вашему магазину или этой сумме, отвечает
400method_unavailable до создания платежа: платёж не создан, изменитесумму или способ либо создайте платёж без
method.Ошибки
{"error": "<код>", "message": "<текст>"}. Ветвитесьпо
error, текст message меняется без предупреждения.| Код | HTTP | Когда |
|---|---|---|
invalid_request | 400 | тело не прошло проверку: сумма вне 1..1 000 000 или больше 2 знаков, неверный URL |
amount_not_supported | 400 | сумму не покрывает тариф магазина; message объясняет, что сделать |
method_unavailable | 400 | способ оплаты недоступен вашему магазину или этой сумме, выключен в настройках магазина в кабинете либо код способа пока не поддерживается; платёж не создан |
unauthorized | 401 | нет заголовка Authorization, ключ неверен или отозван |
duplicate_external_id | 409 | тот же Idempotency-Key с другим телом запроса |
invalid_request | 409 | первый запрос с этим Idempotency-Key ещё выполняется; повторите через несколько секунд |
rate_limited | 429 | больше 120 запросов в минуту одним ключом |
internal_error | 500 | платёж не создан; повторите запрос |
Request
Header Params
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location '/v1/payments' \
--header 'Idempotency-Key: 4f1c9d2e-8a37-4b56-9f0e-1d2c3b4a5968' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"amount": 500,
"currency": "RUB"
}'Response Response Example
201 - Success Example
{
"payment_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"order_code": "7XK4M2QD",
"payment_url": "https://pay.banka.bot/7XK4M2QD",
"status": "pending",
"amount": 500,
"amount_total": 540,
"currency": "RUB",
"method": null,
"order_id": "order_123",
"created_at": "2026-08-02T12:00:00Z",
"paid_at": null,
"expires_at": "2026-08-02T13:00:00Z"
}Modified at 2026-09-07 18:22:00