Выплаты
Как вывести деньги игроку, когда вернуть ему баланс и что сейчас работает в тестовом контуре.
Выплата отправляет деньги клиенту мерчанта на его реквизит. Её заводит сервер мерчанта одним запросом: сумма с комиссией встаёт в резерв из доступного остатка мерчанта, и выплата получает решение модерации. Исход приходит уведомлением payout.updated или узнаётся чтением.
Порядок
- Выберите сервис выплаты из списка сервисов: у него
direction: PAYOUT, а поля получателя начинаются сbeneficiary.. Реквизит, куда платим, ровно один. Заведите выплату. Заголовок
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. Поля запроса и ответа: справочник.
Дождитесь исхода: уведомление
payout.updated(Уведомления) или чтение выплаты. Выплату не в финальном статусе дочитывайте и сами, даже если ждёте уведомлений: недоставленное уведомление (кончились 30 попыток или адрес выключили) не досылается, а адрес, включённый после создания выплаты, получит первое уведомление только при её перемене.curl -sS https://api.paydex.co.uk/api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d \ -H "Authorization: Bearer $PAYDEX_API_KEY"- Возвращайте игроку баланс только при
FAILED,REJECTEDиCANCELLED: статусы выплаты.
Ключ повтора
Без заголовка Idempotency-Key выплата не заводится: отказ 400 с правилом idempotency_key_required. Без ключа повтор после обрыва вывел бы деньги дважды. Ключ работает как у платежа (Повтор запроса), но строже:
- Отказ формы заголовка и тела ключ не занимает: исправленный запрос можно отправить с тем же ключом. Если этим ключом уже записано это же тело, вместо отказа формы придёт записанный ответ.
- Отказ по существу ключ занимает: сервис, границы суммы, поля получателя против сервиса, значение реквизита (422
identifier_invalid, например IBAN или налоговый номер), остаток, номер вывода, а у создания выплаты ещё и отказ по ключу API или мерчанту (401 с правилом, 403) и адрес уведомлений без секрета контура (409callback_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.