Payin8Документация

Для мерчантов

Документация Payin8

Руководство по кабинету мерчанта и справочник API: где взять настройки, куда их прописать и как устроены запросы.

Кабинет

Быстрый старт#

Кабинет мерчанта — место, где вы получаете всё, что нужно вашему серверу для работы с API Payin8: ключ и секрет для подписи запросов, секрет подписи вебхуков, настройки страницы оплаты. Здесь же вы видите сделки, баланс, споры и управляете командой.

Названия пунктов меню, вкладок и кнопок ниже даны так, как они написаны в кабинете на русском языке. Какие пункты меню вы видите, зависит от прав вашей роли (см. Команда и роли).

От приглашения до первой сделки#

  1. Примите приглашение. Первого сотрудника вашей организации (владельца) приглашает площадка Payin8. Откройте ссылку из приглашения, задайте пароль и войдите. Подробно — в разделе Вход и учётная запись.
  2. Включите второй фактор. Для владельца он обязателен: пока он не настроен, кабинет недоступен. Сохраните коды восстановления — они показываются один раз.
  3. Проверьте проект. Проекты заводит площадка. Откройте Подключение → Проекты, выберите проект и посмотрите вкладку «Методы и пределы»: включены ли нужные направления (приём, выплата), какие пределы суммы и какой тариф. Если для направления не назначен тариф, сделки по нему не создаются. См. Организация и проекты.
  4. Выпустите ключ API. Подключение → Ключи API → «Выпустить ключ»: выберите проект, задайте название, права и IP-адреса вашего сервера. Сохраните идентификатор ключа и секрет — секрет показывается один раз. См. Ключи API.
  5. Настройте вебхук. Подключение → Проекты → проект → вкладка «Вебхук» → «Настроить»: укажите адрес и события. После первого сохранения кабинет один раз покажет секрет подписи. Нажмите «Проверить», чтобы отправить проверочное событие. См. Вебхуки.
  6. Оформите страницу оплаты. Вкладка «Страница оплаты» проекта (или Организация → Профиль и правила для всех проектов сразу): название магазина, логотип, цвет, контакты поддержки, адреса возврата на ваш сайт. См. Страница оплаты.
  7. Проверьте правила. Вкладка «Правила» проекта: «Язык страницы оплаты», «Обязателен чек клиента», «Позднее подтверждение приёмов», «Выплата без денег на балансе». См. Правила.
  8. Создайте первую сделку. Ваш сервер отправляет подписанный запрос на создание приёма — см. Приёмы и Подпись запросов. Сделка появится в разделе Приёмы, событие вебхука — в Подключение → Доставка вебхуков.
  9. Для выплат нужен баланс (он пополняется зачислениями по приёмам или переводом USDT, Деньги → Пополнение) и ключ с правом «Создавать выплаты» и непустым списком IP-адресов. См. Выплаты.
  10. Пригласите команду: Организация → Команда → «Пригласить». См. Команда и роли.

Внимание

После некоторых изменений безопасности (вход по коду восстановления, сброс пароля по ссылке, повторная настройка второго фактора) кабинет на время закрывает выпуск ключей, изменение вебхука, добавление адресов вывода и вывод. По умолчанию — на 24 часа. Подробно — в разделе Безопасность.

Что нужно для подключения и где это взять#

Что нужно Где взять в кабинете Куда прописать у себя
Адрес API — Базовый адрес запросов вашего сервера: https://api.payin8.io (см. Обзор API)
Идентификатор ключа Подключение → Ключи API → «Выпустить ключ», окно «Секрет ключа», поле «Ключ». Позже — в карточке ключа, поле «Ключ» Заголовок X-Api-Key каждого запроса
Секрет ключа То же окно, поле «Секрет». Показывается один раз Хранилище секретов сервера; им подписывается каждый запрос (заголовок X-Signature, см. Подпись запросов)
Заголовки и строка подписи То же окно, блоки «Заголовки запроса» и «Строка подписи (шесть строк)» — образец Код подписи запросов; подробности — Подпись запросов
IP-адреса вашего сервера Вы задаёте их сами: поле «Адреса» в окне «Новый ключ» или «Изменить ключ» Если список не пуст, Payin8 принимает запросы с этим ключом только с этих адресов
Адрес вебхука Вы задаёте его сами: Подключение → Проекты → проект → «Вебхук» → «Настроить», поле «Адрес» Обработчик на вашем сервере, который принимает POST-запросы Payin8
Секрет подписи вебхука Окно «Секрет подписи» после первого сохранения вебхука или после «Заменить секрет». Показывается один раз Проверка подписи входящих вебхуков (см. Вебхуки)
События вебхука Там же, блок «События» Обработчик вебхуков: какие типы событий ждать
ID проекта Подключение → Проекты → проект → «Обзор», поле «ID проекта» Для сверки и обращений в поддержку; ключ уже привязан к проекту
Пределы суммы сделки и тариф Подключение → Проекты → проект → «Методы и пределы» Проверка суммы заказа до создания сделки; доступные методы ваш сервер может узнать и через API (см. Обзор API)
Адреса возврата на ваш сайт Подключение → Проекты → проект → «Страница оплаты» → «Изменить», блок «Возврат на ваш сайт» Страницы вашего сайта после успешной и неудачной оплаты; адрес, переданный с приёмом через API, важнее (см. Приёмы)
Название, логотип, цвет, поддержка на странице оплаты Там же —
Ссылка на оплату для клиента Карточка приёма, блок «Ссылка на оплату» Можно переслать клиенту, если он потерял страницу
Домен страницы оплаты В кабинете не настраивается Обратитесь в поддержку Payin8 (см. Страница оплаты)
Адрес для вывода (USDT, сеть TRON) Деньги → Кошельки → «Добавить адрес» Ваш кошелёк; выводить на новый адрес можно после паузы — по умолчанию через 24 часа после добавления
Адрес для пополнения (USDT, сеть TRON) Деньги → Пополнение Перевод USDT со своего кошелька для пополнения баланса

Кабинет

Вход и учётная запись#

Приглашение#

В кабинет попадают только по приглашению. Владельца организации приглашает площадка Payin8, остальных сотрудников — владелец или участник команды с правом приглашать (см. Команда и роли).

  1. Откройте ссылку приглашения. На странице «Приглашение» видны роль, которую вы получите, и срок действия ссылки («Действует до»).
  2. Укажите имя («Ваше имя (необязательно)»), введите «Новый пароль» и «Повторите пароль».
  3. Нажмите «Задать пароль», затем войдите с вашей почтой и новым паролем.

Требования к паролю (кабинет показывает их под полем):

  • длина от 12 до 128 символов (площадка может поднять нижнюю границу);
  • пароль не содержит часть почты до @, если в ней 4 знака и больше (без учёта регистра);
  • оба поля совпадают.

Ссылка приглашения по умолчанию действует 72 часа (срок задаёт площадка). Каждая новая ссылка отменяет прежнюю. Если ссылка истекла, попросите владельца кабинета (или площадку, если приглашала она) прислать приглашение снова.

Примечание

Ссылка приглашения открывается только в том кабинете, для которого выпущена. Если вы открыли её не там, страница подскажет, где её открыть.

Вход#

  1. На странице «Вход» введите «Почта» и «Пароль», нажмите «Войти».
  2. Если у вас включён второй фактор, введите 6-значный код из приложения-аутентификатора. Если телефона нет под рукой, нажмите «Нет доступа к приложению — ввести код восстановления».

На ввод кода после пароля отводится 5 минут; после этого вход нужно начать заново.

После нескольких неудачных попыток подряд вход для учётной записи временно блокируется: по умолчанию после 5 неверных паролей за 15 минут — на 15 минут (числа задаёт площадка).

Забыли пароль? Самостоятельного восстановления нет. Попросите владельца кабинета выпустить ссылку для нового пароля (Организация → Команда → сотрудник → «Ссылка для пароля») или обратитесь в поддержку Payin8. Ссылка одноразовая и по умолчанию действует 30 минут. После смены пароля по ссылке все сеансы завершаются, второй фактор остаётся, а чувствительные действия на время закрываются (см. Безопасность).

Второй фактор#

Второй фактор — одноразовые коды из приложения-аутентификатора (Google Authenticator, 1Password и другие).

  • Для роли владельца и для ролей с правами, которые требуют свежий код, второй фактор обязателен: без него кабинет недоступен, при первом входе откроется экран «Защитите вход».
  • Для остальных ролей он необязателен, но без него недоступны вывод, ключи API и управление командой.

Как включить:

  1. Если кабинет не предложил настройку сам, откройте меню «Учётная запись» (значок в правом верхнем углу) → «Профиль и безопасность», блок «Второй фактор», нажмите «Включить».
  2. Введите «Текущий пароль» и нажмите «Начать».
  3. Отсканируйте QR-код приложением или введите «Секрет» вручную. Введите «Код из приложения» и нажмите «Проверить». На настройку отводится 10 минут.
  4. Сохраните коды восстановления и нажмите «Я сохранил коды».

Если код не подходит, проверьте, что время на телефоне выставляется автоматически.

Перенос на новый телефон. «Профиль и безопасность» → «Перенести на другой телефон»: подтвердите кодом со старого устройства и отсканируйте новый QR-код. При переносе выпускаются новые коды восстановления, а ваши сеансы на других устройствах завершаются.

Выключить второй фактор можно только если ваша роль его не требует («Выключить», с текущим паролем и кодом).

Телефон потерян и кодов нет. Попросите владельца кабинета сбросить вам второй фактор (Организация → Команда → сотрудник → «Сбросить второй фактор»); владельцу — обратитесь в поддержку Payin8. После сброса вы настроите второй фактор заново при следующем входе.

Коды восстановления#

При включении второго фактора кабинет выдаёт 10 кодов восстановления. Они показываются один раз: нажмите «Скопировать все» или «Скачать .txt» и храните их там же, где пароли.

  • Каждый код срабатывает один раз.
  • Вход по коду восстановления на время закрывает чувствительные действия (см. Безопасность).
  • Когда кодов остаётся мало, кабинет предупредит. Новый набор — «Профиль и безопасность» → «Новые коды восстановления» (нужен код из приложения). Прежние коды при этом перестают действовать.

Подтверждение действий кодом#

Чувствительные действия — выпуск и изменение ключа API, замена секрета, настройка вебхука, изменение проекта и страницы оплаты, добавление адреса вывода и вывод, управление командой и ролями — кабинет подтверждает свежим кодом из приложения (окно «Подтвердите действие»).

  • Один код подтверждает одно действие. Если код уже использован, дождитесь следующего — кабинет покажет, через сколько секунд он появится.
  • После нескольких неудачных попыток ввода кода (по умолчанию 5 за 15 минут) все ваши сеансы завершаются — войдите снова.

Отзыв ключа API и повторная отправка вебхука кода не требуют: защитные действия должны выполняться быстро.

Пароль#

«Профиль и безопасность» → блок «Пароль»: введите «Текущий пароль», новый пароль дважды и нажмите «Сменить пароль». Ваши сеансы на других устройствах завершаются, текущий остаётся. Новый пароль не должен совпадать с прежним.

Сеансы#

Блок «Сессии» в «Профиль и безопасность» показывает, где вы сейчас вошли: когда начата сессия, последняя активность и способ входа («только пароль», «с кодом», «с кодом восстановления»).

  • «Завершить» — закрыть одну сессию.
  • «Выйти на других устройствах» — закрыть все, кроме текущей.
  • В меню «Учётная запись»: «Выйти» — из этого браузера, «Выйти везде» — на всех устройствах.

Сессия завершается сама после 24 часов без активности и не позже чем через 7 дней после входа (сроки задаёт площадка). Точное время видно в поле «Сессия истечёт не позже».

Язык, тема и часовой пояс#

  • Язык — меню языка в шапке кабинета: English, Español, Русский.
  • Тема — меню «Тема» в шапке: «Светлая», «Тёмная», «Как в системе».
  • Часовой пояс — «Профиль и безопасность» → блок «Отображение» → «Часовой пояс». По умолчанию — часовой пояс браузера.

Язык и тема также есть в блоке «Отображение». Эти настройки хранятся только в текущем браузере.

Для быстрого перехода по кабинету есть поиск в шапке («Поиск…»): раздел, номер сделки или идентификатор.

Кабинет

Организация и проекты#

Организация#

Организация → Профиль и правила — данные вашей организации в Payin8:

  • «Контакты» — «Почта» и «Telegram», по которым площадка связывается с вами по вашему аккаунту. Клиентам они не показываются. Изменить — кнопка «Изменить» (нужно право «Менять контакты»); пустое поле удаляет контакт.
  • «Организация», «Статус» и «С площадкой с».
  • Блок «Lead» — если вас привёл партнёр площадки: кто он, с какого числа, что он видит и какие ваши настройки может менять. Lead видит ваши сделки без данных клиентов и реквизитов; каждое его изменение попадает в «Журнал действий».
  • «Правила по умолчанию» — значения правил для всех проектов (см. ниже).
  • «Страница оплаты по умолчанию» — оформление страницы оплаты для всех проектов (см. Страница оплаты).

Что такое проект#

Проект — источник ваших приёмов и выплат: например, отдельный сайт или приложение. У каждого проекта свои методы оплаты, пределы сумм, тариф, правила, ключи API, вебхук и страница оплаты. Ключ API принадлежит одному проекту, поэтому сделки, созданные этим ключом, относятся к этому проекту.

Проекты, их методы, пределы и тарифы заводит площадка. Если нужен ещё один проект или другие пределы, обратитесь в поддержку Payin8.

Список проектов#

Подключение → Проекты — таблица: «Название», «Статус», «Методы» (приём, выплата), «Создан». Фильтр — по статусу. Нажмите на проект, чтобы открыть карточку.

Статусы проекта:

Статус Что значит
«Активен» Проект принимает новые сделки
«отключён вами» Вы выключили проект; новые приёмы и выплаты отклоняются, сделки в работе доходят до конца
«отключён площадкой» Проект выключила площадка; включить его может только она

Карточка проекта#

Вкладки карточки (каждая видна, если у вашей роли есть право на неё):

Вкладка Что там
«Обзор» «ID проекта», статус, причина и время последнего изменения статуса, дата создания
«Методы и пределы» Для каждого метода и валюты: включены ли приём и выплата и в каких пределах суммы; блок «Тариф»
«Правила» Правила проекта (см. ниже)
«Ключи API» Короткий список ключей проекта и ссылка «Все ключи проекта»
«Вебхук» Адрес, события и секреты подписи вебхука проекта (см. Вебхуки)
«Страница оплаты» Оформление страницы оплаты проекта и адреса возврата (см. Страница оплаты)

Действия в шапке карточки (каждое подтверждается кодом из приложения):

  • «Переименовать» — новое название, от 1 до 60 символов.
  • «Выключить» — можно указать причину (3–500 символов, необязательно). Новые приёмы и выплаты проекта отклоняются; сделки в работе доходят до конца.
  • «Включить» — проект снова принимает новые сделки. Проект, выключенный площадкой, включить из кабинета нельзя.

Методы, пределы и тариф#

Вкладка «Методы и пределы» показывает, что настроено для проекта:

  • метод (например, «Банковский перевод») и валюта;
  • «приём» и «выплата» — наименьшая и наибольшая сумма одной сделки или «выключено»;
  • блок «Тариф» — для каждого включённого направления: ставка комиссии (процент, а также минимум и фиксированная часть, если они заданы) и откуда она взята: «задан для этого проекта» или «задан для всей организации».

Если для включённого направления тариф не назначен, кабинет показывает предупреждение «Тариф не назначен: сделки по этому направлению не создаются». Пределы и тариф меняет площадка.

Комиссию по каждой сделке видно в её карточке (см. Сделки). Доступные методы ваш сервер может узнать и через API — см. Обзор API.

Правила#

Правила — настройки работы сделок. Их видно на вкладке «Правила» проекта и в блоке «Правила по умолчанию» на странице «Профиль и правила». Рядом со значением указано, откуда оно взято: «по умолчанию площадки», «по умолчанию площадки для валюты», «задано для организации» или «задано для проекта».

Как работает наследование: значение проекта важнее значения организации, значение организации важнее значения площадки по умолчанию. Кнопка «Изменить» задаёт своё значение (окно «Изменить правило»). Кнопка «Наследовать» убирает своё значение, и снова действует значение уровнем выше (нужно право «Сбрасывать правила»).

Правила, которые вы можете менять сами (нужно право «Менять правила»):

Правило Значения По умолчанию
«Позднее подтверждение приёмов» «включено» / «выключено». Если выключено, приём с истёкшим сроком оплаты не подтверждается позже включено
«Выплата без денег на балансе» «отклонить сразу» / «ждать пополнения» (выплата ждёт пополнения баланса до конца своего срока) отклонить сразу
«Обязателен чек клиента» «включено» / «выключено». Если включено, клиент прикладывает чек перевода на странице оплаты перед тем, как сообщить об оплате выключено
«Язык страницы оплаты» «как у приёма» / «испанский» / «английский» как у приёма

Правила, которые задаёт площадка (в кабинете помечены «задаёт площадка»):

Правило По умолчанию
«Срок оплаты приёма» — сколько времени у клиента на оплату после выдачи реквизитов 15 мин
«Окно позднего подтверждения после срока оплаты» 24 ч
«Сколько выплата ждёт исполнителя» — от создания выплаты, включая ожидание денег на балансе 4 ч
«Срок, в который можно открыть спор по сделке» — от создания сделки 7 дн.

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

Кабинет

Ключи API#

Ключ API — то, чем ваш сервер подписывает запросы к API Payin8. Ключ состоит из двух частей:

  • идентификатор ключа — передаётся открыто в заголовке X-Api-Key;
  • секрет — хранится только у вас; им вычисляется подпись X-Signature. В запросах сам секрет не передаётся.

Как устроены заголовки и подпись — в разделе Подпись запросов.

Где ключи#

Подключение → Ключи API — все ключи ваших проектов. Колонки: «Название», «Проект», «Статус», «Права» (число), «Адреса», «Последнее использование», «Секрет» (последние 4 знака), «Выпущен». Фильтры — по проекту и статусу.

Ключи одного проекта видны и в карточке проекта, вкладка «Ключи API».

Статусы ключа: «действует», «отзовётся» (ключ заменён и перестанет работать в указанное время), «отозван».

Выпуск ключа#

  1. Подключение → Ключи API → «Выпустить ключ».
  2. Заполните окно «Новый ключ»:
    • «Название» — от 1 до 60 символов, чтобы отличать ключи между собой;
    • «Проект» — ключ принадлежит одному проекту;
    • «Права» — что ключу разрешено (см. ниже);
    • «Адреса» — IP-адреса вашего сервера, по одному в строке (см. ниже).
  3. Подтвердите кодом из приложения.
  4. Откроется окно «Секрет ключа» с полями «Ключ» (идентификатор) и «Секрет», а также образцами «Заголовки запроса» и «Строка подписи (шесть строк)». Скопируйте ключ и секрет в хранилище секретов вашего сервера и нажмите «Я сохранил секрет».

Внимание

Секрет показывается один раз. Payin8 не сможет показать его снова. Если секрет потерян, замените его («Заменить секрет») или выпустите новый ключ.

Сколько ключей. По умолчанию у проекта может быть не больше 2 действующих ключей (площадка может изменить это число). Ключ, который заменён, но ещё работает, тоже считается.

Права ключа#

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

Право в кабинете Что разрешает
«Создавать приёмы», «Читать приёмы», «Отменять приёмы» Работа с приёмами — см. Приёмы
«Создавать выплаты», «Читать выплаты и их чеки», «Отменять выплаты» Работа с выплатами — см. Выплаты
«Читать баланс» Баланс — см. Баланс
«Открывать споры», «Читать споры» Споры — см. Споры
«Читать методы оплаты» Методы оплаты проекта
«Загружать файлы» Чеки и другие файлы — см. Файлы

Права «Создавать выплаты» и «Отменять выплаты» помечены как права на деньги. Выдать их ключу может только владелец или участник команды с правом «Давать ключам API права на деньги». Остальные увидят такие права недоступными. Менять права и адреса ключа, у которого уже есть права на деньги, и заменять его секрет может тоже только тот, кто вправе эти права выдать.

Список IP-адресов#

В поле «Адреса» укажите IP-адреса, с которых ваши серверы обращаются к API: по одному в строке, можно диапазоном CIDR, до 20 строк.

  • Если список пуст, ключ работает с любого адреса («любой адрес»).
  • Для создания выплат и для приёмов, в ответе на которые сразу выдаются реквизиты для оплаты, ключу нужен непустой список адресов. Без него такой запрос получит отказ ip_allowlist_required (см. Ошибки). Какие операции требуют список, задаёт площадка.
  • Диапазон не может быть шире /24 для IPv4 и /56 для IPv6.

