Общее описание

Вы можете использовать наш API продавца, чтобы создать нужный вам сценарий оплаты. Например, вы можете создать собственную полностью настроенную платежную страницу и подключить ее к нашему платежному шлюзу.

Вы можете скачать коллекцию API-запросов для Postman, чтобы протестировать основные возможности API. Обязательно отправляйте запросы как POST с атрибутами в теле запроса.

Обязательность параметров

Обязательность присутствия параметра в запросе/ответе может принимать следующие значения:

• Обязательно - параметр должен присутствовать всегда. В случае отсутствия значения требуется передавать пустое значение в зависимости от формата;
• Необязательно - параметр может как присутствовать, так и отсутствовать, при этом его избыточное присутствие не приведет к ошибке системы;
• Условие - параметр может как присутствовать (быть обязательным), так и отсутствовать в зависимости от одного или нескольких условий.

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

Аутентификация

Для аутентификации мерчанта в платежном шлюзе можно использовать два метода.

• Используя логин и пароль API-пользователя мерчанта (аккаунт с суффиксом -api), полученный при регистрации. Эти значения передаются в параметрах userName и password соответственно (см. таблицу ниже).

• С помощью специального токена - его значение вы можете запросить в службе технической поддержки. В запросах его значение передается в параметре token (см. таблицу ниже).

URL для API-вызовов

TEST: https://forabank.rbsuat.com/payment/rest/
PROD: https://forabank.rbsgate.com/payment/rest/

Ошибки

Коды состояния HTTP:

• 200 - в случае вызовов API платежного шлюза необходимо проанализировать JSON из ответа, чтобы определить, была ли обработка транзакции успешной или нет. Успех обозначается либо:
  - значением параметра success равным true
  - значением параметра errorCode равным 0
  Если присутствуют оба параметра, success имеет приоритет над errorCode.

• 400 – в системе произошла внутренняя ошибка.

• 404 – ошибка при вызове API – неверный URL (не существует).

• 429 – этот код означает, что система перегружена. Чаще всего основная причина в том, что достигнут лимит запросов в секунду или лимит одновременных запросов. Но также может быть связано с тем, что система в целом перегружена (независимо от ваших запросов).

• 500 или 502 – этот код означает, что что-то пошло не так на нашей стороне.

Если запрос, связанный с оплатой заказа, обработан успешно, это еще не означает, что сам платеж прошел успешно.

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

1. Вызвать getOrderStatusExtended.do;
2. Проверить поле orderStatus в ответе: заказ считается оплаченным, только если значение orderStatus равно 1 или 2.

Подпись запроса API

В некоторых случаях для обеспечения безопасного обмена данными может потребоваться реализовать асимметричную подпись запроса. Обычно это требование применяется, только если вы выполняете запросы P2P/AFT/OCT.

Чтобы иметь возможность подписывать запросы, вам необходимо выполнить следующие шаги:

1. Создайте и загрузите сертификат.
2. Рассчитайте хеш и подпись, используя свой закрытый ключ, и передайте сгенерированный хеш (X-Hash) и значение подписи (X-Signature) в заголовке запроса.

Эти шаги подробно описаны ниже.

Создание и загрузка сертификата

1. Создайте 2048-битный закрытый ключ RSA. Способ генерации зависит от политики конфиденциальности в вашей компании. Например, вы можете сделать это с помощью OpenSSL:

   openssl genrsa -des3 -out private.key 2048

2. Создайте общедоступный CSR (запрос на подпись сертификата), используя сгенерированный закрытый ключ:

   openssl req -key private.key -new -out public.csr

3. Создайте сертификат, используя сгенерированный закрытый ключ и CSR. Пример формирования сертификата на 5 лет:

   openssl x509 -signkey private.key -in public.csr -req -days 1825 -out public.cer

4. Загрузите сгенерированный сертификат в Личный кабинет. Для этого перейдите в Сертификаты кошельков > Merchant API, нажмите Добавить сертификат и загрузите сгенерированный общедоступный сертификат.

Вычисление хеша и подписи

1. Рассчитайте хеш SHA256 тела запроса следующим образом:

2. Используйте тело запроса в виде строки (в нашем примере это amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api).

3. Вычислите хэш SHA256 из этой строки в необработанных байтах.

4. Преобразуйте необработанные байты в кодировку base64.

5. Сгенерируйте подпись для вычисленного хеша SHA256 с помощью алгоритма RSA, используя закрытый ключ.

В нашем примере мы используем следующий закрытый ключ с паролем 12345:

