Absolut Pay API

Начало работы

Интеграция выполняется с вашего сервера. Плательщик получает реквизиты либо открывает платёжную форму; API token и secret остаются на сервере мерчанта.

Что получить от Absolut Pay

Подтверждённый API base URL: https://api.absolutpay.com, без добавленного /api/v2. Например, полный адрес чтения баланса — https://api.absolutpay.com/api/v2/balance. Проверено 25.10.2026: HTTPS и /livez доступны; GET /api/v2/banks и GET /api/v2/balance возвращают HTTP 503. Доступность бизнес-операций не подтверждена; рабочие ключи, разрешённые IP и активация магазина согласуются отдельно. Проверка health не подтверждает готовность платежей. Origin hosted payment page пока не подтверждён: используйте только полный payment_url, возвращённый API.

Рекомендуемый порядок

1. Сохраните ключи в серверном хранилище секретов и согласуйте IP вашего backend.
2. Настройте точное формирование подписи и синхронизацию системных часов.
3. Реализуйте собственную таблицу платежных попыток с merchant_order_id, полученным id, текущим состоянием и историей обработки.
4. Реализуйте проверку webhook и устойчивую обработку повторов.
5. Создайте одну тестовую заявку. Проверьте чтение по своему номеру и по выданному id.
6. Проверьте потерю ответа и повторные уведомления. В локальном контуре merchant webhook подавлен: его формат проверяется отдельными подписанными примерами, не ожиданием доставки после тестового POST.
7. Пройдите согласованный полный сценарий на предоставленном окружении перед включением реального приёма.

Первый запрос

Файл examples/create-payin.json содержит тестовый запрос. Замените номер заказа и данные плательщика своими тестовыми значениями. Адрес webhook в файле — заполнитель: в окружении с доставкой укажите ваш настоящий HTTPS endpoint.

Задайте ABSOLUT_API_BASE_URL=https://api.absolutpay.com, ABSOLUT_API_TOKEN, ABSOLUT_API_SECRET в окружении серверного процесса. Не записывайте реальные значения в файлы примеров, историю команд, исходники или клиентский JavaScript.

# Команды выполняются из папки merchant-v2.
node examples/client.mjs create --body examples/create-payin.json
node examples/client.mjs result shop-order-0001
node examples/client.mjs get ord_123

ord_123 — условный идентификатор, замените его значением реального ответа. Создание выполняется только по явной команде create; примеры не повторяют POST автоматически. Полный ответ может содержать конфиденциальную ссылку или реквизиты: не направляйте вывод примера в общие логи.

Два режима выдачи

В текущем локальном контуре реквизиты имеют тип mock и значение TEST-ONLY-NOT-PAYABLE. По ним нельзя отправлять деньги. Возможности живых реквизитов согласуются после подключения реального провайдера.

Успешное создание HTTP 201 означает выдачу платежа, а не факт оплаты. Выдавайте оплаченный товар/услугу только после проверенного статуса 2 и собственной защищённой обработки результата.

Подключение выплат

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

Аутентификация запросов

Каждый запрос Payin API v2 подписывает ваш сервер. Для магазина выдаётся пара api_token и api_secret; она определяет магазин, от имени которого выполняется запрос. Передавать shop_id в теле не требуется и не допускается.

Настройте адрес API, выданный Absolut Pay для вашего подключения. Наличие примеров в документации не означает, что тестовый или рабочий адрес уже активирован. В проверенной версии API доступен в локальном тестовом окружении; рабочее подключение согласовывается отдельно.

Что необходимо перед первым запросом

• Токен и секрет нужного магазина.
• Добавленные в разрешённый список исходящие IP-адреса вашего сервера.
• Синхронизированное время на сервере.
• Активный магазин и разрешённые условия приёма для создания новых платежей.

Храните секрет в серверном хранилище конфигурации. Не передавайте его в браузер, мобильное приложение, query string или тело запроса. Не записывайте секрет, токен и полный набор подписанных заголовков в обычные логи.

Заголовки

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

Сервер принимает время запроса в пределах ±300 секунд от своего текущего времени. Миллисекунды вместо секунд не подходят. Рекомендуем использовать обычную строчную запись UUID; если вы используете другую допустимую запись, подпись должна содержать именно отправленную строку.

Строка для подписи

Соедините пять компонентов в таком порядке, используя байт перевода строки LF, \n:

timestamp + "\n" +
nonce + "\n" +
UPPERCASE_METHOD + "\n" +
exact_path_and_query + "\n" +
raw_body

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

В подпись не входят схема и домен. Например, для запроса к BASE_URL/api/v2/payins подписывается /api/v2/payins.

Вычислите:

signature = lowercase_hex(HMAC_SHA512(api_secret, canonical_bytes))

Ключ HMAC — буквальная строка выданного api_secret. Не декодируйте её из Base64 или Base64URL, даже если её вид напоминает такую кодировку. Не заменяйте исходное тело его хешем.

POST с JSON

Сначала сериализуйте объект в UTF-8 байты один раз. Эти же байты используйте для подписи и отправки.

1791460800\n
01234567-89ab-4cde-8fab-0123456789ab\n
POST\n
/api/v2/payins\n
{"merchant_order_id":"invoice-10428","amount":"15000.00",...}

Здесь \n обозначает один LF; многоточие показывает сокращение примера и не является допустимым телом запроса. Полный JSON нужно взять из описания создания платежа.

Изменение порядка JSON-полей, пробелов, экранирования или добавление перевода строки после подписи даст другие байты. Если HTTP-библиотека автоматически сериализует объект, убедитесь, что она отправляет именно подписанную сериализацию; проще передавать подготовленные байты.

GET с query string

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

/api/v2/payins/result?merchant_order_id=invoice-10428

Тело GET пустое. Поэтому канонические байты заканчиваются LF, который разделяет путь и пустое тело:

1791460800\n01234567-89ab-4cde-8fab-0123456789ab\nGET\n/api/v2/payins/result?merchant_order_id=invoice-10428\n

После этого LF дополнительных байтов нет. Это не произвольный завершающий перевод строки: он нужен перед пустым пятым компонентом.

Подписывайте query string после URL-кодирования. Не меняйте порядок параметров, + на %20, %2f на %2F или другие байты между подписью и отправкой. Для этого маршрута разрешён ровно один параметр merchant_order_id; дополнительные и повторяющиеся параметры не принимаются.

IP-адреса и область доступа

Разрешённый список относится к исходящему сетевому адресу вашего API-сервера. Поле payer.ip — IP плательщика для обработки заявки; оно не определяет доступ вашего сервера к API.

Пустой разрешённый список запрещает все запросы. Если сервер работает за NAT или использует несколько исходящих адресов, согласуйте фактические адреса заранее. Произвольные X-Forwarded-For и X-Real-IP, отправленные клиентом, не дают доступ с другого IP.

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

Повторы и восстановление результата

Для каждого нового HTTP-запроса, включая повтор и поиск результата, создавайте новый UUID v4, свежий timestamp и новую подпись. Уже принятый nonce нельзя использовать повторно, даже если ответ потерялся.

Nonce защищает HTTP-запрос от повторного воспроизведения. merchant_order_id защищает создание платежа от дублирования. Это разные значения с разным назначением:

При тайм-ауте или потере ответа на создание ищите результат по прежнему merchant_order_id новым подписанным GET. Не создавайте другую заявку под новым номером, пока исходный результат не выяснен. Подробный порядок восстановления приведён в описании Payin API.

Смена ключей

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

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

Ошибки и диагностика

Причины ошибок подписи, неизвестного токена и повторного nonce объединены в authentication_failed; API не раскрывает внутреннюю причину. Для обращения в поддержку сохраните request_id, свой merchant_order_id, время, метод и маршрут. Секрет и токен в обращение не включайте.

Ограничения подписанного запроса: тело до 1 МиБ UTF-8, путь с query string до 8192 байтов. GET с непустым телом не принимается.