Мы рекомендуем ограничивать адреса у каждого ключа.

Изменение ключа#

Карточка ключа (нажмите на ключ в списке) → «Изменить»: название, адреса и права. Изменение подтверждается кодом из приложения и действует сразу, идентификатор и секрет не меняются.

В карточке также видно: «Ключ» (идентификатор), «Проект», последние знаки секрета, «Последнее использование», «Выпустил», «Выпущен», список адресов и прав.

Замена секрета#

Карточка ключа → «Заменить секрет». В поле «Старый секрет работает» выберите, сколько старый ключ ещё будет работать: «перестаёт сразу», «ещё час», «ещё сутки» (выбрано по умолчанию), «ещё 7 дней». Подтвердите кодом из приложения.

Кабинет покажет окно «Секрет ключа» с новым идентификатором ключа и новым секретом — замените оба значения на сервере. Название, права и адреса переходят к новому ключу. Старый ключ получает статус «отзовётся» и перестаёт работать в выбранное время.

Совет

Пока старый ключ работает, он занимает место в лимите действующих ключей проекта. Если у проекта уже 2 действующих ключа, замена с перекрытием не пройдёт: выберите «перестаёт сразу» или сначала отзовите лишний ключ.

Отзыв ключа#

  • Карточка ключа → «Отозвать». Можно оставить «Заметка». Запросы с этим ключом сразу перестают проходить. Отменить отзыв нельзя.
  • Подключение → Ключи API → «Отозвать все»: выберите проект и введите слово «ОТОЗВАТЬ». Все действующие ключи проекта сразу перестают работать.

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

Кому это доступно#

Действие Право роли
Видеть ключи «Видеть ключи API»
«Выпустить ключ» «Выпускать ключи API»
«Изменить» «Менять ключи API»
«Заменить секрет» «Заменять секрет ключа»
«Отозвать» «Отзывать ключи API»
«Отозвать все» «Отзывать все ключи API разом»
Выдавать права на деньги Владелец или «Давать ключам API права на деньги»

У системных ролей «Operator» и «Viewer» доступа к ключам нет. Выпуск, изменение и замена секрета требуют включённого второго фактора и на время закрываются после изменений безопасности (см. Безопасность).

Кабинет

Вебхуки#

Вебхук — POST-запрос с JSON, который Payin8 отправляет на адрес вашего сервера, когда меняется сделка или спор. У каждого проекта один адрес вебхука. Каждый запрос подписан секретом подписи. Формат тела, заголовки и проверка подписи — в разделе Вебхуки.

Где задать адрес#

  1. Подключение → Проекты → проект → вкладка «Вебхук».
  2. Нажмите «Настроить» (если адрес ещё не задан) или «Изменить».
  3. Заполните форму:
    • «Адрес» — адрес обработчика на вашем сервере;
    • «События» — на какие события подписаться (см. ниже); хотя бы одно;
    • «Отправлять события» — выключатель. Выключенный адрес сохраняет настройки, но доставки, ожидающие в очереди, отменяются.
  4. Нажмите «Сохранить» и подтвердите кодом из приложения.

Требования к адресу (кабинет проверяет их сразу):

  • только https://;
  • имя хоста с доменом, не IP-адрес;
  • без логина и пароля в адресе и без части после #;
  • не длиннее 2048 символов;
  • порт — 443 или 8443 (список допустимых портов задаёт площадка);
  • адрес не должен вести во внутреннюю сеть; адреса некоторых доменов не допускаются.

Если поменять адрес, доставки, которые ещё повторяются, пойдут уже на новый адрес.

Где взять секрет подписи#

При первом сохранении вебхука Payin8 создаёт секрет подписи и показывает его один раз в окне «Секрет подписи». Сохраните его в хранилище секретов вашего сервера и нажмите «Я сохранил секрет».

Внимание

Payin8 не хранит секрет подписи в читаемом виде. Если вы его потеряли, замените секрет.

Замена секрета. Вкладка «Вебхук» → «Заменить секрет» → подтвердите кодом из приложения. Новый секрет показывается один раз. Прежний секрет ещё какое-то время (по умолчанию 24 часа, срок задаёт площадка) подписывает запросы вместе с новым: в заголовке подписи в это время два значения v1. Это даёт время переключить сервер на новый секрет без потери событий. В блоке «Секреты подписи» видно, какой секрет «текущий», какой «уходящий» и до какого времени он подписывает.

Краткая памятка по проверке подписи есть на вкладке, блок «Как проверить подпись»; полное описание — в разделе Вебхуки.

События#

Событие в кабинете Тип Когда приходит
«Приём: выдан счёт» payin.assigned Приёму назначены реквизиты для оплаты
«Приём зачислен» payin.completed Приём завершён, деньги зачислены на баланс
«Приём не состоялся» payin.failed Приём закрыт без оплаты
«Сумма приёма изменена» payin.amount_changed Клиент заплатил другую сумму, сумма приёма изменена
«Выплата исполнена» payout.completed Выплата исполнена
«Выплата не состоялась» payout.failed Выплата закрыта без исполнения
«Открыт спор» dispute.opened По сделке открыт спор
«Спор закрыт» dispute.closed Спор закрыт
«Проверка» webhook.ping Вы нажали «Проверить»

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

Проверочное событие. Кнопка «Проверить» на вкладке «Вебхук» отправляет событие «Проверка» на текущий адрес. После отправки можно сразу перейти к нему: «Открыть в журнале».

Журнал доставок#

Подключение → Доставка вебхуков — каждое событие ваших проектов, его доставки и попытки.

  • Колонки: «Создан», «Событие», «Проект», «Сделка», «Доставка» (статус), «Попыток», «Последний ответ», «Следующая попытка».
  • Фильтры: «Проект», «Событие», «Доставка» и период — не длиннее 31 дня.
  • Карточка события: «Тело, как отправлено» и все доставки с попытками — время, длительность, адрес, код ответа или ошибка.

Статусы доставки:

Статус Что значит
«В очереди» Доставка ещё идёт: попытка запланирована
«Доставлено» Ваш сервер ответил кодом 2xx
«Не доставлено» Окно повторов закончилось без успешного ответа
«Отменено» Доставку отменили: например, адрес выключили, пока она ждала в очереди

Если у события нет доставок, значит в момент события адрес не был задан, был выключен или не подписан на этот тип события. Такие события сохраняются в журнале, но после настройки адреса автоматически не отправляются — их можно отправить вручную (см. ниже).

Все события одной сделки видны и из её карточки: вкладка «Вебхуки» → «Открыть доставки этой сделки».

На вкладке «Вебхук» проекта блок «Доставка» показывает, как отвечает адрес: прошла ли последняя доставка, сколько неудачных попыток подряд, «Последний ответ» и «Последняя попытка».

События и доставки хранятся 90 дней, журнал попыток — 30 дней (сроки задаёт площадка).

Повторы и повторная отправка#

Доставка считается успешной, если ваш сервер ответил кодом 2xx. Отвечайте быстро: по умолчанию Payin8 ждёт соединения не дольше 5 секунд, а весь запрос — не дольше 10 секунд. Иначе Payin8 повторяет её с растущей паузой: первая пауза около 10 секунд, затем каждая вдвое длиннее, но не больше 6 часов. Повторы идут в течение 24 часов после события; последняя попытка — в самом конце этого окна. После этого доставка получает статус «Не доставлено». Расписание задаёт площадка.

Отправить снова. В карточке события в журнале — кнопка «Отправить снова». Если доставка ещё в очереди, попытка выполняется сразу; иначе создаётся новая доставка того же тела на текущий адрес проекта, с новым 24-часовым окном повторов. Отправить снова можно, пока событие хранится, и только если адрес вебхука включён. Массовой повторной отправки в кабинете нет.

Что будет при долгих сбоях#

  • Payin8 не выключает адрес автоматически из-за неудачных доставок: каждое новое событие доставляется со своим окном повторов.
  • Если ваш сервер не отвечал дольше окна повторов, доставки получат статус «Не доставлено». После восстановления отправьте нужные события вручную («Отправить снова») или сверьте состояние сделок через API (см. Приёмы, Выплаты).
  • Площадка может выключить вебхук сама. Тогда на вкладке видно «выключен площадкой»: события сохраняются, но не отправляются, и включить адрес снова может только площадка — обратитесь в поддержку Payin8.

Кому это доступно#

Действие Право роли
Видеть вкладку «Вебхук» и журнал доставок «Видеть вебхуки»
«Настроить», «Изменить», «Заменить секрет» «Менять настройки вебхуков» (с кодом из приложения)
«Проверить», «Отправить снова» «Переотправлять события вебхуков»

Системная роль «Operator» может отправлять события снова, но не менять настройки. Изменение настроек вебхука на время закрывается после изменений безопасности (см. Безопасность).

Кабинет

Баланс и пополнения#

Обзор#

Раздел Обзор — первая страница кабинета: баланс и счётчики сделок прямо сейчас: сколько приёмов ждут оплату или клиент сообщил об оплате, сколько выплат созданы, ищут исполнителя или исполняются, сколько сделок, созданных за последние 24 часа, уже завершены или истекли, сколько заявок на вывод ждут одобрения. Нажмите на счётчик, чтобы открыть отфильтрованный список. Ниже — «Последние сделки».

Баланс#

Деньги → Баланс и выписка — деньги организации по валютам. Для каждой валюты:

Поле Что значит
«Доступно» Деньги, которые можно тратить на выплаты и выводить
«Заморожено» Деньги под выплатами в работе и заявками на вывод
«Всего» Сумма доступного и замороженного

Замороженные деньги вернутся в «Доступно», если выплату отменят или заявку на вывод отклонят. Под карточками показан ориентир «В USDT по курсу вывода» — сколько USDT примерно получится при выводе всего баланса.

Как двигаются деньги:

  • Приём. Когда приём завершён, на «Доступно» зачисляется сумма, которую заплатил клиент, за вычетом комиссии по тарифу.
  • Выплата. При создании выплаты замораживается сумма, которая спишется с баланса. Когда выплата исполнена, замороженное списывается; при частичном исполнении остаток возвращается в «Доступно». Если денег не хватает, выплата отклоняется сразу или ждёт пополнения — это задаёт правило «Выплата без денег на балансе» (см. Правила).
  • Вывод. Заявка на вывод замораживает песо до решения площадки (см. Кошельки и вывод).
  • Пополнение. Перевод USDT зачисляется в песо (см. ниже).

Баланс можно получить и через API — см. Баланс.

Выписка#

Под карточками — «Выписка»: каждое движение денег по одной валюте.

  • Фильтры: «Валюта», «Операции» («Все операции», «Приёмы», «Выплаты», «Выводы», «Пополнения», «Корректировки»), «Корзина» («Доступно», «Заморожено», «Обе») и период — до 366 дней.
  • Колонки: «Время», «Операция», «Документ» (сделка, вывод, пополнение или корректировка — со ссылкой), «Часть» (доступно или заморожено), «Изменение», «Остаток после».
  • «Итоги периода» — «На начало», «На конец», «Поступления», «Списания» и разбивка «По операциям». Итоги считаются для периода до 92 дней.

Основные операции выписки:

Операция Что произошло
«Зачисление по приёму» Приём завершён, деньги за вычетом комиссии зачислены
«Зачисление по приёму (оплата после срока)» То же, но оплата подтверждена после срока
«Отмена зачисления по спору» Зачисление по приёму отменено решением по спору
«Заморожено под выплату» Сумма выплаты заморожена
«Разморожено: выплата отменена» Выплата отменена, деньги вернулись в «Доступно»
«Выплата исполнена (остаток при частичной — на баланс)» Выплата исполнена, замороженное списано
«Возврат выплаты по спору» Выплата возвращена решением по спору
«Вывод: заморожено» / «Вывод: разморожено» / «Вывод: выполнен» Движения заявки на вывод
«Пополнение USDT» Зачислено пополнение
«Зачисление площадкой» / «Списание площадкой» Ручная корректировка площадки

Пополнение#

Баланс можно пополнить переводом USDT — например, чтобы хватало денег на выплаты.

  1. Откройте Деньги → Пополнение. Там указаны адрес площадки в сети TRON (с QR-кодом), «Минимум» и «Курс пополнения сейчас».
  2. Переведите USDT (TRC-20) на этот адрес со своего кошелька.
  3. После нужного числа подтверждений сети площадка зачисляет песо по курсу пополнения на момент зачисления. Зачисление появится в истории «Пополнения» и в выписке как «Пополнение USDT».

Внимание

Переводы меньше минимума не зачисляются. По умолчанию минимум — 10 USDT; действующее значение показано на странице. Переводите только USDT в сети TRON.

Перевод регистрирует площадка по хешу транзакции; до этого его нет в истории. Если перевод долго не появляется, сообщите хеш транзакции в поддержку Payin8.

История «Пополнения»: «№», «Зарегистрировано», «Перевод» (хеш со ссылкой «Открыть в обозревателе»), «Сумма», «Статус», «Курс», «Зачислено», «Зачислено в». Статусы: «Зарегистрировано», «Зачислено», «Отклонено», «Возвращено».

Если на странице написано «Пополнение не настроено», пополнение для вас сейчас недоступно — обратитесь в поддержку Payin8.

Кому это доступно#

Что Право роли
«Баланс и выписка» «Видеть баланс и выписку»
Пересчёт в USDT, курсы «Видеть курсы»
Страница «Пополнение» «Видеть адрес пополнения»
История пополнений «Видеть пополнения»

Кабинет

Кошельки и вывод#

Вывод обменивает песо с баланса на USDT по курсу площадки и отправляет их на ваш адрес в сети TRON. Сначала добавьте адрес, затем создайте заявку; заявку одобряет площадка.

Адреса для вывода#

Деньги → Кошельки — адреса USDT в сети TRON (TRC-20), на которые уходят выводы.

Как добавить адрес:

  1. Нажмите «Добавить адрес».
  2. «Адрес» — вставьте его из кошелька. Адрес TRON начинается с T и состоит из 34 знаков; контрольную сумму проверит площадка.
  3. «Название» — от 1 до 64 знаков: как адрес будет называться в кабинете.
  4. Подтвердите кодом из приложения.

Внимание

Проверьте адрес: перевод на чужой адрес не вернуть. Добавление и удаление адреса записываются в «Журнал действий».

Когда адресом можно пользоваться. Новый адрес становится доступен для вывода через 24 часа после добавления (эту паузу задаёт площадка). До этого его состояние — «Ещё недоступен», в поле «Доступен с» указано время. Затем — «Можно выводить».

Другие состояния: «Заблокирован площадкой» — адрес не принимает выводы, его можно только удалить; «Удалён» — удалённые адреса скрыты, их можно показать кнопкой «Показать удалённые».

Действия с адресом (с кодом из приложения): «Переименовать» и «Удалить». Заявки, уже созданные на удалённый адрес, одобрены не будут.

Адресов, не считая удалённых, может быть не больше 10 (по умолчанию; число задаёт площадка).

Создание вывода#

Деньги → Вывод → «Новый вывод». Мастер из трёх шагов.

1. «Сколько». Блок «Что можно вывести» показывает: «Доступно», «Наибольшая сумма к обмену», «Минимум», «Максимум за заявку», «Осталось на сегодня», «Комиссия вывода», «Комиссия обмена» и «Ориентировочный курс». Укажите сумму одним из способов:

  • «В песо» — «Сколько песо обменять»;
  • «В USDT» — «Сколько USDT получить».

Кнопка «Всё доступное» подставляет весь доступный баланс. Нажмите «Дальше».

2. «Куда». Выберите адрес из списка. Адрес, который ещё недоступен, выбрать нельзя. Здесь же можно добавить новый адрес, но вывести на него получится только после паузы.

3. «Расчёт и подтверждение». Нажмите «Рассчитать». Кабинет покажет: «Обмениваете», «Спишется с баланса», «Получите», «На адрес», «Итоговый курс с комиссиями». Курс фиксируется на короткое время (по умолчанию 2 минуты; таймер «Курс зафиксирован на»). Если время вышло, нажмите «Пересчитать». При желании добавьте «Комментарий» (до 500 знаков; его видит площадка) и нажмите «Создать заявку» — с кодом из приложения.

Лимиты и комиссии задаёт площадка; действующие значения всегда видны в блоке «Что можно вывести». По умолчанию для мерчантов: минимум — 50 USDT за заявку, комиссия вывода — 1 % от обмениваемой суммы в песо сверх неё, комиссия обмена — 0 %; ограничений «Максимум за заявку» и лимита за 24 часа («Осталось на сегодня») по умолчанию нет.

Если вывод выключен, мастер покажет «Вывод сейчас выключен площадкой» — свяжитесь с поддержкой Payin8.

Заявки и статусы#

Деньги → Вывод — список заявок: «№», «Создана», «Статус», «Списано», «Получите», «Адрес», «Курс». Фильтры — по статусу и периоду.

Статус Что происходит
«Ждёт одобрения» Песо заморожены на балансе до решения площадки
«Одобрен» USDT будут отправлены на ваш адрес
«Подтверждается» Перевод в сети, ждём подтверждений
«Завершён» USDT пришли на ваш адрес
«Отправка не удалась» Площадка разбирается; песо остаются замороженными
«Отменён» Вы отменили заявку; песо вернулись на баланс
«Отклонён» Площадка отклонила заявку (причина — в карточке); песо вернулись на баланс
«Возвращён на баланс» Площадка вернула песо на баланс, USDT не отправлялись

В карточке заявки — блоки «Суммы», «Курс» и «Перевод» («Адрес», «Хеш перевода» со ссылкой «Открыть в обозревателе»).

Пока заявка ждёт одобрения, можно:

  • «Отменить заявку» — песо вернутся на баланс; отменённую заявку не восстановить;
  • «Обновить курс» — заявка пересчитается по текущему курсу: списываемые песо не меняются, меняется сумма в USDT. Курс заявки действует ограниченное время (поле «Курс держится до»; по умолчанию час). Если он истёк, площадка не может одобрить заявку, пока вы не обновите курс. Число обновлений ограничено.

Эти два действия кода из приложения не требуют.

Кому это доступно#

Действие Право роли
Видеть адреса «Видеть кошельки для вывода»
«Добавить адрес», «Переименовать», «Удалить» «Добавлять кошельки для вывода», «Менять кошельки для вывода», «Удалять кошельки для вывода»
Видеть заявки и лимиты «Видеть выводы», «Открывать вывод», «Видеть лимиты вывода»
«Рассчитать» «Рассчитывать вывод»
«Создать заявку» «Заказывать вывод»
«Отменить заявку», «Обновить курс» «Отменять вывод», «Обновлять курс вывода»

Добавление адреса и создание заявки требуют второго фактора и на время закрываются после изменений безопасности (см. Безопасность).

Кабинет

Сделки#

Сделка — один приём (клиент платит вам) или одна выплата (вы платите получателю). Сделки создаёт ваш сервер через API: приёмы — см. Приёмы, выплаты — см. Выплаты. В кабинете их видно, а некоторые можно отменить или оспорить.

Списки приёмов и выплат#

Разделы Приёмы и Выплаты в меню. Списки обновляются сами. Новые сделки — сверху.

Колонки списка «Приёмы»: «№», «Счёт мерчанта» (номер заказа, который ваш сервер передал при создании), «Создана», «Проект», «Клиент», «Сумма», «Комиссия», «На баланс», «Статус», «Срок / зачислен» (таймер до конца срока оплаты или время зачисления).

Колонки списка «Выплаты»: «№ / счёт», «Создана», «Проект», «Получатель», «Получит», «Комиссия», «Списано», «Статус», «Взята / выплачена».

Фильтры#

  • «Проект» и «Счёт мерчанта» — над списком;
  • «Статус» — можно выбрать несколько;
  • «№ сделки»;
  • «Сумма» — «от» и «до»;
  • период — «С» и «По» или быстрые кнопки «24 ч», «7 дней», «30 дней»; период не длиннее 92 дней.

«Сбросить фильтры» возвращает список целиком.

Статусы#

Статусы приёма:

Статус в кабинете Что значит
«Подбираем счёт» Приём создан, Payin8 подбирает реквизиты для оплаты
«Ждём оплату» Реквизиты выданы, клиент должен перевести деньги до срока
«Клиент сообщил об оплате» Клиент сообщил, что перевёл деньги; ждём подтверждения поступления
«Зачислен» Оплата подтверждена, деньги на балансе
«Время вышло» Срок оплаты истёк. Пока идёт окно позднего подтверждения, приём ещё может завершиться: кабинет пишет «Время вышло — оплата ещё может прийти»
«Отменён» Приём отменён

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