Получаем подпись: pJ/gM4PR1/mKGuIxMvTl5pYDDjJslb0BcXFnIxijFn5qKdPd7W+2ueoctziU7omnkYp01/BlracukH1GOPWMSO+9zKuTDdFueFm1utsS0zaPFU+dmc1niGDRWE0CbCXcti/rGSTDPsnR58mwqgVkbCWxKyCDtuo5LxiKPK9mzgWTUuJ8LX6f6u42MURi5tRG6a9dc8l/+J94g0YOk911R6Lqv2jcluEvZ9ZeMMt8hyxowb0eDaCHlussu2CAyqpE9V+EUAc81Jkwv96MMSsA6UnFwEaCV/k+kwYd0jHCx94m2yWX734p9cWsBW7Fr5F0zox9Yck4GOjqe9nJMMB9jQ== 3. Теперь вам следует передать сгенерированный хэш (X-Hash) и значение подписи (X-Signature) в заголовке запроса. Запрос будет выглядеть так:

curl --request POST \
  --url https://forabank.rbsuat.com/payment/rest/register.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'X-Hash: eYkMUF+xaYJhsETTIGsctl6DBNZha1ITN8muCcWQtZk=' \
  --header 'X-Signature: pJ/gM4PR1/mKGuIxMvTl5pYDDjJslb0BcXFnIxijFn5qKdPd7W+2ueoctziU7omnkYp01/BlracukH1GOPWMSO+9zKuTDdFueFm1utsS0zaPFU+dmc1niGDRWE0CbCXcti/rGSTDPsnR58mwqgVkbCWxKyCDtuo5LxiKPK9mzgWTUuJ8LX6f6u42MURi5tRG6a9dc8l/+J94g0YOk911R6Lqv2jcluEvZ9ZeMMt8hyxowb0eDaCHlussu2CAyqpE9V+EUAc81Jkwv96MMSsA6UnFwEaCV/k+kwYd0jHCx94m2yWX734p9cWsBW7Fr5F0zox9Yck4GOjqe9nJMMB9jQ==' \
  --data 'amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api'

Запрос должен соответствовать следующим требованиям:

• Все параметры запроса включены в тело запроса (не в URL)

• Если параметры запроса передаются в формате JSON, должен использоваться следующий заголовок:

  --header 'content-type: application/json'

• Если параметры запроса передаются в формате Query (например, parameterA=valueA&parameterB=valueB), должен использоваться следующий заголовок:

  --header 'content-type: application/x-www-form-urlencoded'

• Запрос содержит правильный логин и пароль пользователя API.

• Заголовок X-Hash содержит хэш SHA256 тела запроса (рассчитывается на Шаге 1).

• Заголовок X-Signature содержит подпись для хэша SHA256, рассчитанного с помощью алгоритма RSA с использованием закрытого ключа (генерируется на Шаге 2).

Пример кода Java

Ниже приведен пример кода Java, который загружает закрытый ключ, вычисляет хэш SHA256, подписывает его с помощью закрытого ключа с паролем 12345, а затем отправляет правильный запрос register.do:

import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.KeyStore;
import java.security.MessageDigest;
import java.security.PrivateKey;
import java.security.Signature;
import java.util.Base64;

import static java.net.HttpURLConnection.HTTP_OK;

public class SimpleSignatureExample {

    // This example is not production ready. It just shows how to use signatures in API.
    public static void main(String[] args) throws Exception {
        // load private key from jks
        KeyStore ks = KeyStore.getInstance("JKS");
        char[] pwd = "123456".toCharArray();
        ks.load(Files.newInputStream(Paths.get("/path/to/certificates.jks")), pwd);
        PrivateKey privateKey = (PrivateKey) ks.getKey("111111", pwd);

        // Sign
        String httpBody = "amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api";

        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        Signature signature = Signature.getInstance("SHA256withRSA");
        signature.initSign(privateKey);

        byte[] sha256 = digest.digest(httpBody.getBytes());
        signature.update(sha256);
        byte[] sign = signature.sign();

        // Send
        Base64.Encoder encoder = Base64.getEncoder();
        HttpsURLConnection connection = (HttpsURLConnection) new URL("https://<YOUR_DOMAIN>/payment/rest/register.do").openConnection();
        connection.setDoOutput(true);
        connection.setDoInput(true);
        connection.setRequestMethod("POST");
        connection.addRequestProperty("content-type", "application/x-www-form-urlencoded");
        connection.addRequestProperty("X-Hash", encoder.encodeToString(sha256));
        connection.addRequestProperty("X-Signature", encoder.encodeToString(sign));
        connection.addRequestProperty("Content-Length", String.valueOf(httpBody.getBytes().length));
        try (final DataOutputStream outputStream = new DataOutputStream(connection.getOutputStream())) {
            outputStream.write(httpBody.getBytes());
            outputStream.flush();
        }
        connection.connect();

        InputStream inputStream = connection.getResponseCode() == HTTP_OK ? connection.getInputStream() : connection.getErrorStream();
        BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream));
        String line;
        while ((line = reader.readLine()) != null) {
            System.out.println(line);
        }
    }
}

