Массовые выплаты на карты

Отправляйте рубли нескольким получателям одним реестром. RollyPay рассчитывает комиссию, резервирует общую сумму в USDT на балансе кассы и отдельно обрабатывает каждую строку. Получатель получает указанную вами сумму в рублях; комиссия добавляется сверху.

Сервис подключается к кассе отдельно. Для серверной интеграции также требуется включённый доступ к массовым выплатам по API. Вывод собственных средств на кошелёк описан в разделе «Выводы».

Порядок работы

Получите доступность сервиса, комиссию, курс и ограничения кассы.
Отправьте список карт и сумм для расчёта. Сохраните id реестра.
Проверьте рублёвые суммы, комиссию и общий расход в USDT.
До expires_at подтвердите реестр со стабильным ключом идемпотентности.
Проверяйте состояние реестра и каждой строки через GET.

Расчёт действует не более пяти минут и может закончиться раньше, если истекает срок доступного курса. До подтверждения деньги не резервируются и переводы не начинаются. При подтверждении резервируется весь реестр; если средств недостаточно или превышены лимиты, частичного запуска реестра не происходит.

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

Аутентификация

Во всех запросах передавайте X-API-Key кассы и новый X-Nonce; см. аутентификацию. Храните ключ на своём сервере. При API-аутентификации terminal_id можно опустить — используется касса ключа. Указать другую кассу этим ключом нельзя.

Параметр api_enabled: true означает, что кассе разрешён запуск через API. Доступ из кабинета и доступ по API включаются отдельно. Пользователь с правом просмотра не может создавать или подтверждать реестры. В кабинете подтверждение также требует код двухфакторной аутентификации, если она включена для выплат.

Не передавайте CVC, срок действия карты или банковские пароли. Полный номер карты нужен только в запросе расчёта; последующие ответы содержат маску.

1. Получить условия

GET /api/v1/mass-payouts/config?terminal_id=TERMINAL_UUID

curl 'https://rollypay.io/api/v1/mass-payouts/config' \
  -H 'X-API-Key: YOUR_ROLLYPAY_API_KEY' \
  -H "X-Nonce: $(uuidgen)"

Пример ответа:

{
  "enabled": true,
  "api_enabled": true,
  "min_amount_rub": "900.00",
  "max_amount_rub": "150000.00",
  "max_batch_items": 100,
  "fee_percent": "3",
  "available_usdt": "150.00000000",
  "rate_rub_per_usdt": "90",
  "rate_available": true
}

Суммы и процент в примере условные. Используйте условия из ответа своей кассы. rate_rub_per_usdt — количество рублей за один USDT для расчёта выплат. При enabled: false или rate_available: false запуск недоступен; не подставляйте собственный курс.

Лимиты на одну карту учитывают уже принятые операции. Дневные и месячные ограничения проверяются при подтверждении; допустимая сумма строки сама по себе не гарантирует, что оставшегося лимита карты достаточно. Сервис не разбивает превышающую лимит выплату на несколько дней автоматически.

2. Рассчитать реестр

POST /api/v1/mass-payouts/quote?terminal_id=TERMINAL_UUID

curl -X POST 'https://rollypay.io/api/v1/mass-payouts/quote' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_ROLLYPAY_API_KEY' \
  -H "X-Nonce: $(uuidgen)" \
  -d '{
    "items": [
      {
        "reference": "seller-123-order-456",
        "card_number": "4111111111111111",
        "amount_rub": "900.00",
        "recipient_name": "Получатель"
      }
    ]
  }'

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

Поле	Обязательно	Описание
`items`	Да	Массив получателей; не больше `max_batch_items` из условий кассы
`reference`	Да	Ваш уникальный в реестре идентификатор строки, до 128 символов
`card_number`	Да	Номер карты получателя; CVC и срок действия не нужны
`amount_rub`	Да	Сумма на карту строкой, не более двух знаков после точки
`recipient_name`	Нет	Имя или подпись получателя для реестра, до 128 символов

Суммы передавайте десятичными строками с точкой, без разделителей тысяч, знака валюты и экспоненциальной записи. Для вычислений используйте десятичную арифметику, а не двоичный float.

Одна карта может встречаться в реестре только один раз. Для повторной выплаты на ту же карту сначала проверьте результат предыдущей операции и действующие лимиты.

Пример ответа:

{
  "id": "33ad2f64-bc8a-4c07-bab0-c61fcbadca84",
  "terminal_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "status": "draft",
  "expires_at": "2026-10-06T12:05:00Z",
  "fee_percent": "3",
  "rate_rub_per_usdt": "90",
  "amount_rub": "900.00",
  "fee_rub": "27.00",
  "total_usdt": "10.30000000",
  "created_at": "2026-10-06T12:00:00Z",
  "items": [
    {
      "id": "e9a8627f-c23c-4b79-9e45-dca14538f393",
      "reference": "seller-123-order-456",
      "masked_card": "•••• 1111",
      "recipient_name": "Получатель",
      "amount_rub": "900.00",
      "fee_rub": "27.00",
      "total_usdt": "10.30000000",
      "status": "draft"
    }
  ]
}

