Двухэтапные платежи (преавторизация)

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

Метод оплаты СБП не поддерживает предавторизацию на уровне протокола НСПК. Если платёж создан с параметром preauth=1 и пользователь выбирает СБП, средства списываются сразу — платёж автоматически проводится как одностадийный. Подробнее — в разделе Особенности работы с СБП.

Как это работает:

1. Блокировка средств — сумма замораживается на карте клиента, но не списывается.

2. Подтверждение или отмена — продавец может либо подтвердить списание, либо отменить платёж.

3. Автоматическая разблокировка — если платёж не подтверждён в течение установленного срока, средства автоматически разблокируются.

---

Инициализация платежа с преавторизацией

Для создания платежа с преавторизацией необходимо передать дополнительный параметр preauth. Полный набор параметров описан на странице создания платежа.

GET https://unitpay.ru/api?method=initPayment

Path Parameters

Name	Type	Description
preauth	integer	Используйте этот флаг для создания платежа с преавторизацией. По умолчанию флаг выключен и значение равно 0, для включения необходимо передать 1.
preauthExpireLogic	integer	Поле для логики блокировки платежей с преавторизацией: 1 - при отсутствии запроса на подтверждение или отмену, платеж по истечении срока блокировки на стороне банка-эквайера (~114 часов после создания платежа) будет подтвержден; 0 - при отсутствии запроса на подтверждение или отмену, платеж по истечении срока блокировки на стороне банка-эквайера (~114 часов после создания платежа) будет отменен. Если параметр не будет использован, платеж будет отменен по истечении срока.

{
    "result": {
        "type": "redirect",
        "paymentId": 1234567890,
        "message": "Счет успешно выставлен, ожидается оплата",
        "receiptUrl": "https://unitpay.ru/pay/receipt/1234567890-454ac183ac",
        "statusUrl": "https://unitpay.ru/pay/receipt/1234567890-454ac183ac",
        "redirectUrl": "https://unitpay.ru/pay/redirect/1234567890-454ac183ac"
    }
}

Подтверждение платежа с преавторизацией

Для подтверждения платежа с преавторизацией (списания заблокированных на карте плательщика средств) выполните этот запрос:

GET https://unitpay.ru/api

method    = confirmPayment
paymentId = 2142345678
secretKey = sk_live_2YQt9m

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

Name	Type	Description
paymentId	integer	ID платежа в системе UnitPay
secretKey	string	Секретный ключ проекта, доступен в настройках проекта

Успешный ответ

{ "message": "Платеж успешно подтвержден" }

Ошибочный ответ

Отмена платежа с преавторизацией

Для отмены платежа с преавторизацией (разблокировки средств на карте плательщика) выполните следующий запрос:

GET https://unitpay.ru/api

method    = confirmPayment
paymentId = 2142345678
secretKey = sk_live_2YQt9m

Path Parameters

Name	Type	Description
paymentId	integer	ID платежа в системе UnitPay
secretKey	string	Секретный ключ проекта, доступен в настройках проекта

Успешный ответ

{ "message": "Блокировка успешно отменена" }

Ошибочный ответ

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

Особенности работы с СБП

Метод СБП не поддерживает холдирование средств на уровне протокола НСПК. При создании платежа с preauth=1 и выборе пользователем оплаты через СБП платёж автоматически понижается до одностадийного. Это поведение не является ошибкой — оно позволяет не ограничивать пользователей в выборе метода оплаты на форме.

Отличия от стандартного двухэтапного платежа:

	Карта (preauth=1)	СБП (preauth=1)
Средства после оплаты	Заблокированы	Списаны сразу
Финальный статус	Холдирован	Оплачен
confirmPayment	Списывает средства	Возвращает ошибку
cancelPayment	Снимает блокировку	Возвращает средства (refund). Доступен сразу

Ответы API

При инициализации платежа с preauth=1 и paymentType=sbp в поле message возвращается предупреждение:

{
    "result": {
        "type": "redirect",
        "paymentId": 1234567890,
        "message": "Счёт успешно выставлен, ожидается оплата. СБП не поддерживает двухстадийную оплату: после оплаты деньги списываются сразу, без холдирования. Подтверждать платёж не нужно. Для возврата используйте метод refundPayment.",
        "receiptUrl": "https://unitpay.ru/pay/receipt/1234567890-454ac183ac",
        "statusUrl": "https://unitpay.ru/pay/receipt/1234567890-454ac183ac",
        "redirectUrl": "https://unitpay.ru/pay/redirect/1234567890-454ac183ac"
    }
}

При вызове confirmPayment для СБП-платежа:

{
    "error": {
        "message": "Подтверждение недоступно: платёж проведён как одностадийный, так как метод СБП не поддерживает предавторизацию."
    }
}

При вызове cancelPayment для СБП-платежа поведение и все возможные ответы идентичны методу refundPayment — см. документацию по возвратам.

Для СБП-платежей с preauth=1 параметр preauthExpireLogic игнорируется — срок жизни счёта соответствует стандартному таймауту СБП-платежей.