Обзор выплат

Отправка средств с баланса мерчанта на карты, номера телефонов, кошельки и PIX-ключи

Выплаты отправляют средства с баланса мерчанта вашим пользователям. Все направления используют один и тот же endpoint и один и тот же объект выплаты; различаются только валюта, paymentType и поля получателя.

Перед тем как начать

Авторизация

Как подписывать запросы API-токеном.

Выплаты списываются с баланса мерчанта. Перед созданием выплаты убедитесь, что баланса достаточно, и попросите менеджера подключить нужные вам направления.

Как это работает

Выберите направление

Каждая пара «страна + оператор» — это отдельный сервис выплат. Список сервисов, подключённых для вашего аккаунта, возвращает запрос:

GET /v1/payouts/services

При создании выплаты передавайте serviceId нужного направления. Если serviceId не указан, используется сервис по умолчанию.

Создайте выплату

Один запрос POST /v1/payouts. В ответе возвращается объект выплаты в статусе CREATED. Сохраните его id.

Отслеживайте результат

При каждом изменении статуса мы отправляем подписанный webhook. Опрос GET /v1/payouts/{payoutId} — резервный способ. Финальный статус обычно приходит в течение нескольких минут.

Направления

Бразилия

PIX: случайный ключ, телефон, email, CPF, CNPJ. Валюта BRL.

Бангладеш

Банковские счета и мобильные кошельки: Nagad, bKash, Rocket. Валюта BDT.

Россия (СБП)

Переводы на номера телефонов через СБП. Валюта RUB.

Западная Африка

Мобильные деньги (mobile money): MTN, Orange, Wave, Moov и другие. Валюта XOF.

Steam

Пополнение аккаунта Steam по логину. RUB, KZT, UAH, USD.

Создание выплаты

POST /v1/payouts

Параметры запроса

Поле	Тип	Обязательное	Описание
`amount`	number	✅ Да	Сумма выплаты
`currency`	string	✅ Да	Код валюты (ISO 4217)
`paymentType`	string	✅ Да	Тип платежа. Допустимые значения зависят от направления
`account`	object	✅ Да	Реквизиты получателя. Базовые поля приведены ниже; для некоторых направлений нужны дополнительные поля
`serviceId`	number	❌ Нет	Сервис направления из `GET /v1/payouts/services`. Если не указан, используется сервис по умолчанию
`note`	string	❌ Нет	Произвольная заметка к выплате
`externalId`	string	❌ Нет	ID выплаты в вашей системе
`callbackUrl`	string	❌ Нет	URL для webhook-уведомлений по этой выплате. Если не указан, используется адрес из настроек мерчанта

Объект `account`

Базовые поля, обязательные для всех направлений:

Поле	Тип	Обязательное	Описание
`name`	string	✅ Да	Имя получателя
`requisites`	string	✅ Да	Реквизиты получателя: номер карты, номер телефона, PIX-ключ и т. д. в зависимости от `paymentType`
`userId`	string	✅ Да	ID пользователя в вашей системе

Некоторые направления требуют дополнительные поля получателя, например userEmail, userPhone, userIp или bankName. Они перечислены на страницах направлений.

Пример запроса

curl -X POST "https://api.riopay.online/v1/payouts" \
  -H "Content-Type: application/json" \
  -H "X-Api-Token: YOUR_API_TOKEN" \
  -d '{
    "amount": 1000.50,
    "currency": "BRL",
    "paymentType": "EMAIL",
    "externalId": "payout-123",
    "callbackUrl": "https://example.com/webhooks/payouts",
    "account": {
      "name": "John Doe",
      "requisites": "john.doe@example.com",
      "userId": "user_12345"
    },
    "note": "Выплата по заказу №1234"
  }'

Ответ

Успешный запрос возвращает объект выплаты. Тот же объект возвращает endpoint проверки статуса.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "merchantId": "123e4567-e89b-12d3-a456-426614174000",
  "amount": "1000.50",
  "account": {
    "name": "John Doe",
    "requisites": "4111111111111111",
    "userId": "user_12345"
  },
  "status": "CREATED",
  "type": "C2C",
  "requisites": {},
  "statusMessage": null,
  "metadata": null,
  "callbackUrl": null,
  "createdAt": "2023-03-21T12:34:56Z",
  "updatedAt": "2023-03-21T12:34:56Z",
  "completedAt": null
}

Поля объекта выплаты

Поле	Тип	Описание
`id`	string (UUID)	ID выплаты. Используйте его для проверки статуса
`merchantId`	string (UUID)	ID вашего мерчанта
`amount`	string	Сумма выплаты
`account`	object	Реквизиты получателя, переданные в запросе
`status`	string	Текущий статус выплаты, см. Статусы выплат
`type`	string	Тип платежа
`requisites`	object	Дополнительные реквизиты
`statusMessage`	string / null	Описание статуса, если есть
`metadata`	object / null	Дополнительные данные
`callbackUrl`	string / null	URL для webhook-уведомлений по этой выплате (`null` — используются настройки мерчанта)
`createdAt`	string	Время создания (ISO 8601)
`updatedAt`	string	Время последнего обновления (ISO 8601)
`completedAt`	string / null	Время завершения (ISO 8601)

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

Статус	Финальный	Описание
`CREATED`	Нет	Выплата создана
`PROCESSING`	Нет	Выплата обрабатывается
`COMPLETED`	Условно	Выплата успешно завершена
`FAILED`	Да	Ошибка выплаты
`CANCELED`	Да	Выплата отменена
`EXPIRED`	Да	Срок действия выплаты истёк

COMPLETED в штатном режиме финальный. Он меняется только при ручной смене статуса из-за ошибки на стороне банка. Webhook-уведомление о таком изменении автоматически не отправляется: запросите его у вашего менеджера.

CREATED не вызывает отправку webhook; первое уведомление приходит, когда выплата переходит в PROCESSING или в финальный статус.

Проверка статуса выплаты

GET /v1/payouts/{payoutId}

curl -X GET "https://api.riopay.online/v1/payouts/123e4567-e89b-12d3-a456-426614174000" \
  -H "X-Api-Token: YOUR_API_TOKEN"

Используйте webhook-уведомления как основной канал: передайте callbackUrl в запросе или укажите его в настройках мерчанта. Опрашивайте статус по ID только как резервный способ, например каждые 30 минут для выплат, которые ещё не получили финальный статус.