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

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

{% hint style="warning" %}
Метод оплаты СБП не поддерживает предавторизацию на уровне протокола НСПК. Если платёж создан с параметром `preauth=1` и пользователь выбирает СБП, средства списываются сразу — платёж автоматически проводится как одностадийный. Подробнее — в разделе [Особенности работы с СБП](#osobennosti-raboty-s-sbp).
{% endhint %}

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

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

***

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

Для создания платежа с преавторизацией необходимо передать дополнительный параметр **preauth**. Полный набор параметров описан на [странице создания платежа](https://help.unitpay.ru/payments/create-payment).

<mark style="color:blue;">`GET`</mark> `https://unitpay.ru/api?method=initPayment`

#### Path Parameters

<table><thead><tr><th width="186.6666259765625">Name</th><th width="111.2222900390625">Type</th><th>Description</th></tr></thead><tbody><tr><td>preauth</td><td>integer</td><td>Используйте этот флаг для создания платежа с преавторизацией. По умолчанию флаг выключен и значение равно 0, для включения необходимо передать 1.</td></tr><tr><td>preauthExpireLogic</td><td>integer</td><td>Поле для логики блокировки платежей с преавторизацией:<br>0 - при отсутствии запроса на подтверждение или отмену, платеж по истечении срока блокировки на стороне банка-эквайера (~114 часов после создания платежа) будет подтвержден;<br>1 - при отсутствии запроса на подтверждение или отмену, платеж по истечении срока блокировки на стороне банка-эквайера (~114 часов после создания платежа) будет отменен. <br><br>Если параметр не будет использован, платеж будет отменен по истечении срока.</td></tr></tbody></table>

```json
{
    "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"
    }
}
```

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

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

```json
GET https://unitpay.ru/api

method            = confirmPayment
params[paymentId] = 2142345678
params[secretKey] = secretkey
```

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

<table><thead><tr><th width="159">Name</th><th width="196.2222900390625">Type</th><th>Description</th></tr></thead><tbody><tr><td>paymentId</td><td>integer</td><td>ID платежа в системе UnitPay</td></tr><tr><td>secretKey</td><td>string</td><td>Секретный ключ проекта, доступен в настройках проекта</td></tr></tbody></table>

{% tabs %}
{% tab title="Успешный ответ" %}

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

{% endtab %}

{% tab title="Ошибочный ответ" %}

```json
{
    "error": {
        "message": "Платеж не может быть подтвержден"
    }
}
```

{% endtab %}
{% endtabs %}

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

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

```json
GET https://unitpay.ru/api

method            = cancelPayment
params[paymentId] = 2142345678
params[secretKey] = secretkey
```

#### Path Parameters

<table><thead><tr><th width="203.4444580078125">Name</th><th width="155.3333740234375">Type</th><th>Description</th></tr></thead><tbody><tr><td>paymentId</td><td>integer</td><td>ID платежа в системе UnitPay</td></tr><tr><td>secretKey</td><td>string</td><td>Секретный ключ проекта, доступен в настройках проекта</td></tr></tbody></table>

{% tabs %}
{% tab title="Успешный ответ" %}

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

{% endtab %}

{% tab title="Ошибочный ответ" %}

```json
{
    "error": {
        "message": "Платеж не может быть отменен"
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Двухстадийные платежи можно использовать при создании [подписок](https://help.unitpay.ru/payments/recurring-payments/create-subscription).
{% endhint %}

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

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

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

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

**Ответы API**

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

```json
{
    "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` для СБП-платежа:

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

При вызове `cancelPayment` для СБП-платежа поведение и все возможные ответы идентичны методу `refundPayment` — см. [документацию по возвратам](https://help.unitpay.ru/payments/payment-refund).

{% hint style="warning" %}
Для СБП-платежей с `preauth=1` параметр `preauthExpireLogic` игнорируется — срок жизни счёта соответствует стандартному таймауту СБП-платежей.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.unitpay.ru/payments/pre-authorization-payments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.