Статус draft означает, что расчёт ещё не подтверждён и деньги не зарезервированы. Сохраните id реестра как quote_id для подтверждения.

Комиссия рассчитывается для каждой строки и округляется вверх до копейки. Затем сумма строки вместе с комиссией переводится в USDT по указанному курсу и округляется вверх до восьми знаков. Итог реестра — сумма итогов строк. При сумме 900 ₽, комиссии 3% и курсе 90 ₽/USDT расход составит 10,30000000 USDT: 900 ₽ получателю и 27 ₽ комиссии.

3. Подтвердить и запустить

POST /api/v1/mass-payouts?terminal_id=TERMINAL_UUID

curl -X POST 'https://rollypay.io/api/v1/mass-payouts' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_ROLLYPAY_API_KEY' \
  -H "X-Nonce: $(uuidgen)" \
  -d '{
    "quote_id": "33ad2f64-bc8a-4c07-bab0-c61fcbadca84",
    "idempotency_key": "settlement-2026-10-06-001"
  }'

Подтверждение запускает реальные выплаты. Ответ содержит тот же реестр с текущими статусами. В запросе кабинета при включённой двухфакторной аутентификации дополнительно передаётся two_factor_code.

Сохраните idempotency_key до запроса; максимальная длина — 128 байт. При тайм-ауте или потерянном ответе повторите подтверждение с теми же quote_id и idempotency_key, но новым X-Nonce. Смена реестра при прежнем ключе приводит к конфликту 409. Не создавайте замену новым ключом, пока не проверили сохранённый реестр: перевод мог уже начаться.

Если неподтверждённый расчёт истёк, получите новый расчёт и проверьте изменившиеся условия. Для нового реестра используйте новый ключ. Истечение expires_at у уже запущенного реестра не отменяет обработку.

4. Проверить состояние

GET /api/v1/mass-payouts/{id}?terminal_id=TERMINAL_UUID

curl 'https://rollypay.io/api/v1/mass-payouts/33ad2f64-bc8a-4c07-bab0-c61fcbadca84' \
  -H 'X-API-Key: YOUR_ROLLYPAY_API_KEY' \
  -H "X-Nonce: $(uuidgen)"

Возвращается объект реестра со строками. Статусы отдельных получателей могут отличаться.

Статус реестра	Значение
`draft`	Расчёт создан; подтверждение ещё не выполнено
`queued`	Реестр принят, средства зарезервированы
`processing`	Выплаты выполняются
`review`	Результат одной или нескольких строк уточняется
`completed`	Все строки успешно выплачены
`partial`	Обработка завершена: часть строк успешна, часть завершилась отказом
`failed`	Все строки завершились отказом

Статус строки	Значение
`draft`	Строка неподтверждённого расчёта
`queued`	Строка принята и ожидает отправки
`sending`	Отправка начата; результат ещё не получен
`processing`	Перевод обрабатывается
`review`	Результат уточняется; резерв сохраняется
`completed`	Выплата успешно завершена
`failed`	Подтверждён отказ; резерв строки освобождён

У неуспешной строки может присутствовать failure_code. При обращении в поддержку передавайте id реестра и строки, время операции и этот код. Полный номер карты отправлять не нужно.

Не считайте review, сетевую ошибку или длительное ожидание подтверждённым отказом. Не запускайте такую строку повторно новым реестром до выяснения результата. Финальным подтверждением выплаты служит completed у строки.

Для получения результата используйте периодический GET с паузой и увеличивайте интервал при сетевых ошибках. Отдельные уведомления о массовых выплатах не предусмотрены этим API.

История реестров

GET /api/v1/mass-payouts?terminal_id=TERMINAL_UUID&limit=20&offset=0

Ответ содержит items — массив реестров, а также limit и offset. Для следующих страниц увеличивайте offset на limit. Полный состав конкретного реестра запрашивайте по его id.

limit принимает значения от 1 до 100; по умолчанию — 25. offset начинается с 0.

Ошибки

HTTP	Значение и действие
`400`	Некорректное тело, карта, сумма или обязательное поле; исправьте запрос
`401`	Ошибка аутентификации; проверьте ключ и новый `X-Nonce`
`403`	Недостаточно прав, сервис или API-доступ кассы отключён
`404`	Реестр не найден или недоступен в контексте кассы
`409`	Конфликт ключа, истёкший расчёт, недостаточный баланс или превышение лимита; проверьте причину и текущее состояние реестра
`429`	Слишком много незавершённых расчётов или попыток подтверждения; выдержите паузу, указанную в ответе
`503`	Расчёт или обработка сейчас недоступны; сохраните идентификаторы и повторите проверку позднее

Успешное подтверждение означает приём реестра в обработку. Срок зачисления зависит от обработки конкретной строки; фиксированное время зачисления этим API не гарантируется.

Массовые выплаты на карты

Порядок работы​

Аутентификация​

1. Получить условия​

2. Рассчитать реестр​

3. Подтвердить и запустить​

4. Проверить состояние​

История реестров​

Ошибки​