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

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

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

Скачать коллекцию Postman

Вы также можете использовать наш Server Side SDK для выполнения запросов API.

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

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

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

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

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

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

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

Обязательность	Название	Тип	Описание
Условие	`userName`	String [1..100]	Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Условие	`password`	String [1..200]	Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

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

Обязательность	Название	Тип	Описание
Условие	`token`	String [1..256]	Значение, используемое для аутентификации продавца при отправке запросов платежному шлюзу. Если вы передаете этот параметр, то не передавайте `userName` и `password`.

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

TEST: https://vtb.rbsuat.com/payment/rest/
PROD: https://platezh.vtb24.ru/payment/rest/

Ошибки

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

200 - в случае вызовов API платежного шлюза необходимо проанализировать JSON из ответа, чтобы определить, была ли обработка транзакции успешной или нет. Успех обозначается либо:
- значением параметра success равным true
- значеним параметра errorCode равным 0
Если присутствуют оба параметра, success имеет приоритет над errorCode.
400 - в системе произошла внутренняя ошибка.
404 - ошибка при вызове API - неверный URL (не существует).
429 - этот код означает, что система перегружена. Чаще всего основная причина в том, что достигнут лимит запросов в секунду или лимит одновременных запросов. Но также может быть связано с тем, что система в целом перегружена (независимо от ваших запросов).
500 или 502 - этот код означает, что что-то пошло не так на нашей стороне.

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

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

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

В случае orderStatus = 1, заказ необходимо завершить (произвести списание средств). В противном случае деньги будут возвращены владельцу карты (примерно через неделю).

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

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

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

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

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

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

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

openssl genrsa -des3 -out private.key 2048
Создайте общедоступный CSR (запрос на подпись сертификата), используя сгенерированный закрытый ключ:

openssl req -key private.key -new -out public.csr
Создайте сертификат, используя сгенерированный закрытый ключ и CSR. Пример формирования сертификата на 5 лет:

openssl x509 -signkey private.key -in public.csr -req -days 1825 -out public.cer
Загрузите сгенерированный сертификат в Личный кабинет. Для этого перейдите в Сертификаты кошельков > Merchant API, нажмите Добавить сертификат и загрузите сгенерированный общедоступный сертификат.

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

Рассчитайте хеш SHA256 тела запроса следующим образом:
1. Используйте тело запроса в виде строки (в нашем примере это amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api).
2. Вычислите хэш SHA256 из этой строки в необработанных байтах.
3. Преобразуйте необработанные байты в кодировку base64.
Сгенерируйте подпись для вычисленного хеша 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://vtb.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 должен иметь формат:

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

Начните работу с API Sandbox создав учетную запись или войдя в систему.

Для регистрации заказа используется запрос register.do.

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

Обязательность	Название	Тип	Описание
Условие	`userName`	String [1..100]	Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Условие	`password`	String [1..200]	Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Условие	`token`	String [1..256]	Значение, используемое для аутентификации продавца при отправке запросов платежному шлюзу. Если вы передаете этот параметр, то не передавайте `userName` и `password`.

Обязательно	`orderNumber`	String [1..32]	Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа.

Обязательно	`amount`	Integer [0..12]	Сумма платежа в минимальных единицах валюты (например, в копейках).

Необязательно	`currency`	Integer [3]	Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию.

Обязательно	`returnUrl`	String [1..512]	Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, `https://mybestmerchantreturnurl.com` вместо `mybestmerchantreturnurl.com`). В противном случае пользователь будет перенаправлен по адресу следующего вида: `https://vtb.rbsuat.com/payment/<merchant_address>`.

Необязательно	`failUrl`	String [1..512]	Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, `https://mybestmerchantreturnurl.com` вместо `mybestmerchantreturnurl.com`). В противном случае пользователь будет перенаправлен по адресу следующего вида: `https://vtb.rbsuat.com/payment/<merchant_address>`. Адрес не должен быть относительным путем, т.е. он не должен начинаться с "." и "/". В противном случае будет возвращена ошибка 4: "The return URL is invalid". Например: ../test.html, /test.html — неверные URL-адреса.

Необязательно	`dynamicCallbackUrl`	String [1..512]	Параметр для передачи динамического адреса для получения "платежных" callback-уведомлений по заказу, активированных для мерчанта (успешная авторизация, успешное списание, возврат, отмена, отклонение платежа по таймауту, отклонение card present платежа). "Не платежные" callback-уведомления (включение/выключение связки, создание связки), будут отправляться на статический callback адрес.

Необязательно	`description`	String [1..598]	Описание заказа в любом формате. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки.

Необязательно	`language`	String [2]	Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: `ru,en`.

Необязательно	`ip`	String [1..39]	IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). При использовании аутентификации 3DS 2 рекомендуем вам передавать в этом параметре реальный IP адрес клиента. Это позволит повысить конверсию в оплату на стороне ACS.

Необязательно	`clientId`	String [0..255]	Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен.

Необязательно	`merchantLogin`	String [1..255]	Чтобы зарегистрировать заказ от имени другого мерчанта, укажите его логин (для API-аккаунта) в этом параметре. Можно использовать, только если у вас есть разрешение на просмотр транзакций других продавцов или если указанный продавец является вашим дочерним продавцом.

Необязательно	`jsonParams`	Object	Набор дополнительных параметров произвольной формы, структура: `{name1:value1,…,nameN:valueN}` Некоторые предопределенные атрибуты jsonParams: `email` - электронная почта держателя карты для предварительного заполнения на странице оформления заказа `phone` - номер телефона держателя карты для выставления счетов для предварительного заполнения на странице оформления заказа `backToShopUrl` - добавляет на страницу оплаты кнопку, которая вернет держателя карты на назначенный URL-адрес веб-сайта продавца. `backToShopName` - настраивает текстовую метку кнопки Вернуться в магазин по умолчанию, если она используется вместе с `backToShopUrl` `installments` - максимальное количество разрешенных авторизаций для платежей в рассрочку. Требуется для создания связки рассрочки. `recurringFrequency` - минимальное количество дней между авторизациями. Требуется для создания рекуррентной связки, рекомендуется для создания связки рассрочки (если используется 3DS2, параметр обязателен). `recurringExpiry` - дата, после которой авторизации не разрешены, в формате ГГГГММДД. Требуется для создания рекуррентной связки, рекомендуется для создания связки рассрочки (если используется 3DS2, параметр обязателен).

Необязательно	`sessionTimeoutSecs`	Integer [1..9]	Продолжительность жизни заказа в секундах. В случае если параметр не задан, будет использовано значение, указанное в настройках мерчанта или время по умолчанию (1200 секунд = 20 минут). Если в запросе присутствует параметр `expirationDate`, то значение параметра `sessionTimeoutSecs` не учитывается.

Необязательно	`expirationDate`	String	Дата и время истечения срока действия заказа. Формат: `yyyy-MM-ddTHH:mm:ss`. Если этот параметр не передается в запросе, то для определения времени истечения срока действия заказа используется параметр `sessionTimeoutSecs`.

Необязательно	`bindingId`	String [1..255]	Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что: Этот заказ можно оплатить только с помощью связки; Плательщик будет перенаправлен на страницу оплаты, где требуется только ввод CVC.

Необязательно	`features`	String	Функции заказа Ниже приведены возможные значения. `VERIFY` - если передать это значение в запросе на оформление заказа, владелец карты будет верифицирован, однако никакого списания средств не произойдет, так что в этом случае параметр `amount` может иметь значение `0`. Верификация позволяет убедиться, что карта находится в руках владельца, и впоследствии списывать с этой карты средства, не прибегая к проверке аутентификационных данных (CVC, 3D-Secure) при совершении последующих платежей. Даже если сумма платежа будет передана в запросе, она не будет списана со счета клиента при передаче значения `VERIFY`. После успешной регистрации заказ сразу переводится в статус `REVERSED` (отменен). Это значение также можно использовать для создания cвязки — в этом случае параметр `clientId` также должен быть передан. Подробнее читайте здесь. `FORCE_TDS` - Принудительное проведение платежа с использованием 3-D Secure. Если карта не поддерживает 3-D Secure, транзакция не пройдет. `FORCE_SSL` - Принудительное проведение платежа через SSL (без использования 3-D Secure). `FORCE_FULL_TDS` - После проведения аутентификации с помощью 3-D Secure статус PaRes должен быть только `Y`, что гарантирует успешную аутентификацию пользователя. В противном случае транзакция не пройдет. `FORCE_CREATE_BINDING` - передача этого значения в запросе на оформление заказа принудительно создает связку. Эта функциональность должна быть включена на уровне продавца в шлюзе. Это значение нельзя передать в запросе с существующим `bindingId` или же `bindingNotNeeded = true` (вызовет ошибку проверки). Когда эта функция передается, параметр `clientId` также должен быть передан. Если в блоке `features` переданы оба значения `FORCE_CREATE_BINDING` и `VERIFY`, то заказ будет создан ТОЛЬКО для создание связки (без оплаты).

Необязательно	`postAddress`	String [1..255]	Адрес доставки.

Необязательно	`orderBundle`	Object	Объект, содержащий корзину товаров. Описание вложенных элементов приведено ниже.

Необязательно	`additionalOfdParams`	Object	Некоторые параметры `additionalOfdParams` дублируются в `cartItems.items.itemAttributes`. `additionalOfdParams` применяется ко всем идентификаторам позиций, а `cartItems.items.itemAttributes` применяется к каждой отдельной позиции. Если значения `additionalOfdParams` и `cartItems.items.itemAttributes` не совпадают, тогда `cartItems.items.itemAttributes` (то есть, параметры отдельной позиции) будут иметь приоритет.

Необязательно	`taxSystem`	Integer	Система налогообложения, доступны следующие значения:: `0` - общая; `1` - упрощенная, доход; `2` - упрощенная, доходы минус расходы; `3` - единый налог на вмененный доход; `4` - единый сельскохозяйственный налог; `5` - патентная система налогообложения.
Необязательно	`feeInput`	String	Размер комиссии в минимальных единицах валюты. Функциональность должна быть включена на уровне продавца в шлюзе.

Необязательно	`billingPayerData`	Object	Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры.

Необязательно	`shippingPayerData`	Object	Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.

Необязательно	`preOrderPayerData`	Object	Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.

Необязательно	`orderPayerData`	Object	Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.

Необязательно	`billingAndShippingAddressMatchIndicator`	A1	Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. Возможные значения: `Y` - совпадение платежного адреса держателя карты и адреса доставки; `N` - платежный адрес владельца карты и адрес доставки не совпадают.

Использование jsonParams

Вы можете использовать блок jsonParams для передачи дополнительной информации о заказе для ее дальнейшего использования и хранения. Посмотреть дополнительные параметры можно в консоли мерчанта платежного шлюза.

Дополнительные параметры передаются следующим образом {"<name1>":"<value1>",...,"<nameN>":"<valueN>"} Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах.

В качестве дополнительных параметров в том числе возможно передать следующие:

Имя Тип данных Обязательность	Описание	Пример
`email` ANS..255 Условно обязательно	Электронная почта, которая будет отображаться на странице оплаты. Если для продавца настроено уведомление клиента, должна быть передана электронная почта клиента.	`{"email": "client_mail@email.com"}`
`phone` AN..11 Обязательно	Номер телефона клиента - он будет отображаться на странице оплаты	`{"phone": "9001234567"}`
`backToShopUrl` ANS..255 Опционально	Для отображения кнопки, позволяющей покупателю вернуться в интернет-магазин, в этом параметре необходимо указать адрес магазина.	`{"backToShopUrl": "https://mybestmerchantreturnurl.com"}`
`backToShopName` ANS..255 Условно обязательно	Название кнопки, позволяющей покупателю вернуться обратно в интернет-магазин (если используется параметр `backToShopUrl`)	`{"backToShopName": "Cancel"}`

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

Обязательность	Название	Тип	Описание
Необязательно	`billingCity`	String [0..50]	Город, зарегистрированный по конкретной карте у Банка Эмитента.

Необязательно	`billingCountry`	String [0..50]	Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой).

Необязательно	`billingAddressLine1`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки.

Необязательно	`billingAddressLine2`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2.

Необязательно	`billingAddressLine3`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3.

Необязательно	`billingPostalCode`	String [0..9]	Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки.

Необязательно	`billingState`	String [0..50]	Штат, зарегистрированный по конкретной карте у Банка Эмитента.

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

Обязательность	Название	Тип	Описание
Необязательно	`shippingCity`	ANS...50	Город заказчика (из адреса доставки)
Необязательно	`shippingCountry`	ANS...50	Страна заказчика
Необязательно	`shippingAddressLine1`	ANS...50	Основной адрес клиента (из адреса доставки)
Необязательно	`shippingAddressLine2`	ANS...50	Основной адрес клиента (из адреса доставки)
Необязательно	`shippingAddressLine3`	ANS...50	Основной адрес клиента (из адреса доставки)
Необязательно	`shippingPostalCode`	ANS...16	Почтовый индекс клиента для доставки
Необязательно	`shippingState`	ANS...50	Штат/регион покупателя (из адреса доставки)
Необязательно	`shippingMethodIndicator`	N2	Индикатор способа доставки. Возможные значения: `01` - доставка на платежный адрес держателя карты. `02` - доставка на другой адрес, проверенный Мерчантом. `03` - доставка по адресу, отличному от основного адреса держателя карты. `04` - отправка в магазин/самовывоз (адрес магазина должен быть указан в соответствующих параметрах доставки) `05` - Цифровое распространение (включает онлайн-сервисы и электронные подарочные карты) `06` - билеты на путешествия и мероприятия, которые нельзя доставить. `07` - Прочее (например, игры, цифровые товары, не подлежащие доставке, цифровые подписки и т. д.)
Необязательно	`deliveryTimeframe`	N2	Срок поставки товара. Возможные значения: `01` - цифровая дистрибуция `02` - доставка в тот же день `03` - доставка на следующий день `04` - доставка в течение 2-х дней после оплаты и позже.
Необязательно	`deliveryEmail`	ANS...254	Целевой адрес электронной почты для доставки цифрового распространения

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

Обязательность	Название	Тип	Описание
Необязательно	`preOrderDate`	ANS8	Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД.
Необязательно	`preOrderPurchaseInd`	N2	Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения: `01` - возможна доставка; `02` - будущая доставка
Необязательно	`reorderItemsInd`	N2	Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения: `01` - заказ размещается впервые; `02` - повторный заказ

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

Обязательность	Название	Тип	Описание
Необязательно	`homePhone`	ANS...19	Домашний телефон владельца карты с обязательным знаком «+».
Необязательно	`workPhone`	ANS...19	Рабочий телефон владельца карты с обязательным знаком «+».
Необязательно	`mobilePhone`	ANS...19	Номер мобильного телефона владельца карты с обязательным знаком «+».

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

Обязательность	Название	Тип	Описание
Необязательно	`orderCreationDate`	String	Дата создания заказа в формате `YYYY-MM-DDTHH:MM:SS`.

Необязательно	`customerDetails`	Object	Блок, содержащий атрибуты клиента. Описание атрибутов тега приведено ниже.
Необязательно	`cartItems`	Object	Объект, содержащий атрибуты товаров в корзине. Описание вложенных элементов приведено ниже.

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

Обязательность	Название	Тип	Описание
Условие	`email`	String	Электронный адрес клиента. Можно указать несколько адресов электронной почты через запятую и без пробелов. Обязательно следует передать один из двух параметров: `email` или `phone`.

Условие	`phone`	String	Номер телефона покупателя. Всегда нужно указывать код страны, при этом можно указывать или не указывать знак `+`. Таким образом, допустимы следующие варианты: `+449998887766`; `449998887766`. Допустимое количество цифр: от 7 до 15.

Необязательно	`contact`	String [0..40]	Предпочитаемый клиентом способ связи.

Необязательно	`fullName`	String [1..100]	ФИО плательщика.

Необязательно	`passport`	Integer	Серия и номер паспорта плательщика в следующем формате: `2222888888`

Необязательно	`deliveryInfo`	Object	Объект, содержащий атрибуты адреса доставки. Описание вложенных элементов приведено ниже.

Необязательно	`inn`	Integer [10..12]	Индивидуальный номер налогоплательщика. 10 или 12 символов.

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

Обязательность	Название	Тип	Описание
Необязательно	`deliveryType`	String [1..20]	Способ доставки.

Обязательно	`country`	String	Двухбуквенный код страны доставки.

Обязательно	`city`	String [0..40]	Город назначения.

Обязательно	`postAddress`	String [1..255]	Адрес доставки.

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

Обязательность	Название	Тип	Описание
Обязательно	`items`	Object	Элемент массива с атрибутами товарной позиции. Описание вложенных элементов приведено ниже.

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

Обязательность	Название	Тип	Описание
Обязательно	`positionId`	Integer [1..12]	Уникальный идентификатор товарной позиции в корзине.

Обязательно	`name`	String [1..255]	Наименование или описание товарной позиции в свободной форме.

Необязательно	`itemDetails`	Object	Объект с параметрами описания товарной позиции. Описание вложенных элементов приведено ниже.

Обязательно	`quantity`	Object	Элемент, описывающий передается общее количество товарных позиций одного `positionId` и его единицы измерения. Описание вложенных элементов приведено ниже.

Необязательно	`itemAmount`	Integer [1..12]	Сумма стоимости всех товарных позиций одного `positionId` в минимальных единицах валюты. `itemAmount` обязателен к передаче, только если не был передан параметр `itemPrice`. В противном случае передача `itemAmount` не требуется. Если же в запросе передаются оба параметра: `itemPrice` и `itemAmount`, то `itemAmount` должен равняться , в противном случае запрос завершится с ошибкой.

Необязательно	`itemPrice`	Integer [1..18]	Сумма стоимости товарной позиции одного `positionId` в деньгах в минимальных единицах валюты. Обязательно для мерчантов, использующих фискализацию.

Необязательно	`itemCurrency`	Integer	Код валюты ISO 4217. Если не указан, считается равным валюте заказа.

Обязательно	`itemCode`	String [1..100]	Номер (идентификатор) товарной позиции в системе магазина.

Необязательно	`discount`	Object	Объект, содержащий атрибуты скидки на товарную позицию. Описание вложенных элементов приведено ниже.

Необязательно	`agentInterest`	Object	Объект, содержащий атрибуты описания агентского вознаграждения за продажу товаров. Описание вложенных элементов приведено ниже.

Необязательно	`tax`	Object	Объект, содержащий атрибуты налога. Ниже приведено описание содержащихся атрибутов.

Необязательно	`itemAttributes`	Object	Объект, содержащий атрибуты товарной позиции.

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

Обязательность	Название	Тип	Описание
Обязательно	`value`	String	Количество товарных позиций данного `positionId`. Для указания дробных чисел используйте десятичную точку. При ФФД 1.2+ значение `value` всегда `1`.

Обязательно	`measure`	String [1..20]	Единица измерения количества по позиции. Для ФФД 1.2+, если переданы параметры `nomenclature` и `markQuantity`, `measure` всегда равно `0`. Для других ФФД возможны иные значения.

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

Обязательность	Название	Тип	Описание
Необязательно	`itemDetailsParams`	Object	Параметр, описывающий дополнительную информацию по товарной позиции. Описание вложенных элементов приведено ниже.

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

Обязательность	Название	Тип	Описание
Обязательно	`value`	String	Дополнительная информация по товарной позиции.

Обязательно	`name`	String [1..255]	Наименование параметра описания детализации товарной позиции

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

Обязательность	Название	Тип	Описание
Обязательно	`discountType`	String [1..20]	Тип скидки на товарную позицию

Обязательно	`discountValue`	Integer [0..20]	Значение скидки на товарную позицию.

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

Обязательность	Название	Тип	Описание
Обязательно	`interestType`	String [1..20]	Тип агентской комиссии.

Обязательно	`interestValue`	Integer [1..20]	Значение агентской комиссии.

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

Обязательность	Название	Тип	Описание
Обязательно	`taxType`	Integer	Ставка НДС, доступны следующие значения: `0` – без НДС; `1` – НДС по ставке 0%; `2` – НДС чека по ставке 10%; `4` – НДС чека по расчетной ставке 10/110; `6` – НДС чека по ставке 20%; `7` – НДС чека по расчетной ставке 20/120.

Обязательно	`taxSum`	Integer [1..18]	Сумма налога рассчитанная продавцом. Значение указывается в минимальных единицах валюты.

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

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

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

Обязательность	Название	Тип	Описание
Обязательно	`paymentMethod`	Integer	Тип платежа, доступные значения: `1` - полная предоплата; `2` - частичная предоплата; `3` - аванс; `4` - полная оплата; `5` - частичная оплата с последующей оплатой в кредит; `6` - без оплаты с последующей оплатой в кредит; `7` - оплата с последующей оплатой в кредит.

Обязательно	`paymentObject`	Integer	Объект платежа, доступные значения: `1` - товар (значение по умолчанию); `2` - подакцизный товар; `3` - работа; `4` - услуга; `5` - ставка азартной игры; `6` - выигрыш азартной игры; `7` - лотерейный билет; `8` - выигрыш лотереи; `9` - предоставление РИД; `10` - платеж; `11` - агентское вознаграждение; `12` - составной предмет расчета; `13` - иной предмет расчета; `14` - имущественное право; `15` - внереализационный доход; `16` - страховые взносы: о суммах расходов, уменьшающих сумму налога (авансовых платежей) в соответствии с пунктом 3.1 статьи 346.21 Налогового кодекса Российской Федерации; `17` - торговый сбор: о суммах уплаченного торгового сбора; `18` - курортный сбор. Указанные выше значения доступны для ФФД 1.05. Для ФФД 1.2 список доступных значений пополняется также следующими значениями: `30` - подакцизный товар, подлежащий маркировке средством идентификации, не имеющий кода маркировки `31` - подакцизный товар, подлежащий маркировке средством идентификации, имеющий код маркировки `32` - товар, подлежащий маркировке средством идентификации, имеющий код маркировки, за исключением подакцизного товара `33` - товар, подлежащий маркировке средством идентификации, имеющий код маркировки, за исключением подакцизного товара Приоритезация передачи значения происходит по следующему принципу (указано в убывающем порядке приоритета): 1) корзина заказа из API-запроса; 2) настройки фискализации в личном кабинете; 3) значения по умолчанию

Условие	`nomenclature`	String	Код товарной номенклатуры в шестнадцатеричном представлении с пробелами. Максимальная длина – 32 байта. Обязательно, если передано `markQuantity`.

Необязательно	`markQuantity`	Object	Дробное количество маркируемого товара. См. вложенные параметры.

Необязательно	`userData`	String [1..64]	Значение реквизита пользователя. Можно передавать только после согласования с ФНС.

Необязательно	`agent_info`	Object	Объект с данными о платежном агенте для товарной позиции.

Условие*	`agent_info.type`	Integer	Тип агента, доступные значения: `1` - банковский платежный агент; `2` - банковский платежный субагент; `3` - платежный агент; `4` - платежный субагент; `5` - поверенный; `6` - комиссионер; `7` - иной агент.

Необязательно	`agent_info.paying`	Object	Объект с данными о платежном агенте.

Необязательно	`agent_info.paying.operation`	String [1..24]	Название транзакции платежного агента.

Необязательно	`agent_info.paying.phones`	Array of strings	Массив телефонных номеров платежного агента в формате +N.

Необязательно	`agent_info.paymentsOperator`	Object	Объект с информацией об операторе по приему платежей.

Необязательно	`agent_info.paymentsOperator.phones`	Array of strings	Массив телефонных номеров платежного агента в формате +N.

Необязательно	`agent_info.MTOperator`	Object	Объект с данными об Операторе перевода.

Необязательно	`agent_info.MTOperator.phones`	Array of strings	Массив телефонных номеров оператора перевода в формате +N.

Необязательно	`agent_info.MTOperator.address`	String [1..256]	Наименование оператора перевода.

Необязательно	`agent_info.MTOperator.address`	String [1..256]	Адрес оператора перевода.

Необязательно	`agent_info.MTOperator.inn`	String [10..12]	ИНН оператора перевода.

Необязательно	`supplier_info`	Object	Объект с данными о поставщике для товарной позиции.

Необязательно	`supplier_info.phones`	Array of strings	Массив телефонных номеров поставщика в формате +N.

Необязательно	`supplier_info.name`	String	Наименование поставщика.

Необязательно	`supplier_info.inn`	String	ИНН поставщика

Необязательно	`supplier_info.documentId`	String	Уникальный идентификатор платежного документа в системе поставщика.

Необязательно	`supplier_info.payerName`	String	ФИО плательщика.

Необязательно	`supplier_info.payerLs`	String	Лицевой счет плательщика в системе поставщика.

Необязательно	`supplier_info.ls`	String	Единый лицевой счет поставщика.

Необязательно	`supplier_info.bankBic`	String	БИК банка получателя, поставщика.

Необязательно	`supplier_info.kpp`	String	Код причины постановки на учет (КПП) получателя платежа, поставщика.

Необязательно	`supplier_info.kpp`	String	Код причины постановки на учет (КПП) получателя платежа, поставщика.

Необязательно	`supplier_info.rs`	String	Банковский счет получателя платежа, поставщика.

Необязательно	`supplier_info.commission`	String	Размер комиссии в минимальных денежных единицах на стороне поставщика.

* Обязателен, если передается agent_info.

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

Значение	Описание
0	Применяется к позициям, которые могут быть реализованы индивидуально или отдельными единицами, а также если объект платежа является предметом, подлежащим обязательной идентификационной маркировке.
10	Грамм
11	Килограмм
12	Тонна
20	Сантиметр
21	Дециметр
22	Метр
30	Квадратный сантиметр
31	Квадратный дециметр
32	Квадратный метр
40	Миллилитр
41	Литр
42	Кубический метр
50	Киловатт час
51	Гигакалория
70	День
71	Час
72	Минута
73	Секунда
80	Килобайт
81	Мегабайт
82	Гигабайт
83	Терабайт
255	Применяется к другим единицам измерения

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

Обязательность	Название	Тип	Описание
Обязательно	`numerator`	String	Числитель дробной части объекта платежа.

Обязательно	`denominator`	String	Знаменатель дробной части объекта платежа.

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

Обязательность	Название	Тип	Описание
Необязательно	`agent_info.type`	Integer	Тип агента, доступные значения: `1` - банковский платежный агент; `2` - банковский платежный субагент; `3` - платежный агент; `4` - платежный субагент; `5` - поверенный; `6` - комиссионер; `7` - иной агент.

Необязательно	`agent_info.paying.operation`	String [1..24]	Название транзакции платежного агента.

Необязательно	`agent_info.paying.phones`	Array of strings	Массив телефонных номеров платежного агента в формате +N.

Необязательно	`agent_info.paymentsOperator.phones`	Array of strings	Массив телефонных номеров платежного агента в формате +N.

Необязательно	`agent_info.MTOperator.address`	String [1..256]	Адрес оператора перевода.

Необязательно	`agent_info.MTOperator.inn`	String [10..12]	ИНН оператора перевода.

Необязательно	`agent_info.MTOperator.address`	String [1..256]	Наименование оператора перевода.

Необязательно	`agent_info.MTOperator.phones`	Array of strings	Массив телефонных номеров оператора перевода в формате +N.

Необязательно	`supplier_info.phones`	Array of strings	Массив телефонных номеров поставщика в формате +N.

Необязательно	`cashier`	String [1..256]	Имя кассира.

Необязательно	`additional_check_props`	String [1..16]	Дополнительные свойства чека.

Необязательно	`additional_user_props.name`	String [1..24]	Название дополнительного свойства пользователя

Необязательно	`additional_user_props.value`	String [1..24]	Значение дополнительного свойства пользователя

Необязательно	`cashier_inn`	String [10..12]	ИНН кассира.

Необязательно	`client.address`	String [1..256]	Адрес клиента.

Необязательно	`client.birth_date`	String [10]	Дата рождения клиента в формате дд.мм.гггг.