Пример кода Python

Ниже приведен пример кода Python, который генерирует подпись:

import OpenSSL
from OpenSSL import crypto
import base64
from hashlib import sha256
key_file = open("./priv.pem", "r")
key = key_file.read()
key_file.close()

if key.startswith('-----BEGIN '):
    pkey = crypto.load_privatekey(crypto.FILETYPE_PEM, key)
else:
    pkey = crypto.load_pkcs12(key, password).get_privatekey()

data = "amount=2000&currency=978&userName=test_user&password=test_user_password&returnUrl=https%3A%2F%2Fmybestmerchantreturnurl.com&description=my_first_order&language=en"

sha256_hash = sha256(data.encode()).digest()
base64_hash = base64.b64encode(sha256_hash)
print(base64_hash)

sign = OpenSSL.crypto.sign(pkey, sha256_hash, "sha256")

signed_base64 = base64.b64encode(sign)
print(signed_base64)

Файл закрытого ключа для примера Python должен иметь формат:

Регистрация заказа

Регистрация заказа

Для регистрации заказа используется запрос https://forabank.rbsuat.com/payment/rest/register.do.

При выполнении запроса необходимо использовать заголовок: Content-Type: application/x-www-form-urlencoded

Параметры запроса

Ниже приведены параметры блока billingPayerData (данные об адресе регистрации клиента).

Описание параметров объекта shippingPayerData:

Описание параметров объекта preOrderPayerData:

Описание параметров объекта orderPayerData.

Описание параметров в объекте orderBundle:

Ниже перечислены параметры блока agent (данные об агенте).

Описание параметров в объекте customerDetails:

Проверка данных плательщика при передаче корзины

Согласно требованиям ФНС, при передаче ФИО плательщика должно быть передано либо ИНН плательщика, либо его паспортные данные.

В связи с этим, если в запросе с продуктовой корзиной передается какой-либо из параметров (в блоках orderBundle или additionalOfdParams):

• Полное имя – customerDetails.fullname или client.name
• ИНН – customerDetails.inn или client.inn
• Данные документа – customerDetails.passport или client.passport_number
• Код документа – client.document_code
• Дата рождения – client.birth_date
• Гражданство – client.citizenship

то выполняется проверка на обязательное наличие ИНН плательщика ИЛИ набора параметров Дата рождения, Код документа, Данные документа. Если это условие не выполняется, запрос будет обработан с ошибкой.

Описание параметров в объекте deliveryInfo:

Описание параметров в объекте cartItems:

Описание параметров в объекте items:

Описание параметров в объекте quantity:

Возможные значения параметра measure:

Описание параметров в объекте itemDetails:

Описание параметров в объекте itemDetailsParams:

Описание параметров объекта tax:

Описание параметров в объекте itemAttributes:

Параметр itemAttributes должен содержать массив attributes, а уже в этом массиве расположены атрибуты товарной позиции (см. пример и таблицу ниже).

"itemAttributes":{"attributes":[{"name":"paymentMethod","value":"1"},{"name":"paymentObject","value":"1"}]}

Описание параметров в объекте agent_info:

Описание параметров в объекте paying:

Описание параметров в объекте paymentsOperator:

Описание параметров в объекте MTOperator:

Описание параметров в объекте supplier_info:

Описание параметров объекта markQuantity.

Описание параметров в объекте additionalOfdParams:

Параметры ответа

Примеры

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

curl --request POST \
  --url https://forabank.rbsuat.com/payment/rest/register.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data amount=123456 \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderNumber=1234567890ABCDEF \
  --data returnUrl=https://mybestmerchantreturnurl.com \
  --data failUrl=https://mybestmerchantfailurl.com \
  --data email=test@test.com \
  --data clientId=259753456 \
  --data features=FORCE_SSL \
  --data language=ru \
  --data 'jsonParams={"param_1_name":"param_1_value","param_2_name":"param_2_value"}'

