Обязательные
amount — сумма в копейках, от 100 до 1 000 000 000. currency — «RUB». recipient — объект или ID получателя (карта, СБП-телефон, кошелёк).
Смотреть схему
Справочник · API v1
Операция Payout
Полная техническая спецификация эндпоинта для создания выплат: обязательные поля, структура ответов и механизмы идемпотентности. Проведите первый payout за минуту — без лишних шагов.
Создание операцииPOST /v1/payouts
запрос · bodyamount: 12400
валидация · схемаOK · 12 мс
payout_8f3a · созданstatus: pending
Endpoint
POST /v1/payouts
Создаёт новую операцию выплаты. Метод синхронный: возвращает объект payout со статусом pending в течение 40 мс. Фактическое зачисление на счёт исполнителя происходит асинхронно — отслеживайте его через webhook payout.succeeded.
Запросapplication/json
POST https://api.cobalflow.ru/v1/payouts
Authorization: Bearer sk_live_51Nq…a9f
Idempotency-Key: 2025-06-11-tk-4482
Тело запросасм. параметры ниже
Код успеха201 Created
Код ошибки4xx / 5xx
Аутентификация — только по секретному ключу sk_live_* или sk_test_* в заголовке Authorization. Запросы без ключа отклоняются кодом 401. Для продакшена используйте ключ с флагом live; тестовые ключи не влияют на реальные балансы.
Parameters
Поля тела запроса
Поля передаются в JSON-теле. Значения валюты — в копейках (целое число), чтобы избежать ошибок округления. Ниже — обязательные и опциональные поля.
Опциональные
description — комментарий до 255 символов. schedule_at — дата отложенного зачисления (ISO 8601). metadata — произвольный объект до 50 КБ.
Смотреть схемуЛимиты
Максимум 10 000 payout в одном батче. На одного получателя — до 500 операций в сутки. Превышение квоты возвращает 429 с заголовком Retry-After.
О лимитахСхема телаJSON · обязательные
{
"amount": 12400, // int, копейки
"currency": "RUB",
"recipient": {
"type": "sbp", // card | sbp | wallet
"value": "+7 921 555-01-44"
},
"description": "Выплата за проект #118", // опц.
"metadata": { "order": "ord_9f21" } // опц.
}
Response
Объект успеха и объект ошибки
При успехе — 201 Created и объект payout со статусом pending. При ошибке — соответствующий код 4xx/5xx и объект error с машиночитаемым кодом и человекочитаемым сообщением.
Успех201 Created
{
"id": "payout_8f3a2c",
"object": "payout",
"amount": 12400,
"currency": "RUB",
"status": "pending", // pending|succeeded|failed
"created": "2025-06-11T09:42:17Z"
}
Ошибка400 Bad Request
{
"error": {
"code": "amount_out_of_range",
"message": "Сумма должна быть от 100 до 1000000000 копеек.",
"param": "amount"
}
}
400некорректные параметры
402недостаточно средств
429превышен лимит, см. Retry-After
Idempotency
Идемпотентность запросов
Чтобы повторный запрос не создал вторую выплату, передавайте заголовок Idempotency-Key. Ключ хранится 24 часа и гарантирует, что один и тот же запрос вернёт один и тот же результат.
Уникальный ключ
Используйте UUID или детерминированный ключ (например, дата + номер заказа). Повторный запрос с тем же ключом вернёт исходный payout без нового списания.
Пример ключаОкно хранения
Ключ и результат сохраняются 24 часа с момента первого запроса. После истечения окна ключ считается новым — создайте свежий идентификатор для каждой логической операции.
ПодробнееРазные тела
Если к одному ключу приходит запрос с отличным телом, API вернёт 409 idempotency_mismatch. Не меняйте параметры при повторной отправке — только ключ остаётся прежним.
О конфликтахПримерповторный запрос
Idempotency-Key: 2025-06-11-tk-4482
первый запрос201 · payout_8f3a2c
повтор · тот же ключ200 · payout_8f3a2c
повтор · другое тело409 · mismatch
Попробуйте payout в песочнице
Тестовые ключи, готовые примеры запросов и симуляция webhook payout.succeeded. Первые транзакции — без единого лишнего шага.
Вопросы
Что чаще всего спрашивают
Создание операции возвращает статус pending. Фактическое зачисление — асинхронное, обычно в пределах 1–5 секунд. Успешный статус приходит через webhook payout.succeeded или запросом к GET /v1/payouts/{id}.
Отмена доступна только до статуса succeeded через POST /v1/payouts/{id}/cancel. После успешного зачисления операция необратима — создаётся отдельный возврат.
Чаще всего — 400 amount_out_of_range (неверная сумма) и 402 insufficient_balance (недостаточно средств на кассе). Каждый код описан в справочнике ошибок API.
Максимум 10 000 000 000 копеек (100 млн ₽) в одной операции. Для крупных регулярных потоков мы настраиваем отдельные квоты и отдельный канал поддержки.