Необязательно	`client.citizenship`	String [3]	Цифровой код страны, гражданином которой является покупатель (клиент).

Необязательно	`client.document_code`	String [2]	Цифровой код вида документа, удостоверяющего личность (например, 21 - паспорт гражданина РФ).

Необязательно	`client.passport_number`	String [11]	Серия и номер паспорта плательщика.

Необязательно	`client.email`	String [1..64]	Электронная почта плательщика. Обязательно заполнение строго одного из полей: электронная почта или телефон.

Необязательно	`client.phone`	String [19]	Телефон покупателя. Вместе с кодом страны без пробелов и дополнительных символов, кроме символа «+» (номер «+371 2 1234567» следует передавать как «+37121234567»). Обязательно заполнение строго одного из полей: электронная почта или телефон.

Необязательно	`client.inn`	String [12]	ИНН клиента.

Необязательно	`client.name`	String [1..256]	Имя клиента.

Необязательно	`operatingcheckprops.name`	String	Идентификатор транзакции. Принимает значения "0" до тех пор, пока не будет определено значение реквизита ФНС России.

Необязательно	`operatingcheckprops.timestamp`	String [1..19]	Дата и время операции в формате: дд.мм.гггг ЧЧ:ММ:СС.

Необязательно	`operatingcheckprops.value`	String [1..64]	Данные транзакции.

Необязательно	`sectoralcheckprops.date`	String [10]	Дата принятия нормативного акта федерального органа исполнительной власти, регулирующего порядок заполнения "значения отраслевого реквизита", в формате: дд.мм.гггг.

Необязательно	`sectoralcheckprops.federalid`	String	Идентификатор федерального органа исполнительной власти. Должен принимать одно из значений из справочника федеральных органов исполнительной власти.

Необязательно	`sectoralcheckprops.number`	String [32]	Номер нормативного акта федерального органа исполнительной власти, регламентирующего порядок заполнения реквизита «значение отраслевого реквизита»

Необязательно	`sectoralcheckprops.value`	String [1..256]	Состав значений, определенных нормативным актом федерального органа исполнительной власти

Условие	`company.automat_number`	String	Номер автомата. Условия обязательной передачи параметров: Формат фискальных документов 1.05 – для вендинга и транспорта; Формат фискальных документов 1.2 – для вендинга и транспорта.

Условие	`company.location`	String	Адрес для выставления счета. Условия обязательной передачи параметров: Формат фискальных документов 1.05 – для вендинга, транспорта, курьеров. Формат фискальных документов 1.2 – для вендинга, транспорта, курьеров.

Условие	`company.payment_address`	String	Адрес для получения счетов. Условия обязательной передачи параметров: Формат фискальных документов 1.05 – для вендинга, транспорта, курьеров. Формат фискальных документов 1.2 – для вендинга, транспорта, курьеров.

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

Обязательность	Название	Тип	Описание
Необязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Необязательно	`formUrl`	String [1..512]	URL платежной формы, на которую будет перенаправлен покупатель. URL не возвращается, если регистрация заказа не прошла из-за ошибки, указанной в `errorCode`.

Необязательно	`orderId`	String [1..36]	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/register.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data amount=2000 \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderNumber=1218637308 \
  --data returnUrl=https://mybestmerchantreturnurl.com \
  --data failUrl=https://mybestmerchantfailurl.com \
  --data clientId=259753456 \
  --data language=en

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

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

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

Для запроса регистрации заказа с предавторизацией используется метод registerPreAuth.do.

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

Обязательность	Название	Тип	Описание
Условие	`userName`	String [1..100]	Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Условие	`password`	String [1..200]	Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Условие	`token`	String [1..256]	Значение, используемое для аутентификации продавца при отправке запросов платежному шлюзу. Если вы передаете этот параметр, то не передавайте `userName` и `password`.

Обязательно	`orderNumber`	String [1..32]	Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа.

Обязательно	`amount`	Integer [0..12]	Сумма платежа в минимальных единицах валюты (например, в копейках).

Необязательно	`currency`	Integer [3]	Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию.

Обязательно	`returnUrl`	String [1..512]	Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, `https://mybestmerchantreturnurl.com` вместо `mybestmerchantreturnurl.com`). В противном случае пользователь будет перенаправлен по адресу следующего вида: `https://vtb.rbsuat.com/payment/<merchant_address>`.

Необязательно	`failUrl`	String [1..512]	Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, `https://mybestmerchantreturnurl.com` вместо `mybestmerchantreturnurl.com`). В противном случае пользователь будет перенаправлен по адресу следующего вида: `https://vtb.rbsuat.com/payment/<merchant_address>`. Адрес не должен быть относительным путем, т.е. он не должен начинаться с "." и "/". В противном случае будет возвращена ошибка 4: "The return URL is invalid". Например: ../test.html, /test.html — неверные URL-адреса.

Необязательно	`dynamicCallbackUrl`	String [1..512]	Параметр для передачи динамического адреса для получения "платежных" callback-уведомлений по заказу, активированных для мерчанта (успешная авторизация, успешное списание, возврат, отмена, отклонение платежа по таймауту, отклонение card present платежа). "Не платежные" callback-уведомления (включение/выключение связки, создание связки), будут отправляться на статический callback адрес.

Необязательно	`description`	String [1..598]	Описание заказа в любом формате. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки.

Необязательно	`ip`	String [1..39]	IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). При использовании аутентификации 3DS 2 рекомендуем вам передавать в этом параметре реальный IP адрес клиента. Это позволит повысить конверсию в оплату на стороне ACS.

Необязательно	`language`	String [2]	Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: `ru,en`.

Необязательно	`clientId`	String [0..255]	Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен.

Необязательно	`merchantLogin`	String [1..255]	Чтобы зарегистрировать заказ от имени другого мерчанта, укажите его логин (для API-аккаунта) в этом параметре. Можно использовать, только если у вас есть разрешение на просмотр транзакций других продавцов или если указанный продавец является вашим дочерним продавцом.

Необязательно	`jsonParams`	Object	Набор дополнительных параметров произвольной формы, структура: `{name1:value1,…,nameN:valueN}` Некоторые предопределенные атрибуты jsonParams: `email` - электронная почта держателя карты для предварительного заполнения на странице оформления заказа `phone` - номер телефона держателя карты для выставления счетов для предварительного заполнения на странице оформления заказа `backToShopUrl` - добавляет на страницу оплаты кнопку, которая вернет держателя карты на назначенный URL-адрес веб-сайта продавца. `backToShopName` - настраивает текстовую метку кнопки Вернуться в магазин по умолчанию, если она используется вместе с `backToShopUrl` `installments` - максимальное количество разрешенных авторизаций для платежей в рассрочку. Требуется для создания связки рассрочки. `recurringFrequency` - минимальное количество дней между авторизациями. Требуется для создания рекуррентной связки, рекомендуется для создания связки рассрочки (если используется 3DS2, параметр обязателен). `recurringExpiry` - дата, после которой авторизации не разрешены, в формате ГГГГММДД. Требуется для создания рекуррентной связки, рекомендуется для создания связки рассрочки (если используется 3DS2, параметр обязателен).

Необязательно	`sessionTimeoutSecs`	Integer [1..9]	Продолжительность жизни заказа в секундах. В случае если параметр не задан, будет использовано значение, указанное в настройках мерчанта или время по умолчанию (1200 секунд = 20 минут). Если в запросе присутствует параметр `expirationDate`, то значение параметра `sessionTimeoutSecs` не учитывается.

Необязательно	`expirationDate`	String	Дата и время истечения срока действия заказа. Формат: `yyyy-MM-ddTHH:mm:ss`. Если этот параметр не передается в запросе, то для определения времени истечения срока действия заказа используется параметр `sessionTimeoutSecs`.

Необязательно	`bindingId`	String [1..255]	Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что: Этот заказ можно оплатить только с помощью связки; Плательщик будет перенаправлен на страницу оплаты, где требуется только ввод CVC.

Необязательно	`features`	String	Функции заказа Ниже приведены возможные значения. `VERIFY` - если передать это значение в запросе на оформление заказа, владелец карты будет верифицирован, однако никакого списания средств не произойдет, так что в этом случае параметр `amount` может иметь значение `0`. Верификация позволяет убедиться, что карта находится в руках владельца, и впоследствии списывать с этой карты средства, не прибегая к проверке аутентификационных данных (CVC, 3D-Secure) при совершении последующих платежей. Даже если сумма платежа будет передана в запросе, она не будет списана со счета клиента при передаче значения `VERIFY`. После успешной регистрации заказ сразу переводится в статус `REVERSED` (отменен). Это значение также можно использовать для создания cвязки — в этом случае параметр `clientId` также должен быть передан. Подробнее читайте здесь. `FORCE_TDS` - Принудительное проведение платежа с использованием 3-D Secure. Если карта не поддерживает 3-D Secure, транзакция не пройдет. `FORCE_SSL` - Принудительное проведение платежа через SSL (без использования 3-D Secure). `FORCE_FULL_TDS` - После проведения аутентификации с помощью 3-D Secure статус PaRes должен быть только `Y`, что гарантирует успешную аутентификацию пользователя. В противном случае транзакция не пройдет. `FORCE_CREATE_BINDING` - передача этого значения в запросе на оформление заказа принудительно создает связку. Эта функциональность должна быть включена на уровне продавца в шлюзе. Это значение нельзя передать в запросе с существующим `bindingId` или же `bindingNotNeeded = true` (вызовет ошибку проверки). Когда эта функция передается, параметр `clientId` также должен быть передан. Если в блоке `features` переданы оба значения `FORCE_CREATE_BINDING` и `VERIFY`, то заказ будет создан ТОЛЬКО для создание связки (без оплаты).

Необязательно	`autocompletionDate`	String	Дата и время автоматического завершения двухстадийного платежа в следующем формате: 2017-12-29T13:02:51. Используемый часовой пояс: UTC+3. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки.

Необязательно	`autoReverseDate`	String	Дата и время автоматического отмены двухстадийного платежа в следующем формате: 2022-06-23T13:02:51. Используемый часовой пояс: UTC+3. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки.

Необязательно	`postAddress`	String [1..255]	Адрес доставки.

Необязательно	`orderBundle`	Object	Объект, содержащий корзину товаров. Описание вложенных элементов приведено ниже.

Необязательно	`additionalOfdParams`	Object	Некоторые параметры `additionalOfdParams` дублируются в `cartItems.items.itemAttributes`. `additionalOfdParams` применяется ко всем идентификаторам позиций, а `cartItems.items.itemAttributes` применяется к каждой отдельной позиции. Если значения `additionalOfdParams` и `cartItems.items.itemAttributes` не совпадают, тогда `cartItems.items.itemAttributes` (то есть, параметры отдельной позиции) будут иметь приоритет.

Необязательно	`taxSystem`	Integer	Система налогообложения, доступны следующие значения:: `0` - общая; `1` - упрощенная, доход; `2` - упрощенная, доходы минус расходы; `3` - единый налог на вмененный доход; `4` - единый сельскохозяйственный налог; `5` - патентная система налогообложения.
Необязательно	`feeInput`	String	Размер комиссии в минимальных единицах валюты. Функциональность должна быть включена на уровне продавца в шлюзе.

Необязательно	`billingPayerData`	Object	Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры.

Необязательно	`shippingPayerData`	Object	Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.

Необязательно	`preOrderPayerData`	Object	Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.

Необязательно	`orderPayerData`	Object	Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.

Необязательно	`billingAndShippingAddressMatchIndicator`	A1	Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. Возможные значения: `Y` - совпадение платежного адреса держателя карты и адреса доставки; `N` - платежный адрес владельца карты и адрес доставки не совпадают.

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

Обязательность	Название	Тип	Описание
Необязательно	`billingCity`	String [0..50]	Город, зарегистрированный по конкретной карте у Банка Эмитента.

Необязательно	`billingCountry`	String [0..50]	Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой).

Необязательно	`billingAddressLine1`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки.

Необязательно	`billingAddressLine2`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2.

Необязательно	`billingAddressLine3`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3.

Необязательно	`billingPostalCode`	String [0..9]	Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки.

Необязательно	`billingState`	String [0..50]	Штат, зарегистрированный по конкретной карте у Банка Эмитента.

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

Обязательность	Название	Тип	Описание
Необязательно	`shippingCity`	ANS...50	Город заказчика (из адреса доставки)
Необязательно	`shippingCountry`	ANS...50	Страна заказчика
Необязательно	`shippingAddressLine1`	ANS...50	Основной адрес клиента (из адреса доставки)
Необязательно	`shippingAddressLine2`	ANS...50	Основной адрес клиента (из адреса доставки)
Необязательно	`shippingAddressLine3`	ANS...50	Основной адрес клиента (из адреса доставки)
Необязательно	`shippingPostalCode`	ANS...16	Почтовый индекс клиента для доставки
Необязательно	`shippingState`	ANS...50	Штат/регион покупателя (из адреса доставки)
Необязательно	`shippingMethodIndicator`	N2	Индикатор способа доставки. Возможные значения: `01` - доставка на платежный адрес держателя карты. `02` - доставка на другой адрес, проверенный Мерчантом. `03` - доставка по адресу, отличному от основного адреса держателя карты. `04` - отправка в магазин/самовывоз (адрес магазина должен быть указан в соответствующих параметрах доставки) `05` - Цифровое распространение (включает онлайн-сервисы и электронные подарочные карты) `06` - билеты на путешествия и мероприятия, которые нельзя доставить. `07` - Прочее (например, игры, цифровые товары, не подлежащие доставке, цифровые подписки и т. д.)
Необязательно	`deliveryTimeframe`	N2	Срок поставки товара. Возможные значения: `01` - цифровая дистрибуция `02` - доставка в тот же день `03` - доставка на следующий день `04` - доставка в течение 2-х дней после оплаты и позже.
Необязательно	`deliveryEmail`	ANS...254	Целевой адрес электронной почты для доставки цифрового распространения

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

Обязательность	Название	Тип	Описание
Необязательно	`preOrderDate`	ANS8	Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД.
Необязательно	`preOrderPurchaseInd`	N2	Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения: `01` - возможна доставка; `02` - будущая доставка
Необязательно	`reorderItemsInd`	N2	Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения: `01` - заказ размещается впервые; `02` - повторный заказ

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

Обязательность	Название	Тип	Описание
Необязательно	`homePhone`	ANS...19	Домашний телефон владельца карты с обязательным знаком «+».
Необязательно	`workPhone`	ANS...19	Рабочий телефон владельца карты с обязательным знаком «+».
Необязательно	`mobilePhone`	ANS...19	Номер мобильного телефона владельца карты с обязательным знаком «+».

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

Обязательность	Название	Тип	Описание
Необязательно	`orderCreationDate`	String	Дата создания заказа в формате `YYYY-MM-DDTHH:MM:SS`.

Необязательно	`customerDetails`	Object	Блок, содержащий атрибуты клиента. Описание атрибутов тега приведено ниже.
Необязательно	`cartItems`	Object	Объект, содержащий атрибуты товаров в корзине. Описание вложенных элементов приведено ниже.

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

Обязательность	Название	Тип	Описание
Условие	`email`	String	Электронный адрес клиента. Можно указать несколько адресов электронной почты через запятую и без пробелов. Обязательно следует передать один из двух параметров: `email` или `phone`.

Условие	`phone`	String	Номер телефона покупателя. Всегда нужно указывать код страны, при этом можно указывать или не указывать знак `+`. Таким образом, допустимы следующие варианты: `+449998887766`; `449998887766`. Допустимое количество цифр: от 7 до 15.

Необязательно	`contact`	String [0..40]	Предпочитаемый клиентом способ связи.

Необязательно	`fullName`	String [1..100]	ФИО плательщика.

Необязательно	`passport`	Integer	Серия и номер паспорта плательщика в следующем формате: `2222888888`

Необязательно	`deliveryInfo`	Object	Объект, содержащий атрибуты адреса доставки. Описание вложенных элементов приведено ниже.

Необязательно	`inn`	Integer [10..12]	Индивидуальный номер налогоплательщика. 10 или 12 символов.

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

Обязательность	Название	Тип	Описание
Необязательно	`deliveryType`	String [1..20]	Способ доставки.

Обязательно	`country`	String	Двухбуквенный код страны доставки.

Обязательно	`city`	String [0..40]	Город назначения.

Обязательно	`postAddress`	String [1..255]	Адрес доставки.

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

Обязательность	Название	Тип	Описание
Обязательно	`items`	Object	Элемент массива с атрибутами товарной позиции. Описание вложенных элементов приведено ниже.

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

Обязательность	Название	Тип	Описание
Обязательно	`positionId`	Integer [1..12]	Уникальный идентификатор товарной позиции в корзине.

Обязательно	`name`	String [1..255]	Наименование или описание товарной позиции в свободной форме.

Необязательно	`itemDetails`	Object	Объект с параметрами описания товарной позиции. Описание вложенных элементов приведено ниже.

Обязательно	`quantity`	Object	Элемент, описывающий передается общее количество товарных позиций одного `positionId` и его единицы измерения. Описание вложенных элементов приведено ниже.

Необязательно	`itemAmount`	Integer [1..12]	Сумма стоимости всех товарных позиций одного `positionId` в минимальных единицах валюты. `itemAmount` обязателен к передаче, только если не был передан параметр `itemPrice`. В противном случае передача `itemAmount` не требуется. Если же в запросе передаются оба параметра: `itemPrice` и `itemAmount`, то `itemAmount` должен равняться , в противном случае запрос завершится с ошибкой.

Необязательно	`itemPrice`	Integer [1..18]	Сумма стоимости товарной позиции одного `positionId` в деньгах в минимальных единицах валюты. Обязательно для мерчантов, использующих фискализацию.

Необязательно	`itemCurrency`	Integer	Код валюты ISO 4217. Если не указан, считается равным валюте заказа.

Обязательно	`itemCode`	String [1..100]	Номер (идентификатор) товарной позиции в системе магазина.

Необязательно	`discount`	Object	Объект, содержащий атрибуты скидки на товарную позицию. Описание вложенных элементов приведено ниже.

Необязательно	`agentInterest`	Object	Объект, содержащий атрибуты описания агентского вознаграждения за продажу товаров. Описание вложенных элементов приведено ниже.

Необязательно	`tax`	Object	Объект, содержащий атрибуты налога. Ниже приведено описание содержащихся атрибутов.

Необязательно	`itemAttributes`	Object	Объект, содержащий атрибуты товарной позиции.

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

Обязательность	Название	Тип	Описание
Обязательно	`value`	String	Количество товарных позиций данного `positionId`. Для указания дробных чисел используйте десятичную точку. При ФФД 1.2+ значение `value` всегда `1`.

Обязательно	`measure`	String [1..20]	Единица измерения количества по позиции. Для ФФД 1.2+, если переданы параметры `nomenclature` и `markQuantity`, `measure` всегда равно `0`. Для других ФФД возможны иные значения.

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

Обязательность	Название	Тип	Описание
Необязательно	`itemDetailsParams`	Object	Параметр, описывающий дополнительную информацию по товарной позиции. Описание вложенных элементов приведено ниже.

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

Обязательность	Название	Тип	Описание
Обязательно	`value`	String	Дополнительная информация по товарной позиции.

Обязательно	`name`	String [1..255]	Наименование параметра описания детализации товарной позиции

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

Обязательность	Название	Тип	Описание
Обязательно	`discountType`	String [1..20]	Тип скидки на товарную позицию

Обязательно	`discountValue`	Integer [0..20]	Значение скидки на товарную позицию.

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

Обязательность	Название	Тип	Описание
Обязательно	`interestType`	String [1..20]	Тип агентской комиссии.

Обязательно	`interestValue`	Integer [1..20]	Значение агентской комиссии.

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

Обязательность	Название	Тип	Описание
Обязательно	`taxType`	Integer	Ставка НДС, доступны следующие значения: `0` – без НДС; `1` – НДС по ставке 0%; `2` – НДС чека по ставке 10%; `4` – НДС чека по расчетной ставке 10/110; `6` – НДС чека по ставке 20%; `7` – НДС чека по расчетной ставке 20/120.

Обязательно	`taxSum`	Integer [1..18]	Сумма налога рассчитанная продавцом. Значение указывается в минимальных единицах валюты.

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

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

Обязательность	Название	Тип	Описание
Обязательно	`paymentMethod`	Integer	Тип платежа, доступные значения: `1` - полная предоплата; `2` - частичная предоплата; `3` - аванс; `4` - полная оплата; `5` - частичная оплата с последующей оплатой в кредит; `6` - без оплаты с последующей оплатой в кредит; `7` - оплата с последующей оплатой в кредит.

Обязательно	`paymentObject`	Integer	Объект платежа, доступные значения: `1` - товар (значение по умолчанию); `2` - подакцизный товар; `3` - работа; `4` - услуга; `5` - ставка азартной игры; `6` - выигрыш азартной игры; `7` - лотерейный билет; `8` - выигрыш лотереи; `9` - предоставление РИД; `10` - платеж; `11` - агентское вознаграждение; `12` - составной предмет расчета; `13` - иной предмет расчета; `14` - имущественное право; `15` - внереализационный доход; `16` - страховые взносы: о суммах расходов, уменьшающих сумму налога (авансовых платежей) в соответствии с пунктом 3.1 статьи 346.21 Налогового кодекса Российской Федерации; `17` - торговый сбор: о суммах уплаченного торгового сбора; `18` - курортный сбор. Указанные выше значения доступны для ФФД 1.05. Для ФФД 1.2 список доступных значений пополняется также следующими значениями: `30` - подакцизный товар, подлежащий маркировке средством идентификации, не имеющий кода маркировки `31` - подакцизный товар, подлежащий маркировке средством идентификации, имеющий код маркировки `32` - товар, подлежащий маркировке средством идентификации, имеющий код маркировки, за исключением подакцизного товара `33` - товар, подлежащий маркировке средством идентификации, имеющий код маркировки, за исключением подакцизного товара Приоритезация передачи значения происходит по следующему принципу (указано в убывающем порядке приоритета): 1) корзина заказа из API-запроса; 2) настройки фискализации в личном кабинете; 3) значения по умолчанию

Условие	`nomenclature`	String	Код товарной номенклатуры в шестнадцатеричном представлении с пробелами. Максимальная длина – 32 байта. Обязательно, если передано `markQuantity`.

Необязательно	`markQuantity`	Object	Дробное количество маркируемого товара. См. вложенные параметры.

Необязательно	`userData`	String [1..64]	Значение реквизита пользователя. Можно передавать только после согласования с ФНС.

Необязательно	`agent_info`	Object	Объект с данными о платежном агенте для товарной позиции.

Условие*	`agent_info.type`	Integer	Тип агента, доступные значения: `1` - банковский платежный агент; `2` - банковский платежный субагент; `3` - платежный агент; `4` - платежный субагент; `5` - поверенный; `6` - комиссионер; `7` - иной агент.

Необязательно	`agent_info.paying`	Object	Объект с данными о платежном агенте.

Необязательно	`agent_info.paying.operation`	String [1..24]	Название транзакции платежного агента.

Необязательно	`agent_info.paying.phones`	Array of strings	Массив телефонных номеров платежного агента в формате +N.

Необязательно	`agent_info.paymentsOperator`	Object	Объект с информацией об операторе по приему платежей.

Необязательно	`agent_info.paymentsOperator.phones`	Array of strings	Массив телефонных номеров платежного агента в формате +N.

Необязательно	`agent_info.MTOperator`	Object	Объект с данными об Операторе перевода.

Необязательно	`agent_info.MTOperator.phones`	Array of strings	Массив телефонных номеров оператора перевода в формате +N.

Необязательно	`agent_info.MTOperator.address`	String [1..256]	Наименование оператора перевода.

Необязательно	`agent_info.MTOperator.address`	String [1..256]	Адрес оператора перевода.

Необязательно	`agent_info.MTOperator.inn`	String [10..12]	ИНН оператора перевода.

Необязательно	`supplier_info`	Object	Объект с данными о поставщике для товарной позиции.

Необязательно	`supplier_info.phones`	Array of strings	Массив телефонных номеров поставщика в формате +N.

Необязательно	`supplier_info.name`	String	Наименование поставщика.

Необязательно	`supplier_info.inn`	String	ИНН поставщика

Необязательно	`supplier_info.documentId`	String	Уникальный идентификатор платежного документа в системе поставщика.

Необязательно	`supplier_info.payerName`	String	ФИО плательщика.

Необязательно	`supplier_info.payerLs`	String	Лицевой счет плательщика в системе поставщика.

Необязательно	`supplier_info.ls`	String	Единый лицевой счет поставщика.

Необязательно	`supplier_info.bankBic`	String	БИК банка получателя, поставщика.

Необязательно	`supplier_info.kpp`	String	Код причины постановки на учет (КПП) получателя платежа, поставщика.

Необязательно	`supplier_info.kpp`	String	Код причины постановки на учет (КПП) получателя платежа, поставщика.

Необязательно	`supplier_info.rs`	String	Банковский счет получателя платежа, поставщика.

Необязательно	`supplier_info.commission`	String	Размер комиссии в минимальных денежных единицах на стороне поставщика.

* Обязателен, если передается agent_info.

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

Значение	Описание
0	Применяется к позициям, которые могут быть реализованы индивидуально или отдельными единицами, а также если объект платежа является предметом, подлежащим обязательной идентификационной маркировке.
10	Грамм
11	Килограмм
12	Тонна
20	Сантиметр
21	Дециметр
22	Метр
30	Квадратный сантиметр
31	Квадратный дециметр
32	Квадратный метр
40	Миллилитр
41	Литр
42	Кубический метр
50	Киловатт час
51	Гигакалория
70	День
71	Час
72	Минута
73	Секунда
80	Килобайт
81	Мегабайт
82	Гигабайт
83	Терабайт
255	Применяется к другим единицам измерения

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

Обязательность	Название	Тип	Описание
Обязательно	`numerator`	String	Числитель дробной части объекта платежа.

Обязательно	`denominator`	String	Знаменатель дробной части объекта платежа.

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

Обязательность	Название	Тип	Описание
Необязательно	`agent_info.type`	Integer	Тип агента, доступные значения: `1` - банковский платежный агент; `2` - банковский платежный субагент; `3` - платежный агент; `4` - платежный субагент; `5` - поверенный; `6` - комиссионер; `7` - иной агент.

Необязательно	`agent_info.paying.operation`	String [1..24]	Название транзакции платежного агента.

Необязательно	`agent_info.paying.phones`	Array of strings	Массив телефонных номеров платежного агента в формате +N.

Необязательно	`agent_info.paymentsOperator.phones`	Array of strings	Массив телефонных номеров платежного агента в формате +N.

Необязательно	`agent_info.MTOperator.address`	String [1..256]	Адрес оператора перевода.

Необязательно	`agent_info.MTOperator.inn`	String [10..12]	ИНН оператора перевода.

Необязательно	`agent_info.MTOperator.address`	String [1..256]	Наименование оператора перевода.

Необязательно	`agent_info.MTOperator.phones`	Array of strings	Массив телефонных номеров оператора перевода в формате +N.

Необязательно	`supplier_info.phones`	Array of strings	Массив телефонных номеров поставщика в формате +N.

Необязательно	`cashier`	String [1..256]	Имя кассира.

Необязательно	`additional_check_props`	String [1..16]	Дополнительные свойства чека.

Необязательно	`additional_user_props.name`	String [1..24]	Название дополнительного свойства пользователя

Необязательно	`additional_user_props.value`	String [1..24]	Значение дополнительного свойства пользователя

Необязательно	`cashier_inn`	String [10..12]	ИНН кассира.

Необязательно	`client.address`	String [1..256]	Адрес клиента.

Необязательно	`client.birth_date`	String [10]	Дата рождения клиента в формате дд.мм.гггг.

Необязательно	`client.citizenship`	String [3]	Цифровой код страны, гражданином которой является покупатель (клиент).