Статус в кабинете Что значит
«Создана» Выплата создана
«Ищем исполнителя» Выплата предложена исполнителям
«Исполняется» Исполнитель взял выплату и переводит деньги
«Проверяем чек» Зарезервировано: сейчас выплаты в этот статус не переходят
«Выплачена» Деньги отправлены получателю
«Отменена» Выплата отменена, замороженные деньги вернулись на баланс

Отметка «Ждёт денег» у выплаты означает, что на балансе не хватает денег и выплата ждёт пополнения (если так задано правилом «Выплата без денег на балансе»). Рядом со статусом бывают и другие отметки, например «Спор», «Позднее подтверждение», «Изменена сумма», «Частично», «Сторно». Как эти статусы выглядят в API — см. Статусы.

Карточка сделки#

Нажмите на сделку в списке. Карточка открывается сбоку, заголовок — «Приём № …» или «Выплата № …».

Вкладка «Сделка»:

  • Приём: «Деньги» («Запрошено», «Клиент заплатил», «Комиссия», «На баланс»), «Сроки» («Создана», «Оплатить до», «Деньги пришли», «Завершена»), «Как платит клиент» (тип счёта CVU, CBU или Alias, «Счёт», «Владелец», «CUIT / документ», «Банк»), «Клиент» («Id клиента», «Имя», «Почта», «IP» — то, что передал ваш сервер), «Метаданные», «Ссылка на оплату» (см. ниже).
  • Выплата: «Деньги» («Получатель получит», «Комиссия», «Списано с баланса», «Заморожено на балансе» или «Вернулось на баланс»), «Получатель», «Исполнение и чеки» («Взята исполнителем», «Выплачена», чеки перевода), «Метаданные».
  • «Номера счёта» — все номера заказа, на которые отвечает сделка: первый и добавленные повторными запросами клиента.
  • Если клиент заплатил другую сумму, карточка предупредит: «Клиент заплатил другую сумму» — зачислено по фактически полученной сумме.
  • Если выплата исполнена частично, видно, сколько исполнено и сколько вернулось на баланс.
  • Если по сделке был спор — блок «Спор» со ссылкой «Перейти к спору».

Вкладка «Ход сделки» — история сделки по шагам с временем.

Вкладка «Вебхуки» — все события этой сделки, отправленные на адрес вашего проекта: «Открыть доставки этой сделки» (см. Вебхуки).

Ссылка на оплату. У приёма, который клиент оплачивает на странице оплаты Payin8, в карточке есть блок «Ссылка на оплату» и кнопка «Открыть». Отправьте ссылку клиенту, если он потерял страницу; она работает, пока приём открыт.

Чеки и другие файлы сделки ваш сервер может получить и через API — см. Файлы.

Что можно сделать из кабинета#

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

«Отменить приём». Можно, пока приём в статусе «Подбираем счёт» или «Ждём оплату», но реквизиты ещё не показаны клиенту. После отмены клиент больше не сможет оплатить приём.

«Отменить выплату». Можно, пока выплата в статусе «Создана» или «Ищем исполнителя», то есть исполнитель ещё не взял её. Замороженные деньги вернутся на баланс.

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

«Открыть спор». См. Споры.

Отменить приём и выплату можно и через API — см. Приёмы и Выплаты.

Кому это доступно#

Что Право роли
Списки и карточки «Видеть сделки», «Открывать сделку»
Вкладка «Ход сделки» «Видеть историю сделки»
Отмена «Отменять сделки»
Чеки выплаты «Скачивать файлы»
Спор «Видеть споры», «Открывать споры»

Системная роль «Operator» может отменять сделки и работать со спорами; «Viewer» — только смотреть. Отмена сделки кода из приложения не требует.

Кабинет

Споры#

Спор — обращение к площадке, когда со сделкой что-то не так: клиент заплатил, а приём не зачислен, сумма не та, получатель не получил выплату. Спор разбирает и решает площадка Payin8. Пока спор открыт, сроки сделки стоят, а отменить её нельзя.

Споры можно открывать и читать и через API — см. Споры.

Когда можно открыть спор#

Кнопка «Открыть спор» появляется в карточке сделки (Приёмы или Выплаты → сделка), если:

  • по сделке нет открытого спора;
  • приём в статусе «Ждём оплату», «Клиент сообщил об оплате», «Время вышло» или «Зачислен», либо «Отменён» после того, как ему были назначены реквизиты;
  • выплата в статусе «Исполняется» или «Выплачена»;
  • срок для спора не истёк: по умолчанию 7 дней с создания сделки. Действующий срок — правило «Срок, в который можно открыть спор по сделке» (см. Правила). Если срок прошёл, кабинет напишет, до какого времени спор можно было открыть.

Как открыть#

  1. Откройте сделку и нажмите «Открыть спор».
  2. Выберите «Причина»:
    • для приёма — «Клиент оплатил, а приём не завершён», «Сумма не та», «Подозрение на мошенничество», «Другое»;
    • для выплаты — «Получатель не получил деньги», «Подозрение на мошенничество», «Другое».
  3. «Комментарий» — что случилось, что говорит клиент, чего вы ждёте. До 4000 символов; при причине «Другое» обязателен.
  4. Для приёма — «Сколько заплатил клиент» (необязательно, сумма из чека клиента).
  5. Приложите файлы: для приёма — «Чек клиента», для любой сделки — «Другие файлы». Всего до 10 файлов; JPEG, PNG, WebP или PDF, каждый до 10 МБ.
  6. Нажмите «Открыть спор».

Если спор по сделке уже открыт (например, его открыли одновременно с вами), ваш комментарий добавится в него.

Совет

Чем точнее приложенные доказательства, тем быстрее разбор: чек перевода клиента с суммой, временем и номером операции, выписка, переписка с клиентом.

Список споров#

Раздел Споры в меню. Вкладки «Открытые», «Закрытые», «Все»; фильтр «Направление» (приём или выплата).

Колонки: «Сделка», «Причина», «Кто открыл», «Открыт», «Статус», «Итог», «Последнее сообщение». Число новых сообщений отмечено в строке спора.

Спор открывает не только мерчант: площадка тоже может открыть спор по вашей сделке — например, если выплата слишком долго в работе. Такие споры видны в том же списке.

Как отвечать#

Откройте спор. В карточке — сделка («Открыть сделку»), причина, кто и когда открыл, и лента «Сообщения».

Чтобы ответить, заполните блок «Ответить»: «Сообщение» (до 4000 символов) и при необходимости «Файлы» (до 10 файлов), затем нажмите «Отправить». Файлы прикладываются к тексту сообщения.

Сообщение и файлы прочтут площадка и исполнитель сделки.

Как спор закрывается#

  • Спор по приёму закрывается сам, когда исполнитель подтверждает поступление денег («Подтверждение прихода закроет спор само»). Спор по выплате закрывается сам, когда исполнитель прикладывает чек перевода. Исключение — спор по выплате, который ждёт решения поддержки: в карточке тогда написано «Спор ждёт решения поддержки: чек его уже не закроет», и закрывает его только решение площадки.
  • Иначе спор закрывает площадка своим решением. Итог виден в колонке и в карточке, например: «Оставлено как есть», «Сделка завершена», «Сделка отменена, деньги вернулись», «Завершённая сделка отменена», «Сумма изменена».

Решение по спору может изменить деньги на балансе — это видно в выписке (например, «Отмена зачисления по спору» или «Возврат выплаты по спору»). Закрытый спор новых сообщений не принимает.

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

Кому это доступно#

Действие Право роли
Видеть споры и сообщения «Видеть споры»
«Открыть спор» «Открывать споры»
«Отправить» сообщение «Писать в спор»
Прикладывать файлы «Загружать файлы»

Системная роль «Operator» может открывать споры и отвечать в них, но права «Загружать файлы» у неё нет — приложить файлы сможет владелец или сотрудник со своей ролью, где это право есть. «Viewer» — только читает.

Кабинет

Команда и роли#

У каждого сотрудника свой вход и своя роль. Роль определяет, какие разделы видны и какие действия доступны.

Команда#

Организация → Команда — все, у кого есть доступ к кабинету: «Почта», «Имя», «Роль», «Статус», «Второй фактор», «Последний вход», «Добавлен». Фильтры: статус, роль, «Почта начинается с».

Статусы сотрудника: «Приглашён», «Активен», «Отключён», «Удалён».

Приглашение сотрудника#

  1. Команда → «Пригласить».
  2. Укажите «Почта», «Имя» (необязательно) и «Роль».
  3. Нажмите «Создать приглашение» и подтвердите кодом из приложения.
  4. Кабинет покажет «Ссылка приглашения» и срок «Действует до». Ссылка показывается один раз — скопируйте её и передайте сотруднику сами, лично, не в общий чат: она даёт доступ к кабинету.

Ссылка по умолчанию действует 72 часа. Если сотрудник не успел, откройте его в списке и нажмите «Отправить приглашение снова» — появится новая ссылка, прежняя перестанет действовать. Что делает сотрудник по ссылке — см. Приглашение.

Выдать роль шире своих прав нельзя. Роль владельца может выдать только владелец.

Действия с сотрудником#

Откройте сотрудника в списке. Вкладки: «Сотрудник» и «Сеансы» (где он сейчас вошёл).

Действие Что происходит
«Изменить» Имя и роль
«Отключить» Все сеансы сотрудника сразу завершаются. Он остаётся в команде, доступ можно вернуть кнопкой «Включить». Нужна причина
«Сбросить второй фактор» Сотрудник настроит второй фактор заново при следующем входе; его сеансы завершаются, а чувствительные действия для него на время закрываются (см. Безопасность). Нужна причина
«Завершить все сеансы» Сотруднику придётся войти заново на всех устройствах
«Ссылка для пароля» Одноразовая ссылка для нового пароля (по умолчанию действует 30 минут). Кабинет показывает её один раз — передайте её сотруднику сами. Текущий пароль действует, пока не задан новый. Нужна причина
«Удалить» Сотрудник навсегда теряет доступ. Запись остаётся в журнале действий

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

Роли#

Организация → Роли — что видит и может каждая роль. Колонки: «Название», «Код», тип (системная, своя, владелец), «Права», «Второй фактор» («обязателен» или «не обязателен»), «Сотрудников».

Системные роли изменить нельзя:

Роль Что может
«Owner» Всё в кабинете мерчанта. Второй фактор обязателен
«Operator» Видит всё, кроме журнала действий, команды, ролей и ключей API. Отменяет сделки, открывает споры и отвечает в них (без загрузки файлов), отправляет события вебхуков снова
«Viewer» Только смотрит — то же, что «Operator», без действий

Своя роль. «Новая роль»:

  • «Код» — строчная латиница, цифры и _, начинается с буквы, 2–32 символа (заглавные буквы кабинет сам переводит в строчные);
  • «Название» — до 60 символов; «Описание» — по желанию;
  • «Права» — отметьте нужные. Права сгруппированы по разделам и делятся на «Просмотр» и «Изменение»; права с пометкой «Нужен свежий код из приложения» подтверждаются кодом при каждом действии.

Права, которых нет у вас самих, выдать нельзя. Если в роли есть хотя бы одно право с кодом из приложения, второй фактор для неё обязателен. Изменить или удалить можно только свою роль; удалить — только роль без сотрудников. Создание, изменение и удаление ролей подтверждаются кодом из приложения. Площадка может выключить возможность заводить свои роли.

Журнал действий#

Организация → Журнал действий — кто что делал в кабинете: входы, изменения команды и ролей, выпуск и отзыв ключей, показ секретов, изменения проектов и правил, отказы в доступе и другое.

  • Колонки: «Время», «Кто», «Действие», «Объект», «Результат» («выполнено», «отказано», «ошибка»), «IP».
  • Фильтры: «Категория» («Вход», «Безопасность», «Деньги», «Запросы», «Отказ в доступе», «Показ секретов», «Чтение данных»), «Код действия» и период — до 92 дней.
  • В записи — «Подробнее»: «Причина», «Было», «Стало», «Дополнительно».

Действия ключей API помечены как «ключ», действия сотрудников площадки — как «площадка».

Кому это доступно#

Что Право роли
Видеть команду и сеансы «Видеть команду», «Открывать участника команды», «Видеть сеансы входа»
«Пригласить», «Отправить приглашение снова» «Приглашать в команду»
«Изменить», «Отключить», «Включить», «Удалить» «Менять участников команды», «Отключать участников команды», «Включать участников команды», «Удалять из команды»
«Сбросить второй фактор», «Ссылка для пароля», «Завершить все сеансы» «Сбрасывать второй фактор», «Выдавать ссылку для смены пароля», «Завершать сеансы входа»
Роли «Видеть роли», «Создавать роли», «Менять роли», «Удалять роли»
Журнал действий «Видеть журнал действий», «Открывать запись журнала»

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

Кабинет

Страница оплаты#

Страница оплаты Payin8 — страница, на которой клиент видит реквизиты и оплачивает приём банковским переводом. Ссылку на неё ваш сервер получает при создании приёма (см. Приёмы). В кабинете вы настраиваете, как страница выглядит и куда клиент возвращается после оплаты.

Где настраивать#

Настройки есть на двух уровнях:

  • для всех проектов — Организация → Профиль и правила, блок «Страница оплаты по умолчанию». Пустое поле — значение площадки по умолчанию;
  • для одного проекта — Подключение → Проекты → проект → вкладка «Страница оплаты». Пустое поле берётся из настроек организации.

Рядом с каждым значением видно, откуда оно: «от организации» или «по умолчанию площадки». Нажмите «Изменить», заполните поля и сохраните — с кодом из приложения.

Что можно настроить#

Поле Правила
«Название магазина для клиента» От 1 до 60 символов. Если название не задано ни для проекта, ни для организации, на странице показывается название проекта
«Логотип» PNG, WebP или JPEG; SVG не принимается. По умолчанию файл логотипа — не больше 512 КБ. Загруженный логотип можно убрать: у организации — «Убрать логотип», у проекта — «Брать логотип организации»
«Основной цвет» В виде #RRGGBB. Текст на кнопках белый, поэтому контраст цвета с белым должен быть не ниже 3:1 — слишком светлый цвет кабинет не примет
«Ссылка на поддержку» Адрес https:// без логина, до 2048 символов
«Почта поддержки» Адрес электронной почты
«Возврат на ваш сайт»: «После успешной оплаты», «После неудачной оплаты», «Кнопка «Назад»» Адреса https:// без логина, до 2048 символов
«Автовозврат» От 0 до 30 секунд: через сколько секунд после успешной оплаты страница сама вернёт клиента на ваш сайт; 0 — клиент возвращается только кнопкой. Если не задано — по умолчанию площадки, 5 секунд

Адрес возврата, переданный вместе с приёмом через API, важнее адреса из кабинета.

Рядом с настройками и в форме изменения — «Макет шапки страницы»: как будут выглядеть название, логотип, цвет кнопки и ссылка на поддержку.

Язык страницы задаёт правило «Язык страницы оплаты» («как у приёма», «испанский», «английский»), а обязательность чека клиента — правило «Обязателен чек клиента» (см. Правила).

Что видит плательщик#

  1. Пока Payin8 подбирает реквизиты — экран ожидания с просьбой не закрывать страницу.
  2. Сумму к переводу, таймер до конца срока оплаты и реквизиты: CVU или CBU, alias, владелец счёта, CUIT/CUIL, банк, номер заказа — с кнопками копирования. Короткая инструкция: перевести точную сумму одним переводом до конца срока.
  3. Поле для чека перевода — обязательное или необязательное, в зависимости от правила «Обязателен чек клиента».
  4. Кнопку, которой клиент сообщает, что перевёл деньги, и кнопку отмены оплаты.
  5. После этого — экран проверки платежа; затем — экран успешной оплаты с возвратом на ваш сайт или экран истёкшего срока.

На странице — ваше название, логотип, цвет и ссылки на поддержку. Клиент может переключить язык (испанский или английский).

У каждого приёма, который оплачивается на странице оплаты, в карточке сделки есть блок «Ссылка на оплату» с кнопкой «Открыть». Если клиент потерял страницу, отправьте ему эту ссылку: она работает, пока приём открыт.

Свой домен#

Домены, на которых открывается страница оплаты, подключает и проверяет площадка; в кабинете мерчанта этой настройки нет. Если вы хотите, чтобы страница оплаты открывалась на вашем домене, обратитесь в поддержку Payin8. Площадка сообщит, какие DNS-записи нужно создать: запись TXT для подтверждения владения доменом и записи, направляющие домен на адреса площадки. После того как вы создадите записи, площадка проверит их и активирует домен.

Встроить страницу оплаты во фрейм на вашем сайте по умолчанию нельзя. Разрешённые адреса для встраивания задаёт площадка для проекта — обратитесь в поддержку Payin8.

Кому это доступно#

Действие Право роли
Видеть настройки страницы оплаты «Видеть настройки страницы оплаты»
«Изменить» «Менять настройки страницы оплаты» (с кодом из приложения)
Загрузка логотипа «Загружать файлы»

Кабинет

Безопасность#

Карантин после изменений безопасности#

Если кто-то получил доступ к вашей учётной записи, первое, что он попробует, — выпустить ключ, сменить адрес вебхука или вывести деньги. Поэтому после некоторых изменений безопасности кабинет на время закрывает самые чувствительные действия для этого сотрудника. По умолчанию — на 24 часа (срок задаёт площадка).

Что запускает карантин:

  • вход по коду восстановления;
  • смена пароля по ссылке для нового пароля;
  • сброс второго фактора владельцем кабинета (карантин начинается сразу) и включение второго фактора заново — после сброса или выключения;
  • первое включение второго фактора сотрудником, которого пригласили из кабинета;
  • назначение роли владельца участником команды.

Не запускают карантин: обычная смена пароля в профиле (с текущим паролем), перенос второго фактора на новый телефон, выпуск новых кодов восстановления. Владелец, которого завела площадка, при первом включении второго фактора карантина не получает — он может сразу выпустить ключ, настроить вебхук и добавить адрес вывода.

Что закрыто на время карантина:

Действие Где в кабинете
Добавление адреса для вывода Деньги → Кошельки → «Добавить адрес»
Создание заявки на вывод Деньги → Вывод → «Новый вывод»
Выпуск ключа API Подключение → Ключи API → «Выпустить ключ»
Изменение ключа API и замена его секрета Карточка ключа → «Изменить», «Заменить секрет»
Изменение вебхука и замена секрета подписи Вкладка «Вебхук» проекта
Приглашение сотрудника с ролью, которая даёт больше, чем просмотр Организация → Команда → «Пригласить»

При попытке кабинет покажет: «После изменения безопасности чувствительные действия приостановлены до …» — с точным временем окончания. Всё остальное, в том числе отзыв ключей, работает как обычно. Снять карантин досрочно из кабинета нельзя.

Совет

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

Что делать при утечке#

  • Утёк секрет ключа API — сразу отзовите ключ (карточка ключа → «Отозвать»; код из приложения не нужен) или все ключи проекта («Отозвать все»). Затем выпустите новый ключ.
  • Утёк секрет подписи вебхука — замените его (вкладка «Вебхук» → «Заменить секрет»). Прежний секрет ещё какое-то время подписывает вместе с новым.
  • Утёк пароль или телефон с приложением — завершите все свои сеансы («Профиль и безопасность» → «Выйти на других устройствах» или меню «Учётная запись» → «Выйти везде»), смените пароль и перенесите второй фактор. Если доступ к учётной записи потерян, попросите владельца отключить её, сбросить второй фактор и выпустить ссылку для пароля; владельцу — обратитесь в поддержку Payin8.
  • Подозрительные действия проверьте в Организация → Журнал действий (категории «Безопасность», «Показ секретов», «Отказ в доступе»).

Хранение секретов#

  • Секрет ключа API и секрет подписи вебхука показываются один раз. Сразу кладите их в хранилище секретов вашего сервера, не в код, не в репозиторий и не в переписку.
  • Используйте отдельный ключ для каждого проекта и назначения. По умолчанию у проекта может быть не больше 2 действующих ключей — этого хватает, чтобы заменить секрет без простоя.
  • Давайте ключу только нужные права. Права на деньги («Создавать выплаты», «Отменять выплаты») — только тому ключу, который действительно создаёт выплаты.
  • Меняйте секреты планово: «Заменить секрет» с перекрытием («ещё час», «ещё сутки», «ещё 7 дней») позволяет переключить сервер без остановки.
  • Проверяйте подпись каждого входящего вебхука (см. Вебхуки) и не доверяйте запросам без неё.
  • Ссылки приглашения и ссылки для пароля дают доступ к кабинету: передавайте их лично, не в общий чат.
  • Храните коды восстановления там же, где пароли, отдельно от телефона.

