Matching

Что такое matching

matching — это специальный сценарий, в котором мерчант заранее создаёт спрос на выплату, а затем этот спрос закрывается входящими invoice pay-in сделками.

С точки зрения интеграции это не отдельный новый API-домен, а orchestration flow поверх уже существующих endpoint-ов pay-out, pay-in и public invoice confirmation.

Какие endpoint-ы используются

В matching flow участвуют следующие endpoint-ы:

Создание matching-заявки:

POST /payment/pay-out

Наполнение matching-заявки invoice-платежами:

POST /payment/pay-in

Загрузка чека / подтверждения оплаты для invoice pay-in:

POST /file/trading/pay-in/invoice/upload/public?tradeId={tradeId}

Подтверждение оплаты на payment page:

POST /payment/public/{id}/confirm

Шаг 1. Создание matching-заявки

Для создания matching используется стандартный endpoint:

POST /payment/pay-out

Чтобы создать не обычную pay-out сделку, а matching-заявку, нужно передать:

isMatching: true
merchantTransactionId
при необходимости отдельный matchingTransactionId
payout-реквизиты в requisite

Если matchingTransactionId не передан, система использует merchantTransactionId как внешний идентификатор matching-заявки.

Как определяется метод matching

Поле method явно не передаётся.
Метод вычисляется автоматически по реквизитам:

requisite.sbpNumber -> sbp_invoice
requisite.cardNumber -> c2c_invoice

Пример создания matching

POST /payment/pay-out
Host: backend.ohlapay.io
Content-Type: application/json
x-signature: <signature>

{
  "amount": 15000,
  "merchantTransactionId": "txn_matching_001",
  "matchingTransactionId": "matching_001",
  "isMatching": true,
  "callbackUrl": "https://merchant.example/callback",
  "requisite": {
    "sbpNumber": "79991234567",
    "bank": "SBER",
    "ownerName": "Ivan Ivanov"
  }
}

Что происходит после создания

обычная pay-out сделка не создаётся;
создаётся сущность matching;
в ответ возвращается объект, совместимый с payout response;
matching ждёт входящие invoice pay-in сделки;
если matching не наполнится вовремя, система может создать fallback pay-out.

Шаг 2. Наполнение matching-заявки

Для наполнения matching используется стандартный endpoint:

POST /payment/pay-in

Чтобы запрос участвовал в matching flow, нужно передать один из invoice-методов:

c2c_invoice
sbp_invoice

Как работает привязка

Backend автоматически:

ищет подходящую открытую matching-заявку у мерчанта;
проверяет совместимость метода;
если matching найден, создаёт matching-backed pay-in;
если matching не найден, переводит запрос в обычный pay-in flow.

Матрица совместимости методов

sbp_invoice ищет matching по sbp / sbp_invoice
c2c_invoice ищет matching по c2c / c2c_invoice

Пример запроса на наполнение matching

POST /payment/pay-in
Host: backend.ohlapay.io
Content-Type: application/json
x-signature: <signature>

{
  "amount": 5000,
  "method": "sbp_invoice",
  "merchantTransactionId": "txn_payin_001",
  "payerInfo": {
    "ip": "127.0.0.1",
    "userId": "1",
    "userAgent": "Chrome/5.0",
    "fingerprint": "fbb77b9f4265b18538e66cac5a37c6410dc2cdd7f0cddfde6eda25aa10df669b",
    "registeredAt": "1728388185326"
  }
}

Шаг 3. Подтверждение invoice после выдачи реквизитов

После создания invoice pay-in клиент должен подтвердить оплату через payment page flow.

3.1 Загрузка чека

POST /file/trading/pay-in/invoice/upload/public?tradeId={tradeId}

Этот endpoint возвращает uploadMetaKey.

3.2 Подтверждение оплаты

POST /payment/public/{id}/confirm

В body подтверждения передаётся uploadMetaKey, полученный после загрузки файла.

Именно этот шаг завершает пользовательскую часть invoice flow и переводит сделку в дальнейшую обработку.

Fallback-поведение

В matching flow используются два разных fallback-механизма.

Request-time fallback

Если POST /payment/pay-in пришёл с методом c2c_invoice или sbp_invoice, но подходящая matching-заявка не найдена, система не обязана возвращать ошибку.
Она может автоматически переключить запрос в обычный pay-in:

sbp_invoice -> sbp
c2c_invoice -> c2c

SLA fallback для matching

Если matching был создан, но не был полностью наполнен за допустимое время, система может автоматически создать fallback pay-out на остаток суммы.

Это выполняется фоновым процессом и не требует отдельного API-вызова со стороны мерчанта.

Что важно учесть при интеграции

Matching не является отдельным REST-ресурсом с собственным create endpoint.
Создание matching выполняется через POST /payment/pay-out.
Наполнение matching выполняется через POST /payment/pay-in.
Для invoice flow нужно учитывать не только создание pay-in, но и дальнейшие шаги upload + confirm.
Для matching рекомендуется всегда передавать отдельный matchingTransactionId.
matchingTransactionId должен быть уникален в рамках мерчанта.

Postman коллекция

Для быстрого прогона matching flow доступна готовая Postman-коллекция:

Скачать Postman collection

Коллекция покрывает следующие шаги:

Создание matching через POST /payment/pay-out с isMatching=true
Создание invoice pay-in через POST /payment/pay-in
Отмена pay-in
Продление таймера pay-in
Загрузка чека через merchant-auth endpoint
Подтверждение чека через public payment page endpoint

Что нужно заполнить перед запуском

baseUrl — базовый URL API
secureKey — merchant API key
receiptFile — абсолютный путь к файлу чека на вашей машине
callbackUrl — URL для webhook-уведомлений, если вы хотите проверить callback flow

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

Как запускать

Коллекцию нужно выполнять последовательно сверху вниз, потому что следующие шаги используют значения, полученные на предыдущих запросах:

matchingId
payInTradeId
publicTradeId
uploadMetaKey