Методы оплаты и валюты

Для приёма выберите как платит клиент — method_id, и в каких денежных единицах задана сумма — currency. Это два разных поля. Например, method_id: 2 означает оплату картой, а currency: "UZS" — сумму в узбекских сумах. Такая комбинация работает только после подключения для вашего магазина.

Методы приёма: какой method_id передавать

method_id — целое число в запросе POST /api/v2/payins. Передавайте 2, а не "2", "card" или название банка.

Методы 1–4 входят в текущий серверный контракт. За Трансграничным переводом (cross_border) по согласованию закреплён method_id: 5. Поддержка на сервере ещё не реализована: текущий API отклонит 5. Произвольные другие номера не допускаются. Подробнее — Трансграничный перевод.

Названия в таблице объясняют назначение методов, а не подтверждают живое подключение: текущий Payin-контур возвращает только mock / TEST-ONLY-NOT-PAYABLE. Нельзя обещать настоящие карту, QR или мобильные реквизиты до проверки провайдера. У карточного метода нет публичных отдельных ID для Visa, Mastercard, HUMO или Uzcard; не подставляйте чужие номера методов.

Как показать оплату клиенту

mode определяет интерфейс, а не новый метод оплаты. Оба значения передаются отдельно от method_id:

Для всех методов используйте один запрос создания приёма, одну схему подписи и проверку статуса. Получение HTTP 201 означает создание, а подтверждённая оплата — status_id: 2.

Валюты и суммы

В currency передаётся строка с кодом в верхнем регистре. Числового currency_id в текущем Merchant API v2 нет.

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

amount — сумма в основных единицах валюты, не в копейках и не в USDT. "1500.00" RUB означает 1 500 рублей, а не 15 рублей. Не умножайте сумму на 100 перед отправкой. KGS и UZS — разные валюты; их названия «сом» и «сум» не взаимозаменяемы.

USDT — валюта учётного баланса и расчётных полей. Её нельзя передать в currency Create Payin/Create Payout. GET /api/v2/balance возвращает USDT независимо от валюты платежа; значения баланса имеют 8 знаков после точки. USD, EUR, RUR и строчные rub текущими валидаторами не принимаются.

Как подключить нужную валюту

1. Определите направление: приём оплаты от клиента или выплата клиенту.
2. Выберите метод и валюту отдельно. Например, для приёма картой в UZS это method_id: 2 и currency: "UZS".
3. Получите подтверждение подключения этой пары для вашего магазина и окружения: активные условия, минимальная/максимальная сумма, точность, комиссия, курс, режим выдачи и исполнитель. В текущем API нет метода, который вернёт полную доступную матрицу; её предоставляет команда подключения.
4. Для приёма заполните сумму в выбранной валюте, payer, traffic_type, mode и адрес webhook. Сохраните уникальный merchant_order_id до отправки, подпишите фактически отправляемые байты.
5. Для выплаты используйте строковый method и реквизиты получателя из таблицы ниже. Проверьте отдельные условия выплат, канонический банк и достаточный USDT-баланс.
6. После отправки обработайте ответ, webhook и lookup. Проверяйте валюту и подтверждённую сумму, не выдавайте товар по факту создания заявки и не повторяйте POST при timeout.

Изменение только currency в прежнем запросе не конвертирует сумму. Если было "1500.00" RUB и вы заменили код на UZS, теперь вы запросили 1 500 UZS. Для новой намеренной операции используйте новый номер; после неизвестного результата старой сначала выполните lookup.

Пример: приём картой в UZS

Пример формата после согласования пары карта + UZS. Он не подтверждает подключение провайдера или достаточность суммы для лимитов. Текущий sandbox не выдаёт платёжных реквизитов.

{
  "merchant_order_id": "shop-card-uzs-0001",
  "amount": "150000.00",
  "currency": "UZS",
  "method_id": 2,
  "mode": "payment_form",
  "traffic_type": "primary",
  "payer": {
    "id": "customer-1001",
    "ip": "203.0.113.10"
  },
  "webhook_url": "https://merchant.example.invalid/webhooks/absolut-pay"
}

Здесь клиенту предлагается оплатить 150 000 UZS. Сохраните JSON в файл, задайте ключи и выданный API origin в серверном окружении, отправьте тем же клиентом:

node examples/client.mjs create --body request-uzs.json
node examples/client.mjs result 'shop-card-uzs-0001'

При сформированном платеже откройте полученный payment_url. Для H2H поменяйте mode на h2h до создания новой операции и обрабатывайте requisite. Для AZN/KZT/KGS используется тот же маршрут и схема запроса; сумма уже должна быть рассчитана именно в выбранной валюте, а пара с методом — отдельно подключена. Алгоритм подписи от валюты не меняется.

Выплаты: какой метод и реквизиты передавать

Выплаты используют POST /api/v2/payouts и строковое поле method, а не числовой method_id. Не копируйте тело приёма в выплату.

Передавайте ровно один вид реквизита выбранного метода. Для выплаты нет публичных методов qr и mobile. Во всех вариантах amount — сумма получателю в указанной currency; курс и комиссию в запросе вы не задаёте.

Пример формата выплаты на счёт в KZT после согласования отдельной пары account + KZT. Номер счёта и получатель синтетические, не предназначены для реального перевода:

{
  "merchant_order_id": "shop-account-kzt-0001",
  "amount": "15000.00",
  "currency": "KZT",
  "method": "account",
  "recipient": {
    "account_number": "TESTACCOUNT00000001",
    "customer_name": "Тестовый получатель"
  }
}

Это поручение на 15 000 KZT, а резерв рассчитывается в USDT. HTTP 201 не означает перечисление. Без webhook проверяйте результат через подписанный API. Поля и ошибки создания выплаты · Получить банки.

Как связаны валюта клиента и USDT

Приём: rate — сколько единиц валюты платежа приходится на 1 USDT. Для UZS это UZS за USDT; для RUB — RUB за USDT. fee — проценты. Сохраняйте исходный amount и фактический success_paid отдельно.

Выплата: rate_fiat_per_usdt имеет то же направление — единиц валюты выплаты за 1 USDT. Сервер возвращает principal_usdt, fee_usdt, total_usdt; не пересчитывайте резерв по текущему курсу. Условия приёма не задают курс и комиссию выплаты.

Курс UZS/USDT не является курсом RUB/UZS. Приём в UZS сам по себе не означает, что отправитель платит RUB. Две валюты отправителя и получателя относятся к отдельному проекту трансграничного метода.

Если выбранная пара не работает

Полные объяснения и правила повторов — Ошибки. Не пробуйте другую валюту, ID или новый номер заказа как автоматический обход отказа.

Что фактически доступно

Приём проверен в локальном sandbox. Публичный API origin подтверждён, но доступность бизнес-операций, production-сочетаний и реальных коридоров этой публикацией не подтверждается. У выплат реализованы создание, учётный резерв и ручное исполнение; настоящий автоматический провайдер не подтверждён. Настройки магазина и терминала должны разрешать конкретную пару; справочник банков не заменяет эту проверку.

Матрица реализации в JSON фиксирует ограничения версии. Адреса API и платёжной формы выдаются отдельно от домена документации.

Справочник и выбор банка

Получите ID из справочника Absolut Pay. Выбор банка через bank_id относится к выплатам, не к созданию входящего платежа. Наш ID не является кодом НСПК, БИК или кодом провайдера. Он не меняется при переименовании банка и не назначается другому банку.

Список банков и платёжных организаций

Ниже — все 250 записей предоставленного справочника от 08.10.2026: банки, кошельки и мобильные операторы. Повторяющиеся названия сохранены: исходные записи нельзя автоматически объединять.

Это справочный список, а не перечень подключённых банков. Активные записи и канонические ID вашего окружения возвращает API. Страны и типы в исходнике не подтверждены. Старые коды и внутренние сопоставления шлюзов здесь не публикуются.

Чтобы получить рабочий ID: найдите название в таблице, запросите GET /api/v2/banks?q=... с URL-кодированным названием и передайте items[].id выбранной записи в bank_id выплаты. При нескольких совпадениях уточните банк и страну; не выбирайте автоматически первую запись. Если список пуст, согласуйте подключение банка. Не создавайте ID самостоятельно.

GET /api/v2/banks

Запрос выполняется с вашего сервера и подписывается теми же четырьмя заголовками, что Payin API. Тело GET пустое. В подпись входит точный путь с закодированными параметрами:

GET /api/v2/banks?country_code=RU

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

{
  "items": [
    {
      "id": "bank_1",
      "original_name": "Т-Банк",
      "country_code": "RU",
      "kind": "bank"
    }
  ],
  "next_after": null
}

bank_1 — пример, а не гарантированный ID Т-Банка. Всегда используйте фактический items[].id своего окружения. Не переносите ID из чужого справочника или другой установки.

Не передавайте дополнительные или повторяющиеся параметры. Страница содержит не более 100 записей в порядке ID. При next_after: null чтение закончено. Пустой items — корректный результат: например, нет активных банков, соответствующих фильтру.

original_name — согласованное название, которое показывается плательщику. country_code может быть null, если страна не задана. kind различает банк (bank), кошелёк (wallet), мобильного оператора (mobile) и другой тип (other). Названия и технические коды отдельных шлюзов клиенту не передаются.

Наличие банка в справочнике не означает, что он настроен для каждого магазина, метода или терминала. Разрешённые сочетания подтверждаются для вашего подключения.

Банк при приёме платежа

В POST /api/v2/payins поле bank_id не передаётся. Банк определяется по фактически выданным шлюзом реквизитам и проверенному сопоставлению. Когда банк установлен, ответ содержит bank_id и bank_name для обоих режимов; в H2H эта пара также указана в requisite.

bank_name — сохранённый original_name, а не произвольное название провайдера. Hosted form показывает это же название. Переименование банка не переписывает уже выданную заявку. Неизвестное значение провайдера требует сверки: не считайте отсутствие реквизитов доказательством отсутствия операции у провайдера.

Банк при выплате

В POST /api/v2/payouts передайте bank_id из этого справочника. Полный запрос, правила методов, получатель, резервирование и повторы описаны в разделе Выплаты клиентам. ID обязателен для СБП; для карты и счёта требования исполнителя подтверждаются отдельно.

ID передаётся отдельно от карты или телефона получателя. Не передавайте вместо него название банка, код провайдера или числовую часть ID. original_name и внутренние сопоставления вы не задаёте. Сетл мерчанту и выплата его клиенту — разные операции.

node examples/client.mjs banks
# Если next_after не null, подставьте возвращённое значение:
node examples/client.mjs banks --after bank_100

Публичный API origin подтверждён; доступность операций не подтверждена (проверенный GET /api/v2/banks возвращает 503). Локальные тесты приёма используют неплатёжный sandbox. Поддержка справочника не включает настоящий провайдерский адаптер или автоматическое исполнение выплат через реальный шлюз.

Создание и проверка платежа

Все три API-запроса подписываются по протоколу аутентификации. Магазин определяется ключами. Для нового запроса нужна новая подпись с новым nonce, даже если вы читаете тот же платёж.

Создание: POST /api/v2/payins

{
  "merchant_order_id": "shop-order-0001",
  "amount": "15000.00",
  "currency": "RUB",
  "method_id": 1,
  "mode": "h2h",
  "traffic_type": "primary",
  "payer": {
    "id": "customer-1001",
    "ip": "203.0.113.10"
  },
  "webhook_url": "https://merchant.example.invalid/webhooks/absolut-pay"
}

Это пример формата, не рабочий адрес webhook. IP в примере относится к плательщику и не заменяет IP вашего сервера в allowlist.

Обязательные поля

Не меняйте payer.id при каждом платеже одного клиента: он участвует в проверках трафика и ограничений. Не передавайте произвольный тип трафика ради обхода настроек.

Необязательные поля

При отсутствии необязательного значения опускайте поле. Не используйте null как универсальную замену. Неизвестные поля, повторяющиеся JSON-ключи и другие написания имён отклоняются. Не передавайте shop_id, is_test, live, status, курс или комиссию: клиент не задаёт эти значения.

Если нет webhook_url, используется адрес магазина, сохранённый при подготовке заявки. Если отсутствуют оба, запрос заканчивается 422 webhook_required, а merchant_order_id остаётся занятым. Добавление URL позже не перезапускает этот запрос.

Ответ создания

POST ожидает выдачи реквизитов и фиксации условий до 30 секунд. HTTP 201 возвращает объект платежа напрямую, без обёртки data:

{
  "id": "ord_123",
  "merchant_order_id": "shop-order-0001",
  "status_id": 1,
  "amount": "15000.00",
  "currency": "RUB",
  "method_id": 1,
  "mode": "h2h",
  "traffic_type": "primary",
  "rate": "100.00",
  "fee": "2.00",
  "created_at": "2026-10-08T12:00:00Z",
  "expires_at": "2026-10-08T12:10:00Z",
  "is_test": true,
  "requisite": {"type": "mock", "value": "TEST-ONLY-NOT-PAYABLE"}
}

Пример условный и неплатёжный. Не требуйте именно два знака после точки: сервер может вернуть другую точную десятичную запись. В режиме payment_form вместо requisite приходит payment_url. Эти поля взаимно исключаются.

Даты API — ISO 8601 UTC, возможны доли секунды. Для отображения преобразуйте их в выбранный часовой пояс; подпись и данные запроса не меняйте. Деньги и курс сохраняйте как строки/Decimal, без binary float.

Статусы платежа

Подтверждённая поздняя оплата может перевести 3 в 2, а некоторые причины отмены — 4 в 2. Применяйте ответы POST/GET и webhook с проверкой актуального состояния вашего заказа. Уже сохранённый успех 2 нельзя перезаписать задержанным ответом со статусом 1, 3 или 4. Опрос API и webhook должны использовать общий ключ однократной выдачи товара или услуги.

Автоматический callback провайдера принимается только при численном равенстве подтверждённой и исходной суммы. Например, "15000" и "15000.00" равны; сравнивайте точные десятичные значения, а не текстовую запись или binary float. Другая сумма в callback требует сверки и сама по себе не переводит платёж в успех с зачислением.

Ручное подтверждение фактической суммы

Уполномоченный сотрудник может отдельно подтвердить фактически оплаченную сумму с доказательством и аудитом. Тогда status_id=2, исходный amount сохраняется, а success_paid может отличаться. Курс rate и ставка fee остаются сохранёнными условиями заявки; текущие настройки не применяются. Это отдельное подтверждение, а не автоматическое принятие произвольной частичной оплаты и не второе начисление.

Условный пример результата GET для той же тестовой заявки после ручного подтверждения 12000 RUB вместо исходных 15000 RUB; пример не свидетельствует о реальном платеже:

{
  "id": "ord_123",
  "merchant_order_id": "shop-order-0001",
  "status_id": 2,
  "amount": "15000.00",
  "success_paid": "12000.00",
  "currency": "RUB",
  "method_id": 1,
  "mode": "h2h",
  "traffic_type": "primary",
  "rate": "100.00",
  "fee": "2.00",
  "created_at": "2026-10-08T12:00:00Z",
  "expires_at": "2026-10-08T12:10:00Z",
  "paid_at": "2026-10-08T12:09:00Z",
  "is_test": true,
  "requisite": {"type": "mock", "value": "TEST-ONLY-NOT-PAYABLE"}
}

В уведомлении те же суммы называются amount и successPaid. Сохраните обе суммы; не подменяйте фактическую оплату исходной суммой заказа. При расхождении приостановите автоматическую выдачу полного товара или услуги и выполните сверку через API и поддержку по вашим правилам обработки недоплаты или переплаты. Само расхождение сумм не означает недействительную подпись или ошибочный статус. После сверки используйте общий для API и webhook ключ однократного бизнес-действия.

Потерянный ответ: GET /api/v2/payins/result

GET /api/v2/payins/result?merchant_order_id=shop-order-0001

При URL-кодировании номера подпишите тот же точный path/query, который отправляете. Ответ HTTP 200:

{"merchant_order_id":"shop-order-0001","state":"processing"}

После потери ответа, HTTP 409, 503 или 504 проверяйте этот маршрут. Новый nonce нужен на каждый GET. Интервал опроса согласуйте для выданного окружения; общего обещанного лимита или расписания здесь нет.

merchant_order_id уникален внутри магазина после принятия запроса, в том числе после терминальной ошибки. Повтор POST возвращает 409 duplicate_merchant_order_id, а не первоначальный успешный ответ. Нет заголовка Idempotency-Key в текущем контракте.

HTTP 404 при проверке означает отсутствие видимой записи в данный момент. Он не доказывает, что ранее отправленный POST не может ещё завершиться. Сначала завершите сверку; не создавайте другой номер для той же покупки с неопределённым исходом. Новая намеренная попытка после подтверждённого завершения предыдущей получает новый merchant_order_id и связь с покупкой в вашей системе.

Чтение сформированного платежа: GET /api/v2/payins/{id}

GET /api/v2/payins/ord_123

HTTP 200 возвращает тот же объект платежа. Пока он не сформирован, используйте поиск по merchant_order_id. Неизвестный или принадлежащий другому магазину id возвращает 404.

Платёжная форма

Открывайте только payment_url, полученный от сервера. Не собирайте его из id или домена админки: ссылка содержит секретный capability-токен. Не публикуйте её в общих логах/аналитике, не добавляйте посторонние query-параметры. При открытии новой вкладки используйте noopener и noreferrer.

Повторное открытие не создаёт новый платёж. Форма показывает текущее состояние, результат оплаты либо истечение срока. При наличии настроенных действий загрузка чека и «Я оплатил» передают информацию, не подтверждают оплату. Переход браузера, сообщение пользователя и скриншот не заменяют проверенный статус API/webhook.

Выплаты клиентам

Клиентская выплата — перевод получателю по поручению магазина. Это отдельная операция от входящего платежа и сетла мерчанту. Запрос создаёт сохранённую заявку и резервирует USDT; он не означает, что получатель уже получил деньги.

У магазина должны быть активированы отдельные условия выплат для метода и валюты: курс в единицах валюты за 1 USDT и комиссия магазина. Условия приёма платежей не подставляются автоматически. Перед первым запросом согласуйте доступные методы, валюты, банк и способ исполнения с Absolut Pay.

POST /api/v2/payouts

JSON-запрос подписывается четырьмя заголовками из раздела «Подпись запросов». Секрет хранится на сервере мерчанта. Подписывайте точные байты тела, не меняя их после вычисления подписи.

{
  "merchant_order_id": "PAYOUT-2026-000042",
  "amount": "15000.00",
  "currency": "RUB",
  "method": "sbp",
  "bank_id": "bank_1",
  "recipient": {
    "phone_number": "+79991112233",
    "customer_name": "Тестовый получатель"
  },
  "webhook_url": "https://merchant.example/payouts-hook",
  "metadata": {
    "customer_ref": "customer-42"
  }
}

bank_1 — пример. Получите фактический ID из GET /api/v2/banks. Не отправляйте наш ID как код НСПК напрямую в API другого провайдера.

Для всех методов обязательно recipient.customer_name: имя получателя, 1–200 UTF-8 байт. Остальные поля зависят от метода:

Нельзя передавать карту одновременно с телефоном или счётом. Неизвестные поля, дубли ключей, null, повторные параметры URL и числовое JSON-значение вместо суммы отклоняются. Метод account в этой версии доступен для ручного исполнения; автоматический адаптер для него не подключён.

Магазин определяется подписанным API-токеном. Не передавайте shop_id, курс, комиссию или желаемый финансовый статус в публичном запросе.

Расчёт и резерв

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

principal_usdt = round(amount / rate_fiat_per_usdt, 8)
fee_usdt       = round(principal_usdt × fee_percent / 100, 8)
total_usdt     = principal_usdt + fee_usdt

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

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

HTTP 201 означает, что поручение и резерв сохранены:

{
  "id": "b7a09187-553b-4d11-bc28-a725192653fc",
  "merchant_order_id": "PAYOUT-2026-000042",
  "amount": "15000.00",
  "currency": "RUB",
  "method": "sbp",
  "bank_id": "bank_1",
  "bank_name": "Тестовый банк",
  "recipient": {
    "phone_number": "+79991112233",
    "customer_name": "Тестовый получатель"
  },
  "status": "queued",
  "principal_usdt": "150.00000000",
  "fee_usdt": "3.00000000",
  "total_usdt": "153.00000000",
  "rate_fiat_per_usdt": "100.00000000",
  "fee_percent": "2.00000000",
  "paid_amount": "0.00",
  "remainder": "15000.00",
  "revision": 1,
  "created_at": "2026-10-08T18:00:00Z",
  "updated_at": "2026-10-08T18:00:00Z",
  "metadata": {
    "customer_ref": "customer-42"
  }
}

amount остаётся исходной суммой. paid_amount — сумма подтверждённых успешных частей, remainder — исходная сумма минус оплаченные части. Остаток в этом поле не означает, что сумма доступна для повторной отправки: неотправленные, отказанные и неизвестные части различаются внутренними состояниями. Для следующего действия используйте актуальный статус и сверку с поддержкой.

Статусы и чтение

processing может содержать уже исполненные части: их сумма указана в paid_amount. partial — завершение со смешанным результатом. Перед отдельным поручением на неполученную сумму сверяйте результат; не создавайте его автоматически по одному уведомлению. Внутренние исполнители, терминалы, ключи и доказательства сотрудника не возвращаются публичным API.

GET /api/v2/payouts/b7a09187-553b-4d11-bc28-a725192653fc
GET /api/v2/payouts/result?merchant_order_id=PAYOUT-2026-000042

Оба запроса подписанные, тело пустое. Первый возвращает объект выплаты; второй возвращает результат регистрации номера:

{
  "status": "created",
  "payout": {
    "id": "b7a09187-553b-4d11-bc28-a725192653fc",
    "merchant_order_id": "PAYOUT-2026-000042",
    "amount": "15000.00",
    "currency": "RUB",
    "method": "sbp",
    "bank_id": "bank_1",
    "bank_name": "Тестовый банк",
    "recipient": {
      "phone_number": "+79991112233",
      "customer_name": "Тестовый получатель"
    },
    "status": "queued",
    "principal_usdt": "150.00000000",
    "fee_usdt": "3.00000000",
    "total_usdt": "153.00000000",
    "rate_fiat_per_usdt": "100.00000000",
    "fee_percent": "2.00000000",
    "paid_amount": "0.00",
    "remainder": "15000.00",
    "revision": 1,
    "created_at": "2026-10-08T18:00:00Z",
    "updated_at": "2026-10-08T18:00:00Z",
    "metadata": {}
  }
}

При creating поле payout равно null: номер зарегистрирован, окончательный результат требует проверки. При rejected поле payout равно null, дополнительно возвращается error_code; этот номер также нельзя использовать заново. HTTP 404 означает, что запись не найдена в вашем магазине; при потерянном ответе на создание сначала повторите чтение с новой подписью и свяжитесь с поддержкой, не создавая другое поручение автоматически.

Повторы и изменение поручения

merchant_order_id резервируется постоянно после принятия корректного запроса. Параллельные и повторные POST с тем же номером не создают новый резерв; ответ — HTTP 409 duplicate_merchant_order_id. Другой магазин имеет отдельное пространство номеров.

После тайм-аута, обрыва ответа или 5xx обращайтесь к /payouts/result с тем же номером и новыми X-Timestamp/X-Nonce/X-Signature. Если запись остаётся creating, требуется разбор, а не новая отправка. При подтверждённом rejected исправленное поручение требует нового согласованного номера.

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

GET /api/v2/balance

Подписанный запрос без тела и параметров возвращает USDT-баланс магазина, которому принадлежит API-токен:

{
  "currency": "USDT",
  "available": "847.00000000",
  "reserved": "153.00000000",
  "total": "1000.00000000"
}

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

Уведомления о выплатах

Payout webhook — отдельный JSON-формат с типом payout.updated. Подпись: HMAC-SHA512 от X-Webhook-Timestamp + "." + сырые байты тела, тот же алгоритм проверки, что у уведомлений приёма. Не используйте SHA512 от склеенных сортированных полей.

{
  "event_id": "836b36d7-bcec-4652-b512-6b53bf9c5721",
  "event_type": "payout.updated",
  "revision": 2,
  "payout_id": "b7a09187-553b-4d11-bc28-a725192653fc",
  "merchant_order_id": "PAYOUT-2026-000042",
  "status": "processing",
  "amount": "15000.00",
  "currency": "RUB",
  "paid_amount": "0.00",
  "remainder": "15000.00",
  "principal_usdt": "150.00000000",
  "fee_usdt": "3.00000000",
  "updated_at": "2026-10-08T18:01:00Z"
}

1. Проверьте подпись по сырым байтам и свежесть заголовка, затем форму сообщения.
2. В одной транзакции сохраните event_id, примените только новую revision для этого поручения и зафиксируйте свой эффект. Повторный event_id не исполняйте второй раз.
3. Ответьте HTTP 200 после надёжного сохранения. Тело 1 не требуется. Ответы 201/202/204 не подтверждают доставку.

Доставка выполняется как минимум один раз. При потере HTTP-ответа платформа может повторить уже принятую вами запись. Повтор сохраняет event_id и байты тела; подпись и timestamp обновляются для текущей попытки. Не используйте updated_at как ключ дедупликации.

Всего до восьми попыток. Интервалы после неуспеха: 5 секунд, 30 секунд, 2 минуты, 10 минут, 30 минут, 2 часа, 12 часов. После исчерпания попыток сверяйте статус через GET. Работает отдельный worker с MERCHANT_WEBHOOKS_ENABLED=true; наличие URL без запущенного worker не обеспечивает доставку. Ошибка уведомления не меняет выплату и не освобождает резерв.

Дата API — ISO 8601 с часовым поясом; сравнивайте абсолютные моменты. Представление времени в кабинете — московское, независимо от часового пояса браузера.

Доступность первой версии

Рабочий серверный цикл включает создание, резервирование, чтение, разделение до отправки и ручное подтверждение/отказ с аудитом. Исполняемые автоматические подключения пока только тестовые: внесение реального токена в терминал само по себе не подключает шлюз. Перед запуском согласуйте фактический исполнительный адаптер, проверки его результата и доступность worker; тестовое подключение не перечисляет деньги.

node examples/client.mjs balance
node examples/client.mjs payout-create --body examples/create-payout.json
node examples/client.mjs payout-result 'PAYOUT-2026-000042'
node examples/client.mjs payout-get 'b7a09187-553b-4d11-bc28-a725192653fc'

Уведомления о платежах

Absolut Pay отправляет webhook на ваш сервер после изменения статуса сформированного платежа. Уведомление позволяет надёжно обновить заказ в вашей системе; переход браузера и нажатие плательщиком «Я оплатил» не заменяют подтверждённый результат.

Payin API v2 и Merchant Webhook v1 — два разных формата. Запросы API используют merchant_order_id, method_id и даты ISO 8601. Уведомления сохраняют clientOrderID, methodID и Unix-время. Версия webhook не означает наличие платёжных маршрутов /api/v1.

В текущем локальном sandbox тестовые платежи помечены is_test: true: их события сохраняются без внешней доставки и без финансовых зачислений. Отсутствие webhook в таком тесте ожидаемо. Доставку на ваш адрес и рабочее подключение нужно подтвердить отдельно; этот документ описывает реализованный протокол уведомлений, а не активацию production.

Адрес доставки

Укажите HTTPS-адрес в webhook_url при создании платежа или настройте адрес по умолчанию для магазина. Адрес из запроса имеет приоритет. Система сохраняет выбранный адрес для заявки; последующее изменение настроек магазина не меняет адрес старой заявки.

Если адрес отсутствует в обоих местах, создание завершается ошибкой webhook_required до формирования платежа. Его merchant_order_id остаётся зарезервированным. У такого отказа нет сформированного платежа и webhook о его отмене.

Приёмник должен быть доступен по публичному HTTPS-адресу с действительным TLS-сертификатом. Перенаправления не выполняются. Private, loopback, link-local и служебные сетевые адреса для доставки запрещены. Адрес для webhook — серверный обработчик, а не страница возврата браузера.

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

POST /payments/absolut-pay/webhook HTTP/1.1
Content-Type: application/json
X-Webhook-Timestamp: UNIX_SECONDS
X-Webhook-Signature: LOWERCASE_HMAC_SHA512_HEX

Значения UNIX_SECONDS и LOWERCASE_HMAC_SHA512_HEX — обозначения для примера. Подпись проверяется по формуле:

canonical_bytes = timestamp + "." + raw_body
expected_signature = lowercase_hex(HMAC_SHA512(api_secret, canonical_bytes))

Используется буквальная строка секрета API соответствующего магазина; декодировать её из Base64/Base64URL не нужно. Отдельный webhook-secret не выдаётся. В подпись не входят метод, путь, nonce или токен API. Заголовки X-API-Token и X-Nonce в уведомлении не передаются.

Проверьте подпись до доверенного использования JSON. Получите точные исходные байты тела, добавьте к ним строку timestamp и точку, вычислите HMAC и сравните подписи способом с постоянным временем. Повторная JSON-сериализация после разбора тела не подходит: пробелы и порядок полей могут измениться.

Для вашего приёмника рекомендуем проверку свежести X-Webhook-Timestamp в пределах ±300 секунд и синхронизацию времени. Это рекомендуемая защита на вашей стороне: Absolut Pay не настраивает допустимое окно в вашем приложении. Timestamp относится к конкретной попытке доставки. Старый платёж может иметь старые createdAt и paidAt, но свежее время и подпись уведомления.

Свежесть и подпись не заменяют защиту от дублирования: корректно подписанное уведомление может прийти повторно.

Поля уведомления

Текущий протокол отправляет события успеха, истечения срока и отмены. Webhook о создании со статусом 1 не отправляется. Публичного event_id в теле нет. Не ожидайте реквизитов, данных плательщика или текущего баланса в этом сообщении.

Суммы, курс и комиссия передаются строками, чтобы сохранить точность. Не преобразуйте их через обычные дробные числа с плавающей точкой. Unix-время означает момент независимо от часового пояса; переводите его для отображения, сохраняя исходное значение.

amount — исходная сумма заказа, а successPaid — фактически подтверждённая оплаченная сумма. Автоматический callback провайдера требует численного совпадения с исходной суммой: "15000" и "15000.00" означают одну сумму; расхождение само по себе не создаёт успешного зачисления. Уполномоченный сотрудник может отдельно подтвердить другую фактическую сумму с доказательством и аудитом. Тогда amount сохраняется, а successPaid может отличаться; начисление рассчитывается по замороженным курсу и комиссии этой заявки, без применения текущих настроек и без повторного зачисления. Это не автоматическая поддержка произвольной частичной оплаты. При расхождении сохраните обе суммы и проверьте результат через API и поддержку; не подменяйте successPaid исходным amount.

Подтверждённая оплата

Пример структуры уведомления, не свидетельство реального платежа:

{
  "id": "ord_10428",
  "orderType": "payin",
  "status_id": 2,
  "amount": "15000.00",
  "successPaid": "15000.00",
  "currency": "RUB",
  "methodID": 1,
  "rate": "100.00",
  "fee": "2.00",
  "clientOrderID": "invoice-10428",
  "createdAt": 1791460800,
  "expiredAt": 1791461400,
  "paidAt": 1791460920
}

Для status_id: 3 поля successPaid и paidAt отсутствуют. Для status_id: 4 они также отсутствуют, но добавляется closeReason, например merchant_cancelled. Не ожидайте нулевых значений вместо отсутствующих полей.

Надёжный приём

Обрабатывайте уведомление в таком порядке:

1. Выберите секрет магазина по серверной конфигурации своего обработчика. Не определяйте секрет по непроверенным данным платежа.
2. Проверьте заголовки, допустимое время и подпись исходных байтов.
3. Разберите JSON и сверьте id, clientOrderID, валюту и сумму с сохранённым заказом.
4. В транзакции запишите событие с уникальным ключом (id, status_id). При общем обработчике нескольких магазинов добавьте идентификатор магазина в локальный ключ и проверьте область доступа.
5. Обновите состояние заказа и сохраните необходимую внутреннюю задачу на выдачу товара или услуги.
6. Зафиксируйте транзакцию и верните HTTP 200.

Корректный повтор уже сохранённого события также подтверждайте HTTP 200, не выполняя выдачу повторно. Не используйте timestamp или подпись как ключ события: на повторной попытке они изменяются.

Если выдача услуги требует обращения к другой системе, сохраните внутреннюю задачу вместе с событием и выполняйте её отдельно с защитой от повторов. HTTP 200 нужно отправлять после надёжного сохранения, а не после долгой внешней операции. Если запись не завершена или данные противоречат заказу, не подтверждайте успешный приём; сохраните безопасную диагностическую информацию для сверки.

Поздняя оплата и порядок событий

Срок мог истечь, а провайдер позже подтвердил оплату: тогда после 3 может прийти 2. Подтверждённая оплата также может следовать после отмены с причиной client_declined, merchant_cancelled или admin_cancelled. Отмена уже выданной заявки не доказывает, что деньги не поступят позже.

Обрабатывайте первую подтверждённую оплату один раз. Принятый успех 2 нельзя понизить до 3 или 4 из-за запоздавшего сообщения. Уведомление об истечении срока и уведомление об успехе — отдельные события одной заявки; поэтому дедупликация только по id без статуса ошибочно потеряет поздний успех.

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

Подтверждение и повторные попытки

Доставка считается успешной только при HTTP 200. Тело ответа не учитывается. 201, 202, 204, редирект и любой другой код не подтверждают доставку. На один запрос отведено 2 секунды.

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

Во всех попытках тело и адрес остаются прежними; timestamp и подпись формируются заново. Доставка допускает повторы: даже после сохранённого вами события ответ HTTP 200 может потеряться. После пяти неудачных попыток автоматическая доставка считается исчерпанной. Ошибка уведомления не отменяет оплату и не откатывает финансовый результат.

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

Ротация секрета

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

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

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

Ошибки: что произошло и что делать

Ошибка HTTP возвращается в общей оболочке:

{"error":{"code":"authentication_failed","message":"Authentication failed."},"request_id":"example-request-id"}

Обрабатывайте error.code, а не английский message. request_id нужен поддержке; это не номер платежа и не ключ идемпотентности. Все повторы подписывайте заново: новые timestamp, nonce и signature, те же согласованные байты бизнес-запроса.

Справочник errors.json содержит те же объяснения. HTTP 200 в таблице означает вложенный error_code результата lookup, а не ошибку HTTP. У приёма он появляется при state: failed, у выплаты — при status: rejected. processing/creating и review_required требуют дальнейшего чтения или сверки; HTTP 200 сам по себе не означает оплату.

Доступ и формат запроса

Поиск и конфликт номера

Условия и отказ формирования

Неизвестный результат и восстановление

Потерян ответ POST: безопасный порядок

1. Сохраните исходный merchant_order_id, направление, магазин и время попытки.
2. Выполните соответствующий подписанный GET /api/v2/payins/result?merchant_order_id=... или /api/v2/payouts/result?merchant_order_id=....
3. Если запрос ещё обрабатывается, продолжайте чтение с задержкой. При требовании сверки обратитесь в поддержку. Один 404 не исключает гонку с незавершённым первым запросом.
4. Если заявка найдена, обрабатывайте её состояние однократно вместе с webhook. Создание заявки не означает оплату.
5. При окончательном отказе номер остаётся занят. Новый номер означает новое бизнес-действие, а не транспортный retry: его нельзя назначать автоматически, пока исход прежнего запроса не установлен.

Отключите автоматический retry POST в HTTP-клиенте и балансировщике. Здесь нет обещания универсального интервала polling или Retry-After: используйте согласованные ограничения окружения. Если ответ не соответствует JSON-оболочке (например, ответ внешнего proxy), сохраните безопасные HTTP-метаданные и действуйте как при неизвестном исходе; не придумывайте error.code.

Если подпись не проходит

Используйте secret как выданную строку без декодирования. Подписывайте METHOD в верхнем регистре, path/query без hostname, с неизменными порядком query и percent-encoding. JSON должен уйти ровно теми байтами, которые подписаны, включая пробелы и конечный LF. Для GET тело пустое, последний разделитель LF сохраняется. Проверьте часы и UUID v4; принятый nonce нельзя использовать повторно. Внутренние причины вроде invalid_nonce не публикуются как отдельные коды: снаружи это authentication_failed.

Если webhook не приходит

Неоплаченная заявка и отсутствие уведомления — разные факты. В текущем тестовом приёме доставка merchant webhook не выполняется. В окружении с доставкой проверьте публичный HTTPS URL, сертификат/DNS, отсутствие редиректа и ответ именно HTTP 200 за отведённое время. Не размещайте получатель на localhost или частном IP. После исчерпания попыток сверяйте результат через API.

Подпись входящего webhook отличается от подписи запроса API. Проверяйте исходное тело безопасным сравнением и объединяйте webhook с polling через однократное бизнес-действие.

Данные для поддержки

Передавайте request_id, направление, безопасное имя маршрута, HTTP/code, время и ваш номер заказа. Не отправляйте secret, заголовки авторизации, полные тела с персональными данными или capability-ссылки в общие логи.

Каталог ограничен Merchant API. Коды административных операций с исполнителями, ручной проверкой доказательств, ревизиями и экспортом сюда не перенесены. Внутренние причины live_adapter_required и provider_reconciliation_required скрыты lookup приёма: клиент получает state: review_required без этих кодов.

Публичная платёжная форма и H2H

Режим h2h возвращает реквизиты в requisite, режим payment_form — полный payment_url. Выбор режима не подтверждает деньги и не создаёт второй платёж. Текущий контур приёма возвращает неплатёжные mock-реквизиты.

Каноническая ссылка

Сервер выдаёт полный URL существующей заявки с публичным токеном /p/{token}. Токен отличается от внутреннего ID. Не собирайте адрес из домена документации, API, admin или id. Открытие и повторное открытие ссылки не создают заявку.

Не передавайте capability-ссылку в аналитику, Referer, общие логи или службы сокращения ссылок. Для новой вкладки используйте rel="noopener noreferrer". Не размещайте API-ключи в платёжной форме.

Состояния и реквизиты

Срок не вычисляется заново при открытии. Банковские сведения в ответе приёма описывают выданные реквизиты; они не превращают bank_id в поле создания приёма.

Обработчик hosted form поддерживает «Я оплатил» и загрузку чека, если действия разрешены сохранёнными настройками заявки и форма включена в окружении. Исторические настройки выключают оба действия. Они сохраняют свидетельство плательщика, но не меняют статус оплаты, срок, Ledger, баланс или очередь уведомлений мерчанта. Сервер проверяет исходный срок, состояние и CSRF; точный повтор уже принятого свидетельства не создаёт вторую запись. Фактическое включение формы и действий в production здесь не проверено. Сохранённые redirect_urls не означают автоматический переход текущей формы. Только проверенный API/webhook и однократное бизнес-действие мерчанта завершают интеграцию.

Получить баланс и показать его клиенту

Absolut Pay передаёт мерчанту баланс его магазина через GET /api/v2/balance. Мерчант может получить эти данные на своём сервере и показать их уполномоченному пользователю своего кабинета. Это передача информации об остатке, а не перевод средств.

Под «клиентом» в этом сценарии понимается мерчант или пользователь его кабинета с правом видеть баланс магазина. Этот endpoint не возвращает личный кошелёк плательщика и не вычисляет баланс конкретного payer.id. Если вашему продукту нужен баланс конечного покупателя, он ведётся в вашей системе отдельно; общий остаток магазина нельзя выдавать за его личный баланс.

Что мы возвращаем

Запрос читает один магазин по проверенному API-токену, а не все магазины мерчанта. В запросе нет shop_id, payer_id, currency или других query-параметров. Тело пустое, запрос подписывается четырьмя стандартными заголовками.

GET /api/v2/balance
X-API-Token: <токен магазина>
X-Timestamp: <Unix-секунды>
X-Nonce: <новый UUID v4>
X-Signature: <подпись точного запроса>

Пример успешного ответа — HTTP 200:

{
  "currency": "USDT",
  "available": "847.00000000",
  "reserved": "153.00000000",
  "total": "1000.00000000"
}

Все три суммы имеют 8 знаков после точки. Сохраняйте исходные строки; форматируйте для отображения средствами точной десятичной арифметики. Не складывайте available и total: резерв уже входит в total. Запрос не изменяет деньги и не резервирует средства.

Как передать баланс в свой кабинет

Пользователь кабинета мерчанта
    → ваш backend: вход и проверка права на магазин
    → Absolut Pay: подписанный GET /api/v2/balance
    → ваш backend: проверка ответа и выбор публичных полей
    → кабинет: available / reserved / total / USDT

1. На вашем backend сохраните выданные API origin, token и secret магазина. Ключи не передаются в браузер, мобильное приложение, Telegram WebView или публичную платёжную форму.
2. При открытии страницы баланса проверьте вход пользователя и его право видеть конкретный магазин. Связь «пользователь → магазин → ключи» определяется вашим сервером; не выбирайте произвольные ключи по неподтверждённому ID из браузера.
3. Ваш сервер формирует подписанный GET без тела, получает HTTP 200 и проверяет типы полей. Для каждого запроса используйте новые timestamp, nonce и signature.
4. Передайте в свой frontend только currency, available, reserved, total. Не передавайте токен, секрет и подписанные заголовки. Если у пользователя нет права на общий баланс магазина, не отдавайте эти данные.
5. Покажите три значения с разными подписями. Защитите собственный ответ от общего кэширования, например Cache-Control: private, no-store; общий CDN-кэш между клиентами недопустим.

Собственный маршрут вашего кабинета, его авторизация и оформление реализуются у мерчанта. Они не являются дополнительными маршрутами Merchant API Absolut Pay. Для нескольких магазинов используются их отдельные ключи и отдельные запросы; этот endpoint не возвращает агрегат по всем магазинам.

Быстрая проверка с сервера

Используйте скачиваемый клиент Node.js. Задайте ABSOLUT_API_BASE_URL, ABSOLUT_API_TOKEN, ABSOLUT_API_SECRET в серверном окружении и выполните:

node examples/client.mjs balance

Клиент выполняет подписанный GET и выводит HTTP-статус и ответ. Не публикуйте финансовые данные или ключи в общих логах. Описание операции и её ошибок · Подпись запросов.

Пример функции для вашего backend

Пример Node.js 20+ использует prepareRequest из client.mjs. Сохраните функцию рядом с этим файлом. Вызывайте её только после проверки вашей пользовательской сессии и права на магазин. В credentials передавайте конфигурацию из серверного хранилища, а не входной JSON клиента.

import { randomUUID } from 'node:crypto';
import { prepareRequest } from './client.mjs';

export async function readShopBalance(credentials) {
  const request = prepareRequest({
    baseUrl: credentials.baseUrl,
    token: credentials.token,
    secret: credentials.secret,
    method: 'GET',
    target: '/api/v2/balance',
    rawBody: Buffer.alloc(0),
    timestamp: String(Math.floor(Date.now() / 1000)),
    nonce: randomUUID(),
  });

  const response = await fetch(request.url, {
    ...request.options,
    signal: AbortSignal.timeout(10000),
  });
  if (!response.ok) {
    // Не возвращайте клиенту подписанные заголовки или секреты.
    throw new Error('Balance is temporarily unavailable');
  }

  const data = await response.json();
  const decimal = /^(0|[1-9][0-9]*)\.[0-9]{8}$/;
  if (data?.currency !== 'USDT' ||
      !['available', 'reserved', 'total'].every(
        key => typeof data[key] === 'string' && decimal.test(data[key])
      )) {
    throw new Error('Unexpected balance response');
  }

  // Только эти поля передаются авторизованному frontend.
  return {
    currency: data.currency,
    available: data.available,
    reserved: data.reserved,
    total: data.total,
  };
}

Тайм-аут 10 секунд в примере — выбранный лимит вашего клиента, не обещание SLA Absolut Pay. Обработчик вашего приложения должен перехватить ошибку и вернуть безопасное сообщение. Не заменяйте ошибку нулевым балансом.

Когда обновлять баланс

Получайте баланс при открытии раздела и по действию «Обновить». После подтверждённого события приёма/выплаты можно повторно прочитать баланс, но не рассчитывайте актуальный остаток простым прибавлением суммы из webhook: существуют комиссии, резервы и другие операции.

Отдельного webhook «баланс изменился» в текущем Merchant API нет. Уведомления приёма и выплат не содержат полный снимок баланса. Если нужен фоновый polling, согласуйте частоту для своего окружения; фиксированного общего интервала или квоты документация не обещает.

В ответе Absolut Pay нет updated_at или времени снимка. Метку «Получено в…» формирует ваш backend; она означает время получения ответа, а не время последней денежной операции. Не добавляйте её в наш контракт как якобы существующее поле.

Можно ли на основании баланса отправлять выплату

available помогает отобразить доступные средства, но не гарантирует следующую выплату: между GET и POST остаток мог измениться. Сравнивайте с полной стоимостью выплаты в USDT, а не с суммой клиента в RUB/KZT/другой валюте. Окончательную проверку средств и резервирование сервер выполняет атомарно при создании выплаты.

При insufficient_funds не переотправляйте POST автоматически. Проверяйте сохранённый результат поручения и правила ошибок. При неизвестном результате выплаты сначала выполните её lookup; новое чтение баланса само по себе не доказывает исход конкретного перевода.

Направление курса

Приём: rate — единицы исходной валюты за 1 USDT; fee — проценты. Условия фиксируются при выдаче реквизитов и не берутся из новых настроек при подтверждении. Исходный amount и подтверждённый success_paid сохраняются отдельно; webhook использует имя successPaid.

Выплата: rate_fiat_per_usdt — единицы валюты получателя за 1 USDT. principal_usdt, fee_usdt и total_usdt возвращают сохранённые суммы учёта; комиссия выплаты добавляется к основной стоимости. Резерв при неопределённом результате не означает списание без подтверждения и не освобождается по timeout клиента.

Деньги и курсы храните точными decimal-строками или Decimal. Не используйте JavaScript Number / binary float для денежных итогов. Суммы USDT учитываются с точностью 8 знаков. Не пересчитывайте серверный резерв по текущему курсу.

Рыночный курс для нового формирования проверяется на свежесть: основной до 60 секунд, fallback до 300 секунд того же провайдера, будущее наблюдение не более 30 секунд. Договорной фиксированный курс терминала имеет отдельные правила. Эти проверки не меняют условия уже сформированной заявки.

Трансграничный перевод

Проектируемая возможность. «Трансграничный перевод» (cross_border) получает согласованный числовой method_id: 5 как отдельный метод. ID закреплён в проекте контракта; серверная поддержка ещё не реализована. Метод пока не принимается рабочим Merchant API. Наличие UZS в enum не означает доступность RU → UZ. Не добавляйте предлагаемые поля в запросы приёма или выплат.

Например, отправитель в России платит RUB, а получатель в Узбекистане получает UZS. Это две отдельные суммы и валюты. Сначала определяется направление операции Absolut Pay — приём или выплата, затем способ доставки: карта, счёт, телефон и платёжная система. Отдельный метод трансграничного перевода сохраняет детализацию доставки: rail, тип реквизита и платёжная система передаются отдельно в предлагаемой модели.

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

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

Проверка перед запуском

Документация описывает контракт. Включение реальных платежей требует подтверждённого окружения, ключей и методов магазина. Текущий локальный mock не является доказательством реальной интеграции провайдера.

Контрольные сценарии

Для локального контура проверки webhook выполняются подписанными fixtures/примером приёмника. Фактическую доставку, живые реквизиты, финансовое зачисление и провайдерскую сверку проверяют отдельно после подключения соответствующего окружения. Не отмечайте их выполненными только по локальному mock.

Ваш сервер

• API token и secret доступны только backend; шифрование/хранилище секретов и контроль доступа настроены.
• Исходящие IP согласованы, часы синхронизированы.
• JSON подписывается и отправляется одними байтами, query не перестраивается после подписи.
• Суммы хранятся точно; ответ API и исходный номер сохраняются устойчиво.
• Webhook проверяется до применения, подтверждается после надёжного сохранения, бизнес-эффект защищён транзакцией/очередью.
• Все источники результата используют одно правило однократного исполнения: webhook, polling, ручная сверка.
• Есть очередь/задача сверки неопределённых запросов, оповещение о длительном ожидании и согласованный контакт поддержки.
• Логи и мониторинг не раскрывают секреты, реквизиты, персональные данные и платёжные capability-ссылки.

Согласовать до реального включения

Адрес и версия API, разрешённые методы/валюты/режимы/трафик, тариф, лимиты и допустимый опрос, webhook/ротация ключей, тестовые сценарии и контакт поддержки. Документация не обещает конкретный SLA, квоты, автоматические возвраты или сроки поддержки, пока они не выданы отдельно. Если вам нужна обработка неполной или избыточной оплаты, согласуйте отдельный процесс: в текущий контракт он не входит.

Выплаты клиентам и чтение баланса магазина входят в API v2; их маршруты, резервирование и статусы описаны в разделе «Выплаты клиентам». Реальная отправка провайдеру требует отдельного подключения и проверки. Сетлы, отчётные API, апелляции и публичная отмена не представлены как доступные операции этого контракта. Получение «Я оплатил», файла чека или браузерного redirect не подтверждает оплату в вашей системе.

Дополнительные проверки выплат

• Отдельные курс и комиссия активированы для согласованного метода и валюты.
• bank_id взят из активного справочника этого окружения; телефон, карта и счёт не смешиваются.
• Создание резервирует основную сумму USDT и комиссию; повтор номера не создаёт нового резерва.
• Тайм-аут POST восстанавливается через GET результата, без повторной отправки.
• Неопределённое исполнение удерживает резерв; отменяется только неотправленная часть.
• Для ручного успеха сохранены фактическая сумма, валюта, доказательство и уникальный номер перевода.
• Worker доставки включён; приёмник проверяет event_id и revision и подтверждает HTTP 200 после сохранения.
• Реальный провайдер проверен отдельно; тестовый адаптер не выполняет переводов.

Версии и материалы интеграции

25 октября 2026 · документация 2.4.0

База реализации 82b3e33: денежная цепочка 5514c2c и аудит безопасности. Портал не меняет серверный контракт. Приёмка выпуска по CI и проверки реальных провайдеров остаются отдельными условиями запуска.

Комплект содержит реализованный OpenAPI с подтверждённым API origin https://api.absolutpay.com в servers, Postman collection/environment с пустыми ключами и серверные примеры Node.js/Python. Остальные поля OpenAPI совпадают с серверным контрактом. Доступность бизнес-операций не подтверждена; проверенные GET банков и баланса возвращают 503. Версия OpenAPI сохраняется как в источнике; версия документации не повышает версию API.

• OpenAPI
• Postman collection
• Postman environment
• Node.js
• Python
• Матрица возможностей
• Проект трансграничной модели
• Окружение и API base URL

Исторические материалы

Маршруты и примеры старого v1-портала не относятся к текущему Merchant API. Внешние руководства использованы для сравнения полноты; их авторизация, банковские коды и денежные единицы не заменяют Absolut Pay.

Работа с Postman

Используйте локальное desktop-окружение с синтетическими ключами и изолированным API. Не сохраняйте реальные ключи в экспортируемом environment или облачной коллекции. Портал не принимает ключи, не выполняет запросы к API и не хранит секреты в браузере. Отправка POST всегда явная; после неизвестного результата используйте lookup с тем же номером заказа.

Техническое сравнение с внешними API

Это сравнительный обзор для планирования интеграции, а не список доступных операций Absolut Pay. Наличие функции в чужой документации не разрешает отправлять её поля или маршруты в наш API. Изменения денежного контракта требуют отдельного согласования.

Сверка выполнена 18.10.2026 по PDF «Руководство по интеграции v5.3.pdf» (32 физические страницы), BasicPay ReDoc и Postman Main API Collection. На странице BasicPay заголовок API — Xpay Merchant API 1.27.3; Postman показывает Main API Collection. Принадлежность этих источников и PDF к Euphoria не подтверждена их прочитанным содержимым, поэтому ниже они названы по наблюдаемым названиям. Euphoria не исключена из ориентиров; нельзя приписывать ей возможности другого источника без подтверждения.

Подтверждённые технические пробелы

Видимые внешние разделы, требующие дополнительной сверки

В навигации Xpay также видны Transactions, P2P, C2C, Deposit, Withdraw, Widgets, Data и Attachments, а в документации — Authentication, Data Types, Webhooks и Testing. Название раздела само по себе не определяет его полный денежный смысл. Поэтому мы не называем Widgets эквивалентом нашей hosted form, Data — capability discovery, а Deposit/Withdraw — физическим переводом активов без чтения конкретного контракта.

В Postman прочитан вводный контракт, таблица ошибок и примеры callback; полный набор операций в этой сверке не извлечён. Видны статусы created, pending, dispute, in_check, finished, canceled, expired, failed и ошибки invalid orderId, no requisites, method/currency, insufficient funds, processing, duplicate. Это подтверждает структуру описания жизненного цикла и ошибок, но не доказывает отсутствия аналогичной возможности у нас только из-за другого названия статуса.

Различия, которые не являются пробелами

Предлагаемый порядок работ

Сначала подтвердить рабочие окружения, реального провайдера и тестовый end-to-end цикл текущего API. Затем согласовать необходимые мерчанту статистику и диагностику webhook, redirects и способы приёма. Публичные споры/тикеты и трансграничные переводы оформить отдельными проектами с финансовыми правилами. Эта последовательность — предложение для приоритизации, не утверждённый план серверных изменений.

Детальные источники, контрольные суммы и выявленные расхождения зафиксированы в отдельной таблице сверки, переданной владельцу портала. Список ранее исключённых пользователем разделов PDF остаётся неподтверждённым: перечисление чужих возможностей здесь не означает их включения в объём реализации.