Дополнительные возможности

Статус заказа

После регистрации заказа узнать его статус можно одним из следующих способов:

Настроить уведомления обратного вызова (callback). Этот способ является предпочтительным. Для включения callback обратитесь в службу поддержки.
Периодически опрашивать статус заказа в течение не более получаса или времени, указанного в параметре sessionTimeoutSecs при регистрации заказа. Для получения статуса используется запрос getOrderStatusExtended.do.

Пример запроса:

curl -X POST 'https://api.router.rbsuat.com/v2/getOrderStatusExtended.do' -H 'Content-Type: application/json' \
--data-raw '{
    "orderId": "5ab8fb6a-421e-4396-9bf8-d7d77cc1e706",
    "userName": "test_user",
    "password": "test_user_password"
}'

curl -X POST 'https://api.router.rbsuat.com/v1/getOrderStatusExtended.do' -H 'Content-Type: application/json' \
--data-raw '{
    "orderId": "5ab8fb6a-421e-4396-9bf8-d7d77cc1e706",
    "userName": "test_user",
    "password": "test_user_password"
}'

Структура ответа различается в зависимости от того, зарегистрирован ли заказ только в Платежном сервисе или уже передан в какой-либо банк.

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

PREREGISTERED — заказ зарегистрирован только в Платежном сервисе;
CREATED — заказ создан в банке (но не оплачен);
APPROVED — заказ одобрен (средства на счету покупателя заблокированы);
DEPOSITED — заказ завершен (деньги списаны со счета покупателя);
DECLINED — заказ отклонен;
PENDING — идет обработка оплаты заказа;
REVERSED — заказ отменен;
REFUNDED — возврат средств.

Пример ответа для заказа, зарегистрированного в Платежном сервисе:

{
    "state": "PREREGISTERED",
    "depositedAmount": 0,
    "orderStatusResultModel": {
        "allowedPaymentWays": [
            "CARD_BINDING",
            "CARD",
            "MIR_PAY"
        ],
        "amount": 247,
        "clientId": "259753456",
        "currency": "643",
        "date": 1730530148222,
        "depositFlag": "PURCHASE",
        "gwId": null,
        "gwOrderId": null,
        "failUrl": "http://mybestmerchantreturnurl.com",
        "hasTimeout": false,
        "merchantLogin": "test_user",
        "orderDescription": "Test order",
        "orderId": "8e4c2673-98e6-11ef-ab20-4989eedfa34b",
        "orderNumber": "1730530146_3302",
        "orderParams": {
            "paramE": "deposit"
        },
        "orderStatus": -1,
        "paymentWay": null,
        "successUrl": "https://mybestmerchantreturnurl.com"
    }
}

Пример ответа для успешно оплаченного заказа:

{
    "state": "DEPOSITED",
    "depositedAmount": 920,
    "orderStatusResultModel": {
        "actionCode": 0,
        "actionCodeDescription": "",
        "amount": 920,
        "authDateTime": 1730537059726,
        "authRefNum": "152733574684",
        "bankInfo": {
            "bankName": "SBERBANK OF RUSSIA",
            "bankCountryCode": "RU"
        },
        "cardInfo": {
            "approvalCode": "123456",
            "cardholderName": "CARDHOLDER NAME",
            "expirationDate": "202412",
            "maskedPan": "427601**7761",
            "paymentSystem": "VISA"
        },
        "clientId": "259753456",
        "currency": "643",
        "date": 1730537058969,
        "depositFlag": "PURCHASE",
        "depositedDate": 1730537060295,
        "errorCode": "0",
        "errorMessage": "Успешно",
        "gwId": "SBERBANK",
        "gwOrderId": "e369c6ed-ea47-7b11-8087-bba24a87c214",
        "failUrl": "http://error.info?abc-123&def=567",
        "hasTimeout": false,
        "merchantLogin": "test_user",
        "operations": [
            {
                "amount": 920,
                "authCode": "123456",
                "cardHolder": "CARDHOLDER NAME",
                "currencyCode": "643",
                "operationDate": 1730537059726,
                "operationType": "PURCHASE",
                "maskedPan": "427601**7761",
                "processingResultCode": 0,
                "referenceNumber": "152733574684",
                "success": true,
                "terminalId": "22334477"
            }
        ],
        "orderDescription": "Monitored background synergy",
        "orderId": "954aab72-98f6-11ef-ab20-7d13eddab10a",
        "orderNumber": "1730537029_6667",
        "orderParams": {
            "binProductCategory": "CREDIT",
            "mdOrder_svip": "954aab72-98f6-11ef-ab20-7d13eddab10a",
            "paramE": "deposit",
            "paramF": "BG71MQIC844222679G7L4X",
            "binProductCode": "F"
        },
        "orderStatus": 2,
        "payerData": {
            "email": "Magdalena_Moen21@hotmail.com",
            "phone": "628-243-6459"
        },
        "paymentWay": "CARD",
        "processingId": "33224466",
        "refunds": [],
        "transactionAttributes": {
            "paymentNetRefNum": "ac4329d2-2031-416c-9e5b-836b5125c0c5"
        }
    }
}