Необязательно	`client.document_code`	String [2]	Цифровой код вида документа, удостоверяющего личность (например, 21 - паспорт гражданина РФ).

Необязательно	`client.passport_number`	String [11]	Серия и номер паспорта плательщика.

Необязательно	`client.email`	String [1..64]	Электронная почта плательщика. Обязательно заполнение строго одного из полей: электронная почта или телефон.

Необязательно	`client.phone`	String [19]	Телефон покупателя. Вместе с кодом страны без пробелов и дополнительных символов, кроме символа «+» (номер «+371 2 1234567» следует передавать как «+37121234567»). Обязательно заполнение строго одного из полей: электронная почта или телефон.

Необязательно	`client.inn`	String [12]	ИНН клиента.

Необязательно	`client.name`	String [1..256]	Имя клиента.

Необязательно	`operatingcheckprops.name`	String	Идентификатор транзакции. Принимает значения "0" до тех пор, пока не будет определено значение реквизита ФНС России.

Необязательно	`operatingcheckprops.timestamp`	String [1..19]	Дата и время операции в формате: дд.мм.гггг ЧЧ:ММ:СС.

Необязательно	`operatingcheckprops.value`	String [1..64]	Данные транзакции.

Необязательно	`sectoralcheckprops.date`	String [10]	Дата принятия нормативного акта федерального органа исполнительной власти, регулирующего порядок заполнения "значения отраслевого реквизита", в формате: дд.мм.гггг.

Необязательно	`sectoralcheckprops.federalid`	String	Идентификатор федерального органа исполнительной власти. Должен принимать одно из значений из справочника федеральных органов исполнительной власти.

Необязательно	`sectoralcheckprops.number`	String [32]	Номер нормативного акта федерального органа исполнительной власти, регламентирующего порядок заполнения реквизита «значение отраслевого реквизита»

Необязательно	`sectoralcheckprops.value`	String [1..256]	Состав значений, определенных нормативным актом федерального органа исполнительной власти

Условие	`company.automat_number`	String	Номер автомата. Условия обязательной передачи параметров: Формат фискальных документов 1.05 – для вендинга и транспорта; Формат фискальных документов 1.2 – для вендинга и транспорта.

Условие	`company.location`	String	Адрес для выставления счета. Условия обязательной передачи параметров: Формат фискальных документов 1.05 – для вендинга, транспорта, курьеров. Формат фискальных документов 1.2 – для вендинга, транспорта, курьеров.

Условие	`company.payment_address`	String	Адрес для получения счетов. Условия обязательной передачи параметров: Формат фискальных документов 1.05 – для вендинга, транспорта, курьеров. Формат фискальных документов 1.2 – для вендинга, транспорта, курьеров.

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

Обязательность	Название	Тип	Описание
Необязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Необязательно	`orderId`	String [1..36]	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.

Необязательно	`formUrl`	String [1..512]	URL платежной формы, на которую будет перенаправлен покупатель. URL не возвращается, если регистрация заказа не прошла из-за ошибки, указанной в `errorCode`.

Примеры

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

curl --request POST \
  --url https://vtb.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=en

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

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

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

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

Для оплаты заказа используется запрос paymentorder.do.

Если у вас есть договор с международной платежной системой или сертификат, который позволяет выполнять операции 3DS, вы можете использовать запрос paymentorder.do (внешний MPI). Это означает, что вы можете использовать собственный MPI для авторизации 3D Secure. Дополнительная информация об оплате с собственным MPI доступна здесь.

Если у вас нет договора с международной платежной системой или сертификата, который позволяет выполнять операции 3DS, используйте запрос paymentorder.do (внутренний MPI).

Оплата заказа (внешний MPI)

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца.

Обязательно	`MDORDER`	String [1..36]	Номер заказа в платежном шлюзе.

Обязательно	`$PAN`	Integer [1..19]	Номер платежной карты. Обязательный, если не передан `seToken`.

Обязательно	`$CVC`	Integer	Код CVC/CVV2 на обратной стороне карты. Обязательный, если не передан `seToken`.

Обязательно	`YYYY`	Integer	Год окончания действия платежной карты. Если `seToken` не передан, обязательно необходимо передать либо `$EXPIRY`, либо `YYYY` и `MM`.

Обязательно	`MM`	Integer	Месяц окончания действия платежной карты. Если `seToken` не передан, обязательно необходимо передать либо `$EXPIRY`, либо `YYYY` и `MM`.

Условие	`$EXPIRY`	Integer	Срок действия карты в следующем формате: `YYYYMM`. Переопределяет параметры `YYYY` и `MM`. Если `seToken` не передан, обязательно необходимо передать либо `$EXPIRY`, либо `YYYY` и `MM`.

Условие	`seToken`	String	Зашифрованные данные карты, которые заменяют параметры `$PAN`, `$CVC` и `$EXPIRY` (или `YYYY`,`MM`). Обязательно, если используется вместо данных карты. Обязательные параметры для строки seToken: `timestamp`, `UUID`, `PAN`, `EXPDATE`, `MDORDER`. Подробнее о генерации seToken см. здесь. Если seToken содержит шифрованные данные о связке (`bindingId`), для оплаты следует использовать запрос paymentOrderBinding.do.

Обязательно	`TEXT`	String	Имя держателя карты.

Обязательно	`language`	String [2]	Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: `ru,en`.

Необязательно	`ip`	String [1..39]	IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). При использовании аутентификации 3DS 2 рекомендуем вам передавать в этом параметре реальный IP адрес клиента. Это позволит повысить конверсию в оплату на стороне ACS.

Необязательно	`bindingNotNeeded`	Boolean	Допустимые значения: `true`- создание связки после совершения платежа отключено (связка – это идентификатор клиента, переданный в запросе на регистрацию заказа, который после запроса `paymentorder.do` будет удален из деталей заказа); `false` – в случае успешной оплаты может быть создана связка (при соблюдении необходимых условий). Это значение по умолчанию.

Необязательно	`jsonParams`	String	Поля дополнительной информации для последующего хранения, передаются в следующем виде: `{"param":"value","param2":"value2"}`. Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах банка. По умолчанию передаются `orderNumber` (номер заказа) и `description` (описание заказа).`description` не должно превышать 99 символов, не используйте следующие символы: `%`, `+`, возврат каретки `\r` и перевод строки `\n`). Чтобы включить эту функциональность, обратитесь в банк. Если вы используете внешний MPI, платежный шлюз ожидает, что каждый запрос `paymentOrder` будет включать ряд дополнительных параметров.

Необязательно	`billingPayerData`	Object	Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры.

Необязательно	`tii`	String	Идентификатор инициатора транзакции. Параметр, указывающий, какой тип операции будет выполнять инициатор (Клиент или Мерчант). Возможные значения

Необязательно	`threeDSProtocolVersion`	String	Версия протокола 3DS. Возможные значения: "1.0.2" для 3DS1; "2.1.0", "2.2.0" для 3DS2. Если в запросе не передается `threeDSProtocolVersion`, то для авторизации 3D Secure будет использоваться значение по умолчанию (`1.0.2` - для 3DS 1 или `2.1.0` - для 3DS 2).

Необязательно	`shippingPayerData`	Object	Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.

Необязательно	`preOrderPayerData`	Object	Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.

Необязательно	`orderPayerData`	Object	Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.

Необязательно	`billingAndShippingAddressMatchIndicator`	A1	Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. Возможные значения: `Y` - совпадение платежного адреса держателя карты и адреса доставки; `N` - платежный адрес владельца карты и адрес доставки не совпадают.

Необязательно	`clientBrowserInfo`	Object	Блок данных о браузере клиента, который отправляется на ACS во время 3DS аутентификации. Этот блок можно передавать, только если включена специальная настройка (обратитесь в команду поддержки). См. вложенные параметры.

Необязательно	`acsInIFrame`	Boolean	Флаг, показывающий, что для финишного URL будет возвращаться iFrame версия. Возможные значения `true` or `false`. Для подключения данной функциональности обратитесь в службу поддержки.

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

Обязательность	Название	Тип	Описание
Необязательно	`billingCity`	String [0..50]	Город, зарегистрированный по конкретной карте у Банка Эмитента.

Необязательно	`billingCountry`	String [0..50]	Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой).

Необязательно	`billingAddressLine1`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки.

Необязательно	`billingAddressLine2`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2.

Необязательно	`billingAddressLine3`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3.

Необязательно	`billingPostalCode`	String [0..9]	Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки.

Необязательно	`billingState`	String [0..50]	Штат, зарегистрированный по конкретной карте у Банка Эмитента.

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

Обязательность	Название	Тип	Описание
Необязательно	`shippingCity`	ANS...50	Город заказчика (из адреса доставки)
Необязательно	`shippingCountry`	ANS...50	Страна заказчика
Необязательно	`shippingAddressLine1`	ANS...50	Основной адрес клиента (из адреса доставки)
Необязательно	`shippingAddressLine2`	ANS...50	Основной адрес клиента (из адреса доставки)
Необязательно	`shippingAddressLine3`	ANS...50	Основной адрес клиента (из адреса доставки)
Необязательно	`shippingPostalCode`	ANS...16	Почтовый индекс клиента для доставки
Необязательно	`shippingState`	ANS...50	Штат/регион покупателя (из адреса доставки)
Необязательно	`shippingMethodIndicator`	N2	Индикатор способа доставки. Возможные значения: `01` - доставка на платежный адрес держателя карты. `02` - доставка на другой адрес, проверенный Мерчантом. `03` - доставка по адресу, отличному от основного адреса держателя карты. `04` - отправка в магазин/самовывоз (адрес магазина должен быть указан в соответствующих параметрах доставки) `05` - Цифровое распространение (включает онлайн-сервисы и электронные подарочные карты) `06` - билеты на путешествия и мероприятия, которые нельзя доставить. `07` - Прочее (например, игры, цифровые товары, не подлежащие доставке, цифровые подписки и т. д.)
Необязательно	`deliveryTimeframe`	N2	Срок поставки товара. Возможные значения: `01` - цифровая дистрибуция `02` - доставка в тот же день `03` - доставка на следующий день `04` - доставка в течение 2-х дней после оплаты и позже.
Необязательно	`deliveryEmail`	ANS...254	Целевой адрес электронной почты для доставки цифрового распространения

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

Обязательность	Название	Тип	Описание
Необязательно	`preOrderDate`	ANS8	Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД.
Необязательно	`preOrderPurchaseInd`	N2	Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения: `01` - возможна доставка; `02` - будущая доставка
Необязательно	`reorderItemsInd`	N2	Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения: `01` - заказ размещается впервые; `02` - повторный заказ

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

Обязательность	Название	Тип	Описание
Необязательно	`homePhone`	ANS...19	Домашний телефон владельца карты с обязательным знаком «+».
Необязательно	`workPhone`	ANS...19	Рабочий телефон владельца карты с обязательным знаком «+».
Необязательно	`mobilePhone`	ANS...19	Номер мобильного телефона владельца карты с обязательным знаком «+».

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

Значение `tii`	Описание	Тип транзакции	Инициатор транзакции	Данные карты для транзакции	Сохранение данных карты после транзакции	Примечание
Пусто		Обычный	Покупатель	Вводится покупателем	Нет	Транзакция электронной коммерции без сохранения связки.
CI	Инициирующий - Обычный (CIT)	Инициирующая	Покупатель	Вводится покупателем	Да	Транзакция электронной коммерции с сохранением связки.
F	Внеплановый платеж (CIT)	Последующая	Покупатель	Клиент выбирает карту вместо ручного ввода	Нет	Транзакция электронной коммерции, использующая ранее сохраненную обычную связку.
U	Внеплановый платеж (MIT)	Последующая	Продавец	Нет ручного ввода, продавец передает данные	Нет	Транзакция электронной коммерции, использующая ранее сохраненную обычную связку.
RI	Инициирующий - Рекурентные (CIT)	Инициирующая	Покупатель	Вводится покупателем	Да	Транзакция электронной коммерции с сохранением связки.
R	Рекуррентный платеж (MIT)	Последующая	Продавец	Нет ручного ввода, продавец передает данные	Нет	Рекуррентная операция, использующая сохраненную связку.
II	Инициирующий - Рассрочка (CIT)	Инициирующая	Покупатель	Вводится покупателем	Да	Транзакция электронной коммерции с сохранением связки.
I	Платеж по рассрочке (MIT)	Последующая	Продавец	Нет ручного ввода, продавец передает данные	Нет	Операция рассрочки, использующая сохраненную связку.

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

Обязательность	Название	Тип	Описание
Необязательно	userAgent	string	Агент браузера.
Необязательно	OS	string	Операционная система.
Необязательно	OSVersion	string	Версия операционной системы.
Необязательно	browserAcceptHeader	string	Заголовок Accept, который сообщает серверу, какие форматы (или MIME-типы) поддерживает браузер.
Необязательно	browserIpAddress	string	IP-адрес браузера.
Необязательно	browserLanguage	string	Язык браузера.
Необязательно	browserTimeZone	string	Часовой пояс браузера.
Необязательно	browserTimeZoneOffset	integer	Смещение часового пояса в минутах между локальным временем пользователя и UTC.
Необязательно	colorDepth	string	Глубина цвета экрана, в битах.
Необязательно	fingerprint	string	Отпечаток браузера - уникальный цифровой идентификатор браузера.
Необязательно	isMobile	Boolean	Возможные значения: `true` или `false`. Флаг, указывающий на то, что используется мобильное устройство.
Необязательно	javaEnabled	Boolean	Возможные значения: `true` или `false`. Флаг, указывающий на то, что в браузере включена поддержка java.
Необязательно	javascriptEnabled	Boolean	Возможные значения: `true` или `false`. Флаг, указывающий на то, что в браузере включена поддержка javascript.
Необязательно	plugins	string	Список плагинов, используемых в браузере, через запятую.
Необязательно	screenHeight	integer	Высота экрана в пикселях.
Необязательно	screenWidth	integer	Ширина экрана в пикселях.
Необязательно	screenPrint	string	Данные о параметрах печати браузера, включая разрешение, глубину цвета, плотность пикселей.

Пример блока 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":"10.99.50.37"
    }

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

Обязательность	Название	Тип	Описание
Обязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Необязательно	`info`	String	В случае успешного ответа. Результат попытки оплаты. Ниже приведены возможные значения. Ваш платеж обработан, происходит переадресация... Операция отклонена. Проверьте введенные данные, достаточность средств на карте и повторите операцию. Происходит переадресация... Извините, платеж не может быть совершен. Происходит переадресация... Операция отклонена. Обратитесь в магазин. Происходит переадресация... Операция отклонена. Обратитесь в банк, выпустивший карту. Происходит переадресация... Невозможная операция Аутентификация держателя карты завершена неуспешно. Происходит переадресация... Нет связи с банком. Повторите позже. Происходит переадресация... Истек срок ожидания ввода данных. Происходит переадресация... Не получен ответ от банка. Повторите позже. Происходит переадресация...

Необязательно	`acsInIFrame`	Boolean	Флаг, показывающий, что для финишного URL будет возвращаться iFrame версия. Возможные значения `true` or `false`. Для подключения данной функциональности обратитесь в службу поддержки.

Примеры

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

curl --request POST \\
  --url https://vtb.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://vtb.rbsuat.com/payment/merchants/temp/finish.html?orderId=01493844-d4d3-703f-9f7e-a73900a7d8c0&lang=en",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

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

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Обязательно	`MDORDER`	String [1..36]	Номер заказа в платежном шлюзе.

Обязательно	`$PAN`	Integer [1..19]	Номер платежной карты. Обязательный, если не передан `seToken`.

Обязательно	`$CVC`	Integer	Код CVC/CVV2 на обратной стороне карты. Обязательный, если не передан `seToken`.

Обязательно	`YYYY`	Integer	Год окончания действия платежной карты. Если `seToken` не передан, обязательно необходимо передать либо `$EXPIRY`, либо `YYYY` и `MM`.

Обязательно	`MM`	Integer	Месяц окончания действия платежной карты. Если `seToken` не передан, обязательно необходимо передать либо `$EXPIRY`, либо `YYYY` и `MM`.

Условие	`$EXPIRY`	Integer	Срок действия карты в следующем формате: `YYYYMM`. Переопределяет параметры `YYYY` и `MM`. Если `seToken` не передан, обязательно необходимо передать либо `$EXPIRY`, либо `YYYY` и `MM`.

Условие	`seToken`	String	Зашифрованные данные карты, которые заменяют параметры `$PAN`, `$CVC` и `$EXPIRY` (или `YYYY`,`MM`). Обязательно, если используется вместо данных карты. Обязательные параметры для строки seToken: `timestamp`, `UUID`, `PAN`, `EXPDATE`, `MDORDER`. Подробнее о генерации seToken см. здесь. Если seToken содержит шифрованные данные о связке (`bindingId`), для оплаты следует использовать запрос paymentOrderBinding.do.

Обязательно	`TEXT`	String	Имя держателя карты.

Обязательно	`language`	String [2]	Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: `ru,en`.

Необязательно	`ip`	String [1..39]	IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). При использовании аутентификации 3DS 2 рекомендуем вам передавать в этом параметре реальный IP адрес клиента. Это позволит повысить конверсию в оплату на стороне ACS.

Необязательно	`bindingNotNeeded`	Boolean	Допустимые значения: `true`- создание связки после совершения платежа отключено (связка – это идентификатор клиента, переданный в запросе на регистрацию заказа, который после запроса `paymentorder.do` будет удален из деталей заказа); `false` – в случае успешной оплаты может быть создана связка (при соблюдении необходимых условий). Это значение по умолчанию.

Необязательно	`jsonParams`	Object	Набор дополнительных параметров произвольной формы, структура: `{name1:value1,…,nameN:valueN}` Некоторые предопределенные атрибуты jsonParams: `email` - электронная почта держателя карты для предварительного заполнения на странице оформления заказа `phone` - номер телефона держателя карты для выставления счетов для предварительного заполнения на странице оформления заказа `backToShopUrl` - добавляет на страницу оплаты кнопку, которая вернет держателя карты на назначенный URL-адрес веб-сайта продавца. `backToShopName` - настраивает текстовую метку кнопки Вернуться в магазин по умолчанию, если она используется вместе с `backToShopUrl` `installments` - максимальное количество разрешенных авторизаций для платежей в рассрочку. Требуется для создания связки рассрочки. `recurringFrequency` - минимальное количество дней между авторизациями. Требуется для создания рекуррентной связки, рекомендуется для создания связки рассрочки (если используется 3DS2, параметр обязателен). `recurringExpiry` - дата, после которой авторизации не разрешены, в формате ГГГГММДД. Требуется для создания рекуррентной связки, рекомендуется для создания связки рассрочки (если используется 3DS2, параметр обязателен).

Необязательно	`threeDSSDK`	Boolean	Возможные значения: `true` или `false` Флаг, показывающий, что платеж поступает из 3DS SDK.

Необязательно	`billingPayerData`	Object	Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры.

Необязательно	`tii`	String	Идентификатор инициатора транзакции. Параметр, указывающий, какой тип операции будет выполнять инициатор (Клиент или Мерчант). Возможные значения

Необязательно	`externalScaExemptionIndicator`	String	Тип исключения SCA (Strong Customer Authentication). Если указан этот параметр, транзакция будет обработана в зависимости от ваших настроек в платежном шлюзе: либо будет выполнена принудительная операция SSL, либо банк-эмитент получит информацию об исключении SCA и примет решение о проведении операции с 3DS-аутентификацией или без нее (для получения подробной информации свяжитесь с нашей службой поддержки). Допустимые значения: `LVP` – транзакция типа Low Value Payments. Транзакция может быть отнесена к транзакциям с низким уровнем риска на основе суммы транзакции, количества транзакций клиента в день или общей дневной суммы платежей клиента. `TRA` – транзакция типа Transaction Risk Analysis, т.е. транзакция, прошедшая успешную антифрод-проверку. Для передачи этого параметра у вас должны быть достаточные права в платежном шлюзе.

Необязательно	`clientBrowserInfo`	Object	Блок данных о браузере клиента, который отправляется на ACS во время 3DS аутентификации. Этот блок можно передавать, только если включена специальная настройка (обратитесь в команду поддержки). См. вложенные параметры.

Необязательно	`acsInIFrame`	Boolean	Флаг, показывающий, что для финишного URL будет возвращаться iFrame версия. Возможные значения `true` or `false`. Для подключения данной функциональности обратитесь в службу поддержки.

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

Обязательность	Название	Тип	Описание
Необязательно	`billingCity`	String [0..50]	Город, зарегистрированный по конкретной карте у Банка Эмитента.

Необязательно	`billingCountry`	String [0..50]	Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой).

Необязательно	`billingAddressLine1`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки.

Необязательно	`billingAddressLine2`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2.

Необязательно	`billingAddressLine3`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3.

Необязательно	`billingPostalCode`	String [0..9]	Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки.

Необязательно	`billingState`	String [0..50]	Штат, зарегистрированный по конкретной карте у Банка Эмитента.

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

Значение `tii`	Описание	Тип транзакции	Инициатор транзакции	Данные карты для транзакции	Сохранение данных карты после транзакции	Примечание
Пусто		Обычный	Покупатель	Вводится покупателем	Нет	Транзакция электронной коммерции без сохранения связки.
CI	Инициирующий - Обычный (CIT)	Инициирующая	Покупатель	Вводится покупателем	Да	Транзакция электронной коммерции с сохранением связки.
F	Внеплановый платеж (CIT)	Последующая	Покупатель	Клиент выбирает карту вместо ручного ввода	Нет	Транзакция электронной коммерции, использующая ранее сохраненную обычную связку.
U	Внеплановый платеж (MIT)	Последующая	Продавец	Нет ручного ввода, продавец передает данные	Нет	Транзакция электронной коммерции, использующая ранее сохраненную обычную связку.
RI	Инициирующий - Рекурентные (CIT)	Инициирующая	Покупатель	Вводится покупателем	Да	Транзакция электронной коммерции с сохранением связки.
R	Рекуррентный платеж (MIT)	Последующая	Продавец	Нет ручного ввода, продавец передает данные	Нет	Рекуррентная операция, использующая сохраненную связку.
II	Инициирующий - Рассрочка (CIT)	Инициирующая	Покупатель	Вводится покупателем	Да	Транзакция электронной коммерции с сохранением связки.
I	Платеж по рассрочке (MIT)	Последующая	Продавец	Нет ручного ввода, продавец передает данные	Нет	Операция рассрочки, использующая сохраненную связку.

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

Обязательность	Название	Тип	Описание
Необязательно	userAgent	string	Агент браузера.
Необязательно	OS	string	Операционная система.
Необязательно	OSVersion	string	Версия операционной системы.
Необязательно	browserAcceptHeader	string	Заголовок Accept, который сообщает серверу, какие форматы (или MIME-типы) поддерживает браузер.
Необязательно	browserIpAddress	string	IP-адрес браузера.
Необязательно	browserLanguage	string	Язык браузера.
Необязательно	browserTimeZone	string	Часовой пояс браузера.
Необязательно	browserTimeZoneOffset	integer	Смещение часового пояса в минутах между локальным временем пользователя и UTC.
Необязательно	colorDepth	string	Глубина цвета экрана, в битах.
Необязательно	fingerprint	string	Отпечаток браузера - уникальный цифровой идентификатор браузера.
Необязательно	isMobile	Boolean	Возможные значения: `true` или `false`. Флаг, указывающий на то, что используется мобильное устройство.
Необязательно	javaEnabled	Boolean	Возможные значения: `true` или `false`. Флаг, указывающий на то, что в браузере включена поддержка java.
Необязательно	javascriptEnabled	Boolean	Возможные значения: `true` или `false`. Флаг, указывающий на то, что в браузере включена поддержка javascript.
Необязательно	plugins	string	Список плагинов, используемых в браузере, через запятую.
Необязательно	screenHeight	integer	Высота экрана в пикселях.
Необязательно	screenWidth	integer	Ширина экрана в пикселях.
Необязательно	screenPrint	string	Данные о параметрах печати браузера, включая разрешение, глубину цвета, плотность пикселей.

Пример блока 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":"10.99.50.37"
    }

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

Обязательность	Название	Тип	Описание
Необязательно	`threeDSServerTransId`	String	Идентификатор транзакции, созданный на сервере 3DS. Этот параметр используется для аутентификации клиента по протоколу 3DS версии 2.0.

Необязательно	`threeDSVer2FinishUrl`	String	URL-адрес, по которому клиент должен быть перенаправлен после аутентификации на сервере ACS. Этот параметр используется для аутентификации клиента по протоколу 3DS версии 2.0.

Необязательно	`threeDSMethodNotificationUrl`	String	URL-адрес для отправки уведомления о прохождении проверки на ACS. Этот параметр используется для аутентификации клиента по протоколу 3DS версии 2.0.

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

Обязательность	Название	Тип	Описание
Обязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Необязательно	`info`	String	В случае успешного ответа. Результат попытки оплаты. Ниже приведены возможные значения. Ваш платеж обработан, происходит переадресация... Операция отклонена. Проверьте введенные данные, достаточность средств на карте и повторите операцию. Происходит переадресация... Извините, платеж не может быть совершен. Происходит переадресация... Операция отклонена. Обратитесь в магазин. Происходит переадресация... Операция отклонена. Обратитесь в банк, выпустивший карту. Происходит переадресация... Невозможная операция Аутентификация держателя карты завершена неуспешно. Происходит переадресация... Нет связи с банком. Повторите позже. Происходит переадресация... Истек срок ожидания ввода данных. Происходит переадресация... Не получен ответ от банка. Повторите позже. Происходит переадресация...

Необязательно	`redirect`	String [1..512]	Этот параметр возвращается, если платеж прошел успешно и для платежа не проводилась проверка карты на вовлеченность в 3-D Secure. Продавцы могут использовать его, если хотят перенаправить пользователя на страницу платежного шлюза. Если продавец использует собственную страницу, это значение можно игнорировать.

Необязательно	`termUrl`	String [1..512]	При успешном ответе в случае оплаты 3D-Secure. Это URL-адрес, на который ACS перенаправляет владельца карты после аутентификации. Подробнее см. Редирект на ACS.

Необязательно	`acsUrl`	String [1..512]	При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Подробнее см. Редирект на ACS.

Необязательно	`paReq`	String [1..255]	При успешном ответе в случае оплаты 3D-Secure. PAReq (Payment Authentication Request) — сообщение, которое необходимо отправить в ACS вместе с редиректом. Это сообщение содержит данные в кодировке Base64, необходимые для аутентификации держателя карты. Подробнее см. Редирект на ACS.

Необязательно	`acsInIFrame`	Boolean	Флаг, показывающий, что для финишного URL будет возвращаться iFrame версия. Возможные значения `true` or `false`. Для подключения данной функциональности обратитесь в службу поддержки.

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

Обязательность	Название	Тип	Описание
Обязательно	`is3DSVer2`	Boolean	Возможные значения: `true` или `false` Флаг, показывающий, что платеж поступает из 3DS 2.0.

Обязательно	`threeDSServerTransId`	String	Идентификатор транзакции, созданный на сервере 3DS. Этот параметр используется для аутентификации клиента по протоколу 3DS версии 2.0.

Необязательно	`threeDSMethodUrl`	String	URL-адрес сервера ACS для сбора данных браузера.

Обязательно	`threeDSMethodUrlServer`	String	URL-адрес сервера 3DS для сбора данных браузера, которые будут включены в AReq (Authentication Request) с сервера 3DS на сервер ACS.

Необязательно	`threeDSMethodDataPacked`	String	Данные CReq (Challenge Response) в кодировке Base-64 для отправки на сервер ACS.

Необязательно	`threeDSMethodURLServerDirect`	String	URL-адрес `3dsmethod.do` для выполнения метода 3DS на сервере 3DS через платежный шлюз (при наличии соответствующего разрешения на уровне продавца).

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

Обязательность	Название	Тип	Описание
Условие*	`acsUrl`	String [1..512]	При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Подробнее см. Редирект на ACS.

