Приём платежей (Pay-In)

Общая концепция Pay-In

Механизм Pay-In предназначен для приёма фиатных средств от ваших клиентов с последующим зачислением средств на ваш баланс.
Данный процесс позволяет автоматизировать платёжные операции и обеспечить стабильный приём оплат в рамках вашей бизнес-логики.

Каждая операция Pay-In создаётся через API и далее проходит ряд последовательных состояний до финального результата.

Жизненный цикл Pay-In операции

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

Основные статусы

`active`

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

`success`

Оплата успешно завершена.
Средства получены и зачислены.
Операция считается полностью выполненной.

`canceled`

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

`dispute`

По операции инициирован спор.
Обычно возникает при предоставлении подтверждения оплаты клиентом.
Заявка передаётся на рассмотрение.

`success_changed`

Спор успешно разрешён.
Итоговая сумма операции скорректирована с учётом фактического платежа.
Далее операция переходит к финализации.

Создание Pay-In транзакции

Для создания платёжной заявки используется API-метод:

POST /payment/pay-in

При создании необходимо указать точную сумму amount,

В ответ система возвращает:

рассчитанную сумму в криптовалюте;
платёжные реквизиты;
текущий курс;
размер комиссии мерчанта.

Matching

Для сценария matching в спецификации вынесена отдельная страница:

Matching

Если вам нужно наполнить matching-заявку, используйте стандартный POST /payment/pay-in с методом c2c_invoice или sbp_invoice. Полный flow выбора matching, invoice confirmation и fallback-поведения описан на отдельной странице.

Выбор банка и платёжных реквизитов

Если параметр bank не указан, система автоматически подберёт доступный банк.
Если параметр bank указан, реквизиты будут предоставлены именно по выбранному банку.

Список доступных банков можно получить через отдельный API-метод.

Пример запроса на создание Pay-In

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

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

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

{
    "id": "45450d2a-e352-439d-9886-134f27c54750",
    "merchantTransactionId": "1254453",
    "amount": "5000.00",
    "crypto": "61865875",
    "rate": "80.82",
    "fee": "4330612",
    "type": "pay-in",
    "method": "c2c",
    "status": "active",
    "requisite": {
        "id": "8d920c8f-ca6d-4a69-ada0-fe7f43db286c",
        "bank": "ATB",
        "link": null,
        "currency": "RUB",
        "ownerName": "qweqwe",
        "sbpNumber": null,
        "cardNumber": "2323232323232",
        "accountNumber": null,
        "bankBic": null
    },
    "paymentPageUrl": null,
    "dispute": {
        "disputeCreatedAt": null,
        "disputeMerchantCheckUrl": null,
        "disputeTraderCheckUrl": null,
        "disputeTraderFiatAmount": "0.00",
        "disputeTraderDeclineReason": null,
        "cancelReason": "NONE"
    },
    "payerInfo": {},
    "transactionWindowInMin": 15,
    "createdAt": "2026-01-15T20:41:08.822Z",
    "invoicesUrl": null,
    "merchantId": "befbd03c-3c62-42c8-9292-9074abcf7500",
    "callbackUrl": null
}

Поведение системы после создания заявки

Для invoice-методов и matching-related сценариев дополнительно учитывайте payment page flow подтверждения оплаты. Подробное описание вынесено на отдельную страницу:

Matching

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

method — платёжный метод (если не указан, выбирается автоматически);
bank — банк для получения реквизитов (если не указан, назначается системой).

Зачем нужен блок `payerInfo`

Передача дополнительной информации в блоке payerInfo (данные клиента, идентификатор операции из вашей системы и т.д.):

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

Рекомендуется заполнять payerInfo всегда, когда это возможно.

Pay-In является ключевым элементом платёжной интеграции и обеспечивает стабильный приём средств от ваших клиентов.