Выплаты

Как вывести деньги игроку, когда вернуть ему баланс и что сейчас работает в тестовом контуре.

Выплата отправляет деньги клиенту мерчанта на его реквизит. Её заводит сервер мерчанта одним запросом: сумма с комиссией встаёт в резерв из доступного остатка мерчанта, и выплата получает решение модерации. Исход приходит уведомлением payout.updated или узнаётся чтением.

Порядок

  1. Выберите сервис выплаты из списка сервисов: у него direction: PAYOUT, а поля получателя начинаются с beneficiary.. Реквизит, куда платим, ровно один.
  2. Заведите выплату. Заголовок Idempotency-Key обязателен:

    curl -sS -X POST https://api.paydex.co.uk/api/v1/payouts \
      -H "Authorization: Bearer $PAYDEX_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: 7c1d9e42-3a5b-4f80-b6d2-91e4a0c58f17" \
      -d '{
        "reference": "withdrawal-2001",
        "service": "payout_pix_brl_direct",
        "amountMinor": "15000",
        "customer": {
          "id": "player-1001",
          "country": "BR"
        },
        "fields": {
          "beneficiary.pix_key": "player1001@example.com",
          "beneficiary.tax_id": "52998224725"
        },
        "metadata": {
          "withdrawalId": "W-2001"
        }
      }'

    Новая выплата получает ответ 201. Поля запроса и ответа: справочник.

  3. Дождитесь исхода: уведомление payout.updated (Уведомления) или чтение выплаты. Выплату не в финальном статусе дочитывайте и сами, даже если ждёте уведомлений: недоставленное уведомление (кончились 30 попыток или адрес выключили) не досылается, а адрес, включённый после создания выплаты, получит первое уведомление только при её перемене.

    curl -sS https://api.paydex.co.uk/api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d \
      -H "Authorization: Bearer $PAYDEX_API_KEY"
  4. Возвращайте игроку баланс только при FAILED, REJECTED и CANCELLED: статусы выплаты.

Ключ повтора

Без заголовка Idempotency-Key выплата не заводится: отказ 400 с правилом idempotency_key_required. Без ключа повтор после обрыва вывел бы деньги дважды. Ключ работает как у платежа (Повтор запроса), но строже:

  • Отказ формы заголовка и тела ключ не занимает: исправленный запрос можно отправить с тем же ключом. Если этим ключом уже записано это же тело, вместо отказа формы придёт записанный ответ.
  • Отказ по существу ключ занимает: сервис, границы суммы, поля получателя против сервиса, значение реквизита (422 identifier_invalid, например IBAN или налоговый номер), остаток, номер вывода, а у создания выплаты ещё и отказ по ключу API или мерчанту (401 с правилом, 403) и адрес уведомлений без секрета контура (409 callback_secret_missing). Повтор с тем же ключом получит тот же отказ, исправленный запрос отправляйте с новым ключом.
  • Ответ 5xx и обрыв соединения это не отказ: выплата могла быть заведена. Не возвращайте игроку баланс и повторите тот же запрос с тем же ключом: повтор отдаст выплату, если она есть.

Номер вывода reference уникален у мерчанта в контуре отдельно от платежей: вывод 1001 не мешает депозиту 1001.

Деньги

Комиссия берётся сверх суммы: amountMinor это сколько получит игрок, feeMinor комиссия. Если доступного остатка не хватает на сумму с комиссией, выплата не заводится: отказ 409 с правилом insufficient_balance. Доступный остаток пополняют успешные платежи контура, в тестовом контуре тестовые. Отмена возвращает резерв в доступный остаток.

Модерация

Режим модерации задан для каждого контура мерчанта: выплату одобряет сотрудник или она одобряется сразу. По умолчанию в боевом контуре одобряет сотрудник, в тестовом выплата одобряется сразу. Решение видно в поле approval.

  • Выплата тому же клиенту на тот же реквизит той же суммой ждёт сотрудника и в режиме «сразу» (approval: PENDING), если прежняя заведена не раньше чем 24 часа назад и не закрылась без денег (FAILED, REJECTED, CANCELLED). Успешная прежняя тоже в счёт.
  • Выплата клиенту или на реквизит под блокировкой заводится и сразу получает REJECTED с причиной customer_blocked, без резерва. Ответ 201: у выплаты есть номер, по нему её видит и сотрудник.

Статусы выплаты

СтатусЧто значитБаланс игрока
CREATEDВыплата заведена, резерв стоит; ждёт модерации или отправкиНе возвращать
PROCESSINGВыплата отправлена, исход ещё неизвестенНе возвращать: деньги могли уйти
SUCCEEDEDДеньги ушлиВыплачено
FAILEDДеньги не ушлиВернуть
REJECTEDОтклонена у нас до отправки; причину называет reasonВернуть
CANCELLEDОтменена вами до отправкиВернуть

Из SUCCEEDED, FAILED, REJECTED и CANCELLED выплата не выходит. Незнакомый статус читайте как PROCESSING. Пока inReview: true, исход решается на нашей стороне: баланс не возвращайте и выплату прошедшей не считайте. Пока выплата не финальна, не заводите вместо неё новую: если первая уйдёт, деньги уйдут дважды.

Отмена

Выплату в CREATED, которая ещё не отправлена, можно отменить:

curl -sS -X POST https://api.paydex.co.uk/api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d/cancel \
  -H "Authorization: Bearer $PAYDEX_API_KEY"

Отменённая выплата получает CANCELLED с причиной cancelled_by_merchant, резерв возвращается в доступный остаток, а решение модерации, если оно ждало сотрудника, становится WITHDRAWN. Повтор отмены отдаёт ту же выплату. Отправленную или закрытую выплату не отменить: отказ 409 с правилом payout_not_cancellable.

Боевой контур

Боевой ключ получает отказ 403 с правилом live_payouts_closed.

API v1 · собрано 18.11.2026 · выпуск f13e6bf

Справочник методов собирается из кода сервера: он не описывает адрес, которого нет.