Для мерчантов
Документация Payin8
Руководство по кабинету мерчанта и справочник API: где взять настройки, куда их прописать и как устроены запросы.
Настройка кабинета мерчанта шаг за шагом.
Запросы, ответы, статусы и вебхуки.
Кабинет
Быстрый старт#
Кабинет мерчанта — место, где вы получаете всё, что нужно вашему серверу для работы с API Payin8: ключ и секрет для подписи запросов, секрет подписи вебхуков, настройки страницы оплаты. Здесь же вы видите сделки, баланс, споры и управляете командой.
Названия пунктов меню, вкладок и кнопок ниже даны так, как они написаны в кабинете на русском языке. Какие пункты меню вы видите, зависит от прав вашей роли (см. Команда и роли).
От приглашения до первой сделки#
- Примите приглашение. Первого сотрудника вашей организации (владельца) приглашает площадка Payin8. Откройте ссылку из приглашения, задайте пароль и войдите. Подробно — в разделе Вход и учётная запись.
- Включите второй фактор. Для владельца он обязателен: пока он не настроен, кабинет недоступен. Сохраните коды восстановления — они показываются один раз.
- Проверьте проект. Проекты заводит площадка. Откройте Подключение → Проекты, выберите проект и посмотрите вкладку «Методы и пределы»: включены ли нужные направления (приём, выплата), какие пределы суммы и какой тариф. Если для направления не назначен тариф, сделки по нему не создаются. См. Организация и проекты.
- Выпустите ключ API. Подключение → Ключи API → «Выпустить ключ»: выберите проект, задайте название, права и IP-адреса вашего сервера. Сохраните идентификатор ключа и секрет — секрет показывается один раз. См. Ключи API.
- Настройте вебхук. Подключение → Проекты → проект → вкладка «Вебхук» → «Настроить»: укажите адрес и события. После первого сохранения кабинет один раз покажет секрет подписи. Нажмите «Проверить», чтобы отправить проверочное событие. См. Вебхуки.
- Оформите страницу оплаты. Вкладка «Страница оплаты» проекта (или Организация → Профиль и правила для всех проектов сразу): название магазина, логотип, цвет, контакты поддержки, адреса возврата на ваш сайт. См. Страница оплаты.
- Проверьте правила. Вкладка «Правила» проекта: «Язык страницы оплаты», «Обязателен чек клиента», «Позднее подтверждение приёмов», «Выплата без денег на балансе». См. Правила.
- Создайте первую сделку. Ваш сервер отправляет подписанный запрос на создание приёма — см. Приёмы и Подпись запросов. Сделка появится в разделе Приёмы, событие вебхука — в Подключение → Доставка вебхуков.
- Для выплат нужен баланс (он пополняется зачислениями по приёмам или переводом USDT, Деньги → Пополнение) и ключ с правом «Создавать выплаты» и непустым списком IP-адресов. См. Выплаты.
- Пригласите команду: Организация → Команда → «Пригласить». См. Команда и роли.
Внимание
После некоторых изменений безопасности (вход по коду восстановления, сброс пароля по ссылке, повторная настройка второго фактора) кабинет на время закрывает выпуск ключей, изменение вебхука, добавление адресов вывода и вывод. По умолчанию — на 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, остальных сотрудников — владелец или участник команды с правом приглашать (см. Команда и роли).
- Откройте ссылку приглашения. На странице «Приглашение» видны роль, которую вы получите, и срок действия ссылки («Действует до»).
- Укажите имя («Ваше имя (необязательно)»), введите «Новый пароль» и «Повторите пароль».
- Нажмите «Задать пароль», затем войдите с вашей почтой и новым паролем.
Требования к паролю (кабинет показывает их под полем):
- длина от 12 до 128 символов (площадка может поднять нижнюю границу);
- пароль не содержит часть почты до
@, если в ней 4 знака и больше (без учёта регистра); - оба поля совпадают.
Ссылка приглашения по умолчанию действует 72 часа (срок задаёт площадка). Каждая новая ссылка отменяет прежнюю. Если ссылка истекла, попросите владельца кабинета (или площадку, если приглашала она) прислать приглашение снова.
Примечание
Ссылка приглашения открывается только в том кабинете, для которого выпущена. Если вы открыли её не там, страница подскажет, где её открыть.
Вход#
- На странице «Вход» введите «Почта» и «Пароль», нажмите «Войти».
- Если у вас включён второй фактор, введите 6-значный код из приложения-аутентификатора. Если телефона нет под рукой, нажмите «Нет доступа к приложению — ввести код восстановления».
На ввод кода после пароля отводится 5 минут; после этого вход нужно начать заново.
После нескольких неудачных попыток подряд вход для учётной записи временно блокируется: по умолчанию после 5 неверных паролей за 15 минут — на 15 минут (числа задаёт площадка).
Забыли пароль? Самостоятельного восстановления нет. Попросите владельца кабинета выпустить ссылку для нового пароля (Организация → Команда → сотрудник → «Ссылка для пароля») или обратитесь в поддержку Payin8. Ссылка одноразовая и по умолчанию действует 30 минут. После смены пароля по ссылке все сеансы завершаются, второй фактор остаётся, а чувствительные действия на время закрываются (см. Безопасность).
Второй фактор#
Второй фактор — одноразовые коды из приложения-аутентификатора (Google Authenticator, 1Password и другие).
- Для роли владельца и для ролей с правами, которые требуют свежий код, второй фактор обязателен: без него кабинет недоступен, при первом входе откроется экран «Защитите вход».
- Для остальных ролей он необязателен, но без него недоступны вывод, ключи API и управление командой.
Как включить:
- Если кабинет не предложил настройку сам, откройте меню «Учётная запись» (значок в правом верхнем углу) → «Профиль и безопасность», блок «Второй фактор», нажмите «Включить».
- Введите «Текущий пароль» и нажмите «Начать».
- Отсканируйте QR-код приложением или введите «Секрет» вручную. Введите «Код из приложения» и нажмите «Проверить». На настройку отводится 10 минут.
- Сохраните коды восстановления и нажмите «Я сохранил коды».
Если код не подходит, проверьте, что время на телефоне выставляется автоматически.
Перенос на новый телефон. «Профиль и безопасность» → «Перенести на другой телефон»: подтвердите кодом со старого устройства и отсканируйте новый 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».
Статусы ключа: «действует», «отзовётся» (ключ заменён и перестанет работать в указанное время), «отозван».
Выпуск ключа#
- Подключение → Ключи API → «Выпустить ключ».
- Заполните окно «Новый ключ»:
- «Название» — от 1 до 60 символов, чтобы отличать ключи между собой;
- «Проект» — ключ принадлежит одному проекту;
- «Права» — что ключу разрешено (см. ниже);
- «Адреса» — IP-адреса вашего сервера, по одному в строке (см. ниже).
- Подтвердите кодом из приложения.
- Откроется окно «Секрет ключа» с полями «Ключ» (идентификатор) и «Секрет», а также образцами «Заголовки запроса» и «Строка подписи (шесть строк)». Скопируйте ключ и секрет в хранилище секретов вашего сервера и нажмите «Я сохранил секрет».
Внимание
Секрет показывается один раз. 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 отправляет на адрес вашего сервера, когда меняется сделка или спор. У каждого проекта один адрес вебхука. Каждый запрос подписан секретом подписи. Формат тела, заголовки и проверка подписи — в разделе Вебхуки.
Где задать адрес#
- Подключение → Проекты → проект → вкладка «Вебхук».
- Нажмите «Настроить» (если адрес ещё не задан) или «Изменить».
- Заполните форму:
- «Адрес» — адрес обработчика на вашем сервере;
- «События» — на какие события подписаться (см. ниже); хотя бы одно;
- «Отправлять события» — выключатель. Выключенный адрес сохраняет настройки, но доставки, ожидающие в очереди, отменяются.
- Нажмите «Сохранить» и подтвердите кодом из приложения.
Требования к адресу (кабинет проверяет их сразу):
- только
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 — например, чтобы хватало денег на выплаты.
- Откройте Деньги → Пополнение. Там указаны адрес площадки в сети TRON (с QR-кодом), «Минимум» и «Курс пополнения сейчас».
- Переведите USDT (TRC-20) на этот адрес со своего кошелька.
- После нужного числа подтверждений сети площадка зачисляет песо по курсу пополнения на момент зачисления. Зачисление появится в истории «Пополнения» и в выписке как «Пополнение USDT».
Внимание
Переводы меньше минимума не зачисляются. По умолчанию минимум — 10 USDT; действующее значение показано на странице. Переводите только USDT в сети TRON.
Перевод регистрирует площадка по хешу транзакции; до этого его нет в истории. Если перевод долго не появляется, сообщите хеш транзакции в поддержку Payin8.
История «Пополнения»: «№», «Зарегистрировано», «Перевод» (хеш со ссылкой «Открыть в обозревателе»), «Сумма», «Статус», «Курс», «Зачислено», «Зачислено в». Статусы: «Зарегистрировано», «Зачислено», «Отклонено», «Возвращено».
Если на странице написано «Пополнение не настроено», пополнение для вас сейчас недоступно — обратитесь в поддержку Payin8.
Кому это доступно#
| Что | Право роли |
|---|---|
| «Баланс и выписка» | «Видеть баланс и выписку» |
| Пересчёт в USDT, курсы | «Видеть курсы» |
| Страница «Пополнение» | «Видеть адрес пополнения» |
| История пополнений | «Видеть пополнения» |
Кабинет
Кошельки и вывод#
Вывод обменивает песо с баланса на USDT по курсу площадки и отправляет их на ваш адрес в сети TRON. Сначала добавьте адрес, затем создайте заявку; заявку одобряет площадка.
Адреса для вывода#
Деньги → Кошельки — адреса USDT в сети TRON (TRC-20), на которые уходят выводы.
Как добавить адрес:
- Нажмите «Добавить адрес».
- «Адрес» — вставьте его из кошелька. Адрес TRON начинается с
Tи состоит из 34 знаков; контрольную сумму проверит площадка. - «Название» — от 1 до 64 знаков: как адрес будет называться в кабинете.
- Подтвердите кодом из приложения.
Внимание
Проверьте адрес: перевод на чужой адрес не вернуть. Добавление и удаление адреса записываются в «Журнал действий».
Когда адресом можно пользоваться. Новый адрес становится доступен для вывода через 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 дней с создания сделки. Действующий срок — правило «Срок, в который можно открыть спор по сделке» (см. Правила). Если срок прошёл, кабинет напишет, до какого времени спор можно было открыть.
Как открыть#
- Откройте сделку и нажмите «Открыть спор».
- Выберите «Причина»:
- для приёма — «Клиент оплатил, а приём не завершён», «Сумма не та», «Подозрение на мошенничество», «Другое»;
- для выплаты — «Получатель не получил деньги», «Подозрение на мошенничество», «Другое».
- «Комментарий» — что случилось, что говорит клиент, чего вы ждёте. До 4000 символов; при причине «Другое» обязателен.
- Для приёма — «Сколько заплатил клиент» (необязательно, сумма из чека клиента).
- Приложите файлы: для приёма — «Чек клиента», для любой сделки — «Другие файлы». Всего до 10 файлов; JPEG, PNG, WebP или PDF, каждый до 10 МБ.
- Нажмите «Открыть спор».
Если спор по сделке уже открыт (например, его открыли одновременно с вами), ваш комментарий добавится в него.
Совет
Чем точнее приложенные доказательства, тем быстрее разбор: чек перевода клиента с суммой, временем и номером операции, выписка, переписка с клиентом.
Список споров#
Раздел Споры в меню. Вкладки «Открытые», «Закрытые», «Все»; фильтр «Направление» (приём или выплата).
Колонки: «Сделка», «Причина», «Кто открыл», «Открыт», «Статус», «Итог», «Последнее сообщение». Число новых сообщений отмечено в строке спора.
Спор открывает не только мерчант: площадка тоже может открыть спор по вашей сделке — например, если выплата слишком долго в работе. Такие споры видны в том же списке.
Как отвечать#
Откройте спор. В карточке — сделка («Открыть сделку»), причина, кто и когда открыл, и лента «Сообщения».
Чтобы ответить, заполните блок «Ответить»: «Сообщение» (до 4000 символов) и при необходимости «Файлы» (до 10 файлов), затем нажмите «Отправить». Файлы прикладываются к тексту сообщения.
Сообщение и файлы прочтут площадка и исполнитель сделки.
Как спор закрывается#
- Спор по приёму закрывается сам, когда исполнитель подтверждает поступление денег («Подтверждение прихода закроет спор само»). Спор по выплате закрывается сам, когда исполнитель прикладывает чек перевода. Исключение — спор по выплате, который ждёт решения поддержки: в карточке тогда написано «Спор ждёт решения поддержки: чек его уже не закроет», и закрывает его только решение площадки.
- Иначе спор закрывает площадка своим решением. Итог виден в колонке и в карточке, например: «Оставлено как есть», «Сделка завершена», «Сделка отменена, деньги вернулись», «Завершённая сделка отменена», «Сумма изменена».
Решение по спору может изменить деньги на балансе — это видно в выписке (например, «Отмена зачисления по спору» или «Возврат выплаты по спору»). Закрытый спор новых сообщений не принимает.
Отдельного срока для ответов в споре нет, а спор не закрывается сам по истечении времени. Отвечайте на вопросы площадки как можно быстрее: от этого зависит, как скоро будет решение.
Кому это доступно#
| Действие | Право роли |
|---|---|
| Видеть споры и сообщения | «Видеть споры» |
| «Открыть спор» | «Открывать споры» |
| «Отправить» сообщение | «Писать в спор» |
| Прикладывать файлы | «Загружать файлы» |
Системная роль «Operator» может открывать споры и отвечать в них, но права «Загружать файлы» у неё нет — приложить файлы сможет владелец или сотрудник со своей ролью, где это право есть. «Viewer» — только читает.
Кабинет
Команда и роли#
У каждого сотрудника свой вход и своя роль. Роль определяет, какие разделы видны и какие действия доступны.
Команда#
Организация → Команда — все, у кого есть доступ к кабинету: «Почта», «Имя», «Роль», «Статус», «Второй фактор», «Последний вход», «Добавлен». Фильтры: статус, роль, «Почта начинается с».
Статусы сотрудника: «Приглашён», «Активен», «Отключён», «Удалён».
Приглашение сотрудника#
- Команда → «Пригласить».
- Укажите «Почта», «Имя» (необязательно) и «Роль».
- Нажмите «Создать приглашение» и подтвердите кодом из приложения.
- Кабинет покажет «Ссылка приглашения» и срок «Действует до». Ссылка показывается один раз — скопируйте её и передайте сотруднику сами, лично, не в общий чат: она даёт доступ к кабинету.
Ссылка по умолчанию действует 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, важнее адреса из кабинета.
Рядом с настройками и в форме изменения — «Макет шапки страницы»: как будут выглядеть название, логотип, цвет кнопки и ссылка на поддержку.
Язык страницы задаёт правило «Язык страницы оплаты» («как у приёма», «испанский», «английский»), а обязательность чека клиента — правило «Обязателен чек клиента» (см. Правила).
Что видит плательщик#
- Пока Payin8 подбирает реквизиты — экран ожидания с просьбой не закрывать страницу.
- Сумму к переводу, таймер до конца срока оплаты и реквизиты: CVU или CBU, alias, владелец счёта, CUIT/CUIL, банк, номер заказа — с кнопками копирования. Короткая инструкция: перевести точную сумму одним переводом до конца срока.
- Поле для чека перевода — обязательное или необязательное, в зависимости от правила «Обязателен чек клиента».
- Кнопку, которой клиент сообщает, что перевёл деньги, и кнопку отмены оплаты.
- После этого — экран проверки платежа; затем — экран успешной оплаты с возвратом на ваш сайт или экран истёкшего срока.
На странице — ваше название, логотип, цвет и ссылки на поддержку. Клиент может переключить язык (испанский или английский).
Ссылка на оплату#
У каждого приёма, который оплачивается на странице оплаты, в карточке сделки есть блок «Ссылка на оплату» с кнопкой «Открыть». Если клиент потерял страницу, отправьте ему эту ссылку: она работает, пока приём открыт.
Свой домен#
Домены, на которых открывается страница оплаты, подключает и проверяет площадка; в кабинете мерчанта этой настройки нет. Если вы хотите, чтобы страница оплаты открывалась на вашем домене, обратитесь в поддержку 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 из браузера или мобильного приложения и не передавайте туда секрет ключа.
Подключение по шагам#
- Получите ключ. В кабинете выпустите ключ API для проекта с нужными правами и IP-адресами вашего сервера; сохраните идентификатор ключа
mk_…и секретms_…(см. Ключи API). - Подпишите проверочный запрос. Скопируйте готовые функции, передайте ключ и секрет через переменные окружения и вызовите
GET /v1/balance: ответ200— подпись работает. Если нет, сверьте свои значения с разобранным примером. - Проверьте условия.
GET /v1/methodsпоказывает, какие методы и направления включены у проекта, пределы суммы и комиссии (см. Методы). - Принимайте вебхуки. Задайте в кабинете адрес и события проекта и сохраните секрет подписи
whsec_…(см. Вебхуки). Ваш обработчик проверяет подпись и сразу отвечает2xx(см. Чем отвечать). Кнопка «Проверить» отправляетwebhook.ping: так обработчик можно проверить до первой сделки. - Создайте приём.
POST /v1/payinsс вашимinvoiceId, суммой, клиентом и режимомflow(см. Создание приёма). Приflow: requisiteпокажите клиентуrequisiteиamountиз ответа или из вебхукаpayin.assigned; приflow: widgetотправьте клиента по ссылкеpaymentUrl. - Получите результат. Итог приходит вебхуком
payin.completedилиpayin.failed; текущее состояние всегда можно прочитать черезGET /v1/payins/{id}или по вашему номеру (см. Поиск по номеру). - Обработайте сбои. После таймаута или ответа
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}).
Как проходит приём#
- Ваш сервер создаёт приём:
POST /v1/payinsс суммой, клиентом и способом приёма (flow). - Payin8 подбирает исполнителя и его банковский счёт (реквизит). Приём переходит из
createdвawaiting_payment, приходит вебхукpayin.assigned. Срок оплаты — полеexpiresAt. - Клиент переводит деньги на реквизит: при
flow: requisiteреквизит и суммуamountему показываете вы, приflow: widget— страница оплаты Payin8 по ссылкеpaymentUrl. - Поступление подтверждено — приём
completed, вебхукpayin.completed. На баланс зачисляетсяnet=amount−fee. - Если оплаты не было в срок или исполнителя не нашлось —
expiredилиcanceled, вебхукpayin.failed.
Подробно — Приёмы и Статусы сделок.
Как проходит выплата#
- Ваш сервер создаёт выплату:
POST /v1/payoutsс суммой и счётом получателя. С баланса удерживаетсяtotalDebit=amount+fee, выплата предлагается исполнителям (offered). - Исполнитель берёт выплату (
in_progress), переводит деньги получателю и прикладывает чек. - Выплата
completed, вебхукpayout.completed; чек можно скачать (GET /v1/payouts/{id}/receipts/{fileId}). - Если выплату никто не взял в срок, её отменили или перевод невозможен —
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_, без декодирования.
Пример расчёта#
Ключ и секрет — вымышленные, из таблицы выше. Запрос:
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 проверяет запрос в таком порядке и отвечает первой найденной ошибкой:
- Наличие четырёх заголовков подписи, формат
X-Nonce. - Ключ: существует, активен, это ключ API мерчанта.
X-Timestampв окне.- Подпись.
X-Nonceне использован.- Адрес отправителя в списке IP ключа (если список задан).
- Мерчант и проект активны.
- У ключа есть право на эту точку.
- Для создания выплаты — у ключа есть непустой список IP (см. ниже).
- Лимит частоты запросов ключа.
Ошибки шагов 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"
}// Payin8 API: подпись запроса и вызов. Node.js 18+ (встроенные fetch и crypto).
import { createHash, createHmac, randomBytes } from 'node:crypto';
const BASE_URL = process.env.PAYIN8_BASE_URL ?? 'https://api.payin8.io';
const KEY_ID = process.env.PAYIN8_KEY_ID ?? 'mk_7k2m9q4x8p1r5t3v6w0y2z4b8c';
const SECRET = process.env.PAYIN8_SECRET ?? 'ms_dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC1vbmx5LTA';
/** Значение заголовка X-Signature: "v1=" + hex(HMAC-SHA256(секрет, каноническая строка)). */
export function signPayin8Request({ secret, method, pathAndQuery, timestamp, nonce, body }) {
const canonical = [
'v1',
method.toUpperCase(),
pathAndQuery,
timestamp,
nonce,
createHash('sha256').update(body).digest('hex'),
].join('\n');
return 'v1=' + createHmac('sha256', secret).update(canonical).digest('hex');
}
/**
* Подписанный запрос. body: объект (уйдёт JSON), Buffer (уйдёт как есть, нужен contentType) или undefined.
* Возвращает { status, headers, body }: body — разобранный JSON, а у файлов — Buffer.
*/
export async function payin8Request(method, pathAndQuery, body, contentType = 'application/json') {
const raw =
body === undefined ? Buffer.alloc(0) : Buffer.isBuffer(body) ? body : Buffer.from(JSON.stringify(body), 'utf8');
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = randomBytes(16).toString('hex');
const headers = {
'X-Api-Key': KEY_ID,
'X-Timestamp': timestamp,
'X-Nonce': nonce,
'X-Signature': signPayin8Request({ secret: SECRET, method, pathAndQuery, timestamp, nonce, body: raw }),
};
if (raw.length > 0) {
headers['Content-Type'] = contentType;
}
const res = await fetch(BASE_URL + pathAndQuery, {
method,
headers,
body: raw.length > 0 ? raw : undefined,
});
const isJson = (res.headers.get('content-type') ?? '').includes('application/json');
return {
status: res.status,
headers: Object.fromEntries(res.headers),
body: isJson ? await res.json() : Buffer.from(await res.arrayBuffer()),
};
}# Payin8 API: подпись запроса и вызов. Python 3.8+, только стандартная библиотека.
import hashlib
import hmac
import json
import os
import secrets
import time
import urllib.error
import urllib.request
BASE_URL = os.environ.get("PAYIN8_BASE_URL", "https://api.payin8.io")
KEY_ID = os.environ.get("PAYIN8_KEY_ID", "mk_7k2m9q4x8p1r5t3v6w0y2z4b8c")
SECRET = os.environ.get("PAYIN8_SECRET", "ms_dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC1vbmx5LTA")
def sign_payin8_request(secret, method, path_and_query, timestamp, nonce, body):
"""Значение заголовка X-Signature: "v1=" + hex(HMAC-SHA256(секрет, каноническая строка))."""
canonical = "\n".join([
"v1",
method.upper(),
path_and_query,
timestamp,
nonce,
hashlib.sha256(body).hexdigest(),
])
return "v1=" + hmac.new(secret.encode("utf-8"), canonical.encode("utf-8"), hashlib.sha256).hexdigest()
def payin8_request(method, path_and_query, body=None, content_type="application/json"):
"""body: dict (уйдёт JSON), bytes (уйдёт как есть) или None. Возвращает (status, headers, body)."""
if body is None:
raw = b""
elif isinstance(body, bytes):
raw = body
else:
raw = json.dumps(body, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
timestamp = str(int(time.time()))
nonce = secrets.token_hex(16)
headers = {
"X-Api-Key": KEY_ID,
"X-Timestamp": timestamp,
"X-Nonce": nonce,
"X-Signature": sign_payin8_request(SECRET, method, path_and_query, timestamp, nonce, raw),
}
if raw:
headers["Content-Type"] = content_type
request = urllib.request.Request(BASE_URL + path_and_query, data=raw or None, method=method, headers=headers)
try:
with urllib.request.urlopen(request, timeout=40) as response:
return _answer(response.status, response.headers, response.read())
except urllib.error.HTTPError as error:
return _answer(error.code, error.headers, error.read())
def _answer(status, headers, data):
if "application/json" in headers.get("Content-Type", ""):
data = json.loads(data)
return status, dict(headers), data<?php
// Payin8 API: подпись запроса и вызов. PHP 7.4+ с расширениями curl и json.
$PAYIN8_BASE_URL = getenv('PAYIN8_BASE_URL') ?: 'https://api.payin8.io';
$PAYIN8_KEY_ID = getenv('PAYIN8_KEY_ID') ?: 'mk_7k2m9q4x8p1r5t3v6w0y2z4b8c';
$PAYIN8_SECRET = getenv('PAYIN8_SECRET') ?: 'ms_dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC1vbmx5LTA';
/** Значение заголовка X-Signature: "v1=" + hex(HMAC-SHA256(секрет, каноническая строка)). */
function payin8_sign(string $secret, string $method, string $pathAndQuery, string $timestamp, string $nonce, string $body): string
{
$canonical = implode("\n", [
'v1',
strtoupper($method),
$pathAndQuery,
$timestamp,
$nonce,
hash('sha256', $body),
]);
return 'v1=' . hash_hmac('sha256', $canonical, $secret);
}
/**
* Подписанный запрос. $body: массив (уйдёт JSON), строка (уйдёт как есть) или null.
* Возвращает ['status' => int, 'headers' => array, 'body' => array|string].
*/
function payin8_request(string $method, string $pathAndQuery, $body = null, string $contentType = 'application/json'): array
{
global $PAYIN8_BASE_URL, $PAYIN8_KEY_ID, $PAYIN8_SECRET;
if ($body === null) {
$raw = '';
} elseif (is_string($body)) {
$raw = $body;
} else {
$raw = json_encode($body, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
}
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(16));
$headers = [
'X-Api-Key: ' . $PAYIN8_KEY_ID,
'X-Timestamp: ' . $timestamp,
'X-Nonce: ' . $nonce,
'X-Signature: ' . payin8_sign($PAYIN8_SECRET, $method, $pathAndQuery, $timestamp, $nonce, $raw),
];
if ($raw !== '') {
$headers[] = 'Content-Type: ' . $contentType;
}
$responseHeaders = [];
$ch = curl_init($PAYIN8_BASE_URL . $pathAndQuery);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_POSTFIELDS => $raw,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 40,
CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$responseHeaders) {
$parts = explode(':', $line, 2);
if (count($parts) === 2) {
$responseHeaders[strtolower(trim($parts[0]))] = trim($parts[1]);
}
return strlen($line);
},
]);
$data = curl_exec($ch);
if ($data === false) {
throw new RuntimeException('Payin8 request failed: ' . curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if (strpos($responseHeaders['content-type'] ?? '', 'application/json') !== false) {
$data = json_decode($data, true, 512, JSON_THROW_ON_ERROR);
}
return ['status' => $status, 'headers' => $responseHeaders, 'body' => $data];
}Проверка: вызов GET /v1/balance должен вернуть 200 и ваш баланс.
payin8 GET /v1/balanceconst { status, body } = await payin8Request('GET', '/v1/balance');
console.log(status, body);status, headers, body = payin8_request("GET", "/v1/balance")
print(status, body)$r = payin8_request('GET', '/v1/balance');
echo $r['status'], ' ', json_encode($r['body']), "\n";Ошибки аутентификации#
| 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 — отправьте на неё клиента.
Каждая выдача реквизита учитывается в лимитах проекта (см. Ограничения).
{
"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"}}'const { status, body } = await payin8Request('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' },
});
if (status === 201 || status === 200) {
console.log(body.status, body.amount, body.requisite);
} else if (status === 202) {
console.log('исполнитель подбирается, ждите вебхук payin.assigned', body.id);
} else {
console.log(status, body.code, body.details);
}status, headers, body = payin8_request("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"},
})
if status in (200, 201):
print(body["status"], body["amount"], body["requisite"])
elif status == 202:
print("исполнитель подбирается, ждите вебхук payin.assigned", body["id"])
else:
print(status, body["code"], body.get("details"))$r = payin8_request('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'],
]);
if ($r['status'] === 201 || $r['status'] === 200) {
echo $r['body']['status'], ' ', $r['body']['amount'], ' ', json_encode($r['body']['requisite']), "\n";
} elseif ($r['status'] === 202) {
echo "исполнитель подбирается, ждите вебхук payin.assigned ", $r['body']['id'], "\n";
} else {
echo $r['status'], ' ', $r['body']['code'], "\n";
}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-0d7e2c9b1a44const { status, body } = await payin8Request('GET', '/v1/payins/3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44');
console.log(status, body.status, body.final);status, headers, body = payin8_request("GET", "/v1/payins/3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44")
print(status, body.get("status"), body.get("final"))$r = payin8_request('GET', '/v1/payins/3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44');
echo $r['status'], ' ', $r['body']['status'] ?? $r['body']['code'], "\n";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-100501const { status, body } = await payin8Request('GET', '/v1/payins/by-invoice/inv-100501');
console.log(status, body.id, body.status);status, headers, body = payin8_request("GET", "/v1/payins/by-invoice/inv-100501")
print(status, body.get("id"), body.get("status"))$r = payin8_request('GET', '/v1/payins/by-invoice/inv-100501');
echo $r['status'], ' ', $r['body']['id'] ?? $r['body']['code'], "\n";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"// все завершённые приёмы за период, страница за страницей
let cursor = null;
do {
const query = new URLSearchParams({ status: 'completed', createdFrom: '2026-11-01T00:00:00Z', createdTo: '2026-11-20T00:00:00Z', limit: '50' });
if (cursor) query.set('cursor', cursor);
const { status, body } = await payin8Request('GET', `/v1/payins?${query}`);
if (status !== 200) throw new Error(`${status} ${body.code}`);
for (const payin of body.items) console.log(payin.id, payin.invoiceId, payin.amount);
cursor = body.nextCursor;
} while (cursor);from urllib.parse import urlencode
cursor = None
while True:
query = {"status": "completed", "createdFrom": "2026-11-01T00:00:00Z", "createdTo": "2026-11-20T00:00:00Z", "limit": "50"}
if cursor:
query["cursor"] = cursor
status, headers, body = payin8_request("GET", "/v1/payins?" + urlencode(query))
if status != 200:
raise RuntimeError(f"{status} {body['code']}")
for payin in body["items"]:
print(payin["id"], payin["invoiceId"], payin["amount"])
cursor = body["nextCursor"]
if not cursor:
break$cursor = null;
do {
$query = ['status' => 'completed', 'createdFrom' => '2026-11-01T00:00:00Z', 'createdTo' => '2026-11-20T00:00:00Z', 'limit' => '50'];
if ($cursor !== null) {
$query['cursor'] = $cursor;
}
$r = payin8_request('GET', '/v1/payins?' . http_build_query($query));
if ($r['status'] !== 200) {
throw new RuntimeException($r['status'] . ' ' . $r['body']['code']);
}
foreach ($r['body']['items'] as $payin) {
echo $payin['id'], ' ', $payin['invoiceId'], ' ', $payin['amount'], "\n";
}
$cursor = $r['body']['nextCursor'];
} while ($cursor !== null);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/cancelconst { status, body } = await payin8Request('POST', '/v1/payins/3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44/cancel');
console.log(status, body.status ?? body.code, body.details ?? body.failureReason);status, headers, body = payin8_request("POST", "/v1/payins/3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44/cancel")
print(status, body.get("status") or body.get("code"))$r = payin8_request('POST', '/v1/payins/3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44/cancel');
echo $r['status'], ' ', $r['body']['status'] ?? $r['body']['code'], "\n";Повтор того же клиента#
Если у клиента (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.
{
"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"}}'const { status, body } = await payin8Request('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' },
});
if (status === 201 || status === 200) {
console.log(body.id, body.status, body.totalDebit);
} else {
console.log(status, body.code, body.details);
}status, headers, body = payin8_request("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"},
})
if status in (200, 201):
print(body["id"], body["status"], body["totalDebit"])
else:
print(status, body["code"], body.get("details"))$r = payin8_request('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'],
]);
if ($r['status'] === 201 || $r['status'] === 200) {
echo $r['body']['id'], ' ', $r['body']['status'], ' ', $r['body']['totalDebit'], "\n";
} else {
echo $r['status'], ' ', $r['body']['code'], ' ', json_encode($r['body']['details'] ?? null), "\n";
}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-1a2b3c4d5e6fconst { status, body } = await payin8Request('GET', '/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f');
console.log(status, body.status, body.paidAmount, body.receipts);status, headers, body = payin8_request("GET", "/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f")
print(status, body.get("status"), body.get("paidAmount"), body.get("receipts"))$r = payin8_request('GET', '/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f');
echo $r['status'], ' ', $r['body']['status'] ?? $r['body']['code'], "\n";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-200731const { status, body } = await payin8Request('GET', '/v1/payouts/by-invoice/wd-200731');
console.log(status, body.id, body.status);status, headers, body = payin8_request("GET", "/v1/payouts/by-invoice/wd-200731")
print(status, body.get("id"), body.get("status"))$r = payin8_request('GET', '/v1/payouts/by-invoice/wd-200731');
echo $r['status'], ' ', $r['body']['id'] ?? $r['body']['code'], "\n";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"const { status, body } = await payin8Request('GET', '/v1/payouts?customerId=client-77&limit=20');
for (const payout of body.items) console.log(payout.id, payout.status, payout.amount);
console.log('next page:', body.nextCursor);status, headers, body = payin8_request("GET", "/v1/payouts?customerId=client-77&limit=20")
for payout in body["items"]:
print(payout["id"], payout["status"], payout["amount"])
print("next page:", body["nextCursor"])$r = payin8_request('GET', '/v1/payouts?customerId=client-77&limit=20');
foreach ($r['body']['items'] as $payout) {
echo $payout['id'], ' ', $payout['status'], ' ', $payout['amount'], "\n";
}
echo 'next page: ', $r['body']['nextCursor'] ?? 'null', "\n";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.binimport { writeFile } from 'node:fs/promises';
const { status, headers, body } = await payin8Request(
'GET',
'/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f/receipts/5d2e8f1a-9c3b-4a7d-b6e5-0f1e2d3c4b5a',
);
if (status === 200) {
await writeFile('receipt.bin', body);
console.log(headers['content-type'], body.length);
} else {
console.log(status, body.code);
}status, headers, body = payin8_request(
"GET", "/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f/receipts/5d2e8f1a-9c3b-4a7d-b6e5-0f1e2d3c4b5a"
)
if status == 200:
with open("receipt.bin", "wb") as f:
f.write(body)
print(headers["Content-Type"], len(body))
else:
print(status, body["code"])$r = payin8_request('GET', '/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f/receipts/5d2e8f1a-9c3b-4a7d-b6e5-0f1e2d3c4b5a');
if ($r['status'] === 200) {
file_put_contents('receipt.bin', $r['body']);
echo $r['headers']['content-type'], ' ', strlen($r['body']), "\n";
} else {
echo $r['status'], ' ', $r['body']['code'], "\n";
}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/cancelconst { status, body } = await payin8Request('POST', '/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f/cancel');
console.log(status, body.status ?? body.code, body.refundedAmount ?? body.details);status, headers, body = payin8_request("POST", "/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f/cancel")
print(status, body.get("status") or body.get("code"))$r = payin8_request('POST', '/v1/payouts/7c41e0d9-2b3a-4e5f-8d6c-1a2b3c4d5e6f/cancel');
echo $r['status'], ' ', $r['body']['status'] ?? $r['body']['code'], "\n";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 |
{
"balances": [
{ "currency": "ARS", "available": "1243903.76", "hold": "20200.00", "total": "1264103.76" }
]
}Приём зачисляется в available суммой net после completed. Выплата при создании переводит totalDebit из available в hold; после исполнения удержанное списывается, после отмены — возвращается в available. В кабинете эти части баланса называются «Доступно», «Заморожено» и «Всего» (см. Баланс).
payin8 GET /v1/balanceconst { status, body } = await payin8Request('GET', '/v1/balance');
for (const b of body.balances) console.log(b.currency, b.available, b.hold, b.total);status, headers, body = payin8_request("GET", "/v1/balance")
for b in body["balances"]:
print(b["currency"], b["available"], b["hold"], b["total"])$r = payin8_request('GET', '/v1/balance');
foreach ($r['body']['balances'] as $b) {
echo $b['currency'], ' ', $b['available'], ' ', $b['hold'], ' ', $b['total'], "\n";
}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 в объекте выплаты).
{
"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/methodsconst { status, body } = await payin8Request('GET', '/v1/methods');
for (const m of body.items) {
console.log(m.method, m.currency, 'payin:', m.payin?.fee.percent ?? 'off', 'payout:', m.payout?.fee.percent ?? 'off');
}status, headers, body = payin8_request("GET", "/v1/methods")
for m in body["items"]:
payin = m["payin"]["fee"]["percent"] if m["payin"] else "off"
payout = m["payout"]["fee"]["percent"] if m["payout"] else "off"
print(m["method"], m["currency"], "payin:", payin, "payout:", payout)$r = payin8_request('GET', '/v1/methods');
foreach ($r['body']['items'] as $m) {
echo $m['method'], ' ', $m['currency'],
' payin: ', $m['payin']['fee']['percent'] ?? 'off',
' payout: ', $m['payout']['fee']['percent'] ?? 'off', "\n";
}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 | Когда загружен |
{
"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/pdfimport { readFile } from 'node:fs/promises';
const pdf = await readFile('./bank-statement.pdf');
const { status, body } = await payin8Request(
'POST',
'/v1/files?dealId=3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44&purpose=evidence&name=bank-statement.pdf',
pdf,
'application/pdf',
);
console.log(status, body.id ?? body.code, body.contentType ?? body.details);with open("bank-statement.pdf", "rb") as f:
pdf = f.read()
status, headers, body = payin8_request(
"POST",
"/v1/files?dealId=3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44&purpose=evidence&name=bank-statement.pdf",
pdf,
"application/pdf",
)
print(status, body.get("id") or body.get("code"))$pdf = file_get_contents('bank-statement.pdf');
$r = payin8_request(
'POST',
'/v1/files?dealId=3b8f6a2e-6c1d-4f2b-9a51-0d7e2c9b1a44&purpose=evidence&name=bank-statement.pdf',
$pdf,
'application/pdf'
);
echo $r['status'], ' ', $r['body']['id'] ?? $r['body']['code'], "\n";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 |
По сделке уже был открыт спор; возвращён он |
Тело — объект спора:
{
"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"]}'const { status, body } = await payin8Request('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'],
});
console.log(status, body.id ?? body.code, body.status ?? body.details);status, headers, body = payin8_request("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"],
})
print(status, body.get("id") or body.get("code"), body.get("status") or body.get("details"))$r = payin8_request('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'],
]);
echo $r['status'], ' ', $r['body']['id'] ?? $r['body']['code'], "\n";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-0e1f2a3b4c5dconst { status, body } = await payin8Request('GET', '/v1/disputes/c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d');
console.log(status, body.status, body.outcome, body.resolvedAmount);status, headers, body = payin8_request("GET", "/v1/disputes/c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d")
print(status, body.get("status"), body.get("outcome"), body.get("resolvedAmount"))$r = payin8_request('GET', '/v1/disputes/c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d');
echo $r['status'], ' ', $r['body']['status'] ?? $r['body']['code'], "\n";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"const { status, body } = await payin8Request('GET', '/v1/disputes?status=open&limit=20');
for (const d of body.items) console.log(d.id, d.dealType, d.dealId, d.reason, d.openedAt);status, headers, body = payin8_request("GET", "/v1/disputes?status=open&limit=20")
for d in body["items"]:
print(d["id"], d["dealType"], d["dealId"], d["reason"], d["openedAt"])$r = payin8_request('GET', '/v1/disputes?status=open&limit=20');
foreach ($r['body']['items'] as $d) {
echo $d['id'], ' ', $d['dealType'], ' ', $d['dealId'], ' ', $d['reason'], ' ', $d['openedAt'], "\n";
}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"]}'const { status, body } = await payin8Request('POST', '/v1/disputes/c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/evidence', {
comment: 'Second page of the statement',
fileIds: ['9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b'],
});
console.log(status, body.status ?? body.code, body.files?.length ?? body.details);status, headers, body = payin8_request("POST", "/v1/disputes/c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/evidence", {
"comment": "Second page of the statement",
"fileIds": ["9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b"],
})
print(status, body.get("status") or body.get("code"))$r = payin8_request('POST', '/v1/disputes/c2a1b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/evidence', [
'comment' => 'Second page of the statement',
'fileIds' => ['9e1d2c3b-4a5f-4e6d-8c7b-6a5f4e3d2c1b'],
]);
echo $r['status'], ' ', $r['body']['status'] ?? $r['body']['code'], "\n";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 + "." + сырое тело ) )- Возьмите из заголовка
tи все значенияv1. - Посчитайте HMAC-SHA256 от строки
t, точки и сырых байтов тела — до разбора JSON. Ключ — вся строка секрета вместе с префиксомwhsec_. - Примите запрос, если ваше значение совпало с любым
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));# Проверка вебхука Payin8. Python 3.8+, только стандартная библиотека.
import hashlib
import hmac
import json
import os
import time
from http.server import BaseHTTPRequestHandler, HTTPServer
WEBHOOK_SECRET = os.environ.get("PAYIN8_WEBHOOK_SECRET", "whsec_dGhpcy1pcy1hbi1leGFtcGxlLXdlYmhvb2sta2V5LTA")
def verify_payin8_webhook(raw_body, signature_header, secret, tolerance_sec=300):
"""True, если подпись совпала и метка времени не старше tolerance_sec. raw_body — bytes тела как пришли."""
if not signature_header:
return False
parts = [p.strip() for p in signature_header.split(",")]
t = next((p[2:] for p in parts if p.startswith("t=")), "")
signatures = [p[3:] for p in parts if p.startswith("v1=")]
if not t.isdigit() or abs(time.time() - int(t)) > tolerance_sec:
return False
expected = hmac.new(secret.encode("utf-8"), t.encode("utf-8") + b"." + raw_body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(expected, s.lower()) for s in signatures)
# Пример приёмника: проверить подпись, ответить 200, обработать событие.
class Payin8WebhookHandler(BaseHTTPRequestHandler):
seen = set() # в боевом коде — таблица обработанных Payin8-Event-Id
def do_POST(self):
raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))
if not verify_payin8_webhook(raw, self.headers.get("Payin8-Signature"), WEBHOOK_SECRET):
self.send_response(400)
self.end_headers()
return
self.send_response(200)
self.end_headers()
event = json.loads(raw)
if event["id"] in self.seen:
return
self.seen.add(event["id"])
print(event["type"], event["data"]["id"], event["data"].get("status"), event["data"].get("version"))
if __name__ == "__main__":
HTTPServer(("0.0.0.0", int(os.environ.get("PORT", "3000"))), Payin8WebhookHandler).serve_forever()<?php
// Проверка вебхука Payin8. PHP 7.4+.
/** true, если подпись совпала и метка времени не старше $toleranceSec. $rawBody — тело как пришло. */
function payin8_verify_webhook(string $rawBody, ?string $signatureHeader, string $secret, int $toleranceSec = 300): bool
{
if ($signatureHeader === null || $signatureHeader === '') {
return false;
}
$t = '';
$signatures = [];
foreach (explode(',', $signatureHeader) as $part) {
$part = trim($part);
if (strncmp($part, 't=', 2) === 0) {
$t = substr($part, 2);
} elseif (strncmp($part, 'v1=', 3) === 0) {
$signatures[] = strtolower(substr($part, 3));
}
}
if (!ctype_digit($t) || abs(time() - (int) $t) > $toleranceSec) {
return false;
}
$expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
foreach ($signatures as $signature) {
if (hash_equals($expected, $signature)) {
return true;
}
}
return false;
}
// Обработчик (этот же файл за веб-сервером): проверить подпись, ответить 200, обработать событие.
$secret = getenv('PAYIN8_WEBHOOK_SECRET') ?: 'whsec_dGhpcy1pcy1hbi1leGFtcGxlLXdlYmhvb2sta2V5LTA';
$raw = file_get_contents('php://input');
if (!payin8_verify_webhook($raw, $_SERVER['HTTP_PAYIN8_SIGNATURE'] ?? null, $secret)) {
http_response_code(400);
exit;
}
$event = json_decode($raw, true);
// Здесь: если $event['id'] уже обработан — ничего не делать; иначе сохранить событие для обработки.
error_log($event['type'] . ' ' . $event['data']['id'] . ' v' . ($event['data']['version'] ?? '-'));
http_response_code(200);Внимание
Проверяйте подпись по сырым байтам тела. Если фреймворк уже разобрал 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позднего подтверждения. - Дубли возможны. Одно событие может прийти несколько раз: после повтора, после повторной отправки из кабинета, после сбоя на любой стороне.
Как обрабатывать:
- Проверьте подпись.
- Если событие с этим
id(Payin8-Event-Id) уже обработано — ответьте200и ничего не делайте. - Сравните
data.versionс версией сделки, которую вы уже сохранили. Меньше или равна — состояние устарело: запишите событие, но не откатывайте статус. Больше — примените. - Сопоставляйте сделку по
data.id(илиdata.invoiceId/data.invoiceIds), а не по порядку прихода. - Перед зачислением денег клиенту убедитесь, что
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#
{
"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).
{
"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 пересчитаны.
{
"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.
{
"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#
{
"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#
Другой исход той же выплаты: вы отменили её до того, как исполнитель её взял. Удержанное вернулось полностью.
{
"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#
{
"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#
{
"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#
{
"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 и тело одного формата.
Формат ошибки#
{
"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 | Проверка запросов временно недоступна | Повторить с новой подписью |
Как повторять запросы — Повтор после сбоя.