Список IP-адресов#

  • Ограничивайте адреса у каждого ключа: тогда украденный секрет бесполезен с чужого сервера.
  • Для создания выплат и для приёмов, в ответе на которые сразу выдаются реквизиты, список адресов обязателен.
  • Указывайте точные адреса серверов или узкие диапазоны. Шире /24 для IPv4 и /56 для IPv6 кабинет не примет.
  • Меняя серверы, сначала добавьте новые адреса в ключ («Изменить»), переключите трафик и только потом уберите старые.

Команда#

  • Выдавайте сотрудникам минимальные роли: для просмотра — «Viewer», для работы со сделками и спорами — «Operator» или своя роль.
  • Отключайте доступ уволившимся сотрудникам сразу («Отключить» или «Удалить»).
  • Держите в организации больше одного владельца с настроенным вторым фактором, чтобы не потерять управление кабинетом.

Кабинет

Чек-лист перед запуском#

Пройдите по списку перед тем, как пускать живых клиентов.

Доступ#

  • У владельца включён второй фактор, коды восстановления сохранены в надёжном месте.
  • В организации больше одного сотрудника, способного управлять кабинетом, или понятен порядок восстановления доступа через поддержку Payin8.
  • Сотрудники приглашены с минимально нужными ролями (см. Команда и роли).
  • «Контакты» в Организация → Профиль и правила заполнены — по ним площадка свяжется с вами.

Проект#

  • Проект в статусе «Активен».
  • На вкладке «Методы и пределы» включены нужные направления, пределы сумм подходят вашим заказам.
  • Для каждого включённого направления назначен тариф — нет предупреждения «Тариф не назначен».
  • Правила проекта проверены: «Язык страницы оплаты», «Обязателен чек клиента», «Позднее подтверждение приёмов», «Выплата без денег на балансе».

Ключ API#

  • Ключ выпущен для нужного проекта; идентификатор и секрет лежат в хранилище секретов сервера.
  • У ключа только нужные права; права на деньги — только если ключ создаёт выплаты.
  • В «Адреса» указаны IP-адреса ваших серверов (обязательно для выплат и для приёмов с выдачей реквизитов в ответе).
  • Сервер правильно подписывает запросы: тестовый запрос проходит без ошибок подписи (см. Подпись запросов, Ошибки).
  • Повторы запросов создания сделок обрабатываются безопасно (см. Идемпотентность).

Вебхуки#

  • Адрес вебхука задан, «Отправлять события» включено, нужные события отмечены.
  • Секрет подписи сохранён, сервер проверяет подпись каждого запроса (см. Вебхуки).
  • «Проверить» отправляет событие, и в Подключение → Доставка вебхуков оно в статусе «Доставлено».
  • Обработчик отвечает 2xx быстро и корректно принимает повтор одного и того же события.
  • Есть план на случай сбоя: как найти события «Не доставлено» и отправить их снова.

Страница оплаты#

  • Заданы название магазина, логотип, цвет, ссылка или почта поддержки.
  • Заданы адреса возврата «После успешной оплаты» и «После неудачной оплаты» (или ваш сервер передаёт их с каждым приёмом).
  • Если нужен свой домен или встраивание во фрейм — договорились с поддержкой Payin8, домен активирован.

Деньги#

  • Понятно, как пополняется баланс для выплат: зачисления по приёмам или пополнение USDT (Деньги → Пополнение).
  • Адрес для вывода добавлен заранее — им можно пользоваться только после паузы (по умолчанию 24 часа).
  • Учтены лимиты и комиссии вывода (блок «Что можно вывести» в мастере вывода).

Первая сделка#

  • Приём на небольшую сумму прошёл все шаги: создан, клиент оплатил, статус «Зачислен», деньги в «Баланс и выписка».
  • Ваш сервер получил вебхуки «Приём: выдан счёт» и «Приём зачислен».
  • Если вы делаете выплаты — тестовая выплата дошла до статуса «Выплачена», вебхук «Выплата исполнена» получен.
  • Команда знает, где смотреть сделки и как открыть спор (см. Сделки, Споры).

API

Обзор API#

API мерчанта Payin8 — интерфейс для вашего сервера: создать приём (pay-in) или выплату (pay-out) банковским переводом, узнать состояние сделки, баланс и условия методов, загрузить файл к сделке, открыть спор. Об изменениях сделок Payin8 сообщает вебхуками.

Запросы к API делает только ваш сервер: каждый запрос подписывается секретом ключа API (см. Аутентификация). Не вызывайте API из браузера или мобильного приложения и не передавайте туда секрет ключа.

Подключение по шагам#

  1. Получите ключ. В кабинете выпустите ключ API для проекта с нужными правами и IP-адресами вашего сервера; сохраните идентификатор ключа mk_… и секрет ms_… (см. Ключи API).
  2. Подпишите проверочный запрос. Скопируйте готовые функции, передайте ключ и секрет через переменные окружения и вызовите GET /v1/balance: ответ 200 — подпись работает. Если нет, сверьте свои значения с разобранным примером.
  3. Проверьте условия. GET /v1/methods показывает, какие методы и направления включены у проекта, пределы суммы и комиссии (см. Методы).
  4. Принимайте вебхуки. Задайте в кабинете адрес и события проекта и сохраните секрет подписи whsec_… (см. Вебхуки). Ваш обработчик проверяет подпись и сразу отвечает 2xx (см. Чем отвечать). Кнопка «Проверить» отправляет webhook.ping: так обработчик можно проверить до первой сделки.
  5. Создайте приём. POST /v1/payins с вашим invoiceId, суммой, клиентом и режимом flow (см. Создание приёма). При flow: requisite покажите клиенту requisite и amount из ответа или из вебхука payin.assigned; при flow: widget отправьте клиента по ссылке paymentUrl.
  6. Получите результат. Итог приходит вебхуком payin.completed или payin.failed; текущее состояние всегда можно прочитать через GET /v1/payins/{id} или по вашему номеру (см. Поиск по номеру).
  7. Обработайте сбои. После таймаута или ответа 5xx повторите создание с тем же invoiceId: второй сделки не будет (см. Идемпотентность).

Перед запуском пройдите чек-лист.

Базовый адрес и версия#

https://api.payin8.io

Все пути начинаются с версии: /v1/…, например POST https://api.payin8.io/v1/payins. Текущая и единственная версия — v1; версия входит в подписываемый путь.

Формат запросов и ответов#

  • Тела запросов и ответов — JSON в кодировке UTF-8. Запрос с телом отправляйте с заголовком Content-Type: application/json. Исключение — загрузка файла: тело запроса POST /v1/files — сами байты файла (см. Файлы).
  • Поля, которых нет в описании точки, не принимаются: запрос с лишним полем получает 400 validation_failed («property … should not exist»).
  • Строковые значения обрезаются по краям от пробелов; пустая строка после обрезки считается неотправленным полем.
  • Ответ с ошибкой — всегда { "code", "message", "details"? } (см. Ошибки).

Заголовки, которые есть в каждом ответе:

Заголовок Значение
X-Request-Id Идентификатор запроса на стороне Payin8 (UUID). Указывайте его, когда пишете в поддержку.
X-Client-Request-Id Ваш собственный X-Request-Id, если вы его прислали и он состоит из 1–64 символов A–Z a–z 0–9 _ -. Payin8 его не использует как свой идентификатор, только возвращает.
Cache-Control no-store (у скачивания чека выплаты — private, no-store): ответы API не кешируются.

Деньги#

  • Суммы — десятичные строки с точкой: "15000.00". JSON-числа не принимаются (400 validation_failed).
  • В запросе: сумма больше нуля, не больше 13 цифр в целой части и не больше знаков после точки, чем у валюты. У ARS — 2 знака: "15000", "15000.5" и "15000.50" допустимы, "15000.505" — нет.
  • В ответе сумма всегда записана с полным числом знаков валюты: "15000.00".
  • Валюта — код из заглавных букв: ARS. Метод оплаты — bank_transfer (банковский перевод).
  • Проценты комиссий — строки: "2.5" означает 2,5 %.

Время#

  • Все моменты времени в ответах и вебхуках — ISO 8601 в UTC с миллисекундами: "2026-11-19T16:08:12.277Z".
  • Фильтры списков createdFrom и createdTo принимают ISO 8601 (2026-11-19T00:00:00Z).
  • Заголовок подписи X-Timestamp — Unix-время в секундах (10 цифр).

Идентификаторы#

Что Формат Кто задаёт
id сделки, файла, спора, события вебхука UUID v4, например 3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44 Payin8
invoiceId 1–64 символа: латинские буквы, цифры, . _ : - Вы. Уникален в пределах мерчанта отдельно для приёмов и для выплат
customer.id 1–128 печатных символов ASCII без пробелов Вы: ваш идентификатор клиента
version Целое число, растёт при каждом изменении сделки Payin8

invoiceId — ваш номер заказа или заявки; по нему работает идемпотентность создания и поиск сделки (GET /v1/payins/by-invoice/{invoiceId}).

Как проходит приём#

  1. Ваш сервер создаёт приём: POST /v1/payins с суммой, клиентом и способом приёма (flow).
  2. Payin8 подбирает исполнителя и его банковский счёт (реквизит). Приём переходит из created в awaiting_payment, приходит вебхук payin.assigned. Срок оплаты — поле expiresAt.
  3. Клиент переводит деньги на реквизит: при flow: requisite реквизит и сумму amount ему показываете вы, при flow: widget — страница оплаты Payin8 по ссылке paymentUrl.
  4. Поступление подтверждено — приём completed, вебхук payin.completed. На баланс зачисляется net = amount − fee.
  5. Если оплаты не было в срок или исполнителя не нашлось — expired или canceled, вебхук payin.failed.

Подробно — Приёмы и Статусы сделок.

Как проходит выплата#

  1. Ваш сервер создаёт выплату: POST /v1/payouts с суммой и счётом получателя. С баланса удерживается totalDebit = amount + fee, выплата предлагается исполнителям (offered).
  2. Исполнитель берёт выплату (in_progress), переводит деньги получателю и прикладывает чек.
  3. Выплата completed, вебхук payout.completed; чек можно скачать (GET /v1/payouts/{id}/receipts/{fileId}).
  4. Если выплату никто не взял в срок, её отменили или перевод невозможен — canceled, вебхук payout.failed, удержанное возвращается на баланс.

Подробно — Выплаты.

Способы приёма#

Способ задаёт поле flow при создании приёма.

flow Как клиент получает реквизит Что нужно
requisite Реквизит приходит в ответе API (requisite) и в вебхуке payin.assigned; вы показываете его клиенту у себя. Список разрешённых IP-адресов у ключа API (иначе 403 ip_allowlist_required).
widget В ответе — ссылка paymentUrl на страницу оплаты Payin8. Клиент видит реквизит там, может отметить «я оплатил», приложить чек или отменить приём. Настроенная страница оплаты проекта (см. Страница оплаты). Если она недоступна, создание отвечает 422 feature_unavailable с details.feature: "widget".

Итог приёма в обоих случаях приходит вебхуком и виден в GET /v1/payins/{id}.

Список точек#

Каждой точке нужно своё право ключа (см. Права ключа).

Метод и путь Право ключа Что делает
POST /v1/payins merchant_api.payins.create Создать приём
GET /v1/payins merchant_api.payins.read Список приёмов
GET /v1/payins/{id} merchant_api.payins.read Приём по id
GET /v1/payins/by-invoice/{invoiceId} merchant_api.payins.read Приём по вашему номеру
POST /v1/payins/{id}/cancel merchant_api.payins.cancel Отменить приём
POST /v1/payouts merchant_api.payouts.create Создать выплату
GET /v1/payouts merchant_api.payouts.read Список выплат
GET /v1/payouts/{id} merchant_api.payouts.read Выплата по id
GET /v1/payouts/by-invoice/{invoiceId} merchant_api.payouts.read Выплата по вашему номеру
GET /v1/payouts/{id}/receipts/{fileId} merchant_api.payouts.read Скачать чек выплаты
POST /v1/payouts/{id}/cancel merchant_api.payouts.cancel Отменить выплату
GET /v1/balance merchant_api.balance.read Баланс мерчанта
GET /v1/methods merchant_api.methods.read Методы проекта: лимиты и комиссии
POST /v1/files merchant_api.files.create Загрузить файл к сделке
POST /v1/disputes merchant_api.disputes.create Открыть спор
GET /v1/disputes merchant_api.disputes.read Список споров
GET /v1/disputes/{id} merchant_api.disputes.read Спор по id
POST /v1/disputes/{id}/evidence merchant_api.disputes.create Добавить доказательства к спору

Запрос на путь, которого нет в списке, получает 404 route_not_found.

API

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

Каждый запрос к API, включая GET, подписывается ключом API проекта. Подпись — HMAC-SHA256 от канонической строки запроса; секрет ключа в запросе не передаётся.

Ключ API#

Ключ создаётся в кабинете мерчанта для конкретного проекта (см. Ключи API) и состоит из двух частей:

Часть Пример Где используется
Идентификатор ключа mk_7k2m9q4x8p1r5t3v6w0y2z4b8c — mk_ и 26 символов Заголовок X-Api-Key в каждом запросе
Секрет ms_dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC1vbmx5LTA — ms_ и 43 символа Ключ HMAC для подписи. Показывается один раз при создании ключа; храните его только на сервере

Ключ принадлежит одному проекту и видит только сделки, файлы и споры этого проекта: чужая сделка для него не существует (404 not_found). Исключение — баланс: GET /v1/balance показывает баланс мерчанта, общий для всех его проектов.

Отозванный ключ, ключ с истёкшим сроком после ротации и несуществующий ключ получают одинаковый ответ 401 api_key_invalid.

Заголовки запроса#

Заголовок Значение
X-Api-Key Идентификатор ключа mk_…
X-Timestamp Время отправки, Unix-секунды (10 цифр): 1795104000
X-Nonce Одноразовая строка 16–64 символов A–Z a–z 0–9 _ -, новая для каждого запроса. Удобно — 32 случайных шестнадцатеричных символа
X-Signature v1= и 64 шестнадцатеричных символа подписи
Content-Type Для запросов с телом: application/json; для POST /v1/files — тип файла. JSON-тело с другим Content-Type не читается, и запрос получает 401 signature_invalid

Без любого из четырёх заголовков подписи запрос получает 401 signature_missing.

Каноническая строка#

Подписывается строка из шести строк, соединённых символом перевода строки \n (без \n в конце):

v1
<METHOD>
<path and query>
<X-Timestamp>
<X-Nonce>
<hex SHA-256 тела>
  • <METHOD> — метод заглавными буквами: GET, POST.
  • <path and query> — путь, начиная с /v1/, и строка запроса ровно в том виде, в каком она уходит в запросе: /v1/payins?status=completed&limit=20. Параметры не сортируются и не перекодируются; без строки запроса — только путь. Домен и схема в строку не входят.
  • <hex SHA-256 тела> — SHA-256 сырых байтов тела в нижнем регистре. Подписываются именно те байты, которые уходят в запросе: сериализуйте JSON один раз и отправляйте ту же строку. У запроса без тела — хеш пустой строки e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

Подпись:

X-Signature = "v1=" + hex( HMAC-SHA256( key = секрет "ms_…" целиком в UTF-8, message = каноническая строка ) )

Ключ HMAC — вся строка секрета вместе с префиксом ms_, без декодирования.

Пример расчёта#

Ключ и секрет — вымышленные, из таблицы выше. Запрос:

HTTP
POST /v1/payins
X-Timestamp: 1795104000
X-Nonce: 3f9c2a7d1b6e4f08a5c3d2e1f0a9b8c7
Content-Type: application/json

{"invoiceId":"inv-100501","amount":"41400.00","currency":"ARS","method":"bank_transfer","flow":"requisite","customer":{"id":"client-42"}}

SHA-256 тела:

30c3d1602c2e005c5f61912a5e56f9654cfa6b4488ebc502d77e0df913ae6122

Каноническая строка:

v1
POST
/v1/payins
1795104000
3f9c2a7d1b6e4f08a5c3d2e1f0a9b8c7
30c3d1602c2e005c5f61912a5e56f9654cfa6b4488ebc502d77e0df913ae6122

Заголовок подписи:

X-Signature: v1=c4acc4e91400077869ed47cba8b1b4291da546d9e03508505f61a0dd182a8f19

Для GET /v1/payins?status=completed&limit=20 с теми же X-Timestamp и X-Nonce подпись — v1=25c4c4411ddfd6bebbd2bde7c14419dd54c606c27c0cf39f26066362d2896e65. Сверьте с этими значениями свою реализацию.

Время и одноразовая строка#

  • Окно времени. X-Timestamp должен отличаться от времени сервера Payin8 не больше чем на допустимое окно в любую сторону (по умолчанию — 300 секунд), иначе 401 timestamp_out_of_window. В details.serverTime этой ошибки — время сервера в Unix-секундах: по нему можно проверить часы своего сервера. Держите часы синхронизированными (NTP).
  • Одноразовая строка. X-Nonce нельзя использовать дважды с одним ключом: повтор получает 401 nonce_replayed. Payin8 запоминает строку только после того, как подпись запроса сошлась, поэтому запрос с неверной подписью строку не расходует.
  • Повтор запроса. Если вы повторяете запрос (например, после обрыва соединения), подпишите его заново: новые X-Timestamp и X-Nonce, новая подпись. Безопасность повтора создания обеспечивает invoiceId (см. Идемпотентность), а не одноразовая строка.

Порядок проверок#

Payin8 проверяет запрос в таком порядке и отвечает первой найденной ошибкой:

  1. Наличие четырёх заголовков подписи, формат X-Nonce.
  2. Ключ: существует, активен, это ключ API мерчанта.
  3. X-Timestamp в окне.
  4. Подпись.
  5. X-Nonce не использован.
  6. Адрес отправителя в списке IP ключа (если список задан).
  7. Мерчант и проект активны.
  8. У ключа есть право на эту точку.
  9. Для создания выплаты — у ключа есть непустой список IP (см. ниже).
  10. Лимит частоты запросов ключа.

Ошибки шагов 1–5 одинаковы для любых ключей и ничего не сообщают о ключе; адрес проверяется только у запроса с верной подписью. Требование списка IP для приёма с flow: requisite проверяется позже, при обработке тела запроса.

Список IP-адресов ключа#

У ключа может быть список разрешённых адресов отправителя: отдельные адреса или диапазоны CIDR (IPv4 и IPv6, до 20 записей). Список задаётся в кабинете (см. Ключи API и Безопасность).

  • Если список задан, запрос с другого адреса получает 403 ip_not_allowed.
  • Без непустого списка ключ не может создавать выплаты и приёмы с flow: requisite (таков перечень операций по умолчанию): такие запросы получают 403 ip_allowlist_required, в details.code — код операции (merchant_api.payouts.create или merchant_api.payins.create:requisite). Остальные точки работают и без списка.

Права ключа#

Ключу выдаётся набор прав; запрос к точке, на которую права нет, получает 403 permission_denied с кодом права в details.code.

Право Точки
merchant_api.payins.create POST /v1/payins
merchant_api.payins.read GET /v1/payins, GET /v1/payins/{id}, GET /v1/payins/by-invoice/{invoiceId}
merchant_api.payins.cancel POST /v1/payins/{id}/cancel
merchant_api.payouts.create POST /v1/payouts
merchant_api.payouts.read GET /v1/payouts, GET /v1/payouts/{id}, GET /v1/payouts/by-invoice/{invoiceId}, GET /v1/payouts/{id}/receipts/{fileId}
merchant_api.payouts.cancel POST /v1/payouts/{id}/cancel
merchant_api.balance.read GET /v1/balance
merchant_api.methods.read GET /v1/methods
merchant_api.files.create POST /v1/files
merchant_api.disputes.create POST /v1/disputes, POST /v1/disputes/{id}/evidence
merchant_api.disputes.read GET /v1/disputes, GET /v1/disputes/{id}

Права на выплаты (payouts.create, payouts.cancel) выдаёт ключу только владелец мерчанта или сотрудник с отдельным правом на это.

Готовые функции#

Функции подписи и вызова, которые можно перенести в свой проект. Ключ, секрет и базовый адрес берутся из переменных окружения PAYIN8_KEY_ID, PAYIN8_SECRET, PAYIN8_BASE_URL; значения по умолчанию в коде — вымышленные. Примеры в остальных разделах вызывают эти функции: payin8 / payin8_file (cURL), payin8Request (Node.js), payin8_request (Python и PHP).

# Payin8 API: подпись запроса и вызов. Нужны bash, curl и openssl.
PAYIN8_BASE_URL="${PAYIN8_BASE_URL:-https://api.payin8.io}"
PAYIN8_KEY_ID="${PAYIN8_KEY_ID:-mk_7k2m9q4x8p1r5t3v6w0y2z4b8c}"
PAYIN8_SECRET="${PAYIN8_SECRET:-ms_dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC1vbmx5LTA}"

# payin8_sign METHOD PATH_AND_QUERY TIMESTAMP NONCE BODY_SHA256 → печатает "v1=<64 hex>"
payin8_sign() {
  local canonical
  canonical=$(printf 'v1\n%s\n%s\n%s\n%s\n%s' "$1" "$2" "$3" "$4" "$5")
  printf 'v1=%s' "$(printf '%s' "$canonical" \
    | openssl dgst -sha256 -hmac "$PAYIN8_SECRET" -r | cut -d' ' -f1)"
}

# payin8 METHOD PATH_AND_QUERY [JSON_BODY] — JSON-запрос; ответ печатается как есть
payin8() {
  local method="$1" path="$2" body="${3-}"
  local ts nonce hash
  ts=$(date +%s)
  nonce=$(openssl rand -hex 16)
  hash=$(printf '%s' "$body" | openssl dgst -sha256 -r | cut -d' ' -f1)
  local args=(-sS -X "$method" "$PAYIN8_BASE_URL$path"
    -H "X-Api-Key: $PAYIN8_KEY_ID" -H "X-Timestamp: $ts" -H "X-Nonce: $nonce"
    -H "X-Signature: $(payin8_sign "$method" "$path" "$ts" "$nonce" "$hash")")
  if [ -n "$body" ]; then
    args+=(-H "Content-Type: application/json" --data-binary "$body")
  fi
  curl "${args[@]}"
}

# payin8_file METHOD PATH_AND_QUERY FILE CONTENT_TYPE — тело запроса = байты файла
payin8_file() {
  local method="$1" path="$2" file="$3" type="$4"
  local ts nonce hash
  ts=$(date +%s)
  nonce=$(openssl rand -hex 16)
  hash=$(openssl dgst -sha256 -r < "$file" | cut -d' ' -f1)
  curl -sS -X "$method" "$PAYIN8_BASE_URL$path" \
    -H "X-Api-Key: $PAYIN8_KEY_ID" -H "X-Timestamp: $ts" -H "X-Nonce: $nonce" \
    -H "X-Signature: $(payin8_sign "$method" "$path" "$ts" "$nonce" "$hash")" \
    -H "Content-Type: $type" --data-binary "@$file"
}

Проверка: вызов GET /v1/balance должен вернуть 200 и ваш баланс.

payin8 GET /v1/balance

Ошибки аутентификации#

HTTP code Когда Что делать
401 signature_missing Нет одного из заголовков X-Api-Key, X-Timestamp, X-Nonce, X-Signature Отправлять все четыре
401 nonce_invalid X-Nonce не подходит под ^[A-Za-z0-9_-]{16,64}$ Исправить генерацию строки
401 api_key_invalid Ключа нет, он отозван или его срок после ротации истёк Проверить ключ в кабинете, выпустить новый
401 timestamp_out_of_window X-Timestamp не в формате (10 цифр) или дальше допустимого окна от времени сервера (по умолчанию 300 с); details.serverTime — время сервера Синхронизировать часы, подписать запрос заново
401 signature_invalid Подпись не сошлась или заголовок не в формате v1=<64 hex> Сверить каноническую строку с примером: путь со строкой запроса, хеш именно отправленных байтов тела, секрет целиком
401 nonce_replayed X-Nonce уже использован этим ключом Каждый запрос — новая строка
403 ip_not_allowed Адрес отправителя не в списке IP ключа Добавить адрес в список ключа или отправлять с разрешённого адреса
403 ip_allowlist_required Создание выплаты или приёма с flow: requisite ключом без списка IP; details.code — операция Задать ключу список IP
403 tenant_blocked Мерчант заблокирован Обратиться в поддержку Payin8
403 project_disabled Проект ключа выключен Обратиться в поддержку Payin8
403 permission_denied У ключа нет права на точку; details.code — нужное право Выдать ключу право в кабинете
429 rate_limited Превышен лимит запросов ключа в минуту; details.retryAfterSec и заголовок Retry-After — через сколько секунд повторить Подождать и повторить с новой подписью
503 nonce_store_unavailable Проверка запросов временно недоступна Повторить позже с новой подписью

API

Приёмы#

Приём (pay-in) — деньги, которые клиент переводит вам банковским переводом на счёт исполнителя Payin8. Как проходит приём — в обзоре, статусы — в Статусах сделок.

Объект приёма#

Так приём выглядит в ответах API и в поле data вебхуков payin.*.

Поле Тип Смысл
id string (UUID) Идентификатор приёма в Payin8
object string Всегда payin
invoiceId string Ваш номер. В ответе на создание и на GET …/by-invoice/{invoiceId} — номер из запроса, в остальных ответах и вебхуках — первый номер сделки
invoiceIds string[] Все ваши номера, присоединённые к этому приёму (см. Повтор того же клиента)
status string created, awaiting_payment, client_paid, completed, expired, canceled
final boolean true — статус больше не изменится сам. false — может измениться (например, истёкший приём ещё можно подтвердить, по сделке открыт спор)
flow string requisite или widget
method string bank_transfer
currency string Валюта, например ARS
requestedAmount string Сумма из вашего запроса
amount string Сумма к оплате, пока приём открыт; подтверждённая сумма — после completed. Может отличаться от requestedAmount
fee string | null Ваша комиссия с этой суммы
net string | null amount − fee: зачисляется на баланс после completed
customer object { "id", "name" } клиента из запроса (name — null, если не передавали)
paymentUrl string | null Ссылка на страницу оплаты; только при flow: widget
requisite object | null Реквизит для оплаты; только при flow: requisite, в статусах awaiting_payment и client_paid, в ответе на создание, GET одного приёма и вебхуке payin.assigned. В списках всегда null
requisite.type string cvu или cbu
requisite.number string Номер счёта, 22 цифры
requisite.alias string | null Алиас счёта
requisite.holderName string Владелец счёта
requisite.holderTaxId string | null CUIT/CUIL владельца, 11 цифр
requisite.bankName string Банк
expiresAt string | null Срок оплаты; null, пока исполнитель не назначен
failureReason string | null Причина неуспеха при expired и canceled (см. Причины)
dispute object | null { "id", "status" } открытого спора по сделке
returnUrls object { "success", "fail", "back" } из запроса (null, если не передавали)
locale string Язык страницы оплаты: es или en
metadata object Ваши метаданные из запроса
test boolean Зарезервировано, сейчас всегда false
version integer Номер версии сделки; растёт при каждом изменении
createdAt, updatedAt string Создан, изменён
assignedAt string | null Назначен исполнитель
clientPaidAt string | null Клиент отметил оплату на странице оплаты
completedAt string | null Подтверждён
expiredAt string | null Истёк
canceledAt string | null Отменён

Запросы#

POST/v1/payins#

Создаёт приём. Право ключа: merchant_api.payins.create. Для flow: requisite у ключа должен быть непустой список IP.

Тело запроса

Поле Тип Обязательно Ограничения Смысл
invoiceId string да 1–64 символа A–Z a–z 0–9 . _ : - Ваш номер заказа. Уникален среди приёмов мерчанта
amount string да > 0, не больше знаков, чем у валюты Сумма
currency string да Код валюты заглавными буквами ARS
method string да bank_transfer Метод
flow string да requisite | widget Способ приёма
waitSec integer нет от 0 до предела площадки (по умолчанию предел — 20); без поля — значение по умолчанию площадки (по умолчанию 20) Только flow: requisite: сколько секунд ответ ждёт назначения исполнителя, считая от начала запроса. Больше предела — 400 validation_failed
customer.id string да 1–128 печатных символов ASCII без пробелов Ваш идентификатор клиента
customer.name string нет 2–100 символов Имя клиента; повторные пробелы схлопываются
customer.email string нет e-mail, до 254 символов E-mail клиента
customer.ip string нет IPv4 или IPv6 IP-адрес клиента
returnUrls.success string нет https://, до 2048 символов, без # и логина в адресе Куда страница оплаты вернёт клиента после успешной оплаты
returnUrls.fail string нет то же …после неуспеха
returnUrls.back string нет то же Кнопка «назад» на странице оплаты
locale string нет es | en, по умолчанию es Язык страницы оплаты
metadata object нет До 10 ключей [A-Za-z0-9_]{1,40}, значения — строки до 256 символов Ваши данные; возвращаются в ответах и вебхуках

Ответ

HTTP Когда Тело
201 Приём создан, или ваш invoiceId присоединён к открытому приёму того же клиента Объект приёма
202 flow: requisite: исполнитель ещё подбирается после waitSec; status: created, requisite: null Объект приёма
200 Повтор того же запроса; заголовок Idempotent-Replayed: true Объект приёма в текущем состоянии

При flow: requisite ответ 201 обычно уже содержит status: awaiting_payment, requisite и expiresAt: покажите клиенту requisite и сумму amount (не requestedAmount). Если подбор не удался за время ожидания, приходит 201 со status: canceled и failureReason: no_trader. После 202 реквизит придёт в вебхуке payin.assigned и в GET /v1/payins/{id}.

При flow: widget ответ 201 содержит paymentUrl — отправьте на неё клиента.

Каждая выдача реквизита учитывается в лимитах проекта (см. Ограничения).

JSON
{
  "id": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
  "object": "payin",
  "invoiceId": "inv-100501",
  "invoiceIds": ["inv-100501"],
  "status": "awaiting_payment",
  "final": false,
  "flow": "requisite",
  "method": "bank_transfer",
  "currency": "ARS",
  "requestedAmount": "15000.00",
  "amount": "15000.00",
  "fee": "375.00",
  "net": "14625.00",
  "customer": { "id": "client-42", "name": "Juan Perez" },
  "paymentUrl": null,
  "requisite": {
    "type": "cvu",
    "number": "0000003110000987654323",
    "alias": null,
    "holderName": "Martin Suarez",
    "holderTaxId": null,
    "bankName": "Banco Ejemplo"
  },
  "expiresAt": "2026-11-19T16:16:53.925Z",
  "failureReason": null,
  "dispute": null,
  "returnUrls": { "success": "https://shop.example.com/pay/ok", "fail": null, "back": null },
  "locale": "en",
  "metadata": { "orderId": "A-1001" },
  "test": false,
  "version": 2,
  "createdAt": "2026-11-19T16:07:53.910Z",
  "updatedAt": "2026-11-19T16:07:53.979Z",
  "assignedAt": "2026-11-19T16:07:53.925Z",
  "clientPaidAt": null,
  "completedAt": null,
  "expiredAt": null,
  "canceledAt": null
}

Ошибки

HTTP code Когда
400 validation_failed Поле не прошло проверку; details.fields — список полей. В том числе: больше знаков, чем у валюты; сумма не больше нуля; waitSec больше допустимого
400 malformed_json Тело — не JSON
403 ip_allowlist_required flow: requisite ключом без списка IP
409 idempotency_conflict Этот invoiceId уже использован с другими параметрами; details.id — тот приём
409 invoice_id_taken Этот invoiceId занят приёмом другого проекта мерчанта
409 customer_open_payins_limit У клиента уже максимум открытых приёмов в проекте; details.limit
422 method_unavailable Метод или валюта не включены для приёмов проекта; details: method, currency, direction
422 amount_out_of_range Сумма вне лимитов метода; details.min, details.max
422 feature_unavailable flow: widget, а страница оплаты недоступна; details.feature: "widget"
429 requisite_reveal_limit Проект исчерпал лимит выдачи реквизитов; details.limit, details.kind (см. Ограничения)
500 no_widget_domain flow: widget, а у проекта нет действующего адреса страницы оплаты; приём не создан

Плюс общие ошибки аутентификации и временные сбои.

payin8 POST /v1/payins '{"invoiceId":"inv-100501","amount":"15000.00","currency":"ARS","method":"bank_transfer","flow":"requisite","customer":{"id":"client-42","name":"Juan Perez"},"metadata":{"orderId":"A-1001"}}'

GET/v1/payins/{id}#

Возвращает приём проекта по id. Право ключа: merchant_api.payins.read.

Параметр пути Тип Смысл
id string (UUID) id приёма

Ответ 200 — объект приёма. Реквизит есть при flow: requisite в статусах awaiting_payment и client_paid.

Ошибки: 400 validation_failed — id не UUID; 404 not_found — приёма нет в проекте ключа.

payin8 GET /v1/payins/3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44

GET/v1/payins/by-invoice/{invoiceId}#

Возвращает приём по вашему номеру — в том числе по номеру, присоединённому к сделке. Право ключа: merchant_api.payins.read. Удобно, если ответ на создание потерялся.

Параметр пути Тип Смысл
invoiceId string Ваш номер, 1–64 символа A–Z a–z 0–9 . _ : -

Ответ 200 — объект приёма; в invoiceId — номер из запроса.

Ошибки: 400 validation_failed — номер не в формате; 404 not_found — приёма с таким номером в проекте ключа нет.

payin8 GET /v1/payins/by-invoice/inv-100501

GET/v1/payins#

Список приёмов проекта, новые сверху. Право ключа: merchant_api.payins.read. Реквизит в элементах списка всегда null.

Параметр запроса Тип Обязательно Смысл
status string нет Один статус приёма
customerId string нет customer.id клиента
createdFrom string нет Создан не раньше этого момента (ISO 8601)
createdTo string нет Создан раньше этого момента (ISO 8601, граница не входит)
limit integer нет 1–100, по умолчанию 50
cursor string нет nextCursor предыдущей страницы

Без периода список охватывает последние 7 дней. Период — не больше 31 дня. Подробно о периоде и страницах — Пагинация и фильтры.

Ответ 200:

Поле Тип Смысл
items object[] Объекты приёма, новые сверху
nextCursor string | null Курсор следующей страницы; null — страница последняя

Ошибки: 400 validation_failed — неизвестный статус, неверная дата, createdFrom не раньше createdTo, период длиннее 31 дня, limit вне 1–100, испорченный курсор.

payin8 GET "/v1/payins?status=completed&createdFrom=2026-11-01T00:00:00Z&createdTo=2026-11-20T00:00:00Z&limit=50"

POST/v1/payins/{id}/cancel#

Отменяет приём, пока клиент не получил реквизит. Право ключа: merchant_api.payins.cancel. Тело — пустое или {}.

Отменить можно:

  • приём в статусе created (исполнитель ещё не назначен);
  • приём flow: widget в статусе awaiting_payment, пока клиент не открыл реквизит на странице оплаты.

Приём flow: requisite считается показанным в момент назначения исполнителя: реквизит уже ушёл к вам в ответе API или вебхуке. Поэтому после awaiting_payment его не отменить — дождитесь истечения срока.

Отмена уже отменённого приёма отвечает 200 с текущим видом.

Параметр пути Тип Смысл
id string (UUID) id приёма

Ответ 200 — объект приёма со status: canceled, failureReason: canceled_by_merchant. Придёт вебхук payin.failed.

Ошибки

HTTP code Когда
404 not_found Приёма нет в проекте ключа
409 requisite_already_shown Реквизит уже выдан; details.shownAt — когда, details.via — где: api, webhook или widget
409 invalid_state Статус не позволяет отмену; details.status — текущий
409 dispute_open По сделке открыт спор; details.disputeId
payin8 POST /v1/payins/3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44/cancel

Повтор того же клиента#

Если у клиента (customer.id) в проекте уже есть открытый приём на ту же сумму (amount запроса) с тем же методом и валютой, созданный недавно (по умолчанию — не раньше 15 минут назад; окно — настройка площадки), Payin8 не создаёт новую сделку, а присоединяет ваш новый invoiceId к открытой: ответ 201 (у flow: requisite, пока исполнитель подбирается, — 202) содержит id той сделки, ваш новый номер в invoiceId и все номера в invoiceIds. Клиент платит один раз; итог приходит по одной сделке. Такой приём не учитывается в лимите открытых приёмов клиента.

Способ приёма (flow) при присоединении не сравнивается: ответ описывает уже открытую сделку в её собственном flow. Поэтому всегда берите из ответа то, что в нём есть: requisite (если сделка flow: requisite) или paymentUrl (если flow: widget), — а не то, что ожидали по своему запросу.

API

Выплаты#

Выплата (pay-out) — перевод с вашего баланса Payin8 на банковский счёт получателя. Исполнитель Payin8 делает перевод и прикладывает чек. Как проходит выплата — в обзоре, статусы — в Статусах сделок.

Объект выплаты#

Так выплата выглядит в ответах API и в поле data вебхуков payout.*.

Поле Тип Смысл
id string (UUID) Идентификатор выплаты в Payin8
object string Всегда payout
invoiceId string Ваш номер выплаты
invoiceIds string[] Все номера сделки; у выплаты — один
status string created, offered, in_progress, verifying, completed, canceled
final boolean true — статус больше не изменится сам (completed или canceled без открытого спора)
method string bank_transfer
currency string Валюта, например ARS
amount string Сумма из запроса — её получает получатель
feePayer string Кто платит комиссию; сейчас всегда merchant
fee string Ваша комиссия за выплату на текущий момент; "0.00" у отменённой
requestedFee string Комиссия, рассчитанная при создании
totalDebit string Списание с баланса за выплату: amount + requestedFee. Удерживается при создании; у выплаты, которая ждёт пополнения баланса (created), — ещё не удержано; у отменённой до удержания — "0.00"
recipientAmount string Сколько должно уйти получателю
paidAmount string | null Сколько фактически переведено; null, пока выплата открыта; "0.00" у отменённой
refundedAmount string | null Сколько вернулось на баланс (частичное исполнение, отмена, отмена исполненной выплаты по спору); null, пока выплата открыта
bankReference string | null Номер банковской операции перевода, если исполнитель его указал
recipient object Получатель (см. ниже)
recipient.type string cvu, cbu или alias
recipient.account string 22 цифры или алиас в нижнем регистре
recipient.holderName string Владелец счёта, как вы его передали (повторные пробелы схлопнуты)
recipient.taxId string | null CUIT/CUIL, 11 цифр без дефисов
customer object { "id", "name" } клиента из запроса
receipts object[] Чеки исполнителя: id, name, contentType, size (байты), uploadedAt. Скачать — GET /v1/payouts/{id}/receipts/{fileId}
failureReason string | null Причина при canceled (см. Причины)
dispute object | null { "id", "status" } открытого спора
metadata object Ваши метаданные
test boolean Зарезервировано, сейчас всегда false
version integer Номер версии; растёт при каждом изменении
createdAt, updatedAt string Создана, изменена
expiresAt string До какого момента выплату должны взять в работу (с учётом ожидания денег на балансе)
startedAt string | null Исполнитель взял выплату в работу
completedAt string | null Исполнена
canceledAt string | null Отменена

У завершённой или отменённой выплаты всегда totalDebit − refundedAmount = paidAmount + fee.

Запросы#

POST/v1/payouts#

Создаёт выплату и удерживает с баланса amount + комиссию. Право ключа: merchant_api.payouts.create; у ключа должен быть непустой список IP.

Тело запроса

Поле Тип Обязательно Ограничения Смысл
invoiceId string да 1–64 символа A–Z a–z 0–9 . _ : - Ваш номер выплаты. Уникален среди выплат мерчанта
amount string да > 0, не больше знаков, чем у валюты Сколько получит получатель
currency string да Код валюты ARS
method string да bank_transfer Метод
feePayer string нет merchant (по умолчанию) Кто платит комиссию: сейчас только merchant — комиссия списывается сверх суммы. Допустимые значения — в payout.feePayers ответа GET /v1/methods
recipient.account string да До 40 символов CVU или CBU — 22 цифры с верными контрольными цифрами (пробелы, точки и дефисы отбрасываются), или алиас — 6–20 символов A–Z a–z 0–9 . -
recipient.holderName string да 2–100 символов Имя владельца счёта
recipient.taxId string нет До 13 символов CUIT/CUIL владельца: 11 цифр с верной контрольной цифрой, дефисы допустимы
customer.id string да 1–128 печатных символов ASCII без пробелов Ваш идентификатор клиента, для которого выплата
customer.name string нет 2–100 символов Имя клиента
metadata object нет До 10 ключей [A-Za-z0-9_]{1,40}, значения — строки до 256 символов Ваши данные