Пример ответа - успех

{
  "orderId": "01491d0b-c848-7dd6-a20d-e96900a7d8c0",
  "formUrl": "https://forabank.rbsuat.com/payment/payment/merchants/ecom/payment_en.html?mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0"
}

Пример ответа - ошибка

{
  "errorCode": "1",
  "errorMessage": "Order number is duplicated, order with given order number is processed already"
}

Регистрация заказа с предавторизацией

Для запроса регистрации заказа с предавторизацией используется метод https://forabank.rbsuat.com/payment/rest/registerPreAuth.do.

При выполнении запроса необходимо использовать заголовок: Content-Type: application/x-www-form-urlencoded

Параметры запроса

Ниже приведены параметры блока billingPayerData (данные об адресе регистрации клиента).

Описание параметров объекта shippingPayerData:

Описание параметров объекта preOrderPayerData:

Описание параметров объекта orderPayerData.

Описание параметров в объекте orderBundle:

Описание параметров в объекте customerDetails:

Проверка данных плательщика при передаче корзины

Согласно требованиям ФНС, при передаче ФИО плательщика должно быть передано либо ИНН плательщика, либо его паспортные данные.

В связи с этим, если в запросе с продуктовой корзиной передается какой-либо из параметров (в блоках orderBundle или additionalOfdParams):

• Полное имя – customerDetails.fullname или client.name
• ИНН – customerDetails.inn или client.inn
• Данные документа – customerDetails.passport или client.passport_number
• Код документа – client.document_code
• Дата рождения – client.birth_date
• Гражданство – client.citizenship

то выполняется проверка на обязательное наличие ИНН плательщика ИЛИ набора параметров Дата рождения, Код документа, Данные документа. Если это условие не выполняется, запрос будет обработан с ошибкой.

Описание параметров в объекте deliveryInfo:

Описание параметров в объекте cartItems:

Описание параметров в объекте items:

Описание параметров в объекте quantity:

Описание параметров в объекте itemDetails:

Описание параметров в объекте itemDetailsParams:

Описание параметров объекта tax:

Описание параметров в объекте itemAttributes:

Параметр itemAttributes должен содержать массив attributes, а уже в этом массиве расположены атрибуты товарной позиции (см. пример и таблицу ниже).

"itemAttributes":{"attributes":[{"name":"paymentMethod","value":"1"},{"name":"paymentObject","value":"1"}]}

Описание параметров в объекте agent_info:

Описание параметров в объекте paying:

Описание параметров в объекте paymentsOperator:

Описание параметров в объекте MTOperator:

Описание параметров в объекте supplier_info:

Возможные значения параметра measure:

Описание параметров объекта markQuantity.

Описание параметров в объекте additionalOfdParams:

Параметры ответа

Примеры

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

curl --request POST \
  --url https://forabank.rbsuat.com/payment/rest/registerPreAuth.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data amount=2000 \
  --data userName=test_user \
  --data password=test_user_password \
  --data returnUrl=https://mybestmerchantreturnurl.com \
  --data orderNumber=1255555555555 \
  --data clientId=259753456 \
  --data language=ru

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

{
  "orderId": "01492437-d2fb-77fa-8db7-9e2900a7d8c0",
  "formUrl": "https://forabank.rbsuat.com/payment/merchants/pay/payment_en.html?mdOrder=01492437-d2fb-77fa-8db7-9e2900a7d8c0"
}

Прямые платежи

Оплата заказа

Для оплаты ранее зарегистрированного заказа используется запрос https://forabank.rbsuat.com/payment/rest/paymentorder.do.
Запрос используется в режиме внутренний MPI/3DS Server, для этого не требуется наличие дополнительных разрешений и/или сертификаций.
Запрос используется в режиме внешнего MPI/3DS Server если у вас есть договор с международной платежной системой или сертификат, который позволяет самостоятельно проводить аутентификацию 3DS. Это означает, что вы можете использовать собственный MPI/3DS Server для аутентификации клиента с использованием технологии 3D Secure. Дополнительная информация об оплате с собственным MPI/3DS Server доступна здесь.

При выполнении запроса необходимо использовать заголовок: Content-Type: application/x-www-form-urlencoded

Оплата заказа (внутренний MPI/3DS Server)

Оплата заказа происходит с передачей карточных платежных данных, а так же с использованием технологии аутентификации 3DS (применение аутентификации регулируется настройками, регулируемых службой поддержки).

Параметры запроса

Ниже приведены параметры блока billingPayerData (данные об адресе регистрации клиента).