Время жизни заказа

По умолчанию заказ можно оплатить в течение 30 минут после регистрации. Вы можете указать другое время сессии в параметре sessionTimeoutSecs при регистрации заказа register.do. Время сессии учитывается даже если оплата происходит по API без использования платежной страницы Платежного сервиса.

При использовании платежной страницы после истечения времени сессии платежная страница перестанет быть доступна, а при попытке открыть ее будет происходить редирект на failUrl.

Если заказ не оплачен за время сессии и не было попыток оплаты, то по истечении времени статус заказа станет DECLINED с actionCode = -2007 без указания банка. Если заказ не оплачен за время сессии, но попытки оплаты были, то после истечения времени сессии будет статус заказа DECLINED и actionCode = -2007, с указанием банка. Подробнее об actionCodes см. Коды ответа платежей.

Отмены, возвраты

Отмена неоплаченного заказа

Отмена заказа, который еще не оплачен и не авторизован (имеет статус CREATED или PREREGISTERED), осуществляется с помощью метода /decline.do.

После отмены неоплаченного заказа его статус становится DECLINED с actionCode=4005.

Отмена оплаченного заказа

Для отмены оплаченного заказа (в статусе DEPOSITED) можно использовать метод /reverse.do. Эта операция может быть возможна в течение определенного времени после оплаты, например, в течение банковского дня, пока не прошел клиринг (т.е. пока средства не были отправлены в другой банк), или другого периода, о котором Партнер договорился с банком.

Если клиринг уже прошел, необходимо использовать /refund.do

После отмены оплаченного заказа его статус становится REVERSED.

Применимость при одностадийной оплате

Тип отмены	Статус DEPOSITED	Другой статус
Полная отмена	Отменяет заказ полностью и переводит заказ в REVERSED. Вся списанная сумма возвращается клиенту.	Не допускается
Частичная отмена (первый вызов)	Зависит от эквайера: Либо выполняется полная отмена. Либо уменьшает сумму списания на сумму возврата (т.е. фактически возвращает клиенту часть уже списанных средств). В любом случае переводит заказ в REVERSED.	Не допускается
Частичная отмена (повторный вызов)	Зависит от эквайера: Либо не поддерживается (чаще всего). Либо то же самое, что при первом `reverse.do` — уменьшает сумму списания.	Не допускается

Применимость при двухстадийной оплате

Тип отмены	Статус APPROVED	Статус DEPOSITED	Другой статус
Полная отмена	Переводит заказ в REVERSED. Вся авторизованная сумма возвращается клиенту.	Зависит от эквайера: Либо возвращает заказ в состояние APPROVED, возвращает уже списанную сумму в остаток авторизованной, и можно снова выполнить `deposit.do` на другую сумму, Либо еще один `reverse.do` без суммы для окончательной отмены и перевода в REVERSED. Либо переводит заказ в REVERSED. Вся списанная сумма и остаток авторизованной суммы возвращается клиенту.	Не допускается
Частичная отмена (первая)	Зависит от эквайера: Либо уменьшает сумму авторизации на сумму отмены. Либо не поддерживается.	Зависит от эквайера: Либо уменьшает сумму списания на сумму возврата (т.е. фактически возвращает клиенту часть уже списанных средств), переводит заказ в REVERSED. Либо не поддерживается.	Не допускается
Частичная отмена (повторная)	Зависит от эквайера: Либо то же самое что при первом `reverse.do`. Либо не поддерживается.	Зависит от эквайера: Либо то же самое что при первом `reverse.do`. Либо не поддерживается.	Не допускается

Возврат средств

Платежный сервис Роутер поддерживает метод /refund.do для возврата средств за оплаченный заказ (в статусе DEPOSITED).

Особенности использования метода:

Можно оформить полный возврат. Для этого необходимо не передавать параметр amount совсем, либо в параметре amount указать значение 0 или всю сумму заказа.
Можно оформить частичный возврат. Если при регистрации заказа указывались товарные позиции, то в запросе нужно перечислить позиции, по которым выполняется возврат — refundItems; если позиций не было указано, то нужно просто передать сумму возврата amount в запросе.
Можно оформить несколько возвратов по одному заказу. Чтобы различать такие операции и отслеживать их в своей системе, Партнер может передать идентификатор externalRefundId. Если он указывается в операции возврата, то будет возвращен в статусе заказа getOrderStatusExtended.do, в блоке refunds. Используя данный идентификатор, Партнер сможет сопоставить данные из своей системы с данными в статусе заказа.