Ответ

HTTP Когда Тело
201 Выплата создана Объект выплаты
200 Повтор того же запроса; заголовок Idempotent-Replayed: true Объект выплаты в текущем состоянии

Новая выплата обычно сразу в статусе offered. Проверяйте status и в ответе 201: если подходящих исполнителей нет, выплата может прийти уже canceled (failureReason: no_trader или expired), удержанное при этом возвращено на баланс (refundedAmount = totalDebit), и придёт вебхук payout.failed. Если денег на балансе не хватает, поведение зависит от правила проекта «Выплата без денег на балансе» (см. Правила проекта): «отклонить сразу» — отказ 409 insufficient_balance; «ждать пополнения» — выплата создаётся в статусе created и ждёт пополнения баланса до expiresAt; не дождалась — canceled с failureReason: insufficient_balance.

JSON
{
  "id": "7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f",
  "object": "payout",
  "invoiceId": "wd-200731",
  "invoiceIds": ["wd-200731"],
  "status": "offered",
  "final": false,
  "method": "bank_transfer",
  "currency": "ARS",
  "amount": "20000.00",
  "feePayer": "merchant",
  "fee": "200.00",
  "requestedFee": "200.00",
  "totalDebit": "20200.00",
  "recipientAmount": "20000.00",
  "paidAmount": null,
  "refundedAmount": null,
  "bankReference": null,
  "recipient": {
    "type": "cvu",
    "account": "0000003110000123456781",
    "holderName": "Maria Gomez",
    "taxId": "20312345677"
  },
  "customer": { "id": "client-77", "name": "Maria Gomez" },
  "receipts": [],
  "failureReason": null,
  "dispute": null,
  "metadata": { "withdrawalId": "W-77" },
  "test": false,
  "version": 1,
  "createdAt": "2026-11-19T16:09:23.307Z",
  "updatedAt": "2026-11-19T16:09:23.334Z",
  "expiresAt": "2026-11-19T20:09:23.292Z",
  "startedAt": null,
  "completedAt": null,
  "canceledAt": null
}

Ошибки

HTTP code Когда
400 validation_failed Поле не прошло проверку; details.fields
400 malformed_json Тело — не JSON
403 ip_allowlist_required У ключа нет списка IP
409 idempotency_conflict Этот invoiceId уже использован с другими параметрами; details.id — та выплата
409 invoice_id_taken Этот invoiceId занят выплатой другого проекта мерчанта
409 insufficient_balance Не хватает доступного баланса; details.currency, details.available, details.required
422 invalid_recipient Счёт или CUIT получателя неверен; details.field (recipient.account, recipient.holderName, recipient.taxId), details.rule: format — не тот формат, checksum — не сошлась контрольная цифра
422 fee_payer_unavailable feePayer не разрешён; details.allowed — допустимые значения
422 method_unavailable Выплаты по методу или валюте не включены для проекта; details: method, currency, direction
422 amount_out_of_range Сумма вне лимитов метода; details.min, details.max
422 negative_margin Выплату нельзя провести с текущими условиями тарифа; обратитесь в поддержку

Плюс общие ошибки аутентификации и временные сбои.

payin8 POST /v1/payouts '{"invoiceId":"wd-200731","amount":"20000.00","currency":"ARS","method":"bank_transfer","recipient":{"account":"0000003110000123456781","holderName":"Maria Gomez","taxId":"20-31234567-7"},"customer":{"id":"client-77","name":"Maria Gomez"},"metadata":{"withdrawalId":"W-77"}}'

GET/v1/payouts/{id}#

Возвращает выплату проекта по id. Право ключа: merchant_api.payouts.read.

Параметр пути Тип Смысл
id string (UUID) id выплаты

Ответ 200 — объект выплаты.

Ошибки: 400 validation_failed — id не UUID; 404 not_found — выплаты нет в проекте ключа.

payin8 GET /v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f

GET/v1/payouts/by-invoice/{invoiceId}#

Возвращает выплату по вашему номеру. Право ключа: merchant_api.payouts.read.

Параметр пути Тип Смысл
invoiceId string Ваш номер, 1–64 символа A–Z a–z 0–9 . _ : -

Ответ 200 — объект выплаты.

Ошибки: 400 validation_failed — номер не в формате; 404 not_found — выплаты с таким номером в проекте ключа нет.

payin8 GET /v1/payouts/by-invoice/wd-200731

GET/v1/payouts#

Список выплат проекта, новые сверху. Право ключа: merchant_api.payouts.read.

Параметр запроса Тип Обязательно Смысл
status string нет Один статус выплаты
customerId string нет customer.id клиента
createdFrom string нет Создана не раньше этого момента (ISO 8601)
createdTo string нет Создана раньше этого момента (ISO 8601, граница не входит)
limit integer нет 1–100, по умолчанию 50
cursor string нет nextCursor предыдущей страницы

Без периода — последние 7 дней; период — не больше 31 дня (см. Пагинация и фильтры).

Ответ 200: items — объекты выплаты, nextCursor — курсор следующей страницы или null.

Ошибки: 400 validation_failed — как у списка приёмов.

payin8 GET "/v1/payouts?customerId=client-77&limit=20"

GET/v1/payouts/{id}/receipts/{fileId}#

Скачивает чек исполнителя по выплате. fileId — id из массива receipts выплаты. Право ключа: merchant_api.payouts.read.

Параметр пути Тип Смысл
id string (UUID) id выплаты
fileId string (UUID) id чека

Ответ 200 — байты файла (не JSON). Заголовки:

Заголовок Значение
Content-Type application/pdf, image/png, image/jpeg или image/webp
Content-Length Размер в байтах
Content-Disposition attachment; filename="…"; filename*=UTF-8''…
ETag SHA-256 файла в кавычках. Запрос с If-None-Match с этим значением получает 304 без тела

Ошибки: 400 validation_failed — id или fileId не UUID; 404 not_found — нет такой выплаты в проекте или такого чека у этой выплаты.

payin8 GET /v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f/receipts/5d2e8f1a-9c3b-4a7d-b6e5-0f1e2d3c4b5a > receipt.bin

POST/v1/payouts/{id}/cancel#

Отменяет выплату, пока её не взял исполнитель: в статусах created и offered. Удержанное возвращается на баланс. Право ключа: merchant_api.payouts.cancel. Тело — пустое или {}.

Отмена уже отменённой выплаты отвечает 200 с текущим видом.

Параметр пути Тип Смысл
id string (UUID) id выплаты

Ответ 200 — объект выплаты со status: canceled, failureReason: canceled_by_merchant, refundedAmount = totalDebit. Придёт вебхук payout.failed.

Ошибки

HTTP code Когда
404 not_found Выплаты нет в проекте ключа
409 invalid_state Выплата уже взята исполнителем или завершена; details.status — текущий статус
409 dispute_open По выплате открыт спор; details.disputeId
payin8 POST /v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f/cancel

API

Баланс и методы#

Баланс мерчанта и условия методов проекта: лимиты сумм и комиссии. Как пополняется баланс и как вывести деньги — в разделах кабинета Баланс и Выводы.

Запросы#

GET/v1/balance#

Баланс мерчанта по валютам. Право ключа: merchant_api.balance.read. Баланс общий для всех проектов мерчанта: ключи разных проектов видят одни и те же суммы.

Ответ 200

Поле Тип Смысл
balances object[] Счета мерчанта, по одному на валюту
balances[].currency string Валюта
balances[].available string Доступно: можно тратить на выплаты и выводы
balances[].hold string Удержано под открытые операции (например, созданные выплаты)
balances[].total string available + hold
JSON
{
  "balances": [
    { "currency": "ARS", "available": "1243903.76", "hold": "20200.00", "total": "1264103.76" }
  ]
}

Приём зачисляется в available суммой net после completed. Выплата при создании переводит totalDebit из available в hold; после исполнения удержанное списывается, после отмены — возвращается в available. В кабинете эти части баланса называются «Доступно», «Заморожено» и «Всего» (см. Баланс).

payin8 GET /v1/balance

GET/v1/methods#

Методы и валюты проекта: лимиты суммы одной сделки и ваши комиссии отдельно для приёмов и выплат. Право ключа: merchant_api.methods.read.

Ответ 200

Поле Тип Смысл
items object[] По элементу на пару «метод — валюта»
items[].method string bank_transfer
items[].currency string Валюта
items[].payin object | null Условия приёмов; null — приёмы по этой паре недоступны проекту
items[].payout object | null Условия выплат; null — выплаты недоступны
….minAmount, ….maxAmount string Лимиты суммы одной сделки; сумма вне них — 422 amount_out_of_range
….fee.percent string Процент комиссии: "2.5" — 2,5 %
….fee.min string | null Минимальная комиссия; null — нет
….fee.fixed string | null Фиксированная добавка к комиссии; null — нет
items[].payout.feePayers string[] Допустимые значения feePayer при создании выплаты

Комиссия сделки = большее из (сумма × percent / 100) и min, плюс fixed. Для приёма она считается от суммы приёма (fee в объекте приёма), для выплаты — от суммы выплаты и добавляется сверху (fee в объекте выплаты).

JSON
{
  "items": [
    {
      "method": "bank_transfer",
      "currency": "ARS",
      "payin": {
        "minAmount": "1000.00",
        "maxAmount": "1000000.00",
        "fee": { "percent": "2.5", "min": null, "fixed": null }
      },
      "payout": {
        "minAmount": "1000.00",
        "maxAmount": "1000000.00",
        "fee": { "percent": "1", "min": null, "fixed": null },
        "feePayers": ["merchant"]
      }
    }
  ]
}
payin8 GET /v1/methods

API

Файлы#

Файлы к сделкам вашего проекта: чек оплаты клиента по приёму и доказательства для спора. Чеки исполнителя по выплатам скачиваются через GET /v1/payouts/{id}/receipts/{fileId}.

Запросы#

POST/v1/files#

Загружает файл и прикрепляет его к сделке. Право ключа: merchant_api.files.create.

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

Параметр Тип Обязательно Ограничения Смысл
dealId string да UUID id приёма или выплаты вашего проекта
purpose string нет receipt (по умолчанию) | evidence receipt — чек оплаты клиента по приёму; evidence — доказательство для спора
name string нет 1–120 символов, без /, \ и управляющих символов Имя файла. Без него — имя части формы или file

Тело запроса — одно из двух:

  • сами байты файла, Content-Type — тип файла (например, application/pdf);
  • форма multipart/form-data с файлом в части file.

Подписывается всё тело целиком, как у любого запроса (см. Каноническая строка).

Файл

  • Типы: PDF, PNG, JPEG, WebP. Тип определяется по первым байтам файла; заголовок Content-Type и расширение в имени на это не влияют. Другой тип или пустой файл — 415 file_type_not_allowed.
  • Размер одного файла — до предела площадки (по умолчанию 10 МБ); больше — 413 file_too_large. В details.maxBytes — сработавший предел в байтах: предел файла или, если слишком велико всё тело запроса, предел тела (он больше на запас для формы multipart).
  • У одной сделки — не больше 10 ваших файлов (значение по умолчанию; считаются файлы с любым purpose) — 409 files_limit_reached. Есть также предел суммарного объёма файлов сделки (по умолчанию 30 МБ) и суточный предел загрузок мерчанта (по умолчанию 2 ГБ) — 413 files_quota_exceeded.
  • Имя очищается: опасные символы заменяются пробелами, расширение ставится по настоящему типу файла (scan.png, загруженный как PDF, станет scan.pdf).
  • Повторная загрузка тех же байтов с тем же purpose к той же сделке не создаёт новый файл: ответ 200 с ранее загруженным.

Ответ

HTTP Когда
201 Файл загружен
200 Такой файл у сделки уже есть; возвращён он
Поле Тип Смысл
id string (UUID) id файла; для спора передайте его в fileIds
name string Имя после очистки
contentType string Определённый тип: application/pdf, image/png, image/jpeg, image/webp
size integer Размер в байтах
uploadedAt string Когда загружен
JSON
{
  "id": "9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b",
  "name": "bank-statement.pdf",
  "contentType": "application/pdf",
  "size": 48213,
  "uploadedAt": "2026-11-19T16:10:12.480Z"
}

Ошибки

HTTP code Когда
400 validation_failed dealId не UUID, неверный purpose или name, в форме нет части file
404 not_found Сделки нет в проекте ключа
409 files_limit_reached У сделки уже максимум ваших файлов; details.limit
413 file_too_large Файл больше предела; details.maxBytes
413 files_quota_exceeded Исчерпан предел объёма; details.quota (deal — сделка, merchant_day — сутки), details.limitBytes
415 file_type_not_allowed Тип не PDF, PNG, JPEG или WebP; details.allowed
503 files_storage_unavailable Загрузка временно приостановлена; повторите позже
payin8_file POST "/v1/files?dealId=3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44&purpose=evidence&name=bank-statement.pdf" ./bank-statement.pdf application/pdf

API

Споры#

Спор — обращение к Payin8 по сделке вашего проекта: клиент оплатил, а приём не зачислен; клиент заплатил другую сумму; получатель не получил выплату. Спор можно открыть и от имени клиента. Решение по спору принимает Payin8; результат приходит вебхуком dispute.closed и виден в GET /v1/disputes/{id}. Работа со спорами в кабинете — Споры.

Пока по сделке открыт спор, у неё final: false, поле dispute содержит { "id", "status": "open" }, а отмена сделки отвечает 409 dispute_open.

Объект спора#

Так спор выглядит в ответах API и в поле data вебхуков dispute.opened и dispute.closed.

Поле Тип Смысл
id string (UUID) Идентификатор спора
object string Всегда dispute
dealId string (UUID) Сделка спора
dealType string payin или payout
invoiceId string Ваш номер сделки (первый)
status string open или closed
reason string Причина, с которой вы открыли спор; opened_by_platform — спор открыли не вы (Payin8 по своей проверке)
comment string | null Ваш комментарий при открытии. В вебхуках всегда null — читайте его через API
claimedAmount string | null Сумма, которую, по вашим словам, заплатил клиент (для amount_mismatch)
outcome string | null Итог закрытого спора (см. ниже); у открытого — null
resolvedAmount string | null Итоговая сумма сделки при outcome: amount_changed
files object[] Ваши файлы-доказательства по сделке: id, name, contentType, size, uploadedAt
openedAt string Открыт
closedAt string | null Закрыт

Итоги спора (outcome)

Значение Что стало со сделкой
deal_completed Сделка подтверждена (приём зачислен, выплата признана исполненной)
amount_changed Сумма сделки изменена на resolvedAmount; по приёму придёт вебхук payin.amount_changed
deal_canceled Сделка отменена
deal_reversed Завершённая сделка отменена с возвратом денег (failureReason: reversed_after_dispute)
rejected Сделка осталась как была

Запросы#

POST/v1/disputes#

Открывает спор по сделке проекта. Право ключа: merchant_api.disputes.create.

Тело запроса

Поле Тип Обязательно Ограничения Смысл
dealId string да UUID id приёма или выплаты
reason string да см. таблицу ниже Причина
comment string нет До 2000 символов Описание для Payin8
claimedAmount string для amount_mismatch > 0, не больше знаков, чем у валюты Сколько заплатил клиент
fileIds string[] нет До 10 разных UUID Ваши файлы этой сделки, загруженные через POST /v1/files. В поле files спора видны только файлы с purpose=evidence, поэтому доказательства загружайте с ним
Сделка reason Когда
Приём payment_not_credited Клиент оплатил, а приём не завершён
Приём amount_mismatch Клиент заплатил другую сумму; нужна claimedAmount
Приём, выплата other Другое
Выплата recipient_not_paid Получатель не получил деньги

Когда можно открыть

  • Приём — в статусах awaiting_payment, client_paid, expired, completed, а также canceled, если исполнитель был назначен.
  • Выплата — в статусах in_progress и completed.
  • Не позже установленного срока после создания сделки (по умолчанию — 7 дней); срок виден в details.until отказа window.

Если по сделке уже открыт спор, новый не создаётся: ответ 200 с открытым спором, а ваш комментарий и файлы добавляются к нему. Поля reason и comment спора при этом не меняются.

Ответ

HTTP Когда
201 Спор открыт; придёт вебхук dispute.opened
200 По сделке уже был открыт спор; возвращён он

Тело — объект спора:

JSON
{
  "id": "c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "object": "dispute",
  "dealId": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
  "dealType": "payin",
  "invoiceId": "inv-100501",
  "status": "open",
  "reason": "amount_mismatch",
  "comment": "The client paid 11000.00, see the bank statement",
  "claimedAmount": "11000.00",
  "outcome": null,
  "resolvedAmount": null,
  "files": [
    {
      "id": "9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b",
      "name": "bank-statement.pdf",
      "contentType": "application/pdf",
      "size": 48213,
      "uploadedAt": "2026-11-19T16:10:12.480Z"
    }
  ],
  "openedAt": "2026-11-19T16:10:18.841Z",
  "closedAt": null
}

Ошибки

HTTP code Когда
400 validation_failed Поле не прошло проверку; в том числе нет claimedAmount при amount_mismatch
404 not_found Сделки нет в проекте ключа
409 dispute_not_allowed Спор сейчас открыть нельзя; details.why: reason — причина не подходит к типу сделки, status — статус сделки (в details.status), window — прошёл срок (в details.until)
422 file_not_attachable Файл из fileIds нельзя приложить; details.fileId и details.why: deal — файл другой сделки, uploader — файл загрузили не вы, status — файла нет или он уже недоступен
payin8 POST /v1/disputes '{"dealId":"3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44","reason":"amount_mismatch","claimedAmount":"11000.00","comment":"The client paid 11000.00, see the bank statement","fileIds":["9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b"]}'

GET/v1/disputes/{id}#

Возвращает спор проекта. Право ключа: merchant_api.disputes.read.

Параметр пути Тип Смысл
id string (UUID) id спора

Ответ 200 — объект спора.

Ошибки: 400 validation_failed — id не UUID; 404 not_found — спора нет в проекте ключа.

payin8 GET /v1/disputes/c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d

GET/v1/disputes#

Споры проекта, сначала недавно открытые. Право ключа: merchant_api.disputes.read.

Параметр запроса Тип Обязательно Смысл
status string нет open или closed
dealId string нет Споры одной сделки (UUID)
limit integer нет 1–100, по умолчанию 50
cursor string нет nextCursor предыдущей страницы

Ответ 200: items — объекты спора, nextCursor — курсор следующей страницы или null.

Ошибки: 400 validation_failed — неверный status, dealId, limit или курсор.

payin8 GET "/v1/disputes?status=open&limit=20"

POST/v1/disputes/{id}/evidence#

Добавляет к открытому спору комментарий и (или) файлы. Право ключа: merchant_api.disputes.create.

Параметр пути Тип Смысл
id string (UUID) id спора

Тело запроса — нужно хотя бы одно из полей:

Поле Тип Ограничения Смысл
comment string До 2000 символов Текст для Payin8
fileIds string[] До 10 разных UUID Ваши файлы этой сделки, загруженные через POST /v1/files (доказательства — с purpose=evidence)

Ответ 200 — объект спора. Добавленный комментарий в объекте не показывается: поле comment — только текст при открытии.

Ошибки

HTTP code Когда
400 validation_failed Нет ни comment, ни fileIds, или поле не прошло проверку
404 not_found Спора нет в проекте ключа
409 invalid_state Спор уже закрыт; details.status: "closed"
422 file_not_attachable Файл нельзя приложить; details.fileId, details.why (deal, uploader, status — как у открытия спора)
payin8 POST /v1/disputes/c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/evidence '{"comment":"Second page of the statement","fileIds":["9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b"]}'

API

Статусы сделок#

Статус сделки — поле status в объекте приёма и объекте выплаты. Изменения статуса, о которых нужно знать вашей системе, приходят вебхуками; в любой момент статус можно прочитать через GET.

Ориентируйтесь на два поля вместе:

  • status — где сделка сейчас;
  • final — может ли статус ещё измениться без вашего участия. Пока final: false, не считайте исход окончательным: истёкший приём ещё может быть подтверждён, по сделке может идти спор.

Статусы приёма#