Условие*	`packedCReq`	String	Запакованные данные challenge request. Это значение следует использовать как значение параметра `creq` ссылки на ACS (`acsUrl`), для перенаправления клиента на ACS.

* Обязательный, если нужен редирект на ACS

Примеры

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

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

curl --request POST \
  --url https://vtb.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=en

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

curl --request POST \
  --url https://vtb.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=en \
  --data threeDSServerTransID=5802746e-3393-40c3-929a-dc966ebf08c6

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

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

{
  "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": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9jb21tb24wMy50c3QucmJzdGVzdC5ydS8zZHNzZXJ2ZXIvYXBpL3YxL2Fjcy9ub3RpZmljYXRpb24_dGhyZWVEU1NlcnZlclRyYW5zSUQ9NTgwMjc0NmUtMzM5My00MGMzLTkyOWEtZGM5NjZlYmYwOGM2IiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI1ODAyNzQ2ZS0zMzkzLTQwYzMtOTI5YS1kYzk2NmViZjA4YzYifQ"
}

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

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

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

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

Запрос acsRedirect.do позволяет перенаправить клиента на страницу аутентификации ACS упрощенным способом - просто используя параметр orderId, полученный после регистрации заказа.

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

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

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

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

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

https://vtb.rbsuat.com/payment/acsRedirect.do?orderId=<order number in the system>

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

Обязательность	Название	Тип	Описание
Обязательно	`orderId`	String [1..36]	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.

Пример

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

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

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

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

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

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

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

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

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

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

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Необязательно	`token`	String [1..256]	Значение, используемое для аутентификации продавца при отправке запросов платежному шлюзу. Если вы передаете этот параметр, то не передавайте `userName` и `password`.

Обязательно	`orderId`	String	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. В запросе должен присутствовать либо параметр `orderId`, либо `orderNumber`. Если в запросе передаются оба параметра, приоритет `orderId` выше.

Обязательно	`orderNumber`	String [1..32]	Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого мерчанта. В запросе должен присутствовать либо параметр `orderId`, либо `orderNumber`. Если в запросе передаются оба параметра, приоритет `orderId` выше.

Необязательно	`language`	String [2]	Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: `ru,en`.

Необязательно	`merchantLogin`	String [1..255]	Чтобы вместо текущего пользователя получить статус заказа определенного мерчанта, укажите логин мерчанта (для API-аккаунта). Можно использовать, только если у вас есть разрешение на просмотр транзакций других продавцов или если указанный продавец является вашим дочерним продавцом.

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

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

Версия	Обязательность	Название	Тип	Описание
Все	Необязательно	`errorCode`	String [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Все	Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Все	Условие	`orderNumber`	String [1..32]	Номер заказа (ID) в системе мерчанта, должен быть уникальным для каждого мерчанта, зарегистрированного в платежном шлюзе. Если номер заказа генерируется на стороне платежного шлюза, этот параметр передавать необязательно.

Все	Необязательно	`orderStatus`	Integer	Значение этого параметра указывает статус заказа в платежном шлюзе. Отсутствует, если заказ не был найден. Ниже приведен список доступных значений: `0` - заказ зарегистрирован, но не оплачен; `1` - заказ только авторизован и еще не завершен (для двухстадийных платежей); `2` - заказ авторизован и завершен; `3` - авторизация отменена; `4` - по транзакции была проведена операция возврата; `5` - инициирована авторизация через ACS банка-эмитента; `6` - авторизация отклонена; `7` - ожидание оплаты заказы; `8` - промежуточное завершение для многократного частичного завершения.

Все	Обязательно	`actionCode`	Integer	Код ответа от процессинга банка. См. список кодов ответа здесь.

Все	Обязательно	`actionCodeDescription`	String [1..512]	Описание `actionCode`, возвращаемое процессингом банка.

Все	Обязательно	`amount`	Integer [0..12]	Сумма платежа в минимальных единицах валюты (например, в копейках).

Все	Необязательно	`currency`	String [3]	Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию.

Все	Обязательно	`date`	String	Дата регистрации заказа (Unix)

Все	Необязательно	`depositeddate`	String	Дата оплаты заказа (время UNIX).

Все	Необязательно	`orderDescription`	String [1..600]	Описание заказа передаваемое платежному шлюзу при регистрации.

Все	Обязательно	`ip`	String [1..39]	IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). При использовании аутентификации 3DS 2 рекомендуем вам передавать в этом параметре реальный IP адрес клиента. Это позволит повысить конверсию в оплату на стороне ACS.

09+	Необязательно	`authRefNum`	String [1..24]	Номер авторизации платежа, присвоенный ему при регистрации платежа.

01+, обязательно с 27	Необязательно	`refundedDate`	Integer	Дата и время возврата.

12+	Необязательно	`reverseddate`	Integer	Дата и время отмены платежа.

12+	Обязательно	`paymentWay`	String	Способ совершения платежа (платеж с вводом карточных данных, оплата по связке и т.п.). Дополнительные возможные значения параметра приведены ниже

19+	Необязательно	`avsCode`	String	Код ответа верификации AVS (проверка адреса и почтового индекса держателя карты). Возможные значения: A – почтовый индекс и адрес совпадают. B – адрес совпадает, почтовый индекс не совпадает. C - почтовый индекс совпадает, адрес не совпадает. D - почтовый индекс и адрес не совпадают. E - запрошена проверка данных, но результат неуспешен. F - некорректный формат запроса AVS/AVV проверки.

19+	Необязательно	`refund`	Boolean	Были ли средства принудительно возвращены покупателю банком. Возможные значения: `true` - средства были возвращены; `false` - средства не были возвращены.

06+	Необязательно	`authDateTime`	String	Дата и время авторизации, показанные как количество миллисекунд, прошедших с 00:00 GMT 1 января 1970 года (время Unix).

01+	Необязательно	`terminalId`	String [1..10]	Идентификатор терминала в системе, обрабатывающей платеж.

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

CARD - Оплата с вводом данных карты
CARD_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.
SAMSUNG_PAY - Оплата Samsung Pay.
SAMSUNG_PAY_BINDING - Оплата по связке Samsung Pay.
SBP_C2B - Оплата СБП (Система быстрых платежей) для C2B
SBP_C2B_BINDING - Оплата через СБП (Система быстрых платежей) по связке для C2B
SBP_C2B - Оплата СБП
TOKEN_PAY - оплата токеном напрямую
TOKEN_PAY_BINDING - Оплата через токенизированную связку
YANDEX_PAY_CARD - Оплата нетокенизированной картой Яндекс Pay
YANDEX_PAY_TOKENIZED - Оплата токенизированной картой Яндекс Pay
YANDEX_PAY_CARD_BINDING - Оплата нетокенизированной картой Яндекс Pay по связке
YANDEX_PAY_TOKENIZED_BINDING - Оплата токенизированной картой Яндекс Pay по связке
MIR_PAY - Оплата Мир Pay с использованием токенизированной криптограммы
MIR_PAY_BINDING - Оплата Мир Pay по связке

Блок refunds содержит информацию о возврате средств. 05+ Присутствует только при наличии возвратов в заказе.

Версия	Обязательность	Название	Тип	Описание
05+	Необязательно	`date`	String	Дата возврата заказа

21+	Необязательно	`externalRefundId`	String [1..30]	Идентификатор возврата. При попытке возврата проверяется `externalRefundId`: если он существует, возвращается успешный ответ с данными о возврате, если нет — осуществляется возврат.

С 05 до 25 для НЕ карточных платежей. 26+ для всех платежных методов	Необязательно	`approvalCode`	String [6]	Код авторизации МПС. Это поле имеет фиксированную длину (шесть символов) и может содержать цифры и латинские буквы.

05+	Необязательно	`actionCode`	Integer	Код ответа от процессинга банка. См. список кодов ответа здесь.

05+	Необязательно	`referenceNumber`	String [12]	Уникальный идентификационный номер, который присваивается операции по ее завершению.

05+	Необязательно	`amount`	String [0..12]	Сумма возврата в минимальных единицах валюты. Если используется двухстадийный платеж, сумма возврата должна быть меньше или равна общей сумме завершения. Если в запросе указать `amount`=0, то будет возвращена вся сумма заказа.

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

Версия	Обязательность	Название	Тип	Описание
Все	Необязательно	`name`	String [1..255]	Название дополнительного параметра.

Все	Необязательно	`value`	String [1..1024]	Значение дополнительного параметра - до 1024 символов.

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

Версия	Обязательность	Название	Тип	Описание
Все	Необязательно	`name`	String [1..255]	Название дополнительного параметра.

Все	Необязательно	`value`	String [1..1024]	Значение дополнительного параметра - до 1024 символов.

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

Версия	Обязательность	Название	Тип	Описание
Все	Необязательно	`name`	String [1..255]	Название дополнительного параметра.

Все	Необязательно	`value`	String [1..1024]	Значение дополнительного параметра - до 1024 символов.

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

Версия	Обязательность	Название	Тип	Описание
01+	Необязательно	`maskedPan`	String [1..19]	Маскированный номер карты, использованной для платежа. Указывается только после оплаты заказа.

01+	Необязательно	`expiration`	Integer	Срок действия карты в следующем формате: .`YYYYMM` Указывается только после оплаты заказа.

01+	Необязательно	`cardholdername`	String [1..26]	Имя держателя карты латинскими буквами. Этот параметр передается только после оплаты заказа.

01+	Необязательно	`approvalCode`	String [6]	Код авторизации МПС. Это поле имеет фиксированную длину (шесть символов) и может содержать цифры и латинские буквы.

08+	Обязательно	`paymentSystem`	String	Наименование платежной системы. Возможны следующие значения: `VISA`; `MASTERCARD`; `AMEX`; `JCB`; `CUP`;

08+	Обязательно	`product`	String [1..255]	Дополнительные сведения о корпоративных картах. Эти сведения заполняются службой технической поддержки. Если такие сведения отсутствуют, возвращается пустое значение.

17+	Обязательно	`productCategory`	String	Дополнительные сведения о категории корпоративных карт. Эти сведения заполняются службой технической поддержки. Если такие сведения отсутствуют, возвращается пустое значение. Возможные значения: DEBIT, CREDIT, PREPAID, NON_MASTERCARD, CHARGE, DIFFERED_DEBIT.

01+	Необязательно	`corporateCard`	A..5	Указывает, является ли данная карта корпоративной. Возможные значения: false - не является корпоративной картой, true - является корпоративной картой. Может возвращать пустое значение, означает, что значение не найдено.

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

Версия	Обязательность	Название	Тип	Описание
01+	Необязательно	`eci`	Integer [1..4]	Электронный коммерческий индикатор. Указан только после оплаты заказа и в случае наличия соответствующего разрешения. Ниже приводится расшифровка ECI-кодов. `ECI=1` или `ECI=6` - мерчант поддерживает 3-D Secure, платежная карта не поддерживает 3-D Secure, платеж обрабатывается на основе кода CVV2/CVC. `ECI=2` или `ECI=5` - и мерчант, и платежная карта поддерживают 3-D Secure; `ECI=7` - мерчант не поддерживает 3-D Secure, платеж обрабатывается на основе кода CVV2/CVC.

01+	Необязательно	`authTypeIndicator`	String	Тип аутентификации 3DS. В зависимости от значения ECI. Допустимые значения: `0` - SSL (SSL-аутентификация) `1` - THREE_DS1_FULL (аутентификация 3DS 1) `2` - THREE_DS1_ATTEMPT (попытка аутентификации 3DS 1) `3` - THREE_DS2_FULL (Strong customer authentication (SCA)) `4` - THREE_DS2_FRICTIONLESS (Аутентификация на основе риска (RBA)) `5` - THREE_DS2_ATTEMPT (попытка аутентификации 3DS 2)

01+	Необязательно	`cavv`	String [0..200]	Значение проверки аутентификации владельца карты. Указан только после оплаты заказа и в случае наличия соответствующего разрешения.

01+	Необязательно	`xid`	String [1..80]	Электронный коммерческий идентификатор транзакции. Указан только после оплаты заказа и в случае наличия соответствующего разрешения.

30+	Необязательно	`threeDSProtocolVersion`	String	Версия протокола 3DS. Возможные значения: "1.0.2" для 3DS1; "2.1.0", "2.2.0" для 3DS2. Если в запросе не передается `threeDSProtocolVersion`, то для авторизации 3D Secure будет использоваться значение по умолчанию (`1.0.2` - для 3DS 1 или `2.1.0` - для 3DS 2).

30+	Необязательно	`rreqTransStatus`	String [1]	Статус транзакции из запроса на передачу результатов аутентификации пользователя от ACS (RReq). Передается при использовании 3DS 2.0.

30+	Необязательно	`aresTransStatus`	String	Состояние транзакции из ответа ACS на запрос аутентификации (ARes). Передается при использовании 3DS 2.0.

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

Версия	Обязательно	Название	Тип	Описание
Все	Необязательно	`clientId`	String [0..255]	Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен.

Все	Необязательно	`bindingId`	String [1..255]	Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что: Этот заказ можно оплатить только с помощью связки; Плательщик будет перенаправлен на страницу оплаты, где требуется только ввод CVC.

02+	Необязательно	`authDateTime`	String	Дата и время авторизации, показанные как количество миллисекунд, прошедших с 00:00 GMT 1 января 1970 года (время Unix).

02+	Необязательно	`authRefNum`	String [1..24]	Номер авторизации платежа, присвоенный ему при регистрации платежа.

02+	Необязательно	`terminalId`	String [1..10]	Идентификатор терминала в системе, обрабатывающей платеж.

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

Версия	Обязательно	Название	Тип	Описание
03+	Необязательно	`approvedAmount`	Integer [0..12]	Сумма в минимальных единицах валюты (например, в центах), которая была заблокирована на счете покупателя. Используется только в двухстадийных платежах.

03+	Необязательно	`depositedAmount`	Integer [1..12]	Сумма списания в минимальных единицах валюты (например, в копейках).

03+	Необязательно	`refundedAmount`	Integer [1..12]	Сумма возврата в минимальных единицах валюты.

03+	Необязательно	`paymentState`	String	Состояние заказа, параметр может принимать следующие значения: `CREATED` - заказ создан (но не оплачен); `APPROVED` - заказ одобрен (средства на счету покупателя заблокированы); `DEPOSITED` - заказ завершен (деньги списаны со счета покупателя); `DECLINED` - заказ отклонен; `REVERSED` - заказ отклонен; `REFUNDED` - возврат средств.

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

Версия	Обязательность	Название	Тип	Описание
03+	Необязательно	`bankName`	String [1..50]	Название банка-эмитента.

03+	Необязательно	`bankCountryCode`	String	Код страны банка-эмитента.

03+	Необязательно	`bankCountryName`	String [1..160]	Страна банка-эмитента.

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

Версия	Обязательность	Название	Тип	Описание
13+	Необязательно	`email`	String	Электронная почта плательщика.

13+	Необязательно	`phone`	String	Номер телефона покупателя. Всегда нужно указывать код страны, при этом можно указывать или не указывать знак `+`. Таким образом, допустимы следующие варианты: `+449998887766`; `449998887766`. Допустимое количество цифр: от 7 до 15.

13+	Необязательно	`postAddress`	String [1..255]	Адрес доставки.

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

Версия	Обязательность	Название	Тип	Описание
28+	Необязательно	`name`	String	Уникальное наименование платежного плагина.

28+	Необязательно	`params`	Object	Параметры для конкретного способа оплаты должны передаваться следующим образом `{"param":"value","param2":"value2"}`.

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

Обязательность	Название	Тип	Описание
Необязательно	`orderCreationDate`	String	Дата создания заказа в формате `YYYY-MM-DDTHH:MM:SS`.

Необязательно	`customerDetails`	Object	Блок, содержащий атрибуты клиента. Описание атрибутов тега приведено ниже.
Необязательно	`cartItems`	Object	Объект, содержащий атрибуты товаров в корзине. Описание вложенных элементов приведено ниже.

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

Обязательность	Название	Тип	Описание
Условие	`email`	String	Электронный адрес клиента. Можно указать несколько адресов электронной почты через запятую и без пробелов. Обязательно следует передать один из двух параметров: `email` или `phone`.

Условие	`phone`	String	Номер телефона покупателя. Всегда нужно указывать код страны, при этом можно указывать или не указывать знак `+`. Таким образом, допустимы следующие варианты: `+449998887766`; `449998887766`. Допустимое количество цифр: от 7 до 15.

Необязательно	`contact`	String [0..40]	Предпочитаемый клиентом способ связи.

Необязательно	`fullName`	String [1..100]	ФИО плательщика.

Необязательно	`passport`	Integer	Серия и номер паспорта плательщика в следующем формате: `2222888888`

Необязательно	`deliveryInfo`	Object	Объект, содержащий атрибуты адреса доставки. Описание вложенных элементов приведено ниже.

Необязательно	`inn`	Integer [10..12]	Индивидуальный номер налогоплательщика. 10 или 12 символов.

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

Обязательность	Название	Тип	Описание
Необязательно	`deliveryType`	String [1..20]	Способ доставки.

Обязательно	`country`	String	Двухбуквенный код страны доставки.

Обязательно	`city`	String [0..40]	Город назначения.

Обязательно	`postAddress`	String [1..255]	Адрес доставки.

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

Обязательность	Название	Тип	Описание
Обязательно	`items`	Object	Элемент массива с атрибутами товарной позиции. Описание вложенных элементов приведено ниже.

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

Обязательность	Название	Тип	Описание
Обязательно	`value`	String	Количество товарных позиций данного `positionId`. Для указания дробных чисел используйте десятичную точку. При ФФД 1.2+ значение `value` всегда `1`.

Обязательно	`measure`	String [1..20]	Единица измерения количества по позиции. Для ФФД 1.2+, если переданы параметры `nomenclature` и `markQuantity`, `measure` всегда равно `0`. Для других ФФД возможны иные значения.

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

Обязательность	Название	Тип	Описание
Необязательно	`itemDetailsParams`	Object	Параметр, описывающий дополнительную информацию по товарной позиции. Описание вложенных элементов приведено ниже.

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

Обязательность	Название	Тип	Описание
Обязательно	`taxType`	Integer	Ставка НДС, доступны следующие значения: `0` – без НДС; `1` – НДС по ставке 0%; `2` – НДС чека по ставке 10%; `4` – НДС чека по расчетной ставке 10/110; `6` – НДС чека по ставке 20%; `7` – НДС чека по расчетной ставке 20/120.

Обязательно	`taxSum`	Integer [1..18]	Сумма налога рассчитанная продавцом. Значение указывается в минимальных единицах валюты.

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

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

Обязательность	Название	Тип	Описание
Обязательно	`paymentMethod`	Integer	Тип платежа, доступные значения: `1` - полная предоплата; `2` - частичная предоплата; `3` - аванс; `4` - полная оплата; `5` - частичная оплата с последующей оплатой в кредит; `6` - без оплаты с последующей оплатой в кредит; `7` - оплата с последующей оплатой в кредит.

Обязательно	`paymentObject`	Integer	Объект платежа, доступные значения: `1` - товар (значение по умолчанию); `2` - подакцизный товар; `3` - работа; `4` - услуга; `5` - ставка азартной игры; `6` - выигрыш азартной игры; `7` - лотерейный билет; `8` - выигрыш лотереи; `9` - предоставление РИД; `10` - платеж; `11` - агентское вознаграждение; `12` - составной предмет расчета; `13` - иной предмет расчета; `14` - имущественное право; `15` - внереализационный доход; `16` - страховые взносы: о суммах расходов, уменьшающих сумму налога (авансовых платежей) в соответствии с пунктом 3.1 статьи 346.21 Налогового кодекса Российской Федерации; `17` - торговый сбор: о суммах уплаченного торгового сбора; `18` - курортный сбор. Указанные выше значения доступны для ФФД 1.05. Для ФФД 1.2 список доступных значений пополняется также следующими значениями: `30` - подакцизный товар, подлежащий маркировке средством идентификации, не имеющий кода маркировки `31` - подакцизный товар, подлежащий маркировке средством идентификации, имеющий код маркировки `32` - товар, подлежащий маркировке средством идентификации, имеющий код маркировки, за исключением подакцизного товара `33` - товар, подлежащий маркировке средством идентификации, имеющий код маркировки, за исключением подакцизного товара Приоритезация передачи значения происходит по следующему принципу (указано в убывающем порядке приоритета): 1) корзина заказа из API-запроса; 2) настройки фискализации в личном кабинете; 3) значения по умолчанию

Условие	`nomenclature`	String	Код товарной номенклатуры в шестнадцатеричном представлении с пробелами. Максимальная длина – 32 байта. Обязательно, если передано `markQuantity`.

Необязательно	`markQuantity`	Object	Дробное количество маркируемого товара. См. вложенные параметры.

Необязательно	`userData`	String [1..64]	Значение реквизита пользователя. Можно передавать только после согласования с ФНС.

Необязательно	`agent_info`	Object	Объект с данными о платежном агенте для товарной позиции.

Условие*	`agent_info.type`	Integer	Тип агента, доступные значения: `1` - банковский платежный агент; `2` - банковский платежный субагент; `3` - платежный агент; `4` - платежный субагент; `5` - поверенный; `6` - комиссионер; `7` - иной агент.

Необязательно	`agent_info.paying`	Object	Объект с данными о платежном агенте.

Необязательно	`agent_info.paying.operation`	String [1..24]	Название транзакции платежного агента.

Необязательно	`agent_info.paying.phones`	Array of strings	Массив телефонных номеров платежного агента в формате +N.

Необязательно	`agent_info.paymentsOperator`	Object	Объект с информацией об операторе по приему платежей.

Необязательно	`agent_info.paymentsOperator.phones`	Array of strings	Массив телефонных номеров платежного агента в формате +N.

Необязательно	`agent_info.MTOperator`	Object	Объект с данными об Операторе перевода.

Необязательно	`agent_info.MTOperator.phones`	Array of strings	Массив телефонных номеров оператора перевода в формате +N.

Необязательно	`agent_info.MTOperator.address`	String [1..256]	Наименование оператора перевода.

Необязательно	`agent_info.MTOperator.address`	String [1..256]	Адрес оператора перевода.

Необязательно	`agent_info.MTOperator.inn`	String [10..12]	ИНН оператора перевода.

Необязательно	`supplier_info`	Object	Объект с данными о поставщике для товарной позиции.

Необязательно	`supplier_info.phones`	Array of strings	Массив телефонных номеров поставщика в формате +N.

Необязательно	`supplier_info.name`	String	Наименование поставщика.

Необязательно	`supplier_info.inn`	String	ИНН поставщика

* Обязателен, если передается agent_info.

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

Обязательность	Название	Тип	Описание
Обязательно	`discountType`	String [1..20]	Тип скидки на товарную позицию

Обязательно	`discountValue`	Integer [0..20]	Значение скидки на товарную позицию.

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

Обязательность	Название	Тип	Описание
Обязательно	`interestType`	String [1..20]	Тип агентской комиссии.

Обязательно	`interestValue`	Integer [1..20]	Значение агентской комиссии.

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/getOrderStatusExtended.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --data language=en

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

{
  "errorCode": "0",
  "errorMessage": "Success",
  "orderNumber": "7005",
  "orderStatus": 2,
  "actionCode": 0,
  "actionCodeDescription": "",
  "amount": 2000,
  "currency": "643",
  "date": 1617972915659,
  "orderDescription": "",
  "merchantOrderParams": [],
  "transactionAttributes": [],
  "attributes": [
    {
      "name": "mdOrder",
      "value": "01491d0b-c848-7dd6-a20d-e96900a7d8c0"
    }
  ],
  "cardAuthInfo": {
    "maskedPan": "500000**1115",
    "expiration": "203012",
    "cardholderName": "TEST CARDHOLDER",
    "approvalCode": "12345678",
    "pan": "500000**1115"
  },
  "bindingInfo": {
    "clientId": "259753456",
    "bindingId": "01491394-63a6-7d45-a88f-7bce00a7d8c0"
  },
  "authDateTime": 1617973059029,
  "terminalId": "123456",
  "authRefNum": "714105591198",
  "paymentAmountInfo": {
    "paymentState": "DEPOSITED",
    "approvedAmount": 2000,
    "depositedAmount": 2000,
    "refundedAmount": 0
  },
  "bankInfo": {
    "bankCountryCode": "UNKNOWN",
    "bankCountryName": "&ltUnknown&gt"
  }
}

Управление заказом

Завершение заказа

Для завершения предварительно авторизованного заказа используется запрос deposit.do.

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца.

Обязательно	`orderId`	String [1..36]	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.

Обязательно	`amount`	String [0..12]	Сумма платежа в минимальных единицах валюты. Сумма завершения должна соответствовать общей сумме всех товаров по которым идет завершение. Если в запросе указать `amount`=0, будет зачислена вся сумма заказа.

Необязательно	`depositItems`	Object	Объект, содержащий атрибуты товаров в корзине. Ниже приведено описание включенных атрибутов.

Необязательно	`orderBundle`	Object	Объект, содержащий корзину товаров. Описание вложенных элементов приведено ниже.

Необязательно	`language`	String [2]	Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: `ru,en`.

Необязательно	`currency`	Integer [3]	Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию.

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

Обязательность	Название	Тип	Описание
Обязательно	`items`	Object	Элемент массива с атрибутами товарной позиции. Описание вложенных элементов приведено ниже.

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

Обязательность	Название	Тип	Описание
Обязательно	`positionId`	Integer [1..12]	Уникальный идентификатор товарной позиции в корзине.

Обязательно	`name`	String [1..255]	Наименование или описание товарной позиции в свободной форме.

Необязательно	`itemDetails`	Object	Объект с параметрами описания товарной позиции. Описание вложенных элементов приведено ниже.

Обязательно	`quantity`	Object	Элемент, описывающий передается общее количество товарных позиций одного `positionId` и его единицы измерения. Описание вложенных элементов приведено ниже.

Необязательно	`itemAmount`	Integer [1..12]	Сумма стоимости всех товарных позиций одного `positionId` в минимальных единицах валюты. `itemAmount` обязателен к передаче, только если не был передан параметр `itemPrice`. В противном случае передача `itemAmount` не требуется. Если же в запросе передаются оба параметра: `itemPrice` и `itemAmount`, то `itemAmount` должен равняться , в противном случае запрос завершится с ошибкой.

Необязательно	`itemPrice`	Integer [1..18]	Сумма стоимости товарной позиции одного `positionId` в деньгах в минимальных единицах валюты. Обязательно для мерчантов, использующих фискализацию.

Необязательно	`itemCurrency`	Integer	Код валюты ISO 4217. Если не указан, считается равным валюте заказа.

Обязательно	`itemCode`	String [1..100]	Номер (идентификатор) товарной позиции в системе магазина.

Необязательно	`discount`	Object	Объект, содержащий атрибуты скидки на товарную позицию. Описание вложенных элементов приведено ниже.

Необязательно	`agentInterest`	Object	Объект, содержащий атрибуты описания агентского вознаграждения за продажу товаров. Описание вложенных элементов приведено ниже.

Необязательно	`tax`	Object	Объект, содержащий атрибуты налога. Ниже приведено описание содержащихся атрибутов.

Необязательно	`itemAttributes`	Object	Объект, содержащий атрибуты товарной позиции.

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

Обязательность	Название	Тип	Описание
Необязательно	`itemDetailsParams`	Object	Параметр, описывающий дополнительную информацию по товарной позиции. Описание вложенных элементов приведено ниже.

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

Обязательность	Название	Тип	Описание
Обязательно	`value`	String	Количество товарных позиций данного `positionId`. Для указания дробных чисел используйте десятичную точку. При ФФД 1.2+ значение `value` всегда `1`.

Обязательно	`measure`	String [1..20]	Единица измерения количества по позиции. Для ФФД 1.2+, если переданы параметры `nomenclature` и `markQuantity`, `measure` всегда равно `0`. Для других ФФД возможны иные значения.

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

Обязательность	Название	Тип	Описание
Обязательно	`discountType`	String [1..20]	Тип скидки на товарную позицию

Обязательно	`discountValue`	Integer [0..20]	Значение скидки на товарную позицию.

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

Обязательность	Название	Тип	Описание
Обязательно	`interestType`	String [1..20]	Тип агентской комиссии.

Обязательно	`interestValue`	Integer [1..20]	Значение агентской комиссии.

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

Обязательность	Название	Тип	Описание
Обязательно	`taxType`	Integer	Ставка НДС, доступны следующие значения: `0` – без НДС; `1` – НДС по ставке 0%; `2` – НДС чека по ставке 10%; `4` – НДС чека по расчетной ставке 10/110; `6` – НДС чека по ставке 20%; `7` – НДС чека по расчетной ставке 20/120.

Обязательно	`taxSum`	Integer [1..18]	Сумма налога рассчитанная продавцом. Значение указывается в минимальных единицах валюты.

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

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

Обязательность	Название	Тип	Описание
Обязательно	`paymentMethod`	Integer	Тип платежа, доступные значения: `1` - полная предоплата; `2` - частичная предоплата; `3` - аванс; `4` - полная оплата; `5` - частичная оплата с последующей оплатой в кредит; `6` - без оплаты с последующей оплатой в кредит; `7` - оплата с последующей оплатой в кредит.

Обязательно	`paymentObject`	Integer	Объект платежа, доступные значения: `1` - товар (значение по умолчанию); `2` - подакцизный товар; `3` - работа; `4` - услуга; `5` - ставка азартной игры; `6` - выигрыш азартной игры; `7` - лотерейный билет; `8` - выигрыш лотереи; `9` - предоставление РИД; `10` - платеж; `11` - агентское вознаграждение; `12` - составной предмет расчета; `13` - иной предмет расчета; `14` - имущественное право; `15` - внереализационный доход; `16` - страховые взносы: о суммах расходов, уменьшающих сумму налога (авансовых платежей) в соответствии с пунктом 3.1 статьи 346.21 Налогового кодекса Российской Федерации; `17` - торговый сбор: о суммах уплаченного торгового сбора; `18` - курортный сбор. Указанные выше значения доступны для ФФД 1.05. Для ФФД 1.2 список доступных значений пополняется также следующими значениями: `30` - подакцизный товар, подлежащий маркировке средством идентификации, не имеющий кода маркировки `31` - подакцизный товар, подлежащий маркировке средством идентификации, имеющий код маркировки `32` - товар, подлежащий маркировке средством идентификации, имеющий код маркировки, за исключением подакцизного товара `33` - товар, подлежащий маркировке средством идентификации, имеющий код маркировки, за исключением подакцизного товара Приоритезация передачи значения происходит по следующему принципу (указано в убывающем порядке приоритета): 1) корзина заказа из API-запроса; 2) настройки фискализации в личном кабинете; 3) значения по умолчанию

Условие	`nomenclature`	String	Код товарной номенклатуры в шестнадцатеричном представлении с пробелами. Максимальная длина – 32 байта. Обязательно, если передано `markQuantity`.

Необязательно	`markQuantity`	Object	Дробное количество маркируемого товара. См. вложенные параметры.

Необязательно	`userData`	String [1..64]	Значение реквизита пользователя. Можно передавать только после согласования с ФНС.

Необязательно	`agent_info`	Object	Объект с данными о платежном агенте для товарной позиции.

Условие*	`agent_info.type`	Integer	Тип агента, доступные значения: `1` - банковский платежный агент; `2` - банковский платежный субагент; `3` - платежный агент; `4` - платежный субагент; `5` - поверенный; `6` - комиссионер; `7` - иной агент.

Необязательно	`agent_info.paying`	Object	Объект с данными о платежном агенте.

Необязательно	`agent_info.paying.operation`	String [1..24]	Название транзакции платежного агента.

Необязательно	`agent_info.paying.phones`	Array of strings	Массив телефонных номеров платежного агента в формате +N.

Необязательно	`agent_info.paymentsOperator`	Object	Объект с информацией об операторе по приему платежей.

Необязательно	`agent_info.paymentsOperator.phones`	Array of strings	Массив телефонных номеров платежного агента в формате +N.

Необязательно	`agent_info.MTOperator`	Object	Объект с данными об Операторе перевода.

Необязательно	`agent_info.MTOperator.phones`	Array of strings	Массив телефонных номеров оператора перевода в формате +N.

Необязательно	`agent_info.MTOperator.address`	String [1..256]	Наименование оператора перевода.

Необязательно	`agent_info.MTOperator.address`	String [1..256]	Адрес оператора перевода.

Необязательно	`agent_info.MTOperator.inn`	String [10..12]	ИНН оператора перевода.

Необязательно	`supplier_info`	Object	Объект с данными о поставщике для товарной позиции.

Необязательно	`supplier_info.phones`	Array of strings	Массив телефонных номеров поставщика в формате +N.

Необязательно	`supplier_info.name`	String	Наименование поставщика.

Необязательно	`supplier_info.inn`	String	ИНН поставщика

* Обязателен, если передается agent_info.

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

Обязательность	Название	Тип	Описание
Необязательно	`orderCreationDate`	String	Дата создания заказа в формате `YYYY-MM-DDTHH:MM:SS`.

Необязательно	`customerDetails`	Object	Блок, содержащий атрибуты клиента. Описание атрибутов тега приведено ниже.
Необязательно	`cartItems`	Object	Объект, содержащий атрибуты товаров в корзине. Описание вложенных элементов приведено ниже.

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

Обязательность	Название	Тип	Описание
Обязательно	`items`	Object	Элемент массива с атрибутами товарной позиции. Описание вложенных элементов приведено ниже.

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

Обязательность	Название	Тип	Описание
Обязательно	`positionId`	Integer [1..12]	Уникальный идентификатор товарной позиции в корзине.

Обязательно	`name`	String [1..255]	Наименование или описание товарной позиции в свободной форме.

Необязательно	`itemDetails`	Object	Объект с параметрами описания товарной позиции. Описание вложенных элементов приведено ниже.

Обязательно	`quantity`	Object	Элемент, описывающий передается общее количество товарных позиций одного `positionId` и его единицы измерения. Описание вложенных элементов приведено ниже.

Необязательно	`itemAmount`	Integer [1..12]	Сумма стоимости всех товарных позиций одного `positionId` в минимальных единицах валюты. `itemAmount` обязателен к передаче, только если не был передан параметр `itemPrice`. В противном случае передача `itemAmount` не требуется. Если же в запросе передаются оба параметра: `itemPrice` и `itemAmount`, то `itemAmount` должен равняться , в противном случае запрос завершится с ошибкой.

Необязательно	`itemPrice`	Integer [1..18]	Сумма стоимости товарной позиции одного `positionId` в деньгах в минимальных единицах валюты. Обязательно для мерчантов, использующих фискализацию.

Необязательно	`itemCurrency`	Integer	Код валюты ISO 4217. Если не указан, считается равным валюте заказа.

Обязательно	`itemCode`	String [1..100]	Номер (идентификатор) товарной позиции в системе магазина.

Необязательно	`discount`	Object	Объект, содержащий атрибуты скидки на товарную позицию. Описание вложенных элементов приведено ниже.

Необязательно	`agentInterest`	Object	Объект, содержащий атрибуты описания агентского вознаграждения за продажу товаров. Описание вложенных элементов приведено ниже.

Необязательно	`tax`	Object	Объект, содержащий атрибуты налога. Ниже приведено описание содержащихся атрибутов.

Необязательно	`itemAttributes`	Object	Объект, содержащий атрибуты товарной позиции.

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

Обязательность	Название	Тип	Описание
Необязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/deposit.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data currency=978\
  --data amount=2000 \
  --data orderId=01492437-d2fb-77fa-8db7-9e2900a7d8c0 \
  --data language=en

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

{
  "errorCode": 0,
  "errorMessage":"Success"
}

Отмена платежа

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

Платеж можно отменить только один раз. Если он завершится ошибкой, то последующие операции по отмене платежа работать не будут.

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

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца.

Обязательно	`orderId`	String [1..36]	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.

Необязательно	`language`	String [2]	Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: `ru,en`.

Необязательно	`orderNumber`	String [1..32]	Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа.

Необязательно	`jsonParams`	String	Поля для хранения дополнительных данных необходимо передавать следующим образом: `{"param":"value","param2":"value2"}`.Можно передать штраф за возврат в параметре `penalty`: `{"penalty":"1300"}`. Параметр `penalty` игнорируется для возвратов заказов с лояльностью, возвращается ошибка: `{"errorCode":"5","errorMessage":"Штрафы не поддерживаются для заказов с лояльностью"}`.

Необязательно	`merchantLogin`	String [1..255]	Чтобы отменить заказ от имени другого мерчанта, укажите его логин (для API-аккаунта) в этом параметре. Можно использовать, только если у вас есть разрешение на просмотр транзакций других продавцов или если указанный продавец является вашим дочерним продавцом.

Необязательно	`amount`	String [0..12]	Сумма отмены в минимальных единицах валюты. Если используется двухстадийная оплата, сумма отмены должна быть меньше или равна общей предварительно авторизованной сумме.

Необязательно	`currency`	Integer [3]	Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию.

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

Обязательность	Название	Тип	Описание
Необязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/reverse.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data currency=978\
  --data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --data language=en

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

{
  "errorCode": 0,
  "errorMessage":"Success"
}

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

Используйте refund.do для отправки запросов на возврат средств.

Нельзя осуществлять возврат средств по заказам, которые инициируют регулярные платежи, так как в этом случае не происходит списания средств.

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

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца.

Обязательно	`orderId`	String [1..36]	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.

Обязательно	`amount`	String [0..12]	Сумма возврата в минимальных единицах валюты. Если используется двухстадийный платеж, сумма возврата должна быть меньше или равна общей сумме завершения. Если в запросе указать `amount`=0, то будет возвращена вся сумма заказа.

Необязательно	`language`	String [2]	Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: `ru,en`.

Необязательно	`jsonParams`	String	Поля для хранения дополнительных данных необходимо передавать следующим образом: `{"param":"value","param2":"value2"}`.Можно передать штраф за возврат в параметре `penalty`: `{"penalty":"1300"}`. Параметр `penalty` игнорируется для возвратов заказов с лояльностью, возвращается ошибка: `{"errorCode":"5","errorMessage":"Штрафы не поддерживаются для заказов с лояльностью"}`.

Необязательно	`expectedDepositedAmount`	Integer [1..12]	Параметр служит для определения того, что запрос является повторным. Если параметр передан, его значение сравнивается с текущим значением `depositedAmount` в заказе. Операция будет выполнена только в том случае, если значения совпадают. Если два возврата приходят с одинаковым `expectedDepositedAmount`, будет выполнен только один возврат. Этот возврат изменит значение `depositedAmount`, а затем второй возврат будет отклонен.

Необязательно	`externalRefundId`	String [1..30]	Идентификатор возврата. При попытке возврата проверяется `externalRefundId`: если он существует, возвращается успешный ответ с данными о возврате, если нет — осуществляется возврат.

Необязательно	`currency`	Integer [3]	Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию.

Необязательно	`refundItems`	Object	Объект для передачи информации о возвращаемых товарах - номер позиции товара в запросе, название, детали, единица измерения, количество, валюта, код товара, скидка, прибыль агента.

Необязательно	`additionalOfdParams`	Object	Если блок `additionalOfdParams` был передан при регистрации заказа, его можно передать при возврате средств. При этом значения некоторых параметров, переданных при регистрации, можно изменить (см. описание блока ниже). Передача этого блока возможна только при использовании следующих ОФД: АТОЛ; Бизнес.Ру; Эвотор.

Параметр refundItems включает в себя:

Обязательность	Название	Тип	Описание
Необязательно	`items`	Object	Элемент массива с атрибутами товарной позиции. Описание вложенных элементов приведено ниже.

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

Обязательность	Название	Тип	Описание
Обязательно	`positionId`	Integer [1..12]	Уникальный идентификатор товарной позиции в корзине.

Обязательно	`name`	String [1..255]	Наименование или описание товарной позиции в свободной форме.

Необязательно	`itemDetails`	Object	Объект с параметрами описания товарной позиции. Описание вложенных элементов приведено ниже.

Обязательно	`quantity`	Object	Элемент, описывающий передается общее количество товарных позиций одного `positionId` и его единицы измерения. Описание вложенных элементов приведено ниже.

Необязательно	`itemAmount`	Integer [1..12]	Сумма стоимости всех товарных позиций одного `positionId` в минимальных единицах валюты. `itemAmount` обязателен к передаче, только если не был передан параметр `itemPrice`. В противном случае передача `itemAmount` не требуется. Если же в запросе передаются оба параметра: `itemPrice` и `itemAmount`, то `itemAmount` должен равняться , в противном случае запрос завершится с ошибкой.

Необязательно	`itemPrice`	Integer [1..18]	Сумма стоимости товарной позиции одного `positionId` в деньгах в минимальных единицах валюты. Обязательно для мерчантов, использующих фискализацию.

Необязательно	`itemCurrency`	Integer	Код валюты ISO 4217. Если не указан, считается равным валюте заказа.

Обязательно	`itemCode`	String [1..100]	Номер (идентификатор) товарной позиции в системе магазина.

Необязательно	`discount`	Object	Объект, содержащий атрибуты скидки на товарную позицию. Описание вложенных элементов приведено ниже.

Необязательно	`agentInterest`	Object	Объект, содержащий атрибуты описания агентского вознаграждения за продажу товаров. Описание вложенных элементов приведено ниже.

Необязательно	`tax`	Object	Объект, содержащий атрибуты налога. Ниже приведено описание содержащихся атрибутов.

Необязательно	`itemAttributes`	Object	Объект, содержащий атрибуты товарной позиции.

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

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

Обязательность	Название	Тип	Описание
Обязательно	`paymentMethod`	Integer	Тип платежа, доступные значения: `1` - полная предоплата; `2` - частичная предоплата; `3` - аванс; `4` - полная оплата; `5` - частичная оплата с последующей оплатой в кредит; `6` - без оплаты с последующей оплатой в кредит; `7` - оплата с последующей оплатой в кредит.

Обязательно	`paymentObject`	Integer	Объект платежа, доступные значения: `1` - товар (значение по умолчанию); `2` - подакцизный товар; `3` - работа; `4` - услуга; `5` - ставка азартной игры; `6` - выигрыш азартной игры; `7` - лотерейный билет; `8` - выигрыш лотереи; `9` - предоставление РИД; `10` - платеж; `11` - агентское вознаграждение; `12` - составной предмет расчета; `13` - иной предмет расчета; `14` - имущественное право; `15` - внереализационный доход; `16` - страховые взносы: о суммах расходов, уменьшающих сумму налога (авансовых платежей) в соответствии с пунктом 3.1 статьи 346.21 Налогового кодекса Российской Федерации; `17` - торговый сбор: о суммах уплаченного торгового сбора; `18` - курортный сбор. Указанные выше значения доступны для ФФД 1.05. Для ФФД 1.2 список доступных значений пополняется также следующими значениями: `30` - подакцизный товар, подлежащий маркировке средством идентификации, не имеющий кода маркировки `31` - подакцизный товар, подлежащий маркировке средством идентификации, имеющий код маркировки `32` - товар, подлежащий маркировке средством идентификации, имеющий код маркировки, за исключением подакцизного товара `33` - товар, подлежащий маркировке средством идентификации, имеющий код маркировки, за исключением подакцизного товара Приоритезация передачи значения происходит по следующему принципу (указано в убывающем порядке приоритета): 1) корзина заказа из API-запроса; 2) настройки фискализации в личном кабинете; 3) значения по умолчанию

Условие	`nomenclature`	String	Код товарной номенклатуры в шестнадцатеричном представлении с пробелами. Максимальная длина – 32 байта. Обязательно, если передано `markQuantity`.

Необязательно	`markQuantity`	Object	Дробное количество маркируемого товара. См. вложенные параметры.

Необязательно	`userData`	String [1..64]	Значение реквизита пользователя. Можно передавать только после согласования с ФНС.

Необязательно	`agent_info`	Object	Объект с данными о платежном агенте для товарной позиции.

Условие*	`agent_info.type`	Integer	Тип агента, доступные значения: `1` - банковский платежный агент; `2` - банковский платежный субагент; `3` - платежный агент; `4` - платежный субагент; `5` - поверенный; `6` - комиссионер; `7` - иной агент.

Необязательно	`agent_info.paying`	Object	Объект с данными о платежном агенте.

Необязательно	`agent_info.paying.operation`	String [1..24]	Название транзакции платежного агента.

Необязательно	`agent_info.paying.phones`	Array of strings	Массив телефонных номеров платежного агента в формате +N.

Необязательно	`agent_info.paymentsOperator`	Object	Объект с информацией об операторе по приему платежей.

Необязательно	`agent_info.paymentsOperator.phones`	Array of strings	Массив телефонных номеров платежного агента в формате +N.

Необязательно	`agent_info.MTOperator`	Object	Объект с данными об Операторе перевода.

Необязательно	`agent_info.MTOperator.phones`	Array of strings	Массив телефонных номеров оператора перевода в формате +N.

Необязательно	`agent_info.MTOperator.address`	String [1..256]	Наименование оператора перевода.

Необязательно	`agent_info.MTOperator.address`	String [1..256]	Адрес оператора перевода.

Необязательно	`agent_info.MTOperator.inn`	String [10..12]	ИНН оператора перевода.

Необязательно	`supplier_info`	Object	Объект с данными о поставщике для товарной позиции.

Необязательно	`supplier_info.phones`	Array of strings	Массив телефонных номеров поставщика в формате +N.

Необязательно	`supplier_info.name`	String	Наименование поставщика.

Необязательно	`supplier_info.inn`	String	ИНН поставщика

* Обязателен, если передается agent_info.

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

Обязательность	Название	Тип	Описание
Обязательно	`numerator`	String	Числитель дробной части объекта платежа.

Обязательно	`denominator`	String	Знаменатель дробной части объекта платежа.

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

Обязательность	Название	Тип	Описание
Обязательно	`value`	String	Количество товарных позиций данного `positionId`. Для указания дробных чисел используйте десятичную точку. При ФФД 1.2+ значение `value` всегда `1`.

Обязательно	`measure`	String [1..20]	Единица измерения количества по позиции. Для ФФД 1.2+, если переданы параметры `nomenclature` и `markQuantity`, `measure` всегда равно `0`. Для других ФФД возможны иные значения.

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

Значение	Описание
0	Применяется к позициям, которые могут быть реализованы индивидуально или отдельными единицами, а также если объект платежа является предметом, подлежащим обязательной идентификационной маркировке.
10	Грамм
11	Килограмм
12	Тонна
20	Сантиметр
21	Дециметр
22	Метр
30	Квадратный сантиметр
31	Квадратный дециметр
32	Квадратный метр
40	Миллилитр
41	Литр
42	Кубический метр
50	Киловатт час
51	Гигакалория
70	День
71	Час
72	Минута
73	Секунда
80	Килобайт
81	Мегабайт
82	Гигабайт
83	Терабайт
255	Применяется к другим единицам измерения

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

Обязательность	Название	Тип	Описание
Необязательно	`itemDetailsParams`	Object	Параметр, описывающий дополнительную информацию по товарной позиции. Описание вложенных элементов приведено ниже.

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

Обязательность	Название	Тип	Описание
Обязательно	`value`	String	Дополнительная информация по товарной позиции.

Обязательно	`name`	String [1..255]	Наименование параметра описания детализации товарной позиции

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

Обязательность	Название	Тип	Описание
Обязательно	`discountType`	String [1..20]	Тип скидки на товарную позицию

Обязательно	`discountValue`	Integer [0..20]	Значение скидки на товарную позицию.

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

Обязательность	Название	Тип	Описание
Обязательно	`interestType`	String [1..20]	Тип агентской комиссии.

Обязательно	`interestValue`	Integer [1..20]	Значение агентской комиссии.

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

Обязательность	Название	Тип	Описание
Обязательно	`taxType`	Integer	Ставка НДС, доступны следующие значения: `0` – без НДС; `1` – НДС по ставке 0%; `2` – НДС чека по ставке 10%; `4` – НДС чека по расчетной ставке 10/110; `6` – НДС чека по ставке 20%; `7` – НДС чека по расчетной ставке 20/120.

Обязательно	`taxSum`	Integer [1..18]	Сумма налога рассчитанная продавцом. Значение указывается в минимальных единицах валюты.

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

Обязательность	Название	Тип	Описание
Необязательно	`agent_info.type`	Integer	Тип агента, доступные значения: `1` - банковский платежный агент; `2` - банковский платежный субагент; `3` - платежный агент; `4` - платежный субагент; `5` - поверенный; `6` - комиссионер; `7` - иной агент.

Необязательно	`agent_info.paying.operation`	String [1..24]	Название транзакции платежного агента.

Необязательно	`agent_info.paying.phones`	Array of strings	Массив телефонных номеров платежного агента в формате +N.

Необязательно	`agent_info.paymentsOperator.phones`	Array of strings	Массив телефонных номеров платежного агента в формате +N.

Необязательно	`agent_info.MTOperator.address`	String [1..256]	Адрес оператора перевода.

Необязательно	`agent_info.MTOperator.inn`	String [10..12]	ИНН оператора перевода.

Необязательно	`agent_info.MTOperator.address`	String [1..256]	Наименование оператора перевода.

Необязательно	`agent_info.MTOperator.phones`	Array of strings	Массив телефонных номеров оператора перевода в формате +N.

Необязательно	`supplier_info.phones`	Array of strings	Массив телефонных номеров поставщика в формате +N.

Необязательно	`cashier`	String [1..256]	Имя кассира.

Необязательно	`additional_check_props`	String [1..16]	Дополнительные свойства чека.

Необязательно	`additional_user_props.name`	String [1..24]	Название дополнительного свойства пользователя

Необязательно	`additional_user_props.value`	String [1..24]	Значение дополнительного свойства пользователя

Необязательно	`cashier_inn`	String [10..12]	ИНН кассира.

Необязательно	`client.address`	String [1..256]	Адрес клиента.

Необязательно	`client.birth_date`	String [10]	Дата рождения клиента в формате дд.мм.гггг.

Необязательно	`client.citizenship`	String [3]	Цифровой код страны, гражданином которой является покупатель (клиент).

Необязательно	`client.document_code`	String [2]	Цифровой код вида документа, удостоверяющего личность (например, 21 - паспорт гражданина РФ).

Необязательно	`client.passport_number`	String [11]	Серия и номер паспорта плательщика.

Необязательно	`client.email`	String [1..64]	Электронная почта плательщика. Обязательно заполнение строго одного из полей: электронная почта или телефон.

Необязательно	`client.phone`	String [19]	Телефон покупателя. Вместе с кодом страны без пробелов и дополнительных символов, кроме символа «+» (номер «+371 2 1234567» следует передавать как «+37121234567»). Обязательно заполнение строго одного из полей: электронная почта или телефон.

Необязательно	`client.inn`	String [12]	ИНН клиента.

Необязательно	`client.name`	String [1..256]	Имя клиента.

Необязательно	`operatingcheckprops.name`	String	Идентификатор транзакции. Принимает значения "0" до тех пор, пока не будет определено значение реквизита ФНС России.

Необязательно	`operatingcheckprops.timestamp`	String [1..19]	Дата и время операции в формате: дд.мм.гггг ЧЧ:ММ:СС.

Необязательно	`operatingcheckprops.value`	String [1..64]	Данные транзакции.

Необязательно	`sectoralcheckprops.date`	String [10]	Дата принятия нормативного акта федерального органа исполнительной власти, регулирующего порядок заполнения "значения отраслевого реквизита", в формате: дд.мм.гггг.

Необязательно	`sectoralcheckprops.federalid`	String	Идентификатор федерального органа исполнительной власти. Должен принимать одно из значений из справочника федеральных органов исполнительной власти.

Необязательно	`sectoralcheckprops.number`	String [32]	Номер нормативного акта федерального органа исполнительной власти, регламентирующего порядок заполнения реквизита «значение отраслевого реквизита»

Необязательно	`sectoralcheckprops.value`	String [1..256]	Состав значений, определенных нормативным актом федерального органа исполнительной власти

Условие	`company.automat_number`	String	Номер автомата. Условия обязательной передачи параметров: Формат фискальных документов 1.05 – для вендинга и транспорта; Формат фискальных документов 1.2 – для вендинга и транспорта.

Условие	`company.location`	String	Адрес для выставления счета. Условия обязательной передачи параметров: Формат фискальных документов 1.05 – для вендинга, транспорта, курьеров. Формат фискальных документов 1.2 – для вендинга, транспорта, курьеров.

Условие	`company.payment_address`	String	Адрес для получения счетов. Условия обязательной передачи параметров: Формат фискальных документов 1.05 – для вендинга, транспорта, курьеров. Формат фискальных документов 1.2 – для вендинга, транспорта, курьеров.

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

Обязательность	Название	Тип	Описание
Необязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/refund.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data currency=978\
  --data orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --data amount=2000 \
  --data language=en

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

{
  "errorCode": 0,
  "errorMessage":"Success"
}

Отмена заказа

Чтобы отменить еще не оплаченный заказ, используйте запрос decline.do. Отклонить можно только заказ, который не был завершен. После успешного выполнения данного запроса заказ переходит в статус DECLINED.

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца.

Необязательно	`merchantLogin`	String [1..255]	Чтобы зарегистрировать заказ от имени другого мерчанта, укажите его логин (для API-аккаунта) в этом параметре. Можно использовать, только если у вас есть разрешение на просмотр транзакций других продавцов или если указанный продавец является вашим дочерним продавцом.

Необязательно	`language`	String [2]	Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: `ru,en`.

Обязательно	`orderId`	String [1..36]	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.

Обязательно	`orderNumber`	String [1..32]	Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа.

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

Обязательность	Название	Тип	Описание
Обязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Обязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/decline.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderId=8cf0409e-857e-7f95-8ab1-b6810009d884 \
  --data orderNumber=12345678 \
  --data merchantLogin=merch_test418 \
  --data language=en

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

{
  "errorCode": 0,
  "errorMessage":"Success"
}

Связки

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

Оплата по связке

Для оплаты заказа по связке используется запрос paymentOrderBinding.do.

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца.

Обязательно	`mdOrder`	String [1..36]	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.

Обязательно	`bindingId`	String [1..255]	Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что: Этот заказ можно оплатить только с помощью связки; Плательщик будет перенаправлен на страницу оплаты, где требуется только ввод CVC.

Необязательно	`language`	String [2]	Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: `ru,en`.

Необязательно	`ip`	String [1..39]	IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). При использовании аутентификации 3DS 2 рекомендуем вам передавать в этом параметре реальный IP адрес клиента. Это позволит повысить конверсию в оплату на стороне ACS.

Необязательно	`cvc`	Integer	Этот параметр обязателен, если для мерчанта не выбрано разрешение Может проводить оплату без подтверждения CVC.

Необязательно	`threeDSSDK`	Boolean	Возможные значения: `true` или `false` Флаг, показывающий, что платеж поступает из 3DS SDK.

Обязательно	`tii`	String	Идентификатор инициатора транзакции. Параметр, указывающий, какой тип операции будет выполнять инициатор (Клиент или Мерчант). Возможные значения

Необязательно	`jsonParams`	Object	Набор дополнительных параметров произвольной формы, структура: `{name1:value1,…,nameN:valueN}` Некоторые предопределенные атрибуты jsonParams: `email` - электронная почта держателя карты для предварительного заполнения на странице оформления заказа `phone` - номер телефона держателя карты для выставления счетов для предварительного заполнения на странице оформления заказа `backToShopUrl` - добавляет на страницу оплаты кнопку, которая вернет держателя карты на назначенный URL-адрес веб-сайта продавца. `backToShopName` - настраивает текстовую метку кнопки Вернуться в магазин по умолчанию, если она используется вместе с `backToShopUrl` `installments` - максимальное количество разрешенных авторизаций для платежей в рассрочку. Требуется для создания связки рассрочки. `recurringFrequency` - минимальное количество дней между авторизациями. Требуется для создания рекуррентной связки, рекомендуется для создания связки рассрочки (если используется 3DS2, параметр обязателен). `recurringExpiry` - дата, после которой авторизации не разрешены, в формате ГГГГММДД. Требуется для создания рекуррентной связки, рекомендуется для создания связки рассрочки (если используется 3DS2, параметр обязателен).

Необязательно	`threeDSProtocolVersion`	String	Версия протокола 3DS. Возможные значения: "1.0.2" для 3DS1; "2.1.0", "2.2.0" для 3DS2. Если в запросе не передается `threeDSProtocolVersion`, то для авторизации 3D Secure будет использоваться значение по умолчанию (`1.0.2` - для 3DS 1 или `2.1.0` - для 3DS 2).

Необязательно	`externalScaExemptionIndicator`	String	Тип исключения SCA (Strong Customer Authentication). Если указан этот параметр, транзакция будет обработана в зависимости от ваших настроек в платежном шлюзе: либо будет выполнена принудительная операция SSL, либо банк-эмитент получит информацию об исключении SCA и примет решение о проведении операции с 3DS-аутентификацией или без нее (для получения подробной информации свяжитесь с нашей службой поддержки). Допустимые значения: `LVP` – транзакция типа Low Value Payments. Транзакция может быть отнесена к транзакциям с низким уровнем риска на основе суммы транзакции, количества транзакций клиента в день или общей дневной суммы платежей клиента. `TRA` – транзакция типа Transaction Risk Analysis, т.е. транзакция, прошедшая успешную антифрод-проверку. Для передачи этого параметра у вас должны быть достаточные права в платежном шлюзе.

Условие	`seToken`	String	Зашифрованные данные карты, которые заменяют параметры `$PAN`, `$CVC` и `$EXPIRY` (или `YYYY`,`MM`). Обязательно, если используется вместо данных карты. Обязательные параметры для строки seToken: `timestamp`, `UUID`, `bindingId`, `MDORDER`. Подробнее о генерации seToken см. здесь.

Optional	`clientBrowserInfo`	Object	Блок данных о браузере клиента, который отправляется на ACS во время 3DS аутентификации. Этот блок можно передавать, только если включена специальная настройка (обратитесь в команду поддержки). См. вложенные параметры.

Необязательно	`acsInIFrame`	Boolean	Флаг, показывающий, что для финишного URL будет возвращаться iFrame версия. Возможные значения `true` or `false`. Для подключения данной функциональности обратитесь в службу поддержки.

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

Значение `tii`	Описание	Тип транзакции	Инициатор транзакции	Данные карты для транзакции	Сохранение данных карты после транзакции	Примечание
Пусто		Обычный	Покупатель	Вводится покупателем	Нет	Транзакция электронной коммерции без сохранения связки.
CI	Инициирующий - Обычный (CIT)	Инициирующая	Покупатель	Вводится покупателем	Да	Транзакция электронной коммерции с сохранением связки.
F	Внеплановый платеж (CIT)	Последующая	Покупатель	Клиент выбирает карту вместо ручного ввода	Нет	Транзакция электронной коммерции, использующая ранее сохраненную обычную связку.
U	Внеплановый платеж (MIT)	Последующая	Продавец	Нет ручного ввода, продавец передает данные	Нет	Транзакция электронной коммерции, использующая ранее сохраненную обычную связку.
RI	Инициирующий - Рекурентные (CIT)	Инициирующая	Покупатель	Вводится покупателем	Да	Транзакция электронной коммерции с сохранением связки.
R	Рекуррентный платеж (MIT)	Последующая	Продавец	Нет ручного ввода, продавец передает данные	Нет	Рекуррентная операция, использующая сохраненную связку.
II	Инициирующий - Рассрочка (CIT)	Инициирующая	Покупатель	Вводится покупателем	Да	Транзакция электронной коммерции с сохранением связки.
I	Платеж по рассрочке (MIT)	Последующая	Продавец	Нет ручного ввода, продавец передает данные	Нет	Операция рассрочки, использующая сохраненную связку.

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

Обязательность	Название	Тип	Описание
Необязательно	userAgent	string	Агент браузера.
Необязательно	OS	string	Операционная система.
Необязательно	OSVersion	string	Версия операционной системы.
Необязательно	browserAcceptHeader	string	Заголовок Accept, который сообщает серверу, какие форматы (или MIME-типы) поддерживает браузер.
Необязательно	browserIpAddress	string	IP-адрес браузера.
Необязательно	browserLanguage	string	Язык браузера.
Необязательно	browserTimeZone	string	Часовой пояс браузера.
Необязательно	browserTimeZoneOffset	integer	Смещение часового пояса в минутах между локальным временем пользователя и UTC.
Необязательно	colorDepth	string	Глубина цвета экрана, в битах.
Необязательно	fingerprint	string	Отпечаток браузера - уникальный цифровой идентификатор браузера.
Необязательно	isMobile	Boolean	Возможные значения: `true` или `false`. Флаг, указывающий на то, что используется мобильное устройство.
Необязательно	javaEnabled	Boolean	Возможные значения: `true` или `false`. Флаг, указывающий на то, что в браузере включена поддержка java.
Необязательно	javascriptEnabled	Boolean	Возможные значения: `true` или `false`. Флаг, указывающий на то, что в браузере включена поддержка javascript.
Необязательно	plugins	string	Список плагинов, используемых в браузере, через запятую.
Необязательно	screenHeight	integer	Высота экрана в пикселях.
Необязательно	screenWidth	integer	Ширина экрана в пикселях.
Необязательно	screenPrint	string	Данные о параметрах печати браузера, включая разрешение, глубину цвета, плотность пикселей.

Пример блока 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":"10.99.50.37"
    }

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

Обязательность	Название	Тип	Описание
Обязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Необязательно	`redirect`	String [1..512]	Этот параметр возвращается, если платеж прошел успешно и для платежа не проводилась проверка карты на вовлеченность в 3-D Secure. Продавцы могут использовать его, если хотят перенаправить пользователя на страницу платежного шлюза. Если продавец использует собственную страницу, это значение можно игнорировать.

Необязательно	`info`	String	В случае успешного ответа. Результат попытки оплаты. Ниже приведены возможные значения. Ваш платеж обработан, происходит переадресация... Операция отклонена. Проверьте введенные данные, достаточность средств на карте и повторите операцию. Происходит переадресация... Извините, платеж не может быть совершен. Происходит переадресация... Операция отклонена. Обратитесь в магазин. Происходит переадресация... Операция отклонена. Обратитесь в банк, выпустивший карту. Происходит переадресация... Невозможная операция Аутентификация держателя карты завершена неуспешно. Происходит переадресация... Нет связи с банком. Повторите позже. Происходит переадресация... Истек срок ожидания ввода данных. Происходит переадресация... Не получен ответ от банка. Повторите позже. Происходит переадресация...

Необязательно	`error`	String	Сообщение об ошибке (если в ответе вернулась ошибка) на языке, переданном в запросе.

Необязательно	`processingErrorType`	String	Тип ошибки процессинга. Передается, если ошибка возникает на стороне процессинга, а не в платежном шлюзе, при этом число попыток оплаты не превышено и еще не было перенаправления на финальную страницу.

Необязательно	`displayErrorMessage`	String	Отображаемое сообщение об ошибке.

Необязательно*	`errorTypeName`	String	Параметр, необходимый фронтенд странице для определения типа ошибки. Обязательно для неудачных платежей.

Необязательно	`acsUrl`	String [1..512]	При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Подробнее см. Редирект на ACS.

Необязательно	`paReq`	String [1..255]	При успешном ответе в случае оплаты 3D-Secure. PAReq (Payment Authentication Request) — сообщение, которое необходимо отправить в ACS вместе с редиректом. Это сообщение содержит данные в кодировке Base64, необходимые для аутентификации держателя карты. Подробнее см. Редирект на ACS.

Необязательно	`termUrl`	String [1..512]	При успешном ответе в случае оплаты 3D-Secure. Это URL-адрес, на который ACS перенаправляет владельца карты после аутентификации. Подробнее см. Редирект на ACS.

Необязательно	`acsInIFrame`	Boolean	Флаг, показывающий, что для финишного URL будет возвращаться iFrame версия. Возможные значения `true` or `false`. Для подключения данной функциональности обратитесь в службу поддержки.

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/paymentOrderBinding.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data mdOrder=01491d0b-c848-7dd6-a20d-e96900a7d8c0 \
  --data bindingId=01491394-63a6-7d45-a88f-7bce00a7d8c0 \
  --data cvc=123 \
  --data tii=F \
  --data language=en

Пример успешного ответа для SSL-платежа (без 3-D Secure)

{
  "redirect": "https://vtb.rbsuat.com/payment/merchants/temp/finish.html?orderId=01491d0b-c848-7dd6-a20d-e96900a7d8c0&lang=en",
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0
}

Пример успешного ответа на для платежа 3D-Secure

{
  "info": "Your order is proceeded, redirecting...",
  "errorCode": 0,
  "acsUrl": "https://theacsserver.com/acs/auth/start.do",
  "paReq": "eJxVUu9vgjAQ/...4BaHYvAI=",
  "termUrl": "https://vtb.rbsuat.com/payment/rest/finish3ds.do?lang=en"
}

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

{
  "error": "Access denied",
  "errorCode": 5,
  "errorMessage": "Access denied"
}

Получение связок

Для получения списка клиентских привязок используется запрос getBindings.do.

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

Обязательность	Название	Тип	Описание
Обязательно	`clientId`	String [0..255]	Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен.

Необязательно	`language`	String [2]	Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: `ru,en`.

Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Необязательно	`bindingId`	String [1..255]	Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что: Этот заказ можно оплатить только с помощью связки; Плательщик будет перенаправлен на страницу оплаты, где требуется только ввод CVC.

Необязательно	`bindingType`	String	Тип связки, который ожидается в ответе (если он не указан, возвращаются все типы). Возможные значения: C – обычная связка. R – рекуррентная связка. I - связка для рассрочки.

Необязательно	`showExpired`	Boolean	`true`/`false` параметр, определяющий, показывать ли связки с просроченными картами. Значение по умолчанию: `false`.

Необязательно	`merchantLogin`	String [1..255]	Чтобы получить список сохраненных клиентом учетных данных другого мерчанта, укажите в этом параметре логин мерчанта (для API-аккаунта). Можно использовать, только если у вас есть разрешение на просмотр транзакций других продавцов или если указанный продавец является вашим дочерним продавцом. И вы, и указанный продавец должны иметь разрешение на работу с сохраненными учетными данными (связками).

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

Обязательность	Название	Тип	Описание
Обязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Необязательно	`bindings`	Object	Элемент с блоками, содержащими параметры связок. См. описание ниже.

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

Обязательность	Название	Тип	Описание
Необязательно	`maskedPan`	String [1..19]	Маскированный номер карты, использованной для платежа. Указывается только после оплаты заказа.

Необязательно	`paymentWay`	String	Способ совершения платежа (платеж с вводом карточных данных, оплата по связке и т.п.). Дополнительные возможные значения параметра приведены ниже

Обязательно	`bindingId`	String [1..255]	Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что: Этот заказ можно оплатить только с помощью связки; Плательщик будет перенаправлен на страницу оплаты, где требуется только ввод CVC.

Обязательно	`expiryDate`	Integer	Срок действия карты в следующем формате: .`YYYYMM` Указывается только после оплаты заказа.

Необязательно	`bindingCategory`	String	Назначение связки, ожидаемой в ответе. Возможные значения: COMMON, INSTALLMENT, RECURRENT.

Необязательно	`clientId`	String [0..255]	Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен.

Необязательно	`displayLabel`	Integer [1..16]	Последние 4 цифры исходного PAN перед токенизацией.

Необязательно	`paymentSystem`	String	Наименование платежной системы. Возможны следующие значения: `VISA`; `MASTERCARD`; `AMEX`; `JCB`; `CUP`;

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/getBindings.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data clientId=dos-clientos \
  --data bindingType=C

Пример успешного запроса

{
"errorCode":"0",
"errorMessage":"Success",
"bindings": [
    {
        "bindingId":"69d6a793-afb5-79be-8ce7-63ff00a8656a",
        "maskedPan":"400000**1118",
        "expiryDate":"203012",
        "paymentWay":"CARD",
        "displayLabel":"XXXXXXXXXXXX1118"
        }
    ]
 }

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

Для получения списка всех связок банковской карты используется запрос getBindingsByCardOrId.do.

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца.

Условие	`pan`	String [1..19]	Номер платежной карты (обязательно, если если `bindinId` не передается). Значение `pan` заменяет собой значение `bindingId`.

Условие	`bindingId`	String [1..255]	Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что: Этот заказ можно оплатить только с помощью связки; Плательщик будет перенаправлен на страницу оплаты, где требуется только ввод CVC.

Необязательно	`showExpired`	Boolean	`true`/`false` параметр, определяющий, показывать ли связки с просроченными картами. Значение по умолчанию: `false`.

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

Обязательность	Название	Тип	Описание
Обязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Необязательно	`bindings`	Object	Элемент с блоками, содержащими параметры связок: `bindingId`, `maskedPan`, `expiryDate`, `clientId`

Необязательно	`bindingId`	String [1..255]	Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что: Этот заказ можно оплатить только с помощью связки; Плательщик будет перенаправлен на страницу оплаты, где требуется только ввод CVC.

Необязательно	`maskedPan`	String [1..19]	Маскированный номер карты, использованной для платежа. Указывается только после оплаты заказа.

Необязательно	`expiryDate`	Integer	Срок действия карты в следующем формате: .`YYYYMM` Указывается только после оплаты заказа.

Необязательно	`clientId`	String [0..255]	Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен.

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/getBindingsByCardOrId.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data pan=4000001111111118

Пример успешного запроса

{
"errorCode":"0",
"errorMessage":"Success",
"bindings": [
    {
        "bindingId":"69d6a793-afb5-79be-8ce7-63ff00a8656a",
        "maskedPan":"400000**1118",
        "expiryDate":"203012",
        "clientId":"12"
        }
    {
        "bindingId":"6a8c0738-cc88-4200-acf6-afc264d66cb0",
        "maskedPan":"400000**1118",
        "expiryDate":"203012",
        "clientId":"13"
        }
    ]
 }

Деактивация связки

Для деактивации существующей связки используется запрос unBindCard.do.

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца.
Обязательно	`bindingId`	String [1..255]	Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что: Этот заказ можно оплатить только с помощью связки; Плательщик будет перенаправлен на страницу оплаты, где требуется только ввод CVC.

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

Обязательность	Название	Тип	Описание
Необязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/unBindCard.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data bindingId=fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc

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

{
"errorCode":"2",
"errorMessage":"Связка не активна",
}

Активация связки

Запрос, используемый для активации существующей привязки, которая была деактивирована, называется bindCard.do.

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца.
Обязательно	`bindingId`	String [1..255]	Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что: Этот заказ можно оплатить только с помощью связки; Плательщик будет перенаправлен на страницу оплаты, где требуется только ввод CVC.

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

Обязательность	Название	Тип	Описание
Необязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/bindCard.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data bindingId=fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc

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

{
"errorCode":"2",
"errorMessage":"Binging is active",
}

Продление срока действия связки

Запрос, используемый для продления срока действия существующей привязки, называется extendBinding.do.

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца.

Обязательно	`bindingId`	String [1..255]	Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что: Этот заказ можно оплатить только с помощью связки; Плательщик будет перенаправлен на страницу оплаты, где требуется только ввод CVC.

Обязательно	`newExpiry`	Integer	Новая дата (год и месяц) окончания срока действия в формате `YYYYMM`.

Обязательно	`language`	String [2]	Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: `ru,en`.

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

Обязательность	Название	Тип	Описание
Необязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/extendBinding.do \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data bindingId=fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc
  --data newExpiry=202212
  --data language=en

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

{
"errorCode":"0",
"errorMessage":"Success",
}

Рекуррентный платеж

Для проведения рекуррентного платежа используется запрос /payment/recurrentPayment.do. Запрос используется для регистрации и оплаты заказа.

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца.

Обязательно	`orderNumber`	String [1..32]	Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа.

Необязательно	`language`	String [2]	Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: `ru,en`.

Необязательно	`feeInput`	String	Размер комиссии в минимальных единицах валюты. Функциональность должна быть включена на уровне продавца в шлюзе.

Обязательно	`bindingId`	String [1..255]	Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что: Этот заказ можно оплатить только с помощью связки; Плательщик будет перенаправлен на страницу оплаты, где требуется только ввод CVC.

Обязательно	`amount`	Integer [0..12]	Сумма платежа в минимальных единицах валюты (например, в копейках).

Необязательно	`currency`	Integer [3]	Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию.

Необязательно	`description`	String [1..598]	Описание заказа в любом формате. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки.

Необязательно	`additionalParameters`	Object	Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования. `{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}`

Условие	`billingPayerData`	Object	Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры.

Необязательно	`shippingPayerData`	Object	Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.

Необязательно	`preOrderPayerData`	Object	Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.

Необязательно	`orderPayerData`	Object	Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.

Необязательно	`billingAndShippingAddressMatchIndicator`	A1	Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. Возможные значения: `Y` - совпадение платежного адреса держателя карты и адреса доставки; `N` - платежный адрес владельца карты и адрес доставки не совпадают.

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

Обязательность	Название	Тип	Описание
Необязательно	`billingCity`	String [0..50]	Город, зарегистрированный по конкретной карте у Банка Эмитента.

Необязательно	`billingCountry`	String [0..50]	Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой).

Необязательно	`billingAddressLine1`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки.

Необязательно	`billingAddressLine2`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2.

Необязательно	`billingAddressLine3`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3.

Необязательно	`billingPostalCode`	String [0..9]	Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки.

Необязательно	`billingState`	String [0..50]	Штат, зарегистрированный по конкретной карте у Банка Эмитента.

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

Обязательность	Название	Тип	Описание
Необязательно	`shippingCity`	ANS...50	Город заказчика (из адреса доставки)
Необязательно	`shippingCountry`	ANS...50	Страна заказчика
Необязательно	`shippingAddressLine1`	ANS...50	Основной адрес клиента (из адреса доставки)
Необязательно	`shippingAddressLine2`	ANS...50	Основной адрес клиента (из адреса доставки)
Необязательно	`shippingAddressLine3`	ANS...50	Основной адрес клиента (из адреса доставки)
Необязательно	`shippingPostalCode`	ANS...16	Почтовый индекс клиента для доставки
Необязательно	`shippingState`	ANS...50	Штат/регион покупателя (из адреса доставки)
Необязательно	`shippingMethodIndicator`	N2	Индикатор способа доставки. Возможные значения: `01` - доставка на платежный адрес держателя карты. `02` - доставка на другой адрес, проверенный Мерчантом. `03` - доставка по адресу, отличному от основного адреса держателя карты. `04` - отправка в магазин/самовывоз (адрес магазина должен быть указан в соответствующих параметрах доставки) `05` - Цифровое распространение (включает онлайн-сервисы и электронные подарочные карты) `06` - билеты на путешествия и мероприятия, которые нельзя доставить. `07` - Прочее (например, игры, цифровые товары, не подлежащие доставке, цифровые подписки и т. д.)
Необязательно	`deliveryTimeframe`	N2	Срок поставки товара. Возможные значения: `01` - цифровая дистрибуция `02` - доставка в тот же день `03` - доставка на следующий день `04` - доставка в течение 2-х дней после оплаты и позже.
Необязательно	`deliveryEmail`	ANS...254	Целевой адрес электронной почты для доставки цифрового распространения

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

Обязательность	Название	Тип	Описание
Необязательно	`preOrderDate`	ANS8	Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД.
Необязательно	`preOrderPurchaseInd`	N2	Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения: `01` - возможна доставка; `02` - будущая доставка
Необязательно	`reorderItemsInd`	N2	Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения: `01` - заказ размещается впервые; `02` - повторный заказ

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

Обязательность	Название	Тип	Описание
Необязательно	`homePhone`	ANS...19	Домашний телефон владельца карты с обязательным знаком «+».
Необязательно	`workPhone`	ANS...19	Рабочий телефон владельца карты с обязательным знаком «+».
Необязательно	`mobilePhone`	ANS...19	Номер мобильного телефона владельца карты с обязательным знаком «+».

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

Обязательность	Название	Тип	Описание
Обязательно	`success`	Boolean	Основной параметр, который указывает на то, что запрос прошел успешно. Доступны следующие значения: `true` - запрос успешно обработан; `false` - запрос не прошел. Обратите внимание, что значение `true` означает, что запрос был обработан, а не что заказ был оплачен. Более подробная информация о том, как узнать, был ли платеж успешным или нет, доступна здесь.

Условие	`data`	N/A	Этот параметр возвращается только в случае успешной обработки платежа. См. описание ниже.
Условие	`error`	N/A	Этот параметр возвращается только в случае ошибки платежа. См. описание ниже.

Блок data содержит следующие элементы.

Обязательность	Название	Тип	Описание
Обязательно	`orderId`	String [1..36]	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.

Блок error содержит следующие элементы.

Обязательность	Название	Тип	Описание
Обязательно	`code`	Integer [1..3]	Код как информационный параметр, сообщающий об ошибке.

Обязательно	`description`	String [1..598]	Подробное техническое объяснение ошибки - содержимое этого параметра не предназначено для отображения пользователю.

Обязательно	`message`	String [1..512]	Информационный параметр, являющийся описанием ошибки для отображения пользователю. Параметр может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде.

Примеры

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

curl --request POST \
--url https://vtb.rbsuat.com/payment/recurrentPayment.do \
--header 'Content-Type: application/json' \
--data-raw '{
  "userName" : "test_user",
  "password" : "test_user_password",
  "orderNumber" : "UAF-203974-DE-12",
  "language" : "EN",
  "bindingId": "bindingId",
  "amount" : 1200,
  "currency" : "643",
  "description" : "Test description",
  "additionalParameters" : {
    "firstParamName" : "firstParamValue",
    "secondParamName" : "secondParamValue"
    "email" : "email@email.com"
  }
}'

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

Успешно

{
    "success": true,
    "data": {
        "orderId": "f7beebe4-7c9a-43cf-8e26-67ab741f9b9e"
    },
    "orderStatus": {
        "errorCode": "0",
        "orderNumber": "UAF-203974-DE-12",
        "orderStatus": 2,
        "actionCode": 0,
        "actionCodeDescription": "",
        "amount": 12300,
        "currency": "643",
        "date": 1491333938243,
        "orderDescription": "Test description",
        "merchantOrderParams": [
            {
                "name": "firstParamName",
                "value": "firstParamValue"
            },
            {
                "name": "secondParamName",
                "value": "secondParamValue"
            }
        ],
        "attributes": [],
        "cardAuthInfo": {
            "expiration": "203012",
            "cardholderName": "TEST CARDHOLDER",
            "approvalCode": "12345678",
            "paymentSystem": "VISA",
            "pan": "6777770000**0006"
        },
        "authDateTime": 1491333939454,
        "terminalId": "11111",
        "authRefNum": "111111111111",
        "paymentAmountInfo": {
            "paymentState": "DEPOSITED",
            "approvedAmount": 12300,
            "depositedAmount": 12300,
            "refundedAmount": 0
        },
        "bankInfo": {
            "bankCountryName": "<unknown>"
        },
        "chargeback": false,
        "operations": [
            {
                "amount": 12300,
                "cardHolder": "TEST CARDHOLDER",
                "authCode": "123456"
            }
        ]
    }
}

Ошибка

{
  "error": {
    "code": "10",
    "description": "Order with this number is already registered in the system.",
    "message": "Order with this number is already registered in the system."
  },
  "success": false
}

Платеж по рассрочке

Для проведения платежа по рассрочке используется запрос /payment/installmentPayment.do.

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Обязательно	`orderNumber`	String [1..32]	Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа.

Необязательно	`language`	String [2]	Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: `ru,en`.

Обязательно	`bindingId`	String [1..255]	Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что: Этот заказ можно оплатить только с помощью связки; Плательщик будет перенаправлен на страницу оплаты, где требуется только ввод CVC.

Обязательно	`amount`	Integer [0..12]	Сумма платежа в минимальных единицах валюты (например, в копейках).

Необязательно	`currency`	Integer [3]	Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию.

Необязательно	`description`	String [1..598]	Описание заказа в любом формате. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки.

Необязательно	`additionalParameters`	Object	Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования. `{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}`

Обязательно	`preAuth`	Boolean	Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения: `true` - включена двухстадийная оплата; `false` - включена одностадийная оплата (деньги списываются сразу). Если параметр отсутствует, производится одностадийная оплата.

Обязательно	`token`	String [1..256]	Значение, используемое для аутентификации продавца при отправке запросов платежному шлюзу. Если вы передаете этот параметр, то не передавайте `userName` и `password`.

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

Обязательность	Название	Тип	Описание
Необязательно	`orderId`	String [1..36]	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.

Обязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Обязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Условие	`orderStatus`	Object	Содержит параметры статуса заказа и возвращается только в том случае, если платежный шлюз распознал все параметры запроса как правильные. См. описание ниже.

Блок orderStatus содержит следующие элементы.

Обязательность	Название	Тип	Описание
Необязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Необязательно	`orderNumber`	String [1..32]	Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа.

Необязательно	`orderStatus`	Integer	Значение этого параметра указывает статус заказа в платежном шлюзе. Отсутствует, если заказ не был найден. Ниже приведен список доступных значений: `0` - заказ зарегистрирован, но не оплачен; `1` - заказ только авторизован и еще не завершен (для двухстадийных платежей); `2` - заказ авторизован и завершен; `3` - авторизация отменена; `4` - по транзакции была проведена операция возврата; `5` - инициирована авторизация через ACS банка-эмитента; `6` - авторизация отклонена; `7` - ожидание оплаты заказы; `8` - промежуточное завершение для многократного частичного завершения.

Необязательно	`actionCode`	Integer	Код ответа от процессинга банка. См. список кодов ответа здесь.

Необязательно	`actionCodeDescription`	String [1..512]	Описание `actionCode`, возвращаемое процессингом банка.

Необязательно	`amount`	Integer [0..12]	Сумма платежа в минимальных единицах валюты (например, в копейках).

Необязательно	`currency`	Integer [3]	Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию.

Необязательно	`date`	String	Дата регистрации заказа (Unix)

Необязательно	`ip`	String [1..39]	IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). При использовании аутентификации 3DS 2 рекомендуем вам передавать в этом параметре реальный IP адрес клиента. Это позволит повысить конверсию в оплату на стороне ACS.

Необязательно	`chargeback`	Boolean	Были ли средства принудительно возвращены покупателю банком. Возможные значения: `true`, `false`.

Необязательно	`merchantOrderParams`	N/A	Раздел с атрибутами, в котором передаются дополнительные параметры мерчанта. См. описание ниже.
Необязательно	`attributes`	Object	Атрибуты заказа в платежной системе (номер заказа). См. описание ниже.
Необязательно	`cardAuthInfo`	Object	Информация о платежной карте покупателя. См. описание ниже.
Необязательно	`authDateTime`	String	Дата и время авторизации, показанные как количество миллисекунд, прошедших с 00:00 GMT 1 января 1970 года (время Unix).

Необязательно	`terminalId`	String [1..10]	Идентификатор терминала в системе, обрабатывающей платеж.

Необязательно	`authRefNum`	String [1..24]	Номер авторизации платежа, присвоенный ему при регистрации платежа.

Необязательно	`paymentAmountInfo`	Object	Параметр, содержащий вложенные параметры с информацией о суммах подтверждения, списания и возврата. См. описание ниже.
Необязательно	`bankInfo`	Object	Содержит вложенный параметр `bankCountryName`. См. описание ниже.
Необязательно	`bindingInfo`	Object	Объект, содержащий информацию о связке, по которой осуществляется платеж. См. описание ниже.
Необязательно	`operations`	Object	Объект, содержащий информацию об операциях. См. описание ниже.

Блок merchantOrderParams содержит следующие элементы.

Обязательность	Название	Тип	Описание
Обязательно	`name`	String [1..255]	Название дополнительного параметра мерчанта.

Обязательно	`value`	String	Значение дополнительного параметра продавца - до 1024 символов.

Блок attributes содержит следующие элементы.

Обязательность	Название	Тип	Описание
Обязательно	`name`	String [1..255]	Название дополнительного параметра.

Обязательно	`value`	Alphanumeric	Значение дополнительного параметра - до 1024 символов.

Блок cardAuthInfo содержит следующие элементы.

Обязательность	Название	Тип	Описание
Обязательно	`expiration`	Integer	Срок действия карты в следующем формате: .`YYYYMM` Указывается только после оплаты заказа.

Обязательно	`cardholdername`	String [1..26]	Имя держателя карты латинскими буквами. Этот параметр передается только после оплаты заказа.

Обязательно	`approvalCode`	String [6]	Код авторизации МПС. Это поле имеет фиксированную длину (шесть символов) и может содержать цифры и латинские буквы.

Обязательно	`pan`	String [1..19]	Маскированный DPAN: номер, привязанный к мобильному устройству покупателя и выполняющий функции номера платежной карты в системе Apple Pay.

Обязательно	`maskedPan`	String [1..19]	Маскированный номер карты, использованной для платежа. Указывается только после оплаты заказа.

Обязательно	`paymentSystem`	String	Наименование платежной системы. Возможны следующие значения: `VISA`; `MASTERCARD`; `AMEX`; `JCB`; `CUP`;

Блок paymentAmountInfo содержит следующие элементы.

Обязательность	Название	Тип	Описание
Обязательно	`paymentState`	String	Состояние заказа, параметр может принимать следующие значения: `CREATED` - заказ создан (но не оплачен); `APPROVED` - заказ одобрен (средства на счету покупателя заблокированы); `DEPOSITED` - заказ завершен (деньги списаны со счета покупателя); `DECLINED` - заказ отклонен; `REVERSED` - заказ отклонен; `REFUNDED` - возврат средств.

Обязательно	`approvedAmount`	Integer [0..12]	Сумма в минимальных единицах валюты (например, в центах), которая была заблокирована на счете покупателя. Используется только в двухстадийных платежах.

Обязательно	`depositedAmount`	Integer [1..12]	Сумма списания в минимальных единицах валюты (например, в копейках).

Обязательно	`refundedAmount`	Integer [1..12]	Сумма возврата в минимальных единицах валюты.

Обязательно	`totalAmount`	Integer [1..12]	Сумма заказа плюс комиссия, если таковая имеется.

Блок bankInfo содержит следующие элементы.

Обязательность	Название	Тип	Описание
Обязательно	`bankCountryName`	String [1..160]	Страна банка-эмитента.

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

Название	Тип	Обязательно	Описание
Необязательно	`clientId`	String [0..255]	Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен.

Необязательно	`bindingId`	String [1..255]	Идентификатор уже существующей связки. (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что: Этот заказ можно оплатить только с помощью связки; Плательщик будет перенаправлен на страницу оплаты, где требуется только ввод CVC.

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

Название	Тип	Обязательно	Описание
Необязательно	`amount`	Integer [0..12]	Сумма платежа в минимальных единицах валюты (например, в копейках).

Необязательно	`cardHolder`	String [1..26]	Имя держателя карты латинскими буквами. Этот параметр передается только после оплаты заказа.

Необязательно	`authCode`	Integer [6]	Устаревший параметр (не используется). Его значение всегда `2` независимо от статуса заказа и кода авторизации процессинговой системы.

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/installmentPayment.do \
  --header 'Content-Type: application/json' \
  --data '{
  "userName": "test_user",
  "password": "test_user_password",
  "orderNumber": "UAF-203974-DE-12",
  "language": "EN",
  "bindingId": "8aa4fa8b-4d8a-76ca-b314-7bcc00b4f820",
  "amount": 12300,
  "currency": "643",
  "description" : "Test description",
  "additionalParameters": {
    "firstParamName": "firstParamValue",
    "secondParamName": "secondParamValue"
  }
 }'

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

{
  "errorCode": 0,
  "errorMessage": "Success",
  "orderId": "0e441115-f3bc-711c-8827-2fdc00b4f820",
  "orderStatus": {
    "errorCode": "0",
    "orderNumber": "7033",
    "orderStatus": 2,
    "actionCode": 0,
    "actionCodeDescription": "",
    "amount": 12300,
    "currency": "643",
    "date": 1618340470944,
    "orderDescription": "Test description",
    "merchantOrderParams": [
      {
        "name": "firstParamName",
        "value": "firstParamValue"
      },
      {
        "name": "secondParamName",
        "value": "secondParamValue"
      }
    ],
    "transactionAttributes": [],
    "attributes": [
      {
        "name": "mdOrder",
        "value": "0e441115-f3bc-711c-8827-2fdc00b4f820"
      }
    ],
    "cardAuthInfo": {
      "maskedPan": "400000**1118",
      "expiration": "203012",
      "cardholderName": "TEST CARDHOLDER",
      "approvalCode": "123456",
      "paymentSystem": "VISA",
      "product": "visa-product",
      "secureAuthInfo": {
        "eci": 7
      },
      "pan": "400000**1118"
    },
    "bindingInfo": {
      "clientId": "TEST CARDHOLDER",
      "bindingId": "8aa4fa8b-4d8a-76ca-b314-7bcc00b4f820"
    },
    "authDateTime": 1618340471076,
    "authRefNum": "111111111111",
    "paymentAmountInfo": {
      "paymentState": "DEPOSITED",
      "approvedAmount": 12300,
      "depositedAmount": 12300,
      "refundedAmount": 0,
      "totalAmount": 12300
    },
    "bankInfo": {
      "bankName": "ES TEST BANK",
      "bankCountryCode": "ES",
      "bankCountryName": "Spain"
    },
    "chargeback": false,
    "operations": [
      {
        "amount": 12300,
        "cardHolder": "TEST CARDHOLDER",
        "authCode": "123456"
      }
    ]
  },
  "error": false
}

СБП

Получить QR-код для оплаты по СБП

Для получения динамического QR-кода для оплаты через СБП используется запрос sbp/c2b/qr/dynamic/get.do.

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца.

Обязательно	`mdOrder`	String [1..36]	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.

Необязательно	`account`	String	Счет юридического лица.

Необязательно	`memberId`	String	Идентификатор банка-участника СБП.

Необязательно	`tspMerchantId`	String	Идентификатор ТСП.

Необязательно	`paymentPurpose`	String [1..140]	Дополнительная информация от мерчанта. Если не заполнено, то по умолчанию будет подставлено описание заказа, если оно присутствует.

Необязательно	`redirectUrl`	String [1..1024]	Cсылка для автоматического возврата из приложения банка в приложение или на сайт мерчанта. При некорректном заполнении параметр передаётся в значении "null". Пример корректного заполнения: "redirectUrl"="http(s)://test.ru/", "redirectUrl"="mybee://finance.com?sbpId=123123/", "redirectUrl"="mybee://finance?sbpId=1968310434". Примеры некорректного заполнения: "redirectUrl"="httpsы://test.ru/","redirectUrl"="1".
Необязательно	`qrHeight`	String	Высота QR-кода в пикселях. Укажите этот параметр, если хотите получить визуализированный QR-код в формате PNG. Минимальное значение - 10. Максимальное значение - 1000.

Необязательно	`qrWidth`	String	Ширина QR-кода в пикселях. Укажите этот параметр, если хотите получить визуализированный QR-код в формате PNG. Минимальное значение - 10. Максимальное значение - 1000.

Необязательно	`qrFormat`	String	Формат QR-кода. Укажите этот параметр, если хотите получить визуализированный QR-код в формате PNG. Допустимые значения: `matrix` - матрица в виде строки из 0 и 1 `image` - изображение в кодировке base64 (по умолчанию)

Необязательно	`createSubscription`	Boolean	Создается ли связка (банковский счет плательщика привязывается к его идентификатору в системе магазина). Допустимые значения: `true` – связка создается; `false` – связка не создается. Этот параметр является обязательным в случае создания подписки.

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

Обязательность	Название	Тип	Описание
Необязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Необязательно	`payload`	String	Содержимое QR-кода. Этот параметр возвращается, если `qrStatus = STARTED`.

Необязательно	`qrId`	String	Идентификатор QR-кода.

Необязательно	`qrStatus`	String	Статус оплаты по QR-коду. Допустимые значения: `STARTED` - QR-код cформирован `CONFIRMED` - заказ принят к оплате `REJECTED` - платеж отклонен `REJECTED_BY_USER` - платеж отклонен мерчантом `ACCEPTED` - заказ оплачен

Необязательно	`renderedQr`	String	QR-код в формате PNG, закодированный в формате, указанном в параметре `qrFormat`. Если формат не указан, по умолчанию используется `image`. Этот параметр возвращается, если запрос содержит `qrHeight` и `qrWidth` и если `qrStatus = STARTED`.

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/sbp/c2b/qr/dynamic/get.do \
  --header 'Content-Type: application/json' \
  --data '{
    "userName": "test_user",
    "password": "test_user_password",
    "mdOrder": "04888d6f-7920-7531-8332-8de901efddd0",
    "qrFormat": "image"
}'

Пример успешного запроса

{
"qrId": "54d14bae6f7f4a73929308e9afa5915d",
"payload": "https://qr.nspk.ru/54d14bae6f7f4a73929308e9afa5915d",
"qrStatus": "STARTED"
}

Получение статуса СБП-платежа

Для получения статуса СБП-платежа с помощью динамического QR-кода используется запрос sbp/c2b/qr/status.do.

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца.

Обязательно	`mdOrder`	String [1..36]	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.

Необязательно	`qrId`	String	Идентификатор QR-кода.

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

Обязательность	Название	Тип	Описание
Необязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Необязательно	`qrStatus`	String	Статус оплаты по QR-коду. Допустимые значения: `STARTED` - QR-код cформирован `CONFIRMED` - заказ принят к оплате `REJECTED` - платеж отклонен `REJECTED_BY_USER` - платеж отклонен мерчантом `ACCEPTED` - заказ оплачен

Необязательно	`qrType`	String	Тип QR-кода. Допустимые значения: `STATIC` - статический QR-код `DYNAMIC` - динамический QR-код В настоящее время возвращается только значение `DYNAMIC`.

Необязательно	`transactionState`	String	Статус заказа. Допустимые значения: `CREATED` - заказ создан `DECLINED` - заказ отклонен `DEPOSITED` - заказ оплачен

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/sbp/c2b/qr/status.do \
  --header 'Content-Type: application/json' \
  --data '{
    "userName": "test_user",
    "password": "test_user_password",
    "mdOrder": "04888d6f-7920-7531-8332-8de901efddd0",
    "qrId": "3946c0c02d1042f7b7e63cc0f1b52a95"
}'

Пример успешного запроса

{
"qrType": "DYNAMIC",
"qrStatus": "ACCEPTED",
"transactionState": "DEPOSITED"
}

Отклонение СБП-платежа

Для отклонения платежа СБП с помощью динамического QR-кода, используется запрос sbp/c2b/qr/dynamic/reject.do.

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца.

Обязательно	`mdOrder`	String [1..36]	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.

Необязательно	`qrId`	String	Идентификатор QR-кода.

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

Обязательность	Название	Тип	Описание
Необязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Обязательно	`rejected`	Boolean	Указывает результат операции отклонения платежа. Допустимые значения: `true` – платеж отклонен; `false` – платеж не отклонен. Если результат `true`, QR-код получает статус `REJECTED_BY_USER`.

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/sbp/c2b/qr/dynamic/reject.do \
  --header 'Content-Type: application/json' \
  --data '{
    "userName": "test_user",
    "password": "test_user_password",
    "mdOrder": "04888d6f-7920-7531-8332-8de901efddd0",
    "qrId": "3946c0c02d1042f7b7e63cc0f1b52a95"
}'

Пример успешного запроса

{
"rejected": true
}

3DS

Завершение платежа 3DS через API

Этот метод используется в схеме, где ACS банка-эмитента выполняет аутентификацию держателя карты и перенаправляет его продавцу. PARes от ACS отправляется продавцу. Затем продавец должен отправить эти данные в платежный шлюз методом finish3dsPayment.do.

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Обязательно	`mdOrder`	String [1..36]	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.

Обязательно	`paRes`	String	Ответ аутентификации плательщика

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

Обязательность	Название	Тип	Описание
Необязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `error`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`error`	String	Сообщение об ошибке (если в ответе вернулась ошибка) на языке, переданном в запросе.

Необязательно	`redirect`	String [1..512]	Этот параметр возвращается, если платеж прошел успешно и для платежа не проводилась проверка карты на вовлеченность в 3-D Secure. Продавцы могут использовать его, если хотят перенаправить пользователя на страницу платежного шлюза. Если продавец использует собственную страницу, это значение можно игнорировать.

Примеры

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

curl --location --request POST 'https://vtb.rbsuat.com/payment/rest/finish3dsPayment.do' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'mdOrder=906bf262-bd53-4ac7-983c-07127954681b' \
--data-urlencode 'paRes=eJzFV2uTokoS%...%ADPms%0D%0A' \
--data-urlencode 'userName=test_user' \
--data-urlencode 'password=test_user_password'

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

{
    "redirect": "https://mybestmerchantreturnurl.com?orderId=906bf262-bd53-4ac7-983c-07127954681b",
    "errorCode": 0,
}

Завершение платежа 3DS2 через API

Для завершения заказа 3DS2 через API используется метод finish3dsVer2Payment.do.

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

Обязательность	Название	Тип	Описание
Обязательно	`userName`	String [1..100]	Логин учетной записи API продавца.

Обязательно	`password`	String [1..200]	Пароль учетной записи API продавца.

Обязательно	`threeDSServerTransId`	String	Идентификатор транзакции, созданный на сервере 3DS. Этот параметр используется для аутентификации клиента по протоколу 3DS версии 2.0.

Условие	`threeDSVer2MdOrder`	String	Номер заказа, который был зарегистрирован в первой части запроса в рамках 3DS 2.0 операции. Если данный параметр присутствует в запросе, то используется `mdOrder`, который передается в настоящем параметре. В таком случае регистрация заказа не происходит, а происходит сразу оплата заказа.

Необязательно	`threeDSVer2FinishUrl`	String	URL-адрес, по которому клиент должен быть перенаправлен после аутентификации на сервере ACS. Этот параметр используется для аутентификации клиента по протоколу 3DS версии 2.0.

Необязательно	`threeDSSDK`	Boolean	Возможные значения: `true` или `false` Флаг, показывающий, что платеж поступает из 3DS SDK.

Условие	`threeDSSDKEncData`	String	Зашифрованные данные об устройстве. Параметр является обязательным для SDK.


Условие	`threeDSSDKEphemPubKey`	String	Публичная часть эфемерного ключа. Требуется для установки сеанса с ACS. Параметр является обязательным для SDK.


Условие	`threeDSSDKAppId`	String	Уникальный идентификатор SDK. Параметр является обязательным для SDK.


Условие	`threeDSSDKTransId`	String	Уникальный идентификатор транзакции в SDK. Параметр является обязательным для SDK.

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

Обязательность	Название	Тип	Описание
Обязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Обязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Необязательно	`redirect`	String [1..512]	Этот параметр возвращается, если платеж прошел успешно и для платежа не проводилась проверка карты на вовлеченность в 3-D Secure. Продавцы могут использовать его, если хотят перенаправить пользователя на страницу платежного шлюза. Если продавец использует собственную страницу, это значение можно игнорировать.

Необязательно	`is3DSVer2`	Boolean	Возможные значения: `true` или `false` Флаг, показывающий, что платеж поступает из 3DS 2.0.

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/finish3dsVer2Payment.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data threeDSServerTransId=33b17cb5-b4a5-48ac-a3b8-bc8d6d979a46 \
  --data userName=test_user \
  --data password=test_user_password \

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

{
    "redirect": "http://test.com?orderId=f61e2a41-34b9-7a2d-b4d6-83ac00c305c8&lang=en",
    "errorCode": 0,
    "is3DSVer2": true
}

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/finish3dsVer2Payment.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data threeDSServerTransId=33b17cb5-b4a5-48ac-a3b8-bc8d6d979a46 \
  --data threeDSVer2MdOrder=fbcb596f-25ba-70e7-a6cf-4fb100c305c8 \
  --data userName=test_user \
  --data password=test_user_password \

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

{
    "redirect": "http://test.com?orderId=f61e2a41-34b9-7a2d-b4d6-83ac00c305c8&lang=en",
    "errorCode": 0,
    "is3DSVer2": true
}

Разное

Верификация карты

Метод verifyCard.do используется для проверки карты. Оплата не производится, и заказ сразу переходит в статус REVERSED.

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

Обязательность	Название	Тип	Описание
Необязательно	`userName`	String [1..100]	Логин учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Необязательно	`password`	String [1..200]	Пароль учетной записи API продавца. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр `token`), пароль передавать не нужно.

Необязательно	`token`	String [1..256]	Значение, используемое для аутентификации продавца при отправке запросов платежному шлюзу. Если вы передаете этот параметр, то не передавайте `userName` и `password`.

Обязательно	`amount`	Integer [0..12]	Сумма платежа в минимальных единицах валюты (например, в копейках).

Необязательно	`currency`	Integer [3]	Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию.

Необязательно	`pan`	String [1..19]	Маскированный номер карты, которая использовалась для оплаты. Этот параметр указывается только после оплаты заказа.

Необязательно	`cvc`	Integer	Этот параметр обязателен, если для мерчанта не выбрано разрешение Может проводить оплату без подтверждения CVC.

Необязательно	`expiry`	Integer	Срок действия карты в следующем формате: `YYYYMM`. Обязательно, если не переданы ни `seToken`, ни `bindingId`.

Необязательно	`cardholdername`	String [1..26]	Имя держателя карты латинскими буквами. Этот параметр передается только после оплаты заказа.

Необязательно	`backUrl`	String [1..512]	URL-адрес, на который будет перенаправлен пользователь в случае успешной оплаты. Используйте полный путь с указанием протокола, например `https://test.com` (а не `test.com`). В противном случае пользователь будет перенаправлен на URL-адрес следующего вида: `http://paymentGatewayURL/merchantURL` Адрес не должен быть относительным путем, т.е. он не должен начинаться с "." и "/". В противном случае будет возвращена ошибка 4: "The return URL is invalid". Например: ../test.html, /test.html — неверные URL-адреса.

Необязательно	`failUrl`	String [1..512]	Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, `https://mybestmerchantreturnurl.com` вместо `mybestmerchantreturnurl.com`). В противном случае пользователь будет перенаправлен по адресу следующего вида: `https://vtb.rbsuat.com/payment/<merchant_address>`. Адрес не должен быть относительным путем, т.е. он не должен начинаться с "." и "/". В противном случае будет возвращена ошибка 4: "The return URL is invalid". Например: ../test.html, /test.html — неверные URL-адреса.

Необязательно	`description`	String [1..598]	Описание заказа в любом формате. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки.

Необязательно	`language`	String [2]	Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: `ru,en`.

Необязательно	`returnUrl`	String [1..512]	Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, `https://mybestmerchantreturnurl.com` вместо `mybestmerchantreturnurl.com`). В противном случае пользователь будет перенаправлен по адресу следующего вида: `https://vtb.rbsuat.com/payment/<merchant_address>`.

Необязательно	`threeDSServerTransId`	String	Идентификатор транзакции, созданный на сервере 3DS. Этот параметр используется для аутентификации клиента по протоколу 3DS версии 2.0.

Необязательно	`threeDSVer2FinishUrl`	String	URL-адрес, по которому клиент должен быть перенаправлен после аутентификации на сервере ACS. Этот параметр используется для аутентификации клиента по протоколу 3DS версии 2.0.

Условие	`threeDSVer2MdOrder`	String	Номер заказа, который был зарегистрирован в первой части запроса в рамках 3DS 2.0 операции. Если данный параметр присутствует в запросе, то используется `mdOrder`, который передается в настоящем параметре. В таком случае регистрация заказа не происходит, а происходит сразу оплата заказа.

Необязательно	`threeDSSDK`	Boolean	Возможные значения: `true` или `false` Флаг, показывающий, что платеж поступает из 3DS SDK.

Необязательно	`billingPayerData`	Object	Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязательно, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры.

Необязательно	`shippingPayerData`	Object	Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.

Необязательно	`preOrderPayerData`	Object	Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.

Необязательно	`orderPayerData`	Object	Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.

Необязательно	`billingAndShippingAddressMatchIndicator`	A1	Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. Возможные значения: `Y` - совпадение платежного адреса держателя карты и адреса доставки; `N` - платежный адрес владельца карты и адрес доставки не совпадают.

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

Обязательность	Название	Тип	Описание
Необязательно	`billingCity`	String [0..50]	Город, зарегистрированный по конкретной карте у Банка Эмитента.

Необязательно	`billingCountry`	String [0..50]	Страна, зарегистрированная по конкретной карте банка-эмитента (ISO 3166-1, числовой).

Необязательно	`billingAddressLine1`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки.

Необязательно	`billingAddressLine2`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2.

Необязательно	`billingAddressLine3`	String [0..50]	Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3.

Необязательно	`billingPostalCode`	String [0..9]	Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки.

Необязательно	`billingState`	String [0..50]	Штат, зарегистрированный по конкретной карте у Банка Эмитента.

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

Обязательность	Название	Тип	Описание
Необязательно	`shippingCity`	ANS...50	Город заказчика (из адреса доставки)
Необязательно	`shippingCountry`	ANS...50	Страна заказчика
Необязательно	`shippingAddressLine1`	ANS...50	Основной адрес клиента (из адреса доставки)
Необязательно	`shippingAddressLine2`	ANS...50	Основной адрес клиента (из адреса доставки)
Необязательно	`shippingAddressLine3`	ANS...50	Основной адрес клиента (из адреса доставки)
Необязательно	`shippingPostalCode`	ANS...16	Почтовый индекс клиента для доставки
Необязательно	`shippingState`	ANS...50	Штат/регион покупателя (из адреса доставки)
Необязательно	`shippingMethodIndicator`	N2	Индикатор способа доставки. Возможные значения: `01` - доставка на платежный адрес держателя карты. `02` - доставка на другой адрес, проверенный Мерчантом. `03` - доставка по адресу, отличному от основного адреса держателя карты. `04` - отправка в магазин/самовывоз (адрес магазина должен быть указан в соответствующих параметрах доставки) `05` - Цифровое распространение (включает онлайн-сервисы и электронные подарочные карты) `06` - билеты на путешествия и мероприятия, которые нельзя доставить. `07` - Прочее (например, игры, цифровые товары, не подлежащие доставке, цифровые подписки и т. д.)
Необязательно	`deliveryTimeframe`	N2	Срок поставки товара. Возможные значения: `01` - цифровая дистрибуция `02` - доставка в тот же день `03` - доставка на следующий день `04` - доставка в течение 2-х дней после оплаты и позже.
Необязательно	`deliveryEmail`	ANS...254	Целевой адрес электронной почты для доставки цифрового распространения

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

Обязательность	Название	Тип	Описание
Необязательно	`preOrderDate`	ANS8	Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД.
Необязательно	`preOrderPurchaseInd`	N2	Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения: `01` - возможна доставка; `02` - будущая доставка
Необязательно	`reorderItemsInd`	N2	Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения: `01` - заказ размещается впервые; `02` - повторный заказ

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

Обязательность	Название	Тип	Описание
Необязательно	`homePhone`	ANS...19	Домашний телефон владельца карты с обязательным знаком «+».
Необязательно	`workPhone`	ANS...19	Рабочий телефон владельца карты с обязательным знаком «+».
Необязательно	`mobilePhone`	ANS...19	Номер мобильного телефона владельца карты с обязательным знаком «+».

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

Обязательность	Название	Тип	Описание
Необязательно	`errorCode`	Integer [1..2]	Информационный параметр в случае ошибки, который может иметь разные кодовые значения: значение `0` - указывает на успех обработки; другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр `errorMesage`. Может отсутствовать, если результат не вызвал ошибки.

Необязательно	`errorMessage`	String [1..512]	Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение `errorMessage` может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре `language` запроса.

Необязательно	`orderId`	String [1..36]	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.

Необязательно	`orderNumber`	String [1..32]	Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа.

Необязательно	`authCode`	Integer [6]	Устаревший параметр (не используется). Его значение всегда `2` независимо от статуса заказа и кода авторизации процессинговой системы.

Необязательно	`actionCode`	Integer	Код ответа от процессинга банка. См. список кодов ответа здесь.

Необязательно	`actionCodeDescription`	String [1..512]	Описание `actionCode`, возвращаемое процессингом банка.

Необязательно	`time`	String	Время совершения транзакции.

Необязательно	`eci`	Integer [1..4]	Электронный коммерческий индикатор. Указан только после оплаты заказа и в случае наличия соответствующего разрешения. Ниже приводится расшифровка ECI-кодов. `ECI=1` или `ECI=6` - мерчант поддерживает 3-D Secure, платежная карта не поддерживает 3-D Secure, платеж обрабатывается на основе кода CVV2/CVC. `ECI=2` или `ECI=5` - и мерчант, и платежная карта поддерживают 3-D Secure; `ECI=7` - мерчант не поддерживает 3-D Secure, платеж обрабатывается на основе кода CVV2/CVC.

Необязательно	`amount`	Integer [0..12]	Сумма платежа в минимальных единицах валюты (например, в копейках).

Необязательно	`currency`	Integer [3]	Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию.

Необязательно	`rrn`	Integer [1..12]	Reference Retrieval Number - идентификатор транзакции, присвоенный банком-эквайером.

Необязательно	`acsUrl`	String [1..512]	При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Подробнее см. Редирект на ACS.

Необязательно	`termUrl`	String [1..512]	При успешном ответе в случае оплаты 3D-Secure. Это URL-адрес, на который ACS перенаправляет владельца карты после аутентификации. Подробнее см. Редирект на ACS.

Необязательно	`paReq`	String [1..255]	При успешном ответе в случае оплаты 3D-Secure. PAReq (Payment Authentication Request) — сообщение, которое необходимо отправить в ACS вместе с редиректом. Это сообщение содержит данные в кодировке Base64, необходимые для аутентификации держателя карты. Подробнее см. Редирект на ACS.

Примеры

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

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/verifyCard.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data pan=4000001111111118 \
  --data cvc=123 \
  --data expiry=203012

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

{
  "errorCode": "0",
  "errorMessage": "Success",
  "orderId": "cfc238ca-68f9-745c-ba7e-eb9100af79e0",
  "orderNumber": "12017",
  "rrn": "111111111115",
  "authCode": "123456",
  "actionCode": 0,
  "actionCodeDescription": "",
  "time": 1595284781180,
  "eci": "07",
  "amount": 0,
  "currency": "643"
}

Уведомления обратного вызова

API платежного шлюза позволяет получать уведомления обратного вызова (callback-уведомления) об изменении статусов платежей.

Общая информация

События, о которых могут приходить уведомления

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

Наиболее распространенные уведомления описывают изменения статуса заказа, например:

списание средств
удержание (холдирование) средств
отмена платежа
возврат средств

Более сложные интеграции могут подразумевать дополнительные триггеры обратного вызова, такие как:

сохранение карты (т.е. создание связки)
включение/выключение существующей связки
отклонение платежей и т.д.

Тип триггера передается в параметре operation уведомления обратного вызова (см. подробности ниже). Для удобства уведомления для дополнительных триггеров могут быть направлены на другой URL-адрес с помощью параметра dynamicCallbackUrl в запросах на регистрацию заказа.

Интеграция через уведомления обратного вызова (callback)

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

Использовать `returnUrl`

Когда код вашего сайта, расположенный по адресу returnUrl (например, https://mybestmerchantreturnurl.com/?back&orderId=61c33664-85a0-7d6b-af26-09ee009c4000&lang=en), идентифицирует перенаправляемого из шлюза держателя карты посде попытки оплаты, вы можете проверить статус заказа с помощью API-запроса getOrderStatusExtended.
Этот вариант является самым простым, но он не совсем надежен, поскольку перенаправление держателя карты может завершиться ошибкой (например, в результате обрыва соединения или закрытия браузера держателем карты), а returnUrl может не получить триггер для вызова getOrderStatusExtended.

getOrderStatusExtended.do

curl --request POST \
  --url https://vtb.rbsuat.com/payment/rest/getOrderStatusExtended.do \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data userName=test_user \
  --data password=test_user_password \
  --data orderId=016b6f47-4628-7ea2-80f5-6c6e00a7d8c0 \
  --data language=en

{
  "errorCode": "0",
  "errorMessage": "Success",
  "orderNumber": "11008",
  "orderStatus": 2,
  "actionCode": 0,
  "actionCodeDescription": "",
  "amount": 2000,
  "currency": "643",
  "date": 1618577250840,
  "orderDescription": "my_first_order",
  "merchantOrderParams": [
    {
      "name": "browser_language_param",
      "value": "en"
    },
    {
      "name": "browser_os_param",
      "value": "UNKNOWN"
    },
    {
      "name": "user_agent",
      "value": "curl/7.75.0"
    },
    {
      "name": "browser_name_param",
      "value": "DOWNLOAD"
    }
  ],
  "transactionAttributes": [],
  "attributes": [
    {
      "name": "mdOrder",
      "value": "016b7747-c4ed-70b3-bc36-fdd400a7d8c0"
    }
  ],
  "cardAuthInfo": {
    "maskedPan": "555555**5599",
    "expiration": "202412",
    "cardholderName": "TEST CARDHOLDER",
    "approvalCode": "123456",
    "pan": "555555**5599"
  },
  "authDateTime": 1618577288377,
  "terminalId": "123456",
  "authRefNum": "931793605827",
  "paymentAmountInfo": {
    "paymentState": "DEPOSITED",
    "approvedAmount": 2000,
    "depositedAmount": 2000,
    "refundedAmount": 0
  },
  "bankInfo": {
    "bankCountryCode": "UNKNOWN",
    "bankCountryName": "&ltUnknown&gt"
  }
}

Использовать подписанный callback шлюза

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

https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&operation=deposited&status=1

Типы уведомлений

Уведомления без контрольной суммы

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

Уведомления с контрольной суммой

Такие уведомления помимо сведений о заказе содержат аутентификационный код. Аутентификационный код представляет собой контрольную сумму сведений о заказе. Эта контрольная сумма позволяет убедиться, что callback-уведомление действительно было отправлено платежным шлюзом.
Существует два способа реализации callback-уведомлений с контрольной суммой:

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

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

Требования к SSL-сертификатам на сайте продавца

Если уведомление о состоянии заказа приходит через HTTPS-соединение, необходимо удостоверить подлинность сайта с помощью SSL-сертификата, выпущенного и подписанного доверенным центром сертификации (см. таблицу ниже). Использование самозаверенных сертификатов не допускается.

Требование	Описание
Алгоритм подписи.	Не ниже SHA-256.
Поддерживаемые центры сертификации.	Ниже приведены примеры организаций, которые регистрируют цифровые сертификаты: Thawte Consulting cc; VeriSign; DigiCert Inc; COMODO CA Limited; GeoTrust Inc.; GlobalSign; Trustis Limited; UniTrust; GoDaddy.

Формат URL-адресов уведомлений

Поддерживаются запросы POST и GET.

Ниже приведен пример GET-запроса. Параметры получены в запросе.

Уведомление без контрольной суммы (GET)

https://mybestmerchantreturnurl.com/callback/?mdOrder=
1234567890-098776-234-522&orderNumber=0987&operation=deposited&
callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0

Уведомление с контрольной суммы (GET)

https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&
orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&
operation=deposited&callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0

Для POST-коллбэков вы получите те же параметры в теле HTTP (вместо параметров запроса).

Уведомление без контрольной суммы (POST)

https://mybestmerchantreturnurl.com/callback/
mdOrder=
1234567890-098776-234-522&orderNumber=0987&operation=deposited&
callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0

Уведомление с контрольной суммой (POST)

https://mybestmerchantreturnurl.com/callback/
mdOrder=1234567890-098776-234-522&
orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&operation=deposited&callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0

Передаваемые параметры представлены в таблице ниже.

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

Параметр	Описание
`mdOrder`	Уникальный номер заказа, хранящийся в платежном шлюзе.
`orderNumber`	Уникальный номер заказа (идентификатор) в системе мерчанта.
`checksum`	Аутентификационный код или контрольная сумма, полученная из набора параметров.
`operation`	Тип события, вызвавшего уведомление: `approved` - холдирование (удержание) средств на счете покупателя; `deposited` - операция завершения; `reversed` - платеж был отменен; `refunded` - деньги за заказ возвращены; `bindingCreated` - карта плательщика сохранена (cвязка создана); `bindingActivityChanged` - существующая связка была отключена/включена. `declinedByTimeout` - платеж был отклонен из-за истечения времени ожидания; `declinedCardPresent` - отклоненная транзакция с предъявлением карты (оплата физической картой).
`status`	Индикатор успешности операции, указанной в параметре `operation`: `1` - успех; `0` - ошибка.

Пользовательские заголовки callback уведомлений

Пользовательские заголовки callback уведомлений можно задать, обратившись в службу технической поддержки. Например:

'http://mybestmerchantreturnurl.com/callback.php', headers={Authorization=token, Content-type=plain
/text}, params={orderNumber=349002, mdOrder=5ffb1899-cd1e-7c1e-8750-e98500093c43, operation=deposited, status=1}

где {Authorization=token, Content-type=plain/text} – это настраиваемый заголовок.

Примеры

Пример URL-адреса уведомления без контрольной суммы

https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&operation=deposited&status=0

Пример URL-адреса уведомления с контрольной суммой

https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&operation=deposited&status=0

Алгоритм обработки уведомлений о состоянии заказов

В разделах ниже представлен алгоритм обработки уведомлений о состоянии заказов в зависимости от типа таких уведомлений.

Уведомление без контрольной суммы

Платежный шлюз отправляет на сервер продавца следующий запрос.
https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&operation=deposited&status=0
Сервер продавца возвращает HTTP-сообщение 200 OK платежному шлюзу.

Уведомление с контрольной суммой

Платежный шлюз отправляет HTTPS-запрос следующего вида на сервер мерчанта, при этом:
- при использовании симметричной криптографии контрольная сумма формируется с помощью ключа, общего для платежного шлюза и продавца;
- при использовании асимметричной криптографии контрольная сумма формируется с помощью закрытого ключа, известного только платежному шлюзу.
  https://mybestmerchantreturnurl.com/path?amount=123456&orderNumber=10747&checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&mdOrder=3ff6962a-7dcc-4283-ab50-a6d7dd3386fe&operation=deposited&status=1
  Порядок параметров в уведомлении может быть произвольным.
Обратите внимание, что callback-уведомления отправляются только через порт 443 (HTTPS).
На стороне мерчанта из строки параметров уведомления удаляется параметр checksum, а значение этого параметра (контрольная сумма) сохраняется для проверки подлинности уведомления.
Оставшиеся параметры и их значения используются для создания следующей строки.
имя_параметра1;значение_параметра1;имя_параметра2;значение_параметра2;…;имя_параметраN;значение_параметраN;
В этом случае пары имя_параметра;значение_параметра должны быть отсортированы в прямом алфавитном порядке (по возрастанию) по именам параметров.
Пример сгенерированной строки параметров:
amount;123456;mdOrder;3ff6962a-7dcc-4283-ab50-a6d7dd3386fe;operation;deposited;orderNumber;10747;status;1;
Обратите внимание, что строка заканчивается точкой с запятой (";").
Контрольная сумма рассчитывается на стороне мерчанта, способ расчета зависит от способа ее формирования:
- при использовании симметричной криптографии - с помощью алгоритма HMAC-SHA256 и общего с платежным шлюзом закрытого ключа;
- при использовании асимметричной криптографии - с помощью алгоритма хеширования, который зависит от способа создания ключевой пары, и открытого ключа, который связан с закрытым ключом, находящимся на стороне платежного шлюза.
В получившейся строке контрольной суммы все буквы нижнего регистра заменяются на буквы верхнего регистра.
Происходит сравнение полученного значения с контрольной суммой, извлеченной ранее из параметра checksum.
Если контрольные суммы совпадают, сервер отправляет в платежный шлюз HTTP-код 200 OK.

Если контрольные суммы совпадают, это уведомление подлинно и было отправлено платежным шлюзом. В противном случае вероятно, что злоумышленник пытается выдать свое уведомление за уведомление платежного шлюза.

Уведомление о статусе платежа

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

Проверить подпись (параметр checksum в уведомлении);
Проверять два параметра уведомления обратного вызова: operation и status.

Если значение параметра operation отличается от approved или deposited, то уведомление обратного вызова относится к статусу оплаты.

Approved Successfully → operation = approved & status = 1 (Successful Operation)
Approval was Declined → operation = approved & status = 0 (Failed Operation)
Deposited Successfully → operation = deposited & status = 1 (Successful Operation)
Deposit was Declined → operation = deposited & status = 0 (Failed Operation)

Неуспешные уведомления

Если в платежный шлюз возвращается ответ, отличный от HTTP-кода 200 OK, отправка уведомления считается неуспешной. В этом случае платежный шлюз повторяет уведомление с интервалом в 30 секунд до тех пор, пока не будет выполнено одно из следующих условий:

платежный шлюз получает 200 OK или
происходит три неуспешных попытки информирования подряд.

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

Дополнительные параметры уведомлений обратного вызова

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

Параметр	Описание	Тип события
`bindingId`	UUIID созданных/обновленных сохраненных учетных данных (связки).	BINDING_CREATED, BINDING_ACTIVITY_CHANGED
`email`	Электронная почта клиента.	BINDING_CREATED
`phone`	Телефон клиента.	BINDING_CREATED
`panMasked`	Маскированный PAN карты клиента.	BINDING_CREATED
`panCountryCode`	Код страны клиента.	BINDING_CREATED
`enabled`	Активна ли связка (`true`/`false`).	BINDING_ACTIVITY_CHANGED
`currentReverseAmountFormatted`	Форматированная сумма операции отмены.	REVERSED
`currentRefundAmountFormatted`	Отформатированная сумма операции возврата.	REFUNDED
`operationRefundedAmountFormatted`	Отформатированная сумма операции возврата.	REFUNDED
`operationRefundedAmount`	Сумма возврата в минимальных денежных единицах (например, в центах).	REFUNDED
`externalRefundId`	Внешний идентификатор операции возврата.	REFUNDED
`callbackCreationDate`	Дата создания уведомления обратного вызова. Требуется специальная настройка продавца.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED
`status`	Статус операции: 1 - успех, 0 - неудача	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`operation`	Тип callback-а Possible values: `deposited`, `approved`, `reversed`, `refunded`, `bindingCreated`, `bindingActivityChanged`, `declinedByTimeout`, `declinedCardpresent`	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED
`finishCheckUrl`	URL для генерации чека	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`sign_alias`	Имя ключа, используемого для подписи.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED
`checksum`	Контрольная сумма уведомления обратного вызова (используется для уведомлений обратного вызова с контрольной суммой).	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT, BINDING_CREATED, BINDING_ACTIVITY_CHANGED
`cardholderName`	Имя держателя карты.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`amount`	Сумма зарегистрированного заказа в минимальных денежных единицах.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`paymentAmount`	Сумма зарегистрированного заказа в минимальных денежных единицах.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`amountFormatted`	Отформатированная сумма зарегистрированного заказа.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`feeAmount`	Сумма комиссии в минимальных единицах валюты.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`approvedAmount`	Предварительно авторизованная сумма в минимальных денежных единицах.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`depositedAmount`	Сумма завершения в минимальных денежных единицах.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`refundedAmount`	Сумма возмещения в минимальных единицах валюты.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`approvedAmountFormatted`	Отформатированная предварительно авторизованная сумма.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`depositedAmountFormatted`	Отформатированная сумма зачисления.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`refundedAmountFormatted`	Отформатированная сумма возврата.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`totalAmountFormatted`	Отформатированная общая сумма заказа (зарегистрированная сумма + комиссия).	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`depositedTotalAmountFormatted`	Отформатированная общая сумма завершения (все суммы завершения + все суммы возврата + комиссия).	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`approvalCode`	Код авторизации платежа, полученный от процессинга.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`authCode`	Код авторизации	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`bankName`	Наименование банка, выпустившего карту клиента.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`currency`	Валюта заказа.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`depositFlag`	Флаг, указывающий тип операции. `1` - покупка `2` - преавторизация	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`eci`	Электронный коммерческий индикатор.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`ip`	IP адрес плательщика.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`ipCountryCode`	Код страны банка-эмитента.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`maskedPan`	Маскированный номер карты клиента.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`mdOrder`	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`mdorder`	Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`merchantFullName`	ФИО продавца.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`merchantLogin`	Логин продавца.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`orderDescription`	Описание заказа.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`orderNumber`	Номер заказа (ID) в системе мерчанта.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`threeDSType`	Вид транзакции (3DS). Possible values: `SSL`, `THREE_DS1_FULL`, `THREE_DS1_ATTEMPT`, `THREE_DS2_FULL`, `THREE_DS2_FRICTIONLESS`, `THREE_DS2_ATTEMPT`	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`date`	Дата создания заказа.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`clientId`	Номер клиента (ID) в системе мерчанта.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT,BINDING_CREATED, BINDING_ACTIVITY_CHANGED
`actionCode`	Код результата выполнения операции.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`actionCodeDescription`	Описание кода результата выполнения операции.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`paymentRefNum`	Reference Retrieval Number - идентификатор транзакции, присвоенный банком-эквайером.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`paymentState`	Статус заказа. Possible values: `started`, `payment_approved`, `payment_declined`, `payment_void`, `payment_deposited`, `refunded`, `pending`, `partly_deposited`	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`paymentWay`	Способ оплаты заказа. Дополнительные возможные значения параметра приведены здесь.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`processingId`	Идентификатор клиента в процессинге.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`refNum`	Reference Retrieval Number - идентификатор транзакции, присвоенный банком-эквайером.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`refnum`	Reference Retrieval Number - идентификатор транзакции, присвоенный банком-эквайером.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`terminalId`	Идентификатор терминала в системе, обрабатывающей платеж.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`paymentSystem`	Наименование платежной системы.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`currencyName`	Трехбуквенный ISO-код валюты.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`transactionAttributes`	Атрибуты заказа.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`paymentDate`	Дата оплаты заказа.	DEPOSITED, APPROVED, REVERSED, REFUNDED
`depositedDate`	Дата операции завершения по заказу.	DEPOSITED, APPROVED, REVERSED, REFUNDED
`refundedDate`	Дата операции возврата по заказу.	REFUNDED
`reversedDate`	Дата операции отмены заказа.	DEPOSITED, REVERSED, REFUNDED
`declineDate`	Дата отмены заказа.	DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`xid`	Индикатор электронной коммерции транзакции, определяемый продавцом.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`cavv`	Значение проверки аутентификации владельца карты.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`authValue`	Значение проверки аутентификации владельца карты.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`sessionExpiredDate`	Дата и время истечения срока действия заказа.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`tokenizeCryptogram`	Токенизированная криптограмма.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`creditBankName`	Название банка, выпустившего карту для зачисления (в P2P).	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`creditPanCountryCode`	Код страны карты получателя (в P2P).	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`isInternationalP2P`	Является ли P2P-транзакция межстрановой.	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`recipientData`	Информация о получателе P2P.	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`transactionTypeIndicator`	Информация о получателе P2P. Возможные значения: `A` – Account-to-Account Transfer. `P` – Person-to-Person Transfer. `O` - Loan-Prepayment Transfer. `D` - Funds Disbursement. `L` - Card Bill Payment. `G` - Online Gambling Payout. `W` - Transfer to Own Staged Digital Wallet Account. `F` - Transfer to Own Stored Digital Wallet Account.	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`operationType`	Тип операции P2P: AFT/OCT.	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`debitBankName`	Название банка, выпустившего карту для списания (в P2P).	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`debitPanCountryCode`	Код страны карты для списания (в P2P).	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`p2pDebitRrn`	RRN (Reference Retrieval Number) операции списания P2P.	DEPOSITED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT
`taxSystem`	Система налогообложения, доступны следующие значения:: `0` - общая; `1` - упрощенная, доход; `2` - упрощенная, доходы минус расходы; `3` - единый налог на вмененный доход; `4` - единый сельскохозяйственный налог; `5` - патентная система налогообложения.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`inn`	Номер налогоплательщика.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT
`orgName`	Наименование организации-плательщика.	DEPOSITED, APPROVED, REVERSED, REFUNDED, DECLINED_BY_TIMEOUT, DECLINED_CARDPRESENT

Примеры кода

Симметричная криптография

Java

package net.payrdr.test;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Comparator;
import java.util.Map;
import java.util.stream.Collector;

public class SymmetricCryptographyExample {

    private static final String secretToken = "ooc7slpvc61k7sf7ma7p4hrefr";
    private static final Map<String, String> callbackParams = Map.of(
            "checksum", "EAF2FB72CAB99FD5067F4BA493DD84F4D79C1589FDE8ED29622F0F07215AA972",
            "mdOrder", "06cf5599-3f17-7c86-bdbc-bd7d00a8b38b",
            "operation", "approved",
            "orderNumber", "2003",
            "status", "1"
    );

    public static void main(String[] args) throws Exception {
        String signedString = callbackParams.entrySet().stream()
                .filter(entry -> !entry.getKey().equals("checksum"))
                .sorted(Map.Entry.comparingByKey(Comparator.naturalOrder()))
                .collect(Collector.of(
                        StringBuilder::new,
                        (accumulator, element) -> accumulator
                                .append(element.getKey()).append(";")
                                .append(element.getValue()).append(";"),
                        StringBuilder::append,
                        StringBuilder::toString
                ));

        byte[] mac = generateHMacSHA256(secretToken.getBytes(), signedString.getBytes());
        String signature = callbackParams.get("checksum");

        boolean verified = verifyMac(signature, mac);
        System.out.println("signature verification result: " + verified);
    }

    private static boolean verifyMac(String signature, byte[] mac) {
        return signature.equals(bytesToHex(mac));
    }

    public static byte[] generateHMacSHA256(byte[] hmacKeyBytes, byte[] dataBytes) throws Exception {
        SecretKeySpec secretKey = new SecretKeySpec(hmacKeyBytes, "HmacSHA256");

        Mac hMacSHA256 = Mac.getInstance("HmacSHA256");
        hMacSHA256.init(secretKey);

        return hMacSHA256.doFinal(dataBytes);
    }

    private static String bytesToHex(byte[] bytes) {
        final byte[] HEX_ARRAY = "0123456789ABCDEF".getBytes(StandardCharsets.US_ASCII);
        byte[] hexChars = new byte[bytes.length * 2];
        for (int j = 0; j < bytes.length; j++) {
            int v = bytes[j] & 0xFF;
            hexChars[j * 2] = HEX_ARRAY[v >>> 4];
            hexChars[j * 2 + 1] = HEX_ARRAY[v & 0x0F];
        }
        return new String(hexChars, StandardCharsets.UTF_8);
    }
}

Асимметричная криптография

Java

package net.payrdr.test;

import java.io.ByteArrayInputStream;
import java.io.InputStream;
import java.security.Signature;
import java.security.cert.CertificateFactory;
import java.security.cert.X509Certificate;
import java.util.Base64;
import java.util.Comparator;
import java.util.Map;
import java.util.stream.Collector;

public class AsymmetricCryptographyExample {

    private static final Map<String, String> callbackParams = Map.of(
            "amount", "35000099",
            "sign_alias", "SHA-256 with RSA",
            "checksum", "163BD9FAE437B5DCDAAC4EB5ECEE5E533DAC7BD2C8947B0719F7A8BD17C101EBDBEACDB295C10BF041E903AF3FF1E6101FF7DB9BD024C6272912D86382090D5A7614E174DC034EBBB541435C80869CEED1F1E1710B71D6EE7F52AE354505A83A1E279FBA02572DC4661C1D75ABF5A7130B70306CAFA69DABC2F6200A698198F8",
            "mdOrder", "12b59da8-f68f-7c8d-12b5-9da8000826ea",
            "operation", "deposited",
            "status", "1");

    private static final String certificate =
            "MIICcTCCAdqgAwIBAgIGAWAnZt3aMA0GCSqGSIb3DQEBCwUAMHwxIDAeBgkqhkiG9w0BCQEWEWt6" +
                    "bnRlc3RAeWFuZGV4LnJ1MQswCQYDVQQGEwJSVTESMBAGA1UECBMJVGF0YXJzdGFuMQ4wDAYDVQQH" +
                    "EwVLYXphbjEMMAoGA1UEChMDUkJTMQswCQYDVQQLEwJRQTEMMAoGA1UEAxMDUkJTMB4XDTE3MTIw" +
                    "NTE2MDEyMFoXDTE4MTIwNTE2MDExOVowfDEgMB4GCSqGSIb3DQEJARYRa3pudGVzdEB5YW5kZXgu" +
                    "cnUxCzAJBgNVBAYTAlJVMRIwEAYDVQQIEwlUYXRhcnN0YW4xDjAMBgNVBAcTBUthemFuMQwwCgYD" +
                    "VQQKEwNSQlMxCzAJBgNVBAsTAlFBMQwwCgYDVQQDEwNSQlMwgZ8wDQYJKoZIhvcNAQEBBQADgY0A" +
                    "MIGJAoGBAJNgxgtWRFe8zhF6FE1C8s1t/dnnC8qzNN+uuUOQ3hBx1CHKQTEtZFTiCbNLMNkgWtJ/" +
                    "CRBBiFXQbyza0/Ks7FRgSD52qFYUV05zRjLLoEyzG6LAfihJwTEPddNxBNvCxqdBeVdDThG81zC0" +
                    "DiAhMeSwvcPCtejaDDSEYcQBLLhDAgMBAAEwDQYJKoZIhvcNAQELBQADgYEAfRP54xwuGLW/Cg08" +
                    "ar6YqhdFNGq5TgXMBvQGQfRvL7W6oH67PcvzgvzN8XCL56dcpB7S8ek6NGYfPQ4K2zhgxhxpFEDH" +
                    "PcgU4vswnhhWbGVMoVgmTA0hEkwq86CA5ZXJkJm6f3E/J6lYoPQaKatKF24706T6iH2htG4Bkjre" +
                    "gUA=";

    public static void main(String[] args) throws Exception {

        String signedString = callbackParams.entrySet().stream()
                .filter(entry -> !entry.getKey().equals("checksum") && !entry.getKey().equals("sign_alias"))
                .sorted(Map.Entry.comparingByKey(Comparator.naturalOrder()))
                .collect(Collector.of(
                        StringBuilder::new,
                        (accumulator, element) -> accumulator
                                .append(element.getKey()).append(";")
                                .append(element.getValue()).append(";"),
                        StringBuilder::append,
                        StringBuilder::toString
                ));

        InputStream publicCertificate = new ByteArrayInputStream(Base64.getDecoder().decode(certificate));
        String signature = callbackParams.get("checksum");

        boolean verified = checkSignature(signedString.getBytes(), signature.getBytes(), publicCertificate);
        System.out.println("signature verification result: " + verified);
    }

    private static boolean checkSignature(byte[] signedString, byte[] signature, InputStream publicCertificate) throws Exception {
        CertificateFactory certFactory = CertificateFactory.getInstance("X.509");
        X509Certificate x509Cert = (X509Certificate) certFactory.generateCertificate(publicCertificate);

        Signature signatureAlgorithm = Signature.getInstance("SHA512withRSA");
        signatureAlgorithm.initVerify(x509Cert.getPublicKey());
        signatureAlgorithm.update(signedString);

        return signatureAlgorithm.verify(decodeHex(new String(signature)));
    }

    private static byte[] decodeHex(String hex) {
        int l = hex.length();
        byte[] data = new byte[l / 2];
        for (int i = 0; i < l; i += 2) {
            data[i / 2] = (byte) ((Character.digit(hex.charAt(i), 16) << 4)
                    + Character.digit(hex.charAt(i + 1), 16));
        }
        return data;
    }
}

Симметричная криптография

PHP

<?php

$data = 'amount;123456;mdOrder;3ff6962a-7dcc-4283-ab50-a6d7dd3386fe;operation;deposited;orderNumber;10747;status;1;';
$key = 'yourSecretToken';
$hmac = hash_hmac ( 'sha256' , $data , $key);

echo "[$hmac]\n";
?>

Присвойте строковое значение переменной data.
Присвойте значение закрытого ключа переменной key.
Функция hash_hmac ( 'sha256', $data, $key) вычисляет контрольную сумму от переданной строки, с помощью закрытого ключа по алгоритму SHA-256.
Сохраните результат работы функции в переменной hmac.
Выведите результат работы функции командой echo.
Сравните это значение с тем, что передано в уведомлении о состоянии заказа.

Асимметричная криптография

PHP

<?php
// data from response
$data = 'amount;35000099;mdOrder;12b59da8-f68f-7c8d-12b5-9da8000826ea;operation;deposited;status;1;';
$checksum = '9524FD765FB1BABFB1F42E4BC6EF5A4B07BAA3F9C809098ACBB462618A9327539F975FEDB4CF6EC1556FF88BA74774342AF4F5B51BA63903BE9647C670EBD962467282955BD1D57B16935C956864526810870CD32967845EBABE1C6565C03F94FF66907CEDB54669A1C74AC1AD6E39B67FA7EF6D305A007A474F03B80FD6C965656BEAA74E09BB1189F4B32E622C903DC52843C454B7ACF76D6F76324C27767DE2FF6E7217716C19C530CA7551DB58268CC815638C30F3BCA3270E1FD44F63C14974B108E65C20638ECE2F2D752F32742FFC5077415102706FA5235D310D4948A780B08D1B75C8983F22F211DFCBF14435F262ADDA6A97BFEB6D332C3D51010B';

// your public key (e.g. SHA-512 with RSA)
// if you have a CERT, please see openssl_get_publickey()
$publicKey = <<<EOD
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwtuGKbQ4WmfdV1gjWWys
5jyHKTWXnxX3zVa5/Cx5aKwJpOsjrXnHh6l8bOPQ6Sgj3iSeKJ9plZ3i7rPjkfmw
qUOJ1eLU5NvGkVjOgyi11aUKgEKwS5Iq5HZvXmPLzu+U22EUCTQwjBqnE/Wf0hnI
wYABDgc0fJeJJAHYHMBcJXTuxF8DmDf4DpbLrQ2bpGaCPKcX+04POS4zVLVCHF6N
6gYtM7U2QXYcTMTGsAvmIqSj1vddGwvNGeeUVoPbo6enMBbvZgjN5p6j3ItTziMb
Vba3m/u7bU1dOG2/79UpGAGR10qEFHiOqS6WpO7CuIR2tL9EznXRc7D9JZKwGfoY
/QIDAQAB
-----END PUBLIC KEY-----
EOD;

$binarySignature = hex2bin(strtolower($checksum));
$isVerify = openssl_verify($data, $binarySignature, $publicKey, OPENSSL_ALGO_SHA512);
if ($isVerify == 1) {
    echo "signature ok\n";
} elseif ($isVerify == 0) {
    echo "bad (there's something wrong)\n";
} else {
    echo "error checking signature\n";
}
?>