Кроме того, externalRefundId позволяет не выполнить один возврат дважды. При каждой попытке возврата Платежный сервис Роутер проверяет externalRefundId: если он уже существует, то сразу возвращается ответ, если нет — осуществляется возврат.
После успешного возврата статус заказа становится REFUNDED, даже после частичной отмены.

Пример частичного возврата по товарным позициям:

curl --location 'https://api.router.rbsuat.com/v2/refund.do' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 102729,
    "orderNumber": "1730538506_7044",
    "password": "test_user_password",
    "userName": "test_user",
    "refundItems": {
        "items": [
            {
                "positionId": "1",
                "name": "Получен аванс",
                "quantity": {
                    "value": 1027.29,
                    "measure": "шт"
                },
                "itemAmount": 102729,
                "itemCurrency": 643,
                "itemCode": "36035_10.1",
                "itemAttributes": {
                    "attributes": [
                        {
                            "name": "paymentMethod",
                            "value": "3"
                        },
                        {
                            "name": "paymentObject",
                            "value": "10"
                        }
                    ]
                },
                "tax": {
                    "taxType": "4"
                },
                "itemPrice": 100
            }
        ]
    }
}'

curl --location 'https://api.router.rbsuat.com/v1/refund.do' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 102729,
    "orderNumber": "1730538506_7044",
    "password": "test_user_password",
    "userName": "test_user",
    "refundItems": {
        "items": [
            {
                "positionId": "1",
                "name": "Получен аванс",
                "quantity": {
                    "value": 1027.29,
                    "measure": "шт"
                },
                "itemAmount": 102729,
                "itemCurrency": 643,
                "itemCode": "36035_10.1",
                "itemAttributes": {
                    "attributes": [
                        {
                            "name": "paymentMethod",
                            "value": "3"
                        },
                        {
                            "name": "paymentObject",
                            "value": "10"
                        }
                    ]
                },
                "tax": {
                    "taxType": "4"
                },
                "itemPrice": 100
            }
        ]
    }
}'

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

{
    "errorCode": 0,
    "errorMessage": "Успешно"
}

Двухстадийные платежи

Виды платежей

В зависимости от специфики бизнеса компания может использовать два вида платежей:

Одностадийные - операции по оплате товаров/услуг, совершаемые через Интернет с использованием банковских карт, не требующие дополнительного подтверждения, т.е. холдирование и списание денежных средств происходит в один этап. Этот вид оплаты предпочтителен, если товар или услуга предоставляется сразу после оплаты.
Двухстадийные - операции по оплате товаров/услуг, совершаемые через Интернет с использованием банковских карт, требующие дополнительного подтверждения, т.е. оплата производится в два этапа. На первом этапе происходит проверка наличия и холдирование (резевирование) средств плательщика (предавторизация); затем на втором этапе компания либо подтверждает списание средств, либо отменяет холдирование средств.

Сумма завершения может быть меньше суммы удержания. Также есть возможность делать завершения на сумму, превышающую величину удержания (в пределах настраиваемых лимитов). Если вы хотите использовать этот функционал, свяжитесь с нашей службой поддержки.

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

Чтобы платеж был двухстадийным, заказ должен быть зарегистрирован с помощью запроса registerPreAuth.do, а не register.do.

При использовании метода instantPayment.do тип оплаты (одностадийная или двухстадийная) определяется параметром preAuth.

Двухстадийная оплата возможна при любом способе интеграции:

При оплате с помощью СБП есть некоторые особенности, см. Двухстадийная оплата и СБП

У Партнера должно быть разрешение на двухстадийную оплату в банке, в который будет направлен платеж.

Завершения

Завершение происходит на втором этапе двухэтапного платежа, когда предварительно зарезервированные средства списываются со счета держателя карты. Как только происходит списание, заказ становится завершенным и переходит в статус DEPOSITED. Сумма завершения может быть больше или меньше суммы предварительной авторизации. Также доступно поэтапное частичное завершение. Если вы не передадите сумму, то будет списана вся сумма.

Завершение осуществляется с помощью запроса deposit.do.

Для отмены авторизованного, но еще не завершенного заказа используется метод reverse.do. У Партнера должно быть разрешение на использование отмены в банке, в который направлен платеж.

Также есть возможность сделать частичное завершение. В этом случае заказ будет завершен на меньшую сумму (чем сумма авторизации).

Завершение и отмена заказов автоматически

Если наша служба поддержки включила для вас эту функцию, вы можете настроить свою интеграцию так, чтобы все предварительно авторизованные (в статусе Подтвержден) двухстадийные заказы завершались или отменялись автоматически по истечении определенного периода времени. В этом случае не нужно будет вызывать методы deposit.do и/или /reverse.do.

Чтобы задать период, по истечении которого заказ будет автоматически подтвержден или отменен, передавайте в запросе на регистрацию заказа register.do параметр autocompletionDate или autoReverseDate соответственно.