Статус Что значит final
created Приём создан, Payin8 подбирает исполнителя и реквизит false
awaiting_payment Реквизит назначен, ждём перевода клиента до expiresAt false
client_paid Клиент отметил на странице оплаты, что перевёл деньги; поступление ещё не подтверждено. Бывает только при flow: widget false
completed Поступление подтверждено, net зачислен на баланс true, если нет открытого спора
expired Срок оплаты прошёл без подтверждения, или клиент отменил оплату на странице оплаты false, пока открыто окно позднего подтверждения; затем true
canceled Приём отменён: исполнитель не найден, отменили вы, клиент или Payin8, либо завершённый приём отменён по спору true, если нет открытого спора

Переходы приёма#

Из В Когда Вебхук
created awaiting_payment Назначен исполнитель payin.assigned
created canceled Исполнитель не найден (no_trader); отмена вами, клиентом или Payin8 payin.failed
awaiting_payment client_paid Клиент отметил оплату на странице оплаты —
awaiting_payment, client_paid completed Поступление подтверждено payin.completed
awaiting_payment, client_paid expired Истёк срок expiresAt; клиент отменил оплату на странице оплаты (из awaiting_payment) payin.failed
awaiting_payment, client_paid canceled Отмена вами (только flow: widget до показа реквизита) или Payin8 payin.failed
expired completed Деньги пришли после срока, поступление подтверждено в окне позднего подтверждения payin.completed
expired, canceled completed / canceled Решение Payin8 по спору payin.completed / payin.failed
completed canceled Решение по спору: завершённый приём отменён (reversed_after_dispute), зачисление списано с баланса payin.failed
completed completed Решение по спору: изменена сумма приёма payin.amount_changed

Подтверждённая сумма может отличаться от суммы к оплате: если клиент перевёл другую сумму, приём может быть подтверждён на фактическую. Итоговые amount, fee и net — в вебхуке payin.completed и в GET /v1/payins/{id}.

Сроки приёма#

  • Подбор исполнителя идёт сразу после создания и длится не дольше настроенного времени (по умолчанию — 30 секунд). Не нашёлся — приём canceled с failureReason: no_trader.
  • Срок оплаты отсчитывается от назначения исполнителя; момент окончания — expiresAt. Длительность задаётся настройками (по умолчанию — 15 минут).
  • Окно позднего подтверждения. После expired приём ещё может стать completed, если деньги всё-таки пришли. Окно отсчитывается от expiresAt; пока оно открыто, у истёкшего приёма final: false. Включено ли окно и его длительность — настройки проекта (по умолчанию включено, 24 часа; см. Проекты).

Причины неуспеха приёма#

Поле failureReason заполнено в статусах expired и canceled, в остальных — null.

failureReason Статус Что произошло
expired expired Истёк срок оплаты
canceled_by_customer expired или canceled Клиент отменил оплату на странице оплаты: до назначения — canceled, после — expired с окном позднего подтверждения
no_trader canceled Не нашлось исполнителя
canceled_by_merchant canceled Отменили вы (POST /v1/payins/{id}/cancel или кабинет)
canceled_by_support canceled Отменил Payin8 (в том числе решением по спору)
reversed_after_dispute canceled Завершённый приём отменён решением по спору

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

Статус Что значит final
created Выплата ждёт пополнения баланса: денег не хватило при создании, а проект настроен ждать false
offered Сумма удержана, выплата предложена исполнителям false
in_progress Исполнитель взял выплату и переводит деньги false
verifying Зарезервировано; сейчас выплаты в этот статус не переходят false
completed Перевод выполнен; чеки исполнителя — в receipts true, если нет открытого спора
canceled Выплата отменена, удержанное вернулось на баланс true, если нет открытого спора

Переходы выплаты#

Из В Когда Вебхук
created offered Баланс пополнен, сумма удержана —
created canceled Деньги не появились до expiresAt (insufficient_balance); отмена вами или Payin8 payout.failed
offered in_progress Исполнитель взял выплату —
offered canceled Никто не взял до expiresAt (expired); нет подходящих исполнителей (no_trader); отмена вами или Payin8 payout.failed
in_progress offered Исполнитель вернул выплату или не начал перевод вовремя; её снова предлагают исполнителям —
in_progress completed Перевод выполнен payout.completed
in_progress canceled Перевод невозможен: счёт не существует, имя владельца не совпало, банк получателя отказал; или отмена Payin8 payout.failed
completed canceled Решение по спору: выплата признана неисполненной (reversed_after_dispute) payout.failed
completed completed Решение по спору: изменена исполненная сумма payout.completed
canceled completed Решение по спору: выплата признана исполненной payout.completed

Выплата может быть исполнена частично: тогда paidAmount меньше amount, комиссия fee пересчитывается, а неизрасходованная часть удержания возвращается на баланс (refundedAmount). У завершённой и отменённой выплаты всегда totalDebit − refundedAmount = paidAmount + fee.

Сроки выплаты#

  • expiresAt — до какого момента выплату должен взять исполнитель; время ожидания пополнения баланса входит в этот срок. Длительность задаётся настройками проекта (по умолчанию — 4 часа от создания).
  • Взятая выплата (in_progress) по expiresAt не отменяется. Если исполнитель долго не прикладывает чек, Payin8 сам открывает по ней спор — он придёт вебхуком dispute.opened с reason: opened_by_platform.

Причины неуспеха выплаты#

Поле failureReason заполнено только в статусе canceled.

failureReason Что произошло
expired Никто не взял выплату до expiresAt
insufficient_balance Выплата ждала пополнения баланса, а деньги не появились до expiresAt
no_trader Нет исполнителей, которые могут её выполнить
canceled_by_merchant Отменили вы
canceled_by_support Отменил Payin8
recipient_invalid Счёт получателя не существует или закрыт, либо имя владельца не совпало
recipient_rejected Банк получателя не принял перевод
reversed_after_dispute Исполненная выплата отменена решением по спору

Окончательный исход#

Считайте сделку закрытой, когда в data вебхука или в ответе GET пришло final: true (сам факт прихода вебхука, например payin.failed об истёкшем приёме, этого не означает):

  • приём: completed или canceled без спора; expired — после закрытия окна позднего подтверждения;
  • выплата: completed или canceled без спора.

final: true значит, что сделка не изменится сама. Изменить её может только решение по спору — открытому вами или Payin8: сначала придёт dispute.opened, затем, если решение меняет сделку, — вебхук сделки с её новым состоянием (например, payin.failed с reversed_after_dispute или payin.amount_changed) и dispute.closed. Поэтому обрабатывайте эти вебхуки и после того, как сделка стала окончательной.

Вебхука о том, что final стал true (окно позднего подтверждения закрылось, спор закрыт без изменения сделки), нет: после dispute.closed и для истёкших приёмов перечитайте сделку через GET, когда это важно для учёта.

API

Вебхуки#

Вебхук — запрос POST от Payin8 на адрес вашего сервера, когда со сделкой или спором что-то произошло. Адрес, список событий и секрет подписи задаются для проекта в кабинете (см. Вебхуки); там же журнал доставок и повторная отправка события.

Требования к адресу#

  • Только https://; порт — из разрешённых площадкой (по умолчанию 443 или 8443).
  • В адресе — доменное имя (не IP-адрес), без логина и пароля, без #; до 2048 символов.
  • Имя должно указывать на публичные адреса: внутренние и служебные адреса не принимаются.
  • Сертификат — действительный, выданный публичным удостоверяющим центром, TLS 1.2 или новее.
  • Перенаправления (3xx) не выполняются и считаются неудачной попыткой.

События#

Тип Когда data
payin.assigned Приёму назначен исполнитель, статус awaiting_payment. При flow: requisite тело содержит реквизит Объект приёма
payin.completed Приём подтверждён: из awaiting_payment, client_paid, после истечения срока или по решению спора Объект приёма
payin.failed Приём expired или canceled (см. failureReason) Объект приёма
payin.amount_changed По решению спора изменена сумма завершённого приёма. В конверте есть previous Объект приёма
payout.completed Выплата исполнена (в том числе повторно — при изменении суммы или по решению спора) Объект выплаты
payout.failed Выплата canceled (см. failureReason) Объект выплаты
dispute.opened По сделке открыт спор — вами или Payin8 Объект спора
dispute.closed Спор закрыт, в outcome — итог Объект спора
webhook.ping Кнопка «Проверить» в кабинете. Приходит, даже если вы на него не подписаны { "projectId", "message": "ping" }

Приходят только события, на которые подписан адрес проекта (кроме webhook.ping). На переходы без вебхука (client_paid, offered, in_progress) ориентируйтесь по GET — см. Статусы сделок.

data вебхука — тот же объект, что вернёт GET по этой сделке или спору в той же версии. Отличие одно: в data событий dispute.* поле comment всегда null.

Конверт#

Поле Тип Смысл
id string (UUID) Идентификатор события. Один и тот же во всех попытках и при повторной отправке
type string Тип события
apiVersion string v1
createdAt string Когда событие произошло
test boolean Зарезервировано, сейчас всегда false
data object Объект сделки или спора (см. таблицу событий)
previous object Только у payin.amount_changed: amount, fee, net до изменения

Тело события фиксируется в момент события и не превышает 32 КБ; каждая попытка и повторная отправка несут одни и те же байты.

Заголовки запроса#

Заголовок Значение
Content-Type application/json
User-Agent payin8-webhooks/1.0
Payin8-Signature Подпись: t=<unix-секунды>,v1=<hex>[,v1=<hex>]
Payin8-Event-Id id события — то же, что id в теле
Payin8-Event-Type Тип события
Payin8-Delivery-Id Идентификатор доставки. Повторная отправка из кабинета после того, как доставка закончилась, создаёт новую доставку с новым Payin8-Delivery-Id, но тем же событием; пока доставка ещё повторяется, она лишь ускоряет следующую попытку той же доставки
Payin8-Attempt Номер попытки в доставке: 1, 2, …

Проверка подписи#

Payin8-Signature: t=1795104473,v1=5b0c0f1e8a…(64 hex)
v1 = hex( HMAC-SHA256( key = секрет "whsec_…" целиком в UTF-8, message = t + "." + сырое тело ) )
  1. Возьмите из заголовка t и все значения v1.
  2. Посчитайте HMAC-SHA256 от строки t, точки и сырых байтов тела — до разбора JSON. Ключ — вся строка секрета вместе с префиксом whsec_.
  3. Примите запрос, если ваше значение совпало с любым v1 (сравнивайте за постоянное время) и |сейчас − t| не больше 300 секунд.

Значений v1 бывает несколько после смены секрета в кабинете: какое-то время запрос подписан и новым, и прежним секретом. t — время попытки, поэтому у каждой попытки подпись своя.

Секрет вебхука выдаётся в кабинете при создании адреса и при смене секрета; после смены прежний секрет ещё некоторое время подписывает запросы вторым v1. Пример секрета: whsec_dGhpcy1pcy1hbi1leGFtcGxlLXdlYmhvb2sta2V5LTA (вымышленный).

// Проверка вебхука Payin8. Node.js 18+, без зависимостей.
import { createHmac, timingSafeEqual } from 'node:crypto';
import { createServer } from 'node:http';

const WEBHOOK_SECRET = process.env.PAYIN8_WEBHOOK_SECRET ?? 'whsec_dGhpcy1pcy1hbi1leGFtcGxlLXdlYmhvb2sta2V5LTA';

/** true, если подпись совпала и метка времени не старше toleranceSec. rawBody — байты тела как пришли. */
export function verifyPayin8Webhook(rawBody, signatureHeader, secret, toleranceSec = 300) {
  if (typeof signatureHeader !== 'string') return false;

  const parts = signatureHeader.split(',').map((p) => p.trim());
  const t = parts.find((p) => p.startsWith('t='))?.slice(2) ?? '';
  const signatures = parts.filter((p) => p.startsWith('v1=')).map((p) => p.slice(3));

  if (!/^\d+$/.test(t) || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;

  const expected = createHmac('sha256', secret)
    .update(Buffer.concat([Buffer.from(`${t}.`, 'utf8'), Buffer.from(rawBody)]))
    .digest();

  return signatures.some((s) => {
    const got = Buffer.from(s, 'hex');
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
}

// Пример приёмника: проверить подпись, ответить 200 сразу, обработать событие после ответа.
const seen = new Set(); // в боевом коде — таблица обработанных Payin8-Event-Id

createServer((req, res) => {
  const chunks = [];
  req.on('data', (c) => chunks.push(c));
  req.on('end', () => {
    const raw = Buffer.concat(chunks);

    if (!verifyPayin8Webhook(raw, req.headers['payin8-signature'], WEBHOOK_SECRET)) {
      res.writeHead(400).end();
      return;
    }

    res.writeHead(200).end();

    const event = JSON.parse(raw.toString('utf8'));
    if (seen.has(event.id)) return; // повтор той же доставки
    seen.add(event.id);
    console.log(event.type, event.data.id, event.data.status, event.data.version);
  });
}).listen(Number(process.env.PORT ?? 3000));

Внимание

Проверяйте подпись по сырым байтам тела. Если фреймворк уже разобрал JSON, а вы сериализуете его заново, байты могут измениться, и подпись не сойдётся.

Чем отвечать#

  • Любой ответ 2xx — доставка успешна. Тело ответа не используется.
  • Ответ должен прийти за 10 секунд, соединение — установиться за 5 секунд (значения по умолчанию). Не обрабатывайте событие до ответа: сохраните его и ответьте 200, обработку делайте отдельно.
  • Любой другой код, перенаправление 3xx, таймаут или ошибка соединения — неудачная попытка, будет повтор.
  • Отвечайте 2xx и на событие, которое уже обработали: иначе Payin8 будет повторять его доставку.

Повторы#

После неудачной попытки доставка повторяется с растущей паузой в пределах окна, которое отсчитывается от создания доставки. Расписание — настройка площадки; по умолчанию окно — 24 часа, пауза после первой неудачи — 10 секунд, затем удваивается (20 с, 40 с, 80 с, …) до 6 часов; у каждой паузы разброс ±10 %. Последняя попытка — в конце окна; при расписании по умолчанию всего до 16 попыток. Не удалось за окно — доставка прекращается.

Попытка Примерно через (от первой), по умолчанию
1 сразу
2 10 с
3 30 с
4 1 мин 10 с
5 2,5 мин
6 5 мин
7 10,5 мин
8 21 мин
9 42,5 мин
10 1 ч 25 мин
11 2 ч 50 мин
12 5 ч 40 мин
13 11 ч 23 мин
14 17 ч 23 мин
15 23 ч 23 мин
16 24 ч
  • Все попытки несут то же тело, тот же Payin8-Event-Id и Payin8-Delivery-Id; растёт Payin8-Attempt, подпись считается заново.
  • Если адрес вебхука выключили или удалили, недоставленные события больше не отправляются.
  • События, которые не ушли (адреса не было, он был выключен, не было подписки), остаются в журнале проекта; отправить событие ещё раз на текущий адрес проекта можно из кабинета, пока событие хранится в журнале (по умолчанию 90 дней; см. Вебхуки). Если доставка этого события ещё повторяется, повторная отправка только ускоряет её следующую попытку; иначе создаётся новая доставка того же события с тем же телом и новым окном повторов.

Порядок и дубли#

  • Порядок не гарантирован. Доставки идут параллельно и повторяются независимо: payin.completed может прийти раньше payin.assigned, а payin.failed истёкшего приёма — после payin.completed позднего подтверждения.
  • Дубли возможны. Одно событие может прийти несколько раз: после повтора, после повторной отправки из кабинета, после сбоя на любой стороне.

Как обрабатывать:

  1. Проверьте подпись.
  2. Если событие с этим id (Payin8-Event-Id) уже обработано — ответьте 200 и ничего не делайте.
  3. Сравните data.version с версией сделки, которую вы уже сохранили. Меньше или равна — состояние устарело: запишите событие, но не откатывайте статус. Больше — примените.
  4. Сопоставляйте сделку по data.id (или data.invoiceId / data.invoiceIds), а не по порядку прихода.
  5. Перед зачислением денег клиенту убедитесь, что data.status = completed; окончательность — по data.final (см. Окончательный исход).

Если вебхуки долго не приходят, сверяйтесь через GET /v1/payins/{id} и GET /v1/payouts/{id} — их ответы имеют тот же формат и ту же version.

Реквизит в вебхуке#

При flow: requisite вебхук payin.assigned содержит реквизит (data.requisite); в остальных событиях реквизит — null. Реквизит такого приёма считается выданным вам уже при назначении исполнителя: через вебхук, если адрес проекта подписан на payin.assigned (при попытке отмены — requisite_already_shown с via: "webhook"), иначе — через API (via: "api").

Примеры событий#

payin.assigned#

JSON
{
  "id": "6f0e1d2c-3b4a-4958-8776-655443322110",
  "type": "payin.assigned",
  "apiVersion": "v1",
  "createdAt": "2026-11-19T16:07:53.975Z",
  "test": false,
  "data": {
    "id": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
    "object": "payin",
    "invoiceId": "inv-100501",
    "invoiceIds": ["inv-100501"],
    "status": "awaiting_payment",
    "final": false,
    "flow": "requisite",
    "method": "bank_transfer",
    "currency": "ARS",
    "requestedAmount": "15000.00",
    "amount": "15000.00",
    "fee": "375.00",
    "net": "14625.00",
    "customer": { "id": "client-42", "name": "Juan Perez" },
    "paymentUrl": null,
    "requisite": {
      "type": "cvu",
      "number": "0000003110000987654323",
      "alias": null,
      "holderName": "Martin Suarez",
      "holderTaxId": null,
      "bankName": "Banco Ejemplo"
    },
    "expiresAt": "2026-11-19T16:16:53.925Z",
    "failureReason": null,
    "dispute": null,
    "returnUrls": { "success": "https://shop.example.com/pay/ok", "fail": null, "back": null },
    "locale": "en",
    "metadata": { "orderId": "A-1001" },
    "test": false,
    "version": 2,
    "createdAt": "2026-11-19T16:07:53.910Z",
    "updatedAt": "2026-11-19T16:07:53.957Z",
    "assignedAt": "2026-11-19T16:07:53.925Z",
    "clientPaidAt": null,
    "completedAt": null,
    "expiredAt": null,
    "canceledAt": null
  }
}

payin.failed#

Срок оплаты истёк. final: false: деньги ещё могут прийти в окне позднего подтверждения. Тем временем к приёму был присоединён второй номер того же клиента (invoiceIds).

JSON
{
  "id": "6f0e1d2c-3b4a-4958-8776-655443322111",
  "type": "payin.failed",
  "apiVersion": "v1",
  "createdAt": "2026-11-19T16:16:55.678Z",
  "test": false,
  "data": {
    "id": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
    "object": "payin",
    "invoiceId": "inv-100501",
    "invoiceIds": ["inv-100501", "inv-100502"],
    "status": "expired",
    "final": false,
    "flow": "requisite",
    "method": "bank_transfer",
    "currency": "ARS",
    "requestedAmount": "15000.00",
    "amount": "15000.00",
    "fee": "375.00",
    "net": "14625.00",
    "customer": { "id": "client-42", "name": "Juan Perez" },
    "paymentUrl": null,
    "requisite": null,
    "expiresAt": "2026-11-19T16:16:53.925Z",
    "failureReason": "expired",
    "dispute": null,
    "returnUrls": { "success": "https://shop.example.com/pay/ok", "fail": null, "back": null },
    "locale": "en",
    "metadata": { "orderId": "A-1001" },
    "test": false,
    "version": 4,
    "createdAt": "2026-11-19T16:07:53.910Z",
    "updatedAt": "2026-11-19T16:16:55.665Z",
    "assignedAt": "2026-11-19T16:07:53.925Z",
    "clientPaidAt": null,
    "completedAt": null,
    "expiredAt": "2026-11-19T16:16:55.661Z",
    "canceledAt": null
  }
}

payin.completed#

Тот же приём подтверждён после срока на фактически пришедшую сумму 14 800,00: amount, fee и net пересчитаны.

JSON
{
  "id": "6f0e1d2c-3b4a-4958-8776-655443322112",
  "type": "payin.completed",
  "apiVersion": "v1",
  "createdAt": "2026-11-19T16:17:06.246Z",
  "test": false,
  "data": {
    "id": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
    "object": "payin",
    "invoiceId": "inv-100501",
    "invoiceIds": ["inv-100501", "inv-100502"],
    "status": "completed",
    "final": true,
    "flow": "requisite",
    "method": "bank_transfer",
    "currency": "ARS",
    "requestedAmount": "15000.00",
    "amount": "14800.00",
    "fee": "370.00",
    "net": "14430.00",
    "customer": { "id": "client-42", "name": "Juan Perez" },
    "paymentUrl": null,
    "requisite": null,
    "expiresAt": "2026-11-19T16:16:53.925Z",
    "failureReason": null,
    "dispute": null,
    "returnUrls": { "success": "https://shop.example.com/pay/ok", "fail": null, "back": null },
    "locale": "en",
    "metadata": { "orderId": "A-1001" },
    "test": false,
    "version": 5,
    "createdAt": "2026-11-19T16:07:53.910Z",
    "updatedAt": "2026-11-19T16:17:06.219Z",
    "assignedAt": "2026-11-19T16:07:53.925Z",
    "clientPaidAt": null,
    "completedAt": "2026-11-19T16:17:06.217Z",
    "expiredAt": "2026-11-19T16:16:55.661Z",
    "canceledAt": null
  }
}

payin.amount_changed#

Вы открыли спор amount_mismatch, Payin8 изменил сумму завершённого приёма на 14 500,00. Спор в этот момент ещё открыт (dispute.status: "open", final: false); следом придёт dispute.closed.

JSON
{
  "id": "6f0e1d2c-3b4a-4958-8776-655443322113",
  "type": "payin.amount_changed",
  "apiVersion": "v1",
  "createdAt": "2026-11-19T16:21:32.085Z",
  "test": false,
  "data": {
    "id": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
    "object": "payin",
    "invoiceId": "inv-100501",
    "invoiceIds": ["inv-100501", "inv-100502"],
    "status": "completed",
    "final": false,
    "flow": "requisite",
    "method": "bank_transfer",
    "currency": "ARS",
    "requestedAmount": "15000.00",
    "amount": "14500.00",
    "fee": "362.50",
    "net": "14137.50",
    "customer": { "id": "client-42", "name": "Juan Perez" },
    "paymentUrl": null,
    "requisite": null,
    "expiresAt": "2026-11-19T16:16:53.925Z",
    "failureReason": null,
    "dispute": { "id": "c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "status": "open" },
    "returnUrls": { "success": "https://shop.example.com/pay/ok", "fail": null, "back": null },
    "locale": "en",
    "metadata": { "orderId": "A-1001" },
    "test": false,
    "version": 7,
    "createdAt": "2026-11-19T16:07:53.910Z",
    "updatedAt": "2026-11-19T16:21:32.083Z",
    "assignedAt": "2026-11-19T16:07:53.925Z",
    "clientPaidAt": null,
    "completedAt": "2026-11-19T16:17:06.217Z",
    "expiredAt": "2026-11-19T16:16:55.661Z",
    "canceledAt": null
  },
  "previous": { "amount": "14800.00", "fee": "370.00", "net": "14430.00" }
}

payout.completed#

JSON
{
  "id": "6f0e1d2c-3b4a-4958-8776-655443322114",
  "type": "payout.completed",
  "apiVersion": "v1",
  "createdAt": "2026-11-19T16:09:48.859Z",
  "test": false,
  "data": {
    "id": "7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f",
    "object": "payout",
    "invoiceId": "wd-200731",
    "invoiceIds": ["wd-200731"],
    "status": "completed",
    "final": true,
    "method": "bank_transfer",
    "currency": "ARS",
    "amount": "20000.00",
    "feePayer": "merchant",
    "fee": "200.00",
    "requestedFee": "200.00",
    "totalDebit": "20200.00",
    "recipientAmount": "20000.00",
    "paidAmount": "20000.00",
    "refundedAmount": "0.00",
    "bankReference": "BR-55120397",
    "recipient": {
      "type": "cvu",
      "account": "0000003110000123456781",
      "holderName": "Maria Gomez",
      "taxId": "20312345677"
    },
    "customer": { "id": "client-77", "name": "Maria Gomez" },
    "receipts": [
      {
        "id": "5d2e8f1a-9c3b-4a7d-b6e5-0f1e2d3c4b5a",
        "name": "transfer-receipt.png",
        "contentType": "image/png",
        "size": 84210,
        "uploadedAt": "2026-11-19T16:09:48.763Z"
      }
    ],
    "failureReason": null,
    "dispute": null,
    "metadata": { "withdrawalId": "W-77" },
    "test": false,
    "version": 4,
    "createdAt": "2026-11-19T16:09:23.307Z",
    "updatedAt": "2026-11-19T16:09:48.852Z",
    "expiresAt": "2026-11-19T20:09:23.292Z",
    "startedAt": "2026-11-19T16:09:31.447Z",
    "completedAt": "2026-11-19T16:09:48.814Z",
    "canceledAt": null
  }
}

payout.failed#

Другой исход той же выплаты: вы отменили её до того, как исполнитель её взял. Удержанное вернулось полностью.

JSON
{
  "id": "6f0e1d2c-3b4a-4958-8776-655443322115",
  "type": "payout.failed",
  "apiVersion": "v1",
  "createdAt": "2026-11-19T16:09:43.514Z",
  "test": false,
  "data": {
    "id": "7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f",
    "object": "payout",
    "invoiceId": "wd-200731",
    "invoiceIds": ["wd-200731"],
    "status": "canceled",
    "final": true,
    "method": "bank_transfer",
    "currency": "ARS",
    "amount": "20000.00",
    "feePayer": "merchant",
    "fee": "0.00",
    "requestedFee": "200.00",
    "totalDebit": "20200.00",
    "recipientAmount": "20000.00",
    "paidAmount": "0.00",
    "refundedAmount": "20200.00",
    "bankReference": null,
    "recipient": {
      "type": "cvu",
      "account": "0000003110000123456781",
      "holderName": "Maria Gomez",
      "taxId": "20312345677"
    },
    "customer": { "id": "client-77", "name": "Maria Gomez" },
    "receipts": [],
    "failureReason": "canceled_by_merchant",
    "dispute": null,
    "metadata": { "withdrawalId": "W-77" },
    "test": false,
    "version": 2,
    "createdAt": "2026-11-19T16:09:23.307Z",
    "updatedAt": "2026-11-19T16:09:43.505Z",
    "expiresAt": "2026-11-19T20:09:23.292Z",
    "startedAt": null,
    "completedAt": null,
    "canceledAt": "2026-11-19T16:09:43.485Z"
  }
}

dispute.opened#

JSON
{
  "id": "6f0e1d2c-3b4a-4958-8776-655443322116",
  "type": "dispute.opened",
  "apiVersion": "v1",
  "createdAt": "2026-11-19T16:20:18.856Z",
  "test": false,
  "data": {
    "id": "c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "object": "dispute",
    "dealId": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
    "dealType": "payin",
    "invoiceId": "inv-100501",
    "status": "open",
    "reason": "amount_mismatch",
    "comment": null,
    "claimedAmount": "14500.00",
    "outcome": null,
    "resolvedAmount": null,
    "files": [
      {
        "id": "9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b",
        "name": "bank-statement.pdf",
        "contentType": "application/pdf",
        "size": 48213,
        "uploadedAt": "2026-11-19T16:20:12.480Z"
      }
    ],
    "openedAt": "2026-11-19T16:20:18.841Z",
    "closedAt": null
  }
}

dispute.closed#

JSON
{
  "id": "6f0e1d2c-3b4a-4958-8776-655443322117",
  "type": "dispute.closed",
  "apiVersion": "v1",
  "createdAt": "2026-11-19T16:21:32.094Z",
  "test": false,
  "data": {
    "id": "c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "object": "dispute",
    "dealId": "3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44",
    "dealType": "payin",
    "invoiceId": "inv-100501",
    "status": "closed",
    "reason": "amount_mismatch",
    "comment": null,
    "claimedAmount": "14500.00",
    "outcome": "amount_changed",
    "resolvedAmount": "14500.00",
    "files": [
      {
        "id": "9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b",
        "name": "bank-statement.pdf",
        "contentType": "application/pdf",
        "size": 48213,
        "uploadedAt": "2026-11-19T16:20:12.480Z"
      }
    ],
    "openedAt": "2026-11-19T16:20:18.841Z",
    "closedAt": "2026-11-19T16:21:32.090Z"
  }
}

webhook.ping#

JSON
{
  "id": "6f0e1d2c-3b4a-4958-8776-655443322118",
  "type": "webhook.ping",
  "apiVersion": "v1",
  "createdAt": "2026-11-19T05:59:30.218Z",
  "test": false,
  "data": {
    "projectId": "e4d3c2b1-a0f9-4e8d-9c7b-6a5d4c3b2a10",
    "message": "ping"
  }
}

API

Повторы, списки и ограничения#

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

Идемпотентность создания#

Ключ идемпотентности создания — ваш invoiceId. Он уникален в пределах мерчанта отдельно для приёмов и для выплат: один и тот же номер можно дать одному приёму и одной выплате.

Ситуация Ответ
Первый запрос с этим invoiceId 201 (у приёма бывает 202) — сделка создана
Повтор с теми же параметрами 200, заголовок Idempotent-Replayed: true, та же сделка в текущем состоянии
Повтор с другими параметрами 409 idempotency_conflict, details.id — id уже созданной сделки
Номер занят сделкой другого проекта мерчанта 409 invoice_id_taken

Что сравнивается при повторе:

  • приём — amount, currency, method, flow, customer.id, customer.name, customer.email, returnUrls, locale, metadata; не сравниваются waitSec и customer.ip. Для номера, присоединённого к приёму того же клиента, сравниваются amount, currency, method и customer.id;
  • выплата — amount, currency, method, feePayer, recipient (после нормализации: номер без пробелов и дефисов, алиас в нижнем регистре, схлопнутые пробелы в имени), customer.id, customer.name, metadata.

Повтор создания приёма с flow: requisite тоже ждёт назначения исполнителя до waitSec.

Остальные операции тоже безопасно повторять:

Операция Повтор
POST /v1/payins/{id}/cancel, POST /v1/payouts/{id}/cancel Уже отменённая сделка — 200 с текущим видом
POST /v1/files Те же байты к той же сделке с тем же purpose — 200 с ранее загруженным файлом
POST /v1/disputes Спор по сделке уже открыт — 200 с ним; комментарий и файлы добавляются к спору
POST /v1/disputes/{id}/evidence Каждый вызов добавляет сообщение к спору; повторяйте только неудавшиеся

Повтор после сбоя#

Каждый повтор — новый запрос: новые X-Timestamp и X-Nonce, подпись заново (см. Аутентификация). Тело и invoiceId — те же.

Что случилось Что делать
Обрыв соединения, таймаут, нет ответа Повторить тот же запрос. Если сделка успела создаться, повтор вернёт её с 200
429 rate_limited Повторить через Retry-After секунд
503 с кодом busy, tx_timeout, service_restarting, dependency_unavailable, nonce_store_unavailable Ничего не записано; повторить через несколько секунд
409 concurrent_update, 409 lock_busy Сделку одновременно меняли; повторить
500 internal_error Исход неизвестен. Проверить через GET /v1/payins/by-invoice/{invoiceId} (или …/payouts/…), затем при необходимости повторить с тем же invoiceId
409 idempotency_conflict Не повторять: номер уже занят сделкой с другими параметрами. Найти её по details.id
Остальные 4xx Не повторять без исправления запроса

Используйте нарастающую паузу между повторами и ограничьте их число.

Пагинация и фильтры#

Списки GET /v1/payins, GET /v1/payouts и GET /v1/disputes постраничные, с курсором.

  • limit — размер страницы, 1–100, по умолчанию 50.
  • Ответ: { "items": [...], "nextCursor": "…" }. Пока nextCursor не null, передавайте его в параметре cursor следующего запроса вместе с теми же фильтрами.
  • Курсор непрозрачен: не разбирайте и не собирайте его сами. Испорченный курсор — 400 validation_failed по полю cursor.
  • Сортировка: приёмы и выплаты — по createdAt, новые сверху; споры — по openedAt, новые сверху.

Период у приёмов и выплат. Фильтр — по createdAt: createdFrom включительно, createdTo — не включая.

Передано Период
Ничего Последние 7 дней до текущего момента
Только createdFrom Наибольший допустимый период от createdFrom
Только createdTo 7 дней до createdTo
Оба Как задано; не длиннее наибольшего допустимого периода

Наибольший период — настройка площадки, по умолчанию 31 день. createdFrom не раньше createdTo или период длиннее допустимого — 400 validation_failed. Чтобы выгрузить больший период, разбейте его на части.

Фильтры: приёмы и выплаты — status, customerId, createdFrom, createdTo; споры — status (open, closed) и dealId. Параметр запроса подписывается в том виде, в каком отправлен (см. Каноническая строка).

Ограничения#

Числовые пределы, кроме metadata, — настройки площадки или проекта; в таблице указаны значения по умолчанию, действующие могут отличаться.

Что Предел При превышении
Частота запросов одного ключа 3000 запросов в минуту (окно — календарная минута) 429 rate_limited, details.retryAfterSec, заголовок Retry-After
Размер JSON-тела запроса 1 МБ 413 payload_too_large
Файл в POST /v1/files 10 МБ на файл; до 10 ваших файлов на сделку (любого purpose); 30 МБ всех файлов сделки; 2 ГБ загрузок мерчанта за сутки 413 file_too_large, 409 files_limit_reached, 413 files_quota_exceeded
Открытые приёмы одного клиента (customer.id) в проекте 3 409 customer_open_payins_limit, details.limit
Выдача реквизитов проекту: разные счета за скользящий час 300 429 requisite_reveal_limit, details.kind: "distinct_requisites_per_hour"
Открытые приёмы flow: requisite проекта 200 429 requisite_reveal_limit, details.kind: "open_requisite_payins"
Период списка 31 день 400 validation_failed
metadata 10 ключей [A-Za-z0-9_]{1,40}, значения до 256 символов 400 validation_failed
waitSec 20 секунд 400 validation_failed

Действующее значение лимита клиента и лимитов выдачи реквизитов приходит в details.limit ошибки, предел файлов сделки — в details.limit ошибки files_limit_reached, предел размера — в details.maxBytes.

Лимиты выдачи реквизитов и открытых приёмов клиента проверяются до создания сделки: отказ ничего не создаёт. requisite_reveal_limit не несёт Retry-After: повторяйте позже, когда часть приёмов закроется.

API

Ошибки#

Неуспешный ответ — HTTP-статус 4xx или 5xx и тело одного формата.

Формат ошибки#

JSON
{
  "code": "validation_failed",
  "message": "Validation failed",
  "details": {
    "fields": [
      { "path": "amount", "errors": ["amount must be a decimal string with at most 13 integer and 6 fraction digits"] },
      { "path": "customer.email", "errors": ["email must be an email"] }
    ]
  }
}
Поле Тип Смысл
code string Машинный код ошибки. Стабилен — по нему и стройте обработку
message string Описание по-английски для журнала. Текст может меняться; не разбирайте его
details object Подробности; есть не у всех ошибок. Состав — в каталоге ниже

У validation_failed в details.fields — список полей: path — имя поля через точку (customer.email, recipient.account), errors — что не так. Проверка идёт в два этапа: сначала формат всех полей (ошибки по всем полям приходят вместе, как в примере), затем — значения, которые зависят от валюты и настроек (например, число знаков суммы у валюты: amount must be a decimal string with at most 2 fraction digits); такие ошибки приходят, только когда формат уже верен.

В каждом ответе, и в ошибке тоже, есть заголовок X-Request-Id: указывайте его, когда обращаетесь в поддержку.

Каталог кодов#

Запрос и формат#

code HTTP Когда Что делать
validation_failed 400 Поле тела, параметр пути или запроса не прошли проверку; лишнее поле в теле; details.fields Исправить запрос
malformed_json 400 Тело — не JSON Исправить сериализацию
bad_request 400 Тело не удалось прочитать Проверить Content-Type и тело
route_not_found 404 Такого метода и пути нет Проверить путь и метод
not_found 404 Сделки, спора или файла нет в проекте ключа Проверить id; убедиться, что используете ключ того проекта
payload_too_large 413 Тело запроса слишком большое Уменьшить тело
http_<статус> 4xx Прочие ошибки чтения запроса (например, http_415 — неподдерживаемая кодировка тела) Отправлять JSON в UTF-8

Аутентификация и доступ#

code HTTP Когда Что делать
signature_missing 401 Нет X-Api-Key, X-Timestamp, X-Nonce или X-Signature Отправлять все четыре заголовка
nonce_invalid 401 X-Nonce не 16–64 символа A–Z a–z 0–9 _ - Исправить генерацию
api_key_invalid 401 Ключа нет, он отозван или истёк Проверить ключ, выпустить новый
timestamp_out_of_window 401 X-Timestamp вне окна; details.serverTime Синхронизировать часы, подписать заново
signature_invalid 401 Подпись не сошлась Сверить каноническую строку
nonce_replayed 401 X-Nonce уже использован Новая строка на каждый запрос
ip_not_allowed 403 Адрес отправителя не в списке IP ключа Добавить адрес в список ключа
ip_allowlist_required 403 Операции нужен ключ со списком IP; details.code Задать ключу список IP
permission_denied 403 У ключа нет права; details.code Выдать право ключу
tenant_blocked 403 Мерчант заблокирован Обратиться в поддержку
project_disabled 403 Проект выключен Обратиться в поддержку
forbidden 403 Доступ запрещён Обратиться в поддержку с X-Request-Id
rate_limited 429 Превышен лимит запросов ключа в минуту; details.retryAfterSec, заголовок Retry-After Повторить через указанное время

Сделки#

code HTTP Когда Что делать
idempotency_conflict 409 invoiceId уже использован с другими параметрами; details.id Не повторять; взять сделку по details.id или выбрать новый номер
invoice_id_taken 409 invoiceId занят сделкой другого проекта мерчанта Выбрать другой номер
customer_open_payins_limit 409 У клиента максимум открытых приёмов; details.limit Дождаться закрытия его приёмов
insufficient_balance 409 Не хватает баланса на выплату; details.currency, details.available, details.required Пополнить баланс или уменьшить сумму
invalid_state 409 Действие невозможно в текущем статусе; details.status Перечитать сделку
requisite_already_shown 409 Отмена приёма после выдачи реквизита; details.shownAt, details.via Дождаться истечения срока приёма
dispute_open 409 По сделке открыт спор; details.disputeId Дождаться решения по спору
concurrent_update 409 Сделку одновременно меняли Повторить запрос
lock_busy 409 Ресурс занят Повторить запрос
conflict 409 Конфликт записи Перечитать сделку, при необходимости повторить
method_unavailable 422 Метод, валюта или направление не включены для проекта; details.method, details.currency, details.direction Проверить GET /v1/methods
amount_out_of_range 422 Сумма вне лимитов метода; details.min, details.max Изменить сумму
invalid_recipient 422 Неверный счёт, имя или CUIT получателя; details.field, details.rule (format или checksum) Исправить данные получателя
fee_payer_unavailable 422 feePayer не разрешён; details.allowed Передать значение из details.allowed или не передавать поле
feature_unavailable 422 Возможность недоступна; details.feature (например, widget) Использовать другой способ или обратиться в поддержку
negative_margin 422 Сделку нельзя провести с текущими условиями тарифа Обратиться в поддержку
requisite_reveal_limit 429 Исчерпан лимит выдачи реквизитов проекта; details.limit, details.kind Повторить позже
no_widget_domain 500 flow: widget, а у проекта нет действующего адреса страницы оплаты; сделка не создана Обратиться в поддержку

Файлы и споры#

code HTTP Когда Что делать
file_type_not_allowed 415 Файл не PDF, PNG, JPEG или WebP, или пустой; details.allowed Загрузить файл допустимого типа
file_too_large 413 Файл больше предела; details.maxBytes Уменьшить файл
files_quota_exceeded 413 Исчерпан объём файлов; details.quota, details.limitBytes Повторить позже или обратиться в поддержку
files_limit_reached 409 У сделки максимум ваших файлов; details.limit —
file_not_attachable 422 Файл нельзя приложить к спору; details.fileId, details.why Загрузить файл к этой сделке с purpose=evidence
files_storage_unavailable 503 Загрузка временно приостановлена Повторить позже
dispute_not_allowed 409 Спор открыть нельзя; details.why: reason, status, window См. условия открытия

Временные сбои#

code HTTP Когда Что делать
internal_error 500 Внутренняя ошибка; исход операции неизвестен Проверить состояние через GET (по invoiceId), затем повторить
busy 503 Сервис занят, ничего не записано Повторить через несколько секунд
tx_timeout 503 Операция не успела, ничего не записано Повторить
service_restarting 503 Сервис перезапускается, ничего не записано Повторить через несколько секунд
dependency_unavailable 503 Временная недоступность Повторить позже
nonce_store_unavailable 503 Проверка запросов временно недоступна Повторить с новой подписью

Как повторять запросы — Повтор после сбоя.