Описание параметров объекта shippingPayerData:

Описание параметров объекта preOrderPayerData:

Описание параметров объекта orderPayerData.

Возможные значения tii (Подробнее о типах связок, поддерживаемых платежным шлюзом, читайте здесь).

Ниже приведены параметры блока clientBrowserInfo (данные о браузере клиента).

Пример блока clientBrowserInfo:

"clientBrowserInfo":
    {
		"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
		"fingerprint":850891523,
		"OS":"Windows",
		"OSVersion":"10",
		"isMobile":false,
		"screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
		"colorDepth":24,
		"screenHeight":"864",
		"screenWidth":"1536",
		"plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
		"javaEnabled":false,
		"javascriptEnabled":true,
		"browserLanguage":"it-IT",
		"browserTimeZone":"Europe/Rome",
		"browserTimeZoneOffset":-120,
		"browserAcceptHeader":"gzip",
        "browserIpAddress":"x.x.x.x"
	}

При аутентификации по протоколу 3DS2 также передаются следующие параметры:

Параметры ответа

При аутентификации по протоколу 3DS2 в ответ на первый запрос приходят следующие параметры:

Ниже приведены параметры, которые должны присутствовать в ответе, после повторного запроса платежа и необходимости перенаправления клиента в ACS при аутентификации по протоколу 3DS2:

Примеры

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

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

curl --request POST \
  --url https://forabank.rbsuat.com/payment/rest/paymentorder.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data MDORDER=64d3b8c2-5d87-7d92-bd20-d8db011b4f5b \
  --data '$PAN=4000001111111118' \
  --data '$CVC=123' \
  --data YYYY=2030 \
  --data MM=12 \
  --data 'TEXT=TEST CARDHOLDER' \
  --data language=ru \
  --data 'jsonParams={"param_1_name":"param_1_value","param_2_name":"param_2_value"}'

Пример второго запроса:

curl --request POST \
  --url https://forabank.rbsuat.com/payment/rest/paymentorder.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data MDORDER=64d3b8c2-5d87-7d92-bd20-d8db011b4f5b \
  --data '$PAN=4000001111111118' \
  --data '$CVC=123' \
  --data YYYY=2030 \
  --data MM=12 \
  --data 'TEXT=TEST CARDHOLDER' \
  --data language=ru \
  --data threeDSServerTransID=5802746e-3393-40c3-929a-dc966ebf08c6

Пример запроса c криптограммой (seToken):

curl --location --request POST 'https://forabank.rbsuat.com/payment/rest/paymentorder.do' \
    --header 'Content-type: application/x-www-form-urlencoded' \
    --data-urlencode 'MDORDER=63447c9c-b432-7c8e-962f-161c0008f9da' \
    --data-urlencode 'language=en' \
    --data-urlencode 'TEXT=CARDHOLDER NAME' \
    --data-urlencode 'email=' \
    --data-urlencode 'seToken=Cfqv4t2XHBb9k8ixM7jxxCvziETS4koa3bV3F0QUvGVY47nKyMBqjGzV%2FrvmCAw6KzwoBDzeLsqwBLEzvQhaF627ZS0OJnhttBi4fL3%2Fh%2FsBSwFtxr3s%2BoVUeoE3e4SNVUq9vciinOyNCIKqfpeQya%2BpOUYt3MgrtSeu66Ar12XEj4k6lecZN7Ffquj9RqhZsYhP63np5VCxJR90cNQG%2BTMWIFU6rqxLAe4gzCJtcXNrPT8aDOI201Zwd%2Be4K1YnrI7dZGlibO7MVMPB9m7NJaJTHko%2FMiJNWumAjS4yDDovLraIKMwOFTvAhqXsHslthpcUO0GZXEIaDRgERD7%2Bjw%3D%3D' \
    --data-urlencode 'userName=tm-api' \
    --data-urlencode 'password=XXXXXXX'

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

Пример ответа на первый запрос:

{
  "errorCode": 0,
  "is3DSVer2": true,
  "threeDSServerTransId": "5802746e-3393-40c3-929a-dc966ebf08c6",
  "threeDSMethodURL": "https://example.com/acs2/acs/3dsMethod",
  "threeDSMethodURLServer": "example.com/3dsserver/api/v1/client/gather?threeDSServerTransID=5802746e-3393-40c3-929a-dc966ebf08c6",
  "threeDSMethodDataPacked": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9hY3F1aXJlci5jb20vM2Rzc2VydmVyL2FwaS92MS9hY3Mvbm90aWZpY2F0aW9uP3RocmVlRFNTZXJ2ZXJUcmFuc0lEPTNhZmMxNjhhLTk0YjQtNGViMy04ZTJlLTgwZjZjMTg2NjY5ZCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiM2FmYzE2OGEtOTRiNC00ZWIzLThlMmUtODBmNmMxODY2NjlkIn0="
}

Пример ответа на второй запрос:

{
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0,
  "acsUrl": "https://example.com/acs2/acs/creq",
  "is3DSVer2": true,
  "packedCReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjU4MDI3NDZlLTMzOTMtNDBjMy05MjlhLWRjOTY2ZWJmMDhjNiIsIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsIm1lc3NhZ2VWZXJzaW9uIjoiMi4xLjAiLCJhY3NUcmFuc0lEIjoiODFmZTU1ODUtZmZhOS00Y2NkLTljMjAtY2QzYWFiZDQwNTllIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0"
}

Оплата заказа (в режиме внешнего MPI/3DS Server)

Для использования запроса paymenOrder.do в режиме внешний MPI/3DS Server вам необходимо выполнить аутентификацию 3DS с использованием вашего собственного сервера MPI/3DS.
Также вам необходимо дополнительное разрешение, назначаемое службой поддержки.

Параметры запроса

Ниже приведены параметры блока billingPayerData (данные об адресе регистрации клиента).

Описание параметров объекта shippingPayerData:

Описание параметров объекта preOrderPayerData:

Описание параметров объекта orderPayerData.

Возможные значения tii (Подробнее о типах связок, поддерживаемых платежным шлюзом, читайте здесь).

Ниже приведены параметры блока clientBrowserInfo (данные о браузере клиента).

Пример блока clientBrowserInfo:

"clientBrowserInfo":
    {
		"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36 Edg/111.0.1661.41",
		"fingerprint":850891523,
		"OS":"Windows",
		"OSVersion":"10",
		"isMobile":false,
		"screenPrint":"Current Resolution: 1536x864, Available Resolution: 1536x824, Color Depth: 24, Device XDPI: undefined, Device YDPI: undefined",
		"colorDepth":24,
		"screenHeight":"864",
		"screenWidth":"1536",
		"plugins":"PDF Viewer, Chrome PDF Viewer, Chromium PDF Viewer, Microsoft Edge PDF Viewer, WebKit built-in PDF",
		"javaEnabled":false,
		"javascriptEnabled":true,
		"browserLanguage":"it-IT",
		"browserTimeZone":"Europe/Rome",
		"browserTimeZoneOffset":-120,
		"browserAcceptHeader":"gzip",
        "browserIpAddress":"x.x.x.x"
	}

Параметры ответа

Примеры

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

curl --request POST \\
  --url https://forabank.rbsuat.com/payment/rest/paymentorder.do \\
  --header 'content-type: application/x-www-form-urlencoded' \\
  --data userName=test_user \\
  --data password=test_user_password \\
  --data MDORDER=0140dda0-71ed-7706-a61f-36bd00a7d8c0 \\
  --data '$PAN=4000001111111118' \\
  --data '$CVC=123' \\
  --data YYYY=2030 \\
  --data MM=12 \\
  --data 'TEXT=TEST CARDHOLDER' \\
  --data language=en \\
  --data 'jsonParams={
  "eci": "02",
  "cavv": "AkZO5XQAA0rhBxoaufa+MAABAAA=",
  "xid": "5010857f-8d3f-74e1-9c5a-54a000cc4110",
  "threeDSProtocolVersion": "2.2.0",
  "authenticationTypeIndicator": "5"
}'

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

{
  "redirect": "https://forabank.rbsuat.com/payment/merchants/temp/finish.html?orderId=01493844-d4d3-703f-9f7e-a73900a7d8c0",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

Редирект на ACS (упрощенный)

Если требуется 3-D Secure, то после получения ответа на запрос оплаты клиент должен быть перенаправлен на ACS. В этом случае ответ на запрос оплаты содержит параметр acsUrl, который будет использоваться для перенаправления.

Запрос https://forabank.rbsuat.com/payment/acsRedirect.do?orderId={orderId} позволяет перенаправить клиента на страницу аутентификации ACS упрощенным способом - просто используя параметр orderId, полученный после регистрации заказа.

Также возможно перенаправление клиента на ACS с помощью POST-запроса (обычный редирект). Описание этого метода доступно здесь.

Без каких-либо других действий, требуемых от клиента, платежный шлюз перенаправляет его на страницу ACS, где клиент аутентифицируется.

Затем, в зависимости от результата аутентификации, клиент перенаправляется на следующий URL-адрес:

• если аутентификация прошла успешно - returnUrl с добавленным параметром orderId;
• если аутентификация не удалась - failUrl (или returnUrl, если failUrl не был передан) с добавленным параметром orderID.

Чтобы перенаправить клиента на ACS, используйте следующий URL-адрес:

https://forabank.rbsuat.com/payment/acsRedirect.do?orderId={Номер заказа в платежном шлюзе}

Параметры запроса

Параметры ответа

Пример

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

curl -X GET https://forabank.rbsuat.com/payment/acsRedirect.do?orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1

Пример URL редиректа

https://mybestmerchantreturnurl.com/?orderId=85eb9a84-2a47-7cca-b0ae-662c000016d1

Статус платежа

Самый простой способ узнать статус платежа — использовать специальный вызов API:

1. Сделать вызов getOrderStatusExtended.do;
2. Проверить поле orderStatus в ответе: заказ считается оплаченным, только если значение orderStatus равно 1 или 2.

Еще один способ проверить, прошел ли платеж успешно или нет, – это посмотреть уведомление обратного вызова.

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

Для получения статуса заказа используется метод https://forabank.rbsuat.com/payment/rest/getOrderStatusExtended.do.

При выполнении запроса необходимо использовать заголовок: Content-Type: application/x-www-form-urlencoded

Дополнительная информация о причинах отказа доступна здесь.

Параметры запроса

Параметры ответа

Существует несколько наборов параметров ответа. Какой набор параметров возвращается в ответе, зависит от версии getOrderStatusExtended, указанной в настройках мерчанта в платежном шлюзе.

Описание версий

Значения параметра paymentWay:

• CARD – Оплата с вводом данных карты
• CARD_BINDING – Проведение оплаты по связке
• FILE_BINDING – Оплата через файл
• FILE_SBP_C2B_BINDING – Оплата СБП (Система быстрых платежей) через файл
• P2P – Перевод денег с карты на карту
• P2P_BINDING – Перевод с карты на карту по связке
• APPLE_PAY – Платеж Apple Pay
• APPLE_PAY_BINDING – Оплата по связке Apple Pay
• GOOGLE_PAY_CARD – Оплата нетокенизированной картой Google Pay
• GOOGLE_PAY_CARD_BINDING – Оплата по связке с помощью нетокенизированной карты Google Pay
• GOOGLE_PAY_TOKENIZED – Оплата токенизированной картой Google Pay
• GOOGLE_PAY_TOKENIZED_BINDING – Оплата по связке с помощью токенизированной карты Google Pay
• SBP_C2B – Оплата СБП (Система быстрых платежей) для C2B
• SBP_C2B_BINDING – Оплата через СБП (Система быстрых платежей) по связке для C2B
• SBP_B2C – Оплата СБП (Система быстрых платежей) для B2C
• TOKEN_PAY – Оплата токеном напрямую
• TOKEN_PAY_BINDING – Оплата через токенизированную связку
• MIR_PAY – Оплата Мир Pay с использованием токенизированной криптограммы
• MIR_PAY_BINDING – Оплата Мир Pay по связке

Описание параметров в объекте массива ofdOrderBundle:

Массив itemAttributes состоит из объектов:

• paymentMethod - тип платежа. Обязателен, если передан при регистрации. Возможны следующие значения:

  • 1 - полная предварительная оплата до момента передачи предмета расчета;
  • 2 - частичная предварительная оплата до момента передачи предмета расчета;
  • 3 - аванс;
  • 4 - полная оплата в момент передачи предмета расчёта;
  • 5 - частичная оплата предмета расчёта в момент его передачи с последующей оплатой в кредит;
  • 6 - передача предмета расчёта без его оплаты в момент его передачи с последующей оплатой в кредит;
  • 7 - оплата предмета расчёта после его передачи с оплатой в кредит.

  Приоритезация передачи значения происходит по следующему принципу (указано в убывающем порядке приоритета):
  

  1. Корзина заказа из API-запроса.
     
  2. Настройки фискализации в личном кабинете.
     
  3. Значения по умолчанию.

  Для paymentMethod значением по умолчанию является 1 (полная предварительная оплата до момента передачи предмета расчета).

• paymentObject - Объект платежа. Обязателен, если передан при регистрации. Возможны следующие значения:

  • 1 - товар;
  • 2 - подакцизный товар;
  • 3 - работа;
  • 4 - услуга;
  • 5 - ставка азартной игры;
  • 6 - выигрыш азартной игры;
  • 7 - лотерейный билет;
  • 8 - выигрыш лотереи;
  • 9 - предоставление РИД;
  • 10 - платёж;
  • 11 - агентское вознаграждение;
  • 12 - составной предмет расчёта;
  • 13 - иной предмет расчёта;
  • 14 - имущественное право;
  • 15* - внереализационный доход;
  • 16* - страховые взносы: о суммах расходов, уменьшающих сумму налога (авансовых платежей) в соответствии с пунктом 3.1 статьи 346.21 Налогового кодекса Российской Федерации;
  • 17 - торговый сбор: о суммах уплаченного торгового сбора;
  • 18 - курортный сбор.

  Приоритезация передачи значения происходит по следующему принципу (указано в убывающем порядке приоритета):
  

  1. Корзина заказа из API-запроса.
     
  2. Настройки фискализации в личном кабинете.
     
  3. Значения по умолчанию.

  Для paymentObject значением по умолчанию является 1 (товар).

Описание параметров в объекте quantity:

Возможные значения параметра name:

• При передаче признака предмета расчета paymentObject=15 параметр name должен содержать одно из значений от 1 до 25.
• При передаче признака предмета расчета paymentObject=16 параметр name должен содержать одно из значений от 26 до 31.

Возможные значения tii (Подробнее о типах связок, поддерживаемых платежным шлюзом, читайте здесь).

Блок refunds содержит следующие параметры.

Блок attributes cодержит информацию о номере заказа в платежном шлюзе. Параметр name всегда принимает значение mdOrder, а параметр value - номер заказа в платежной системе.

Блок transactionAttributes содержит набор дополнительных атрибутов транзакции. Используется для версии 14 и выше. Ниже приведен список включенных параметров.

блок merchantOrderParams передается в ответе, если в заказе есть дополнительные параметры мерчанта. Каждый дополнительный параметр передается в отдельном элементе merchantOrderParams.

Некоторые предопределенные параметры в merchantOrderParams:

• originalResponseCode - оригинальный код ответа, полученный от НСПК. Присутствует, если был передан НСПК в ответ на запросы оплаты, регистрации или завершения заказа.

В элементе cardAuthInfo лежит структура, состоящая из списка элемента secureAuthInfo и следующих параметров.

Элемент secureAuthInfo состоит из следующих элементов (параметры cavv и xid включены в элемент threeDSInfo).

Элемент bindingInfo содержит следующие параметры.

Элемент paymentAmountInfo содержит следующие параметры.

Элемент bankInfo содержит следующие параметры.

Элемент payerData содержит следующие параметры.

Блок efectyOrderInfo содержит следующие параметры.

Элемент pluginInfo (объект JSON) присутствует в ответе, если оплата была произведена через платежный плагин. Содержит следующие параметры.

Описание параметров в объекте orderBundle:

Описание параметров в объекте loyalties:

Описание параметров в объекте customerDetails:

Проверка данных плательщика при передаче корзины

Согласно требованиям ФНС, при передаче ФИО плательщика должно быть передано либо ИНН плательщика, либо его паспортные данные.

В связи с этим, если в запросе с продуктовой корзиной передается какой-либо из параметров (в блоках orderBundle или additionalOfdParams):

• Полное имя – customerDetails.fullname или client.name
• ИНН – customerDetails.inn или client.inn
• Данные документа – customerDetails.passport или client.passport_number
• Код документа – client.document_code
• Дата рождения – client.birth_date
• Гражданство – client.citizenship

то выполняется проверка на обязательное наличие ИНН плательщика ИЛИ набора параметров Дата рождения, Код документа, Данные документа. Если это условие не выполняется, запрос будет обработан с ошибкой.

Описание параметров в объекте deliveryInfo:

Описание параметров в объекте cartItems:

Описание параметров в объекте items:

Описание параметров в объекте quantity:

Описание параметров в объекте itemDetails:

Описание параметров объекта tax:

Описание параметров в объекте itemAttributes:

Параметр itemAttributes должен содержать массив attributes, а уже в этом массиве расположены атрибуты товарной позиции (см. пример и таблицу ниже).

"itemAttributes":{"attributes":[{"name":"paymentMethod","value":"1"},{"name":"paymentObject","value":"1"}]}

Описание параметров в объекте agent_info:

Описание параметров в объекте paying:

Описание параметров в объекте paymentsOperator:

Описание параметров в объекте MTOperator:

Описание параметров в объекте supplier_info: