По любому вопросу мы в одном клике

Задать вопрос
Поиск по ключевым словам
/

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

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

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

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

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

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

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

Обязательность Название Тип Описание
Условие

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

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

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

Используя протокол REST, отправляйте запросы с типом application/x-www-form-urlencoded, а не multipart/form-data.

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

TEST: https://abby.rbsuat.com/payment/rest/
PROD: https://ecom.alfabank.by/payment/rest/

Ошибки

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

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

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

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

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

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

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

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

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

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

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

    openssl genrsa -des3 -out private.key 2048

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

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

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

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

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

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

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

    1. Используйте тело запроса в виде строки (в нашем примере это amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api).
    2. Вычислите хэш SHA256 из этой строки в необработанных байтах.
    3. Преобразуйте необработанные байты в кодировку base64.

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

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

-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,C502560EDE8F82B7
O4+bY1Q1ZcXFLDGVE8s9G2iVISHR/c/IMZKZEjkBED/TbuOCUGVjcav2ZaZO2dO0 lm771N6JNB01uhJbTHScVQ6R0UnGezHFTcsJlAlBa9RQyOwujs4Pk6riOGnLliIs urnTXD0oskBR1wLRA2kp8+V0UPOAMXQaoLxFGE/o8taDGSrkyIcYTBoh9o7ZBxvO SqUWAt2vPbGVyc6XspyuVtgHgEctaJO+E26QTweqdpN5JITF+fDFPNwUrFHoho4N pxpKRWbiCJSpbvbsvhdizkmfgvRw+qYJvTirF3JTfGr14DttudFwjm7sNrr0JILR XPKDUhRyWjkthZM+oDjF2HwISAGkbxcpn4PU7Tywq0uax+5KCQQn2uz4jLM2P6+9 000cvVLwhMnoUdOxuISRXeOcOWVyTO1mPfKiWnHaoO4yS3Y36OCIOe9RHGP8TTmq acb3LUIF30eQyk3KxH/tUB0ScPDKEKMiww13/Kcfr0JkdIe/BWCvV+hSQm38TLQe bTFy+wnD9kHACCwTSVVSOO+rHgJGVIyLgnpClZKWQyyJ4clH7/cORA7mTmp85Ckx IjV5Egu0bPPUMudOB5BnQ4u85RnqXavasgrLRA3JZM4+Jzl8MNy/fsFXnVBQLJJC Wlz/B7S7W8sabRogFuiqkkPmXE/QcpdKQoY3yh748QqMSl8vkA6WgndyYv1EnDDl jA5j7vSf0wKI8BHgdHBEWuEjn3X/s0S/BiPPI6puboYY90tYVJTWSQCR83QrMF3N BIcMu4+RIYu6GWnPx9npZpt0858c670ZII56np24iMse3qgHCOZxsGOenK2x7ta6 163gvaD8bu8xoeQcGVfd6IMbXWVb0+z1hvWR5HWHSalof4lMzZrDsQDKc2UA0ygh hA1+VAl1MAEHVLNCCmyG1SwRwg1PI7FfftW7YARngCZRWkJ1haj1fgy7rtYolrdv lEz/vjFD6diABx67omGgfiJhWdiKIlzsYlX1SW7yaik/Uxf1j8gTFwY34y8ekVd9 6pQTzV2V/4a48ELZl4LvelLWyt1AB3AR+/fM7YG6LYIqlo+qnLtro7Bqu8RNTNRP wcWCd04r/20ulFWMIH8pVa60C98pSdOXriWEI1KDLc0E/fCdhjW2kL+FTPLC7ORe cuzmfI27+06P/BvLZq/FAVBrDAmkioKwe6XYzTjpK1p5jZ3IrNwjAiasY1MNxCRy 5ufhQwkW//d+VUdU5m8Sm30/kXe9UkxMaetXgzPxbB7+5QFFr0bi7D1MjIrJNtTx 5g5E+UfOhqrp8ztBht9csQeFYSYabyyGX4Lh7ymVWrKCVdHlJib3M36nvOjpV/lA zf35sxFz9kaQqNK7xJdQ9Bx6TBUzLjpYhNry37vKk+SIB6Weo+LJ99mALMeX79CB osRqZqX5yrZhaQ8bbpo981nvLy5xFnpRqCuSWVZrVMBq3LQLaOvaCeyGC0V+ZN0C CU6lHlR6XQqd/IjoEN8+8aiVp6Ubw8FuD28TDaEvCltrX3ARL0xFpABsa42LgV1F 09Vi+ju7SSNDvbezN8q0EILq9xp/zNCVhMpyRCIXBq9fzHkyCZ5qMw==
-----END RSA PRIVATE KEY-----

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

curl --request POST \
  --url https://abby.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'

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

Пример кода 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 должен иметь формат:

-----BEGIN PRIVATE KEY-----
MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDdpOwhY/p9x0WmBd3HaDfCD+KYung3M8Cxrw0ozF+h//GltRdnkJD7ejsBDB6/YeIVXZeU3AyqWvsi/IfeHwnokGxVg2IMw8OPacY6o1x7W0EQtfRoZa2Cn2PMCpZhEHlIVraXZDDeg4HY26YP0FZxRbpNnpXhGbiop+Bq0wHeE3JIk53cRmwYhxdxMmvFpgNd6C3dYhmnQqLv6WSpVNDFbQxBVU+JDNyR9FQwB1dU2MadgYwFJnEssbhUkM+sXAC4Wv3qhcZek6MWeWsbFIIlyTPa1T3yrWSXIb4qFJEro4pRMmwQ72qG02p8EPx1tlveQo22TojV9WbTPtaVwQtxAgMBAAECggEBANheTGkYOYsZwgMdzPAB7BSU/0bLGdoBuoV6dqUyRdVWjqaOTwe519625uzR0R5RRqxGzlfyLKcM5Aa2cUhEEp8mhatA87G0Va8lue66VOjTH4RZq/tR7v0J7hlc6Ipe05brl5nYo+BEjriNS+I6Jnizcfid7IBvZJW4NFr0G+mWTxl2BhUK/Mk895n8hg9QtgSRoMNO4jK2f0vJrH4hBHehTYpjHx+QhbUyIvsp60bEnNOXzl054TuWBVCYAQHcHTTZowWMY0s1Z0kGNxwsqQm4amW/v+1EqCF4fjRDrU6v/kjDKxGFx9GJUktKZAe2T8e2LySjgGpJO5g4AdxIVpUCgYEA8x9te+i2ijxoS3kIUSwXaPq5EdKGWGl5mW8KZHzmt9LB/CqTKvSOiDkMGoAx/76t5QmKOYojP+Vsc2XdfQfhT6d00MGTdiPBd+8//MmQQ07/D1/PV58Jd1O8bQFU4fZCMpQl/8Azp9ix/NEx0sHDv2KigLfFMBVGeJxwSoU2JzMCgYEA6WJC0BDTA9vx+i+p9i/41f7ozpQuYey5sxdZa2emOSYen6ptxUFLAYXMxVDaBJ89PMUa8GzWoXHhgXzbuRJk74IzUhWgPpneS4HTr5KDStJh2TqWWVLwEIgLwxvtuw0i9uSEU64D/Czzm801lrOhVgmZsWwNpFtP8ujz0v84MssCgYEA1P4YhbB3kx2e5VfwgGSXUcIttr5wMi6deF0+hpCh9DNw/QEzkzNTV2ZbAzCCHSKo5/n2nbg2b3kIDQUWCL6JlqYHAghErwBeMztoHIddmoovjAGM/Z93xJGYhwremWOL1RHTRH7XAlomfG2tL43PdvDrmsbkut44sdujyLVxnt8CgYBirK3tBMADKLJVgmOM+FlwORe7iAFYW9tj8iJXe/pWvVxDS66fsOyCl0ytvHKBc8ZTdE7gilPw7JJYyi6oQDO25EjIkuYusaXALQMQf5TNRMgkLVY2LA/eHXdDpgJMjNBUrOeZ7cA3ldXl8MyQjCBRnTuDPVlDPWw/GulEM65SIwKBgQDIEv8XK2YBkZrr+0fZSFTQAeK4R7Ve3z4hbpHhJi41YanCNaEWoeYAuQd6/b/QLwABllvfJBDYCNnF8heUxqISpyWd+FZ8nhZtxBoKj5l80czTcutIz/M+ETcvl8FqnMBsoCdp1wodqaLkOx6DIldgKLze6AqKXl5lHUsU4mvVqg==
-----END PRIVATE KEY-----

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

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

Для регистрации заказа используется запрос 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://abby.rbsuat.com/payment/<merchant_address>.
Необязательно

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

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

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

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

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Необязательно

pageView String [1..20] По значению данного параметра определяется, какие страницы платежного интерфейса должны загружаться для клиента. Доступны следующие значения:
  • DESKTOP – для загрузки страниц, верстка которых предназначена для отображения на экранах ПК (в архиве страниц платежного интерфейса будет осуществляться поиск страниц с названиямиpayment_<locale>.html и errors_<locale>.html).
  • MOBILE – для загрузки страниц, верстка которых предназначена для отображения на экранах мобильных устройств (в архиве страниц платежного интерфейса будет осуществляться поиск страниц с названиями mobile_payment_<locale>.html и mobile_errors_<locale>.html).
  • Если магазин создал страницы платежного интерфейса, добавив в название файлов страниц произвольные префиксы, передайте значение нужного префикса в параметре pageView для загрузки соответствующей страницы. Например, при передаче значения iphone в архиве страниц платежного интерфейса будет осуществляться поиск страниц с названиями iphone_payment_<locale>.html и iphone_error_<locale>.html

Где:
  • locale - язык согласно ISO 639-1. Например, fr для французского или en для английского.

Если параметр отсутствует, либо не соответствует формату, то по умолчанию считается pageView=DESKTOP.
Необязательно

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

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

jsonParams Object Набор дополнительных параметров произвольной формы, структура:
{name1:value1,…,nameN:valueN}
Некоторые предопределенные атрибуты jsonParams:
  • email - электронная почта держателя карты для предварительного заполнения на странице оформления заказа
  • phone - номер телефона держателя карты для выставления счетов для предварительного заполнения на странице оформления заказа
  • backToShopUrl - добавляет на страницу оплаты кнопку, которая вернет держателя карты на назначенный URL-адрес веб-сайта продавца.
  • backToShopName - настраивает текстовую метку кнопки Вернуться в магазин по умолчанию, если она используется вместе с backToShopUrl
  • payerPostalCode - почтовый индекс доставки держателя карты
  • payerCountry - страна доставки держателя карты
  • payerState - штат доставки держателя карты
  • payerCity - город доставки держателя карты
  • postAddress - адрес доставки держателя карты
  • 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, то заказ будет создан ТОЛЬКО для создание связки (без оплаты).
Необязательно

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

email String Электронная почта для выставления счетов владельца карты
Необязательно

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

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

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 Объект, содержащий атрибуты адреса доставки. Описание вложенных элементов приведено ниже.

Описание параметров в объекте 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 Объект, содержащий атрибуты описания агентского вознаграждения за продажу товаров. Описание вложенных элементов приведено ниже.

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

Обязательность Название Тип Описание
Обязательно

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

measure String [1..20] Единица измерения количества по позиции.

Описание параметров в объекте 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] Значение агентской комиссии.

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

Обязательность Название Тип Описание
Необязательно

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://abby.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 email=test@test.com \
  --data clientId=259753456 \
  --data language=en

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

{
  "orderId": "01491d0b-c848-7dd6-a20d-e96900a7d8c0",
  "formUrl": "https://abby.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://abby.rbsuat.com/payment/<merchant_address>.
Необязательно

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

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

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

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Необязательно

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

pageView String [1..20] По значению данного параметра определяется, какие страницы платежного интерфейса должны загружаться для клиента. Доступны следующие значения:
  • DESKTOP – для загрузки страниц, верстка которых предназначена для отображения на экранах ПК (в архиве страниц платежного интерфейса будет осуществляться поиск страниц с названиямиpayment_<locale>.html и errors_<locale>.html).
  • MOBILE – для загрузки страниц, верстка которых предназначена для отображения на экранах мобильных устройств (в архиве страниц платежного интерфейса будет осуществляться поиск страниц с названиями mobile_payment_<locale>.html и mobile_errors_<locale>.html).
  • Если магазин создал страницы платежного интерфейса, добавив в название файлов страниц произвольные префиксы, передайте значение нужного префикса в параметре pageView для загрузки соответствующей страницы. Например, при передаче значения iphone в архиве страниц платежного интерфейса будет осуществляться поиск страниц с названиями iphone_payment_<locale>.html и iphone_error_<locale>.html

Где:
  • locale - язык согласно ISO 639-1. Например, fr для французского или en для английского.

Если параметр отсутствует, либо не соответствует формату, то по умолчанию считается pageView=DESKTOP.
Необязательно

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

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

jsonParams Object Набор дополнительных параметров произвольной формы, структура:
{name1:value1,…,nameN:valueN}
Некоторые предопределенные атрибуты jsonParams:
  • email - электронная почта держателя карты для предварительного заполнения на странице оформления заказа
  • phone - номер телефона держателя карты для выставления счетов для предварительного заполнения на странице оформления заказа
  • backToShopUrl - добавляет на страницу оплаты кнопку, которая вернет держателя карты на назначенный URL-адрес веб-сайта продавца.
  • backToShopName - настраивает текстовую метку кнопки Вернуться в магазин по умолчанию, если она используется вместе с backToShopUrl
  • payerPostalCode - почтовый индекс доставки держателя карты
  • payerCountry - страна доставки держателя карты
  • payerState - штат доставки держателя карты
  • payerCity - город доставки держателя карты
  • postAddress - адрес доставки держателя карты
  • 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. Чтобы включить отправку этого поля в процессинговую систему, обратитесь в службу технической поддержки.
Необязательно

email String Электронная почта для выставления счетов владельца карты
Необязательно

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

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

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

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 Объект, содержащий атрибуты адреса доставки. Описание вложенных элементов приведено ниже.

Описание параметров в объекте 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 Объект, содержащий атрибуты описания агентского вознаграждения за продажу товаров. Описание вложенных элементов приведено ниже.

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

Обязательность Название Тип Описание
Обязательно

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

measure String [1..20] Единица измерения количества по позиции.

Описание параметров в объекте 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] Значение агентской комиссии.

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

Обязательность Название Тип Описание
Необязательно

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://abby.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://abby.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. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.
Необязательно

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Необязательно

email String Электронная почта для выставления счетов владельца карты
Необязательно

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. Возможные значения: "2.1.0", "2.2.0" для 3DS2.
Если в запросе не передается threeDSProtocolVersion, то для авторизации 3D Secure будет использоваться значение по умолчанию (2.1.0 - для 3DS 2).
Необязательно

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 Номер мобильного телефона владельца карты с обязательным знаком «+».

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

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

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

Обязательность Название Тип Описание
Обязательно

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

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

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

Примеры

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

curl --request POST \\
  --url https://abby.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://abby.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. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.
Необязательно

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Необязательно

email String Электронная почта для выставления счетов владельца карты
Необязательно

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

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

threeDSSDK String Возможные значения: 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, т.е. транзакция, прошедшая успешную антифрод-проверку.

Для передачи этого параметра у вас должны быть достаточные права в платежном шлюзе.

Ниже приведены параметры блока 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) Инициирующая Покупатель Вводится покупателем Да Транзакция электронной коммерции с сохранением связки.
RI Инициирующий - Рекурентные (CIT) Инициирующая Покупатель Вводится покупателем Да Транзакция электронной коммерции с сохранением связки.
U Внеплановый платеж (MIT) Последующая Продавец Нет ручного ввода, продавец передает данные Нет Транзакция электронной коммерции, использующая ранее сохраненную обычную связку.

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

Обязательность Название Тип Описание
Необязательно

threeDSServerTransId String Идентификатор транзакции, созданный на сервере 3DS.
Необязательно

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

threeDSMethodNotificationUrl String URL-адрес для отправки уведомления о прохождении проверки на ACS.

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

Обязательность Название Тип Описание
Обязательно

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.

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

Обязательность Название Тип Описание
Обязательно

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

threeDSServerTransId String Идентификатор транзакции, созданный на сервере 3DS.
Необязательно

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://abby.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://abby.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"
}

Мгновенная оплата

Запрос, используемый для регистрации заказа и одновременной оплаты за него, – instantPayment.do.

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

Обязательность Название Тип Описание
Условие

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. Если не указано, то используется значение по умолчанию.
Необязательно

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

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Необязательно

email String Электронная почта для выставления счетов владельца карты
Необязательно

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

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

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

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

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

preAuth Boolean Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
  • true - включена двухстадийная оплата;
  • false - включена одностадийная оплата (деньги списываются сразу).
Если параметр отсутствует, производится одностадийная оплата.
Необязательно

pan String [1..19] Номер платежной карты (обязательно, если если bindinId не передается). Значение pan заменяет собой значение bindingId.
Необязательно

cvc Integer Этот параметр обязателен, если для мерчанта не выбрано разрешение Может проводить оплату без подтверждения CVC.
Необязательно

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

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

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

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

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

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

backUrl String [1..512] URL-адрес, на который будет перенаправлен пользователь в случае успешной оплаты.
Используйте полный путь с указанием протокола, например https://test.com (а не test.com).
В противном случае пользователь будет перенаправлен на URL-адрес следующего вида: http://paymentGatewayURL/merchantURL
Необязательно

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

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

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, то заказ будет создан ТОЛЬКО для создание связки (без оплаты).
Необязательно

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

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

threeDSServerTransId String Идентификатор транзакции, созданный на сервере 3DS.
Необязательно

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

threeDSMethodNotificationUrl String URL-адрес для отправки уведомления о прохождении проверки на ACS.
Условие

threeDSVer2MdOrder String Номер заказа, который был зарегистрирован в первой части запроса в рамках 3DS 2.0 операции.
Если данный параметр присутствует в запросе, то используется mdOrder, который передается в настоящем параметре. В таком случае регистрация заказа не происходит, а происходит сразу оплата заказа. Для транзакций Google Pay этот параметр является обязательным.
Необязательно

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

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

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

expiry Integer Срок действия карты в следующем формате: YYYYMM. Обязательно, если не переданы ни seToken, ни bindingId.
Необязательно

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

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

Для передачи этого параметра у вас должны быть достаточные права в платежном шлюзе.
Необязательно

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

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

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

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

Описание параметров в объекте 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 Объект, содержащий атрибуты адреса доставки. Описание вложенных элементов приведено ниже.

Описание параметров в объекте 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 Объект, содержащий атрибуты описания агентского вознаграждения за продажу товаров. Описание вложенных элементов приведено ниже.

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

Обязательность Название Тип Описание
Необязательно

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

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

Обязательность Название Тип Описание
Обязательно

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

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

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

Обязательность Название Тип Описание
Обязательно

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

measure String [1..20] Единица измерения количества по позиции.

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

Обязательность Название Тип Описание
Обязательно

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

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

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

Обязательность Название Тип Описание
Обязательно

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

interestValue Integer [1..20] Значение агентской комиссии.

Ниже приведены параметры блока 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) Инициирующая Покупатель Вводится покупателем Да Транзакция электронной коммерции с сохранением связки.
RI Инициирующий - Рекурентные (CIT) Инициирующая Покупатель Вводится покупателем Да Транзакция электронной коммерции с сохранением связки.
U Внеплановый платеж (MIT) Последующая Продавец Нет ручного ввода, продавец передает данные Нет Транзакция электронной коммерции, использующая ранее сохраненную обычную связку.

Описание параметров объекта 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 - указывает на успех обработки;
  • другое положительное числовое значение - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр error.
Может отсутствовать, если результат не вызвал ошибки.
Необязательно

error String Сообщение об ошибке (если в ответе вернулась ошибка) на языке, переданном в запросе.
Необязательно

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

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.
Условие orderStatus Object Содержит параметры статуса заказа и возвращается только в том случае, если платежный шлюз распознал все параметры запроса как правильные. См. описание ниже.

Блок orderStatus содержит следующие элементы.

Обязательность Название Тип Описание
Необязательно

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

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

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

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

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

cardholderName String [1..26] Имя держателя карты (при наличии).
Необязательно

depositAmount String [0..12] В REST-запросах вместо данного параметра используется параметр amount.
Необязательно

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

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

authCode Integer [6] Устаревший параметр (не используется). Его значение всегда 2 независимо от статуса заказа и кода авторизации процессинговой системы.
Необязательно

Pan String [1..19] Маскированный номер карты, которая использовалась для оплаты. Указывается только после оплаты заказа. При оплате Apple Pay используется DPAN. Это номер, привязанный к мобильному устройству покупателя и выполняющий функции номера платежной карты в системе Apple Pay.
Необязательно

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

Ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Необязательно

originalActionCode String Код ответа, полученный от процессинга. Чтобы включить получение этого поля, обратитесь в службу технической поддержки.
Необязательно

rrn Integer [1..12] Reference Retrieval Number - идентификатор транзакции, присвоенный банком-эквайером.

Примеры

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

curl --request POST \
--url  https://abby.rbsuat.com/payment/rest/instantPayment.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data userName=test_user \
--data password=test_user_password \
--data amount=100 \
--data currency=933 \
--data description=my_first_order \
--data orderNumber=1218637308 \
--data pan=5000001111111115 \
--data cvc=123 \
--data expiry=203012 \
--data cardHolderName="TEST CARDHOLDER" \
--data language=en \
--data backUrl=https%3A%2F%2Fmybestmerchantreturnurl.com \
--data failUrl=https%3A%2F%2Fmybestmerchantreturnurl.com

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

{
    "errorCode": "0",
    "orderId": "eee72f6e-b980-79c5-92e8-6f4200b1eae0",
    "info": "Your order is proceeded, redirecting...",
    "redirect": "https://www.test.com/payment/merchants/gateway/finish.html?orderId=eee72f6e-b980-79c5-92e8-6f4200b1eae0&lang=en",
    "orderStatus": {
        "expiration": "202412",
        "cardholderName": "TEST CARDHOLDER",
        "depositAmount": 100,
        "currency": "933",
        "approvalCode": "123456",
        "authCode": 2,
        "originalActionCode": "S1",
        "rrn": "311489272111",
        "ErrorCode": "0",
        "ErrorMessage": "Success",
        "OrderStatus": 2,
        "OrderNumber": "2011",
        "Pan": "500000**1115",
        "Amount": 100,
        "Ip": "10.99.50.35"
    }
}

Проверка данных карты

Проверка платежной карты выполняется, как показано в таблице ниже.

Параметр Описание Валидация

PAN

 Полный номер платежной карты. Валидация карты (проверка того, что карта с таким номером реально существует), количество цифр в номер карты от 13 до 20

CVC

 Integer 3 цифры

YYYY, MM

 Год, Месяц Дата в настоящем или будущем. В случае, если срок действия карты до текущего года текущего месяца, оплата возможна до конца календарного месяца

TEXT

 Держатель карты Не проверяется.

MOTO-платеж

Для осуществления MOTO-платежей используется метод motoPayment.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://abby.rbsuat.com/payment/<merchant_address>.
Необязательно

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

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

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

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

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

email String Электронная почта для выставления счетов владельца карты
Необязательно

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

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

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, то заказ будет создан ТОЛЬКО для создание связки (без оплаты).
Необязательно

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

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

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Необязательно

preAuth Boolean Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
  • true - включена двухстадийная оплата;
  • false - включена одностадийная оплата (деньги списываются сразу).
Если параметр отсутствует, производится одностадийная оплата.
Обязательно

pan String [1..19] Маскированный номер карты, которая использовалась для оплаты. Этот параметр указывается только после оплаты заказа. При оплате через Apple Pay в качестве номера карты используется DPAN - это номер, привязанный к мобильному устройству клиента, который функционирует как номер платежной карты в системе Apple Pay.
Обязательно

expiry Integer Срок действия карты в следующем формате: YYYYMM. Обязательно, если не переданы ни seToken, ни bindingId.
Обязательно

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

cvc Integer Этот параметр обязателен, если для мерчанта не выбрано разрешение Может проводить оплату без подтверждения CVC.

Ниже приведены параметры блока 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] Штат, зарегистрированный по конкретной карте у Банка Эмитента.

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

Обязательность Название Тип Описание
Обязательно

success Boolean Основной параметр, который напрямую указывает на то, что запрос прошел успешно. Доступны следующие значения:
  • true - запрос успешно обработан;
  • false - запрос не прошел.

Обратите внимание, что значение true означает, что запрос был обработан, а не что заказ был оплачен. Статус платежа отражается значением другого параметра — orderStatus.
Обязательно

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

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

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

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

userMessage String [1..512] Сообщению пользователю с описанием кода результата.

Примеры

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

curl --request POST \
--url https://abby.rbsuat.com/payment/rest/motoPayment.do \
--header 'content-type: application/x-www-form-urlencoded' \
  --data amount=2000 \
  --data currency=933 \
  --data userName=test_user \
  --data password=test_user_password \
  --data returnUrl=https://mybestmerchantreturnurl.com \
  --data description=my_first_order \
  --data pan=4000001111111118 \
  --data expiry=203012 \
  --data cvc=123 \
  --data cardholder="TEST CARDHOLDER" \
  --data language=en

Пример ответа (успешный платеж)

{
   "errorCode":"0",
   "success":true,
   "mdOrder":"088433e9-e34d-769e-9366-696200a7d8c0",
   "orderNumber":"62001"
}

Кошельки

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

Для регистрации заказа используется метод /applepay/payment.do.

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

Обязательность Название Тип Описание
Обязательно

merchant String Логин продавца в системе платежного шлюза.
Обязательно

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

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

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

additionalParameters Object Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
Необязательно

preAuth Boolean Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
  • true - включена двухстадийная оплата;
  • false - включена одностадийная оплата (деньги списываются сразу).
Если параметр отсутствует, производится одностадийная оплата.
Обязательно

paymentToken String [1..8192] Параметр paymentToken должен содержать расшифрованное и закодированное в Base64 значение свойства paymentData, полученного из объекта PKPaymentToken Object от системы Apple Pay (подробнее см. документацию Apple Pay). Таким образом, чтобы сделать запрос на оплату в платежный шлюз, продавец должен:
  1. получить PKPaymentToken Object, содержащий paymentData от Apple Pay;
  2. извлечь значение paymentData и закодировать его в Base64;
  3. включить закодированное значение свойства paymentData в качестве значения параметра paymentToken в запросе на оплату, который продавец направит в платежный шлюз.
Обязательно

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

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

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

Для передачи этого параметра у вас должны быть достаточные права в платежном шлюзе.

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

Обязательность Название Тип Описание
Обязательно

success Boolean Основной параметр, который напрямую указывает на то, что запрос прошел успешно. Доступны следующие значения:
  • true - запрос успешно обработан;
  • false - запрос не прошел.

Обратите внимание, что значение true означает, что запрос был обработан, а не что заказ был оплачен. Статус платежа отражается значением другого параметра — orderStatus.
Условие data Object Этот параметр возвращается только в случае успешной обработки платежа. См. описание ниже.
Условие error Object Этот параметр возвращается только в случае ошибки платежа. См. описание ниже.
Условие orderStatus Object Содержит параметры статуса заказа и возвращается только в том случае, если платежный шлюз распознал все параметры запроса как правильные. См. описание ниже.

Блок data содержит следующие элементы.

Обязательность Название Тип Описание
Обязательно

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

Блок error содержит следующие элементы.

Обязательность Название Тип Описание

code Integer [1..3] Код как информационный параметр, сообщающий об ошибке.

description String [1..598] Подробное техническое объяснение ошибки - содержимое этого параметра не предназначено для отображения пользователю.

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

Блок 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 символов).
Условие merchantOrderParams Object Объект с атрибутами, в которых передаются дополнительные параметры мерчанта. См. описание ниже.
Условие 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. См. описание ниже.

Блок 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.

Блок paymentAmountInfo содержит следующие элементы.

Обязательность Название Тип Описание
Обязательно

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

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

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

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

Блок bankInfo содержит следующие элементы.

Обязательность Название Тип Описание
Обязательно

bankCountryName String [1..160] Страна банка-эмитента.

Примеры

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

curl --request POST \
--url https://abby.rbsuat.com/payment/applepay/payment.do \
--header 'Content-Type: application/json' \
--data-raw '{
  "additionalParameters" : {
    "phone" : "9521235847",
    "order-pain" : "111",
    "email" : "apple@pay.com"
  },
  "language" : "en",
  "clientId" : "259753456",
  "orderNumber" : "281477871",
  "paymentToken" : "eyJkYXRhIjoiYPhK3M1bEtm...YjM2NWMzZWNmYjE5fIkVDX3YxIn0=",
  "preAuth" : false
}'

Ответ в случае успешной оплаты

{
    "success": true,
    "data": {
        "orderId": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
    },
    "orderStatus": {
        "errorCode": "0",
        "orderNumber": "229",
        "orderStatus": 1,
        "actionCode": 0,
        "actionCodeDescription": "",
        "amount": 960000,
        "currency": "933",
        "date": 1478682458102,
        "ip": "81.18.144.51",
        "merchantOrderParams": [
            {
                "name": "param2",
                "value": "param2"
            },
            {
                "name": "param1",
                "value": "param1"
            }
        ],
        "attributes": [
            {
                "name": "mdOrder",
                "value": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
            }
        ],
        "cardAuthInfo": {
            "expiration": "203012",
            "cardholderName": "TEST CARDHOLDER",
            "approvalCode": "123456",
            "pan": "500000**1115"
        },
        "authDateTime": 1478682459082,
        "terminalId": "12345678",
        "authRefNum": "111111111111",
        "paymentAmountInfo": {
            "paymentState": "APPROVED",
            "approvedAmount": 960000,
            "depositedAmount": 0,
            "refundedAmount": 0
        },
        "bankInfo": {
            "bankCountryName": "<UNKNOWN>"
        }
    }
}

Ответ в случае неудачной оплаты

{
  "error": {
    "code": 10,
    "description": "Processing Error",
    "message": "Auth is invalid"
  },
  "success": false
}

Apple Pay Direct

Запрос, используемый для осуществления прямого платежа через Apple Pay, - applepay/paymentDirect.do. Этот запрос можно использовать для интеграций, предполагающих расшифровку платежных данных на стороне продавца.

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

Обязательность Название Тип Описание
Обязательно

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

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

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

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

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

feeInput String Размер комиссии в минимальных единицах валюты. Функциональность должна быть включена на уровне продавца в шлюзе.
Необязательно

additionalParameters Object Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
Необязательно

preAuth Boolean Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
  • true - включена двухстадийная оплата;
  • false - включена одностадийная оплата (деньги списываются сразу).
Если параметр отсутствует, производится одностадийная оплата.
Обязательно

paymentToken String [1..8192] Платежные данные, полученные от Apple Pay и расшифрованные продавцом. Последовательность действий:
  1. Получите PKPaymentToken Object от Apple Pay (Payment Token Format Reference) с зашифрованными платежными данными;
  2. Расшифруйте (ECC/RSA) paymentData, чтобы получить текстовое представление объекта: {"applicationPrimaryAccountNumber":"4111111111111111","deviceManufacturerIdentifier":"050110030273","currencyCode":"840","applicationExpirationDate" :"220430","paymentData":{"onlinePaymentCryptogram":"AM32yL0vuOOmAAGG0iQUAoABFA=="}," paymentDataType":"3DSecure","transactionAmount":1010};
  3. Закодируйте в BASE64 открытый текст объекта paymentData и отправьте его как paymentToken.
Необязательно

merchant String Логин продавца в системе платежного шлюза.
Необязательно

features String В этом параметре можно передать значение VERIFY. Тогда оплата производиться не будет, вместо этого будет создана связка (будет сохранена карта клиента).
Если передается features, paymentToken.transactionAmount должно быть 0. В противном случае будет возвращена ошибка.
Необязательно

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

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

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

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

Для передачи этого параметра у вас должны быть достаточные права в платежном шлюзе.
Необязательно

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

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

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

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

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

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

Ниже приведены параметры блока 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 означает, что запрос был обработан, а не что заказ был оплачен. Статус платежа отражается значением другого параметра — orderStatus.
Обязательно

data Object Возвращается только в случае успешной оплаты.
Обязательно

error Object Этот параметр возвращается только в случае ошибки платежа.
Необязательно

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

Параметры в блоке data:

Обязательность Название Тип Описание
Обязательно

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

Параметры в блоке error:

Обязательность Название Тип Описание
Обязательно

code Integer [1..3] Код как информационный параметр, сообщающий об ошибке.
Обязательно

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

description String [1..598] Подробное техническое объяснение ошибки - содержимое этого параметра не предназначено для отображения пользователю.

Параметры в блоке 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 - авторизация отклонена.
Необязательно

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 символов).
Необязательно

merchantOrderParams Object Раздел с атрибутами, в котором передаются дополнительные параметры мерчанта.
Необязательно

cardAuthInfo Object Блок с данными о карте плательщика см вложенные параметры.
Необязательно

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

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

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

paymentAmountInfo Object Объект с информацией о суммах подтверждения, списания, возврата. Список вложенных параметров см. ниже.
Необязательно

bankInfo Object Объект, содержащий вложенный параметр bankCountryName, в котором передается наименование страны банка-эмитента (при наличии). Используемый язык совпадает с языком, переданным в параметре запроса language. Если язык не передан, будет использоваться язык пользователя, вызывающего метод.

Параметры в блоке cardAuthInfo:

Обязательность Название Тип Описание
Необязательно

expiration Integer Год и месяц окончания действия карты.
Необязательно

cardholderName String [1..26] Имя держателя карты (при наличии).
Необязательно

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

pan String [1..19] Маскированный DPAN: номер, привязанный к мобильному устройству покупателя и выполняющий функции номера платежной карты в системе Apple Pay.

Параметры в блоке 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] Сумма заказа плюс комиссия, если таковая имеется.

Примеры

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

curl --location --request POST 'https://abby.rbsuat.com/payment/applepay/paymentDirect.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "test_user",
    "password": "test_user_password",
    "orderNumber": "947664b3-4a42-4cdf-9f8c-2e9679bad9e4",
    "description": "description of the order",
    "language": "en",
    "paymentToken": "eyJhcHBsaWNhPT...0ifX0="
}'

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

Пример ответа (успешный платеж)

{
    "success": true,
    "data": {
        "orderId": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
    },
    "orderStatus": {
        "errorCode": "0",
        "orderNumber": "229",
        "orderStatus": 1,
        "actionCode": 0,
        "actionCodeDescription": "",
        "amount": 960000,
        "currency": "933",
        "date": 1478682458102,
        "ip": "81.18.144.51",
        "merchantOrderParams": [
            {
                "name": "param2",
                "value": "param2"
            },
            {
                "name": "param1",
                "value": "param1"
            }
        ],
        "attributes": [
            {
                "name": "mdOrder",
                "value": "b926351f-a634-49cf-9484-ccb0a3b8cfad"
            }
        ],
        "cardAuthInfo": {
            "expiration": "203012",
            "cardholderName": "TEST CARDHOLDER",
            "approvalCode": "123456",
            "pan": "500000**1115"
        },
        "authDateTime": 1478682459082,
        "terminalId": "12345678",
        "authRefNum": "111111111111",
        "paymentAmountInfo": {
            "paymentState": "APPROVED",
            "approvedAmount": 960000,
            "depositedAmount": 0,
            "refundedAmount": 0
        },
        "bankInfo": {
            "bankCountryName": "<UNKNOWN>"
        }
    }
}

Пример ответа (ошибка платежа)

{
  "error": {
    "code": 1,
    "description": "Processing Error",
    "message": "Insufficient amount on card"
  },
  "success": false
}

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

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

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

Обязательность Название Тип Описание
Обязательно

merchant String Логин продавца в системе платежного шлюза.
Обязательно

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

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

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

additionalParameters Object Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
Необязательно

preAuth Boolean Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
  • true - включена двухстадийная оплата;
  • false - включена одностадийная оплата (деньги списываются сразу).
Если параметр отсутствует, производится одностадийная оплата.
Обязательно

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

paymentToken String [1..8192] Токен, полученный от Google Pay и закодированный в Base64.
Обязательно

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Обязательно

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

currencyCode String [3] Цифровой код валюты платежа ISO 4217. Если не указан, считается равным 643 (российский рубль).
Условие

email String Электронная почта для выставления счетов владельца карты
Условие

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

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

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

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

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

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

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

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

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

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

Обязательность Название Тип Описание
Условие

threeDSServerTransId String Идентификатор транзакции, созданный на сервере 3DS.
Необязательно

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

threeDSMethodNotificationUrl String URL-адрес для отправки уведомления о прохождении проверки на ACS.

Ниже приведены параметры блока 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 Целевой адрес электронной почты для доставки цифрового распространения

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

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

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

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

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

Обязательность Название Тип Описание
Обязательно

success Boolean Основной параметр, который напрямую указывает на то, что запрос прошел успешно. Доступны следующие значения:
  • true - запрос успешно обработан;
  • false - запрос не прошел.

Обратите внимание, что значение true означает, что запрос был обработан, а не что заказ был оплачен. Статус платежа отражается значением другого параметра — orderStatus.
Условие data Object Этот параметр возвращается только в случае успешной обработки платежа. См. описание ниже.
Условие error Object Этот параметр возвращается только в случае ошибки платежа. См. описание ниже.

Блок data содержит следующие элементы.

Обязательность Название Тип Описание
Обязательно

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

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.
Условие**

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

* Только если используется дополнительная аутентификация на ACS банка-эмитента
** Параметр возвращается, если используются связки

Если используется протокол 3DS 2.0, ответ на первоначальный запрос также включает следующие параметры в блоке data:

Обязательность Название Тип Описание
Обязательно

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

threeDSServerTransId String Идентификатор транзакции, созданный на сервере 3DS.
Необязательно

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 через платежный шлюз (при наличии соответствующего разрешения на уровне продавца).

Блок error содержит следующие элементы.

Обязательность Название Тип Описание
Обязательно

code Integer [1..3] Код как информационный параметр, сообщающий об ошибке.
Обязательно

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

description String [1..598] Подробное техническое объяснение ошибки - содержимое этого параметра не предназначено для отображения пользователю.

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

Обязательность Название Тип Описание
Условие*

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

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

* Только в случае необходимости перенаправления на ACS

Примеры

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

curl --request POST \
--url https://abby.rbsuat.com/payment/google/payment.do \
--header 'Content-Type: application/json' \
--data-raw '{
  "merchant": "OurBestMerchantLogin",
  "orderNumber": "UAF-203974-DE",
  "language": "RU",
  "preAuth": true,
  "description" : "Test description",
  "additionalParameters":
  {
      "firstParamName": "firstParamValue",
      "secondParamName": "secondParamValue"
  },
  "paymentToken": "eyJtZXJjaGFudCI6ICJrdXBpdmlwIiwib3JkZXJOdW1iZXIiOiAyMDUxOTIzMzkxLCJwYXltZW50VG9rZW4iOiAie1wiZXBoZW1lcmFsUHVibGljS2V5XCI6XCJrZXlcIixcImVuY3J5cHRlZE1lc3NhZ2VcIjpcIm1lc3NhZ2VcIixcInRhZ1wiOlwidGFnXCJ9In0=",
  "ip" : "127.0.0.1",
  "amount" : "230000",
  "currencyCode" : 643,
  "failUrl" : "https://mybestmerchantfailurl.ru"
  "returnUrl" : "https://mybestmerchantreturnurl.ry"
}'

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

curl --request POST \
--url https://abby.rbsuat.com/payment/google/payment.do \
--header 'Content-Type: application/json' \
--data-raw '{
  "merchant": "OurBestMerchantLogin",
  "orderNumber": "UAF-203974-DE",
  "language": "RU",
  "preAuth": true,
  "description" : "Test description",
  "additionalParameters":
  {
      "firstParamName": "firstParamValue",
      "secondParamName": "secondParamValue"
  },
  "paymentToken": "eyJtZXJjaGFudCI6ICJrdXBpdmlwIiwib3JkZXJOdW1iZXIiOiAyMDUxOTIzMzkxLCJwYXltZW50VG9rZW4iOiAie1wiZXBoZW1lcmFsUHVibGljS2V5XCI6XCJrZXlcIixcImVuY3J5cHRlZE1lc3NhZ2VcIjpcIm1lc3NhZ2VcIixcInRhZ1wiOlwidGFnXCJ9In0=",
  "ip" : "127.0.0.1",
  "amount" : "230000",
  "currencyCode" : 643,
  "failUrl" : "https://mybestmerchantfailurl.ru"
  "returnUrl" : "https://mybestmerchantreturnurl.ru"
  "threeDSServerTransId" : "f44d6d21-1874-45a5-aeb0-1c710dd6e134"
  "threeDSVer2FinishUrl" : "https:test.com"
}'

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

{
"success":true,
"data": {
 "orderId": "12312312123"
 "is3DSVer2": true,
 "threeDSServerTransId": "f44d6d21-1874-45a5-aeb0-1c710dd6e134",
 "threeDSMethodURLServer": "https://test.com/3dsserver/gatherClientInfo?threeDSServerTransID=f44d6d21-1874-45a5-aeb0-1c710dd6e134"
 }
}

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

{
"success":true,
"data": {
  "info": "Ваш платёж обработан, происходит переадресация...",
  "acsUrl": "https://test.com/acs2/acs/creq",
  "is3DSVer2": true,
  "packedCReq": "eyJ0aHJl<skipped>IuMS4wIn0="
 }
}

Google Pay Direct

Запрос, используемый для прямого платежа через Google Pay, -google/paymentDirect.do. Этот запрос можно использовать для интеграций, предполагающих расшифровку платежных данных на стороне продавца.

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

Обязательность Название Тип Описание
Обязательно

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

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

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

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

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

additionalParameters Object Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
Необязательно

preAuth Boolean Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
  • true - включена двухстадийная оплата;
  • false - включена одностадийная оплата (деньги списываются сразу).
Если параметр отсутствует, производится одностадийная оплата.
Необязательно

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

protocolVersion String Версия протокола, определенная Google для платежного токена: ECv1 (по умолчанию) или ECv2
Обязательно

paymentToken String [1..8192] Платежные данные, полученные от Google Pay и расшифрованные продавцом. Последовательность действий:
  1. Получите PKPaymentToken Object от Google Pay (Payment Token Format Reference) с зашифрованными платежными данными;
  2. Расшифруйте (ECC/RSA) paymentData, чтобы получить текстовое представление объекта: {"paymentMethod": "CARD","paymentMethodDetails": {"pan": "5555555555555599","expirationMonth": 12,"expirationYear": 2024},"gatewayMerchantId": "GPay-decrypted","messageId": "AH2EjtcHYs1Ye9Baqr4FAM735VNThPiP","messageExpiration": "1577862000000"};
  3. Закодируйте в BASE64 открытый текст объекта paymentData и отправьте его как paymentToken.
Необязательно

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Обязательно

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

currencyCode String [3] Цифровой код валюты платежа ISO 4217. Если не указан, считается равным 643 (российский рубль).
Необязательно

email String Электронная почта для выставления счетов владельца карты
Необязательно

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

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

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

merchant String Логин продавца в системе платежного шлюза.
Необязательно

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, то заказ будет создан ТОЛЬКО для создание связки (без оплаты).
Необязательно

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

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

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

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

Для передачи этого параметра у вас должны быть достаточные права в платежном шлюзе.
Необязательно

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 Номер мобильного телефона владельца карты с обязательным знаком «+».

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

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

Если используется 3DS 2.0, необходимо также передать следующие параметры:

Обязательность Название Тип Описание
Условие

threeDSServerTransId String Идентификатор транзакции, созданный на сервере 3DS.
Необязательно

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

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

threeDSMethodNotificationUrl String URL-адрес для отправки уведомления о прохождении проверки на ACS.

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

Обязательность Название Тип Описание
Обязательно

success Boolean Основной параметр, который напрямую указывает на то, что запрос прошел успешно. Доступны следующие значения:
  • true - запрос успешно обработан;
  • false - запрос не прошел.

Обратите внимание, что значение true означает, что запрос был обработан, а не что заказ был оплачен. Статус платежа отражается значением другого параметра — orderStatus.
Обязательно*

data Object Возвращается только в случае успешной оплаты.
Обязательно*

error Object Этот параметр возвращается только в случае ошибки платежа.

Блок data содержит следующие элементы.

Обязательность Название Тип Описание
Обязательно

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

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

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

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

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

Если используется протокол 3DS 2.0, ответ на первоначальный запрос также включает следующие параметры в блоке data:

Обязательность Название Тип Описание
Обязательно

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

threeDSServerTransId String Идентификатор транзакции, созданный на сервере 3DS.
Необязательно

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 через платежный шлюз (при наличии соответствующего разрешения на уровне продавца).

Параметры в блоке error:

Обязательность Название Тип Описание
Обязательно

code Integer [1..3] Код как информационный параметр, сообщающий об ошибке.
Обязательно

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

description String [1..598] Подробное техническое объяснение ошибки - содержимое этого параметра не предназначено для отображения пользователю.

Примеры

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

curl --request POST \
--url https://abby.rbsuat.com/payment/google/paymentDirect.do \
--header 'Content-Type: application/json' \
--data-raw '{
"amount" : "1000",
"orderNumber" : "350467565",
"features" : [ ],
"language" : "EN",
"password" : "test_user_password",
"paymentToken" : "eyJnYXRldTWVY2hRJ...b25ZZWFyyMD0fX0=",
"preAuth" : true,
"returnUrl" : "https://mybestmerchantreturnurl.com",
"username" : "test_user"
}'

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

curl --request POST \
--url https://abby.rbsuat.com/payment/google/paymentDirect.do \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "test_user",
"password": "test_user_password",
"paymentToken": "eyJnYXR<skipped>lBQT0ifX0=",
"amount": 100,
"orderNumber": "1534175806640",
"ip": "0.0.0.0",
"description": "description",
"language": "en",
"preAuth": false,
"returnUrl": "https://mybestmerchantreturnurl.com",
"currencyCode": "933",
"threeDSVer2FinishUrl" : "https:test.com"
}'

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

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

{
  "success": true,
  "data": {
    "orderId": "12312312123"
  }
}

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

{
  "success": true,
  "data": {
    "orderId": "12312312123",
    "acsUrl": "https://test.com/acs2/acs/creq",
    "is3DSVer2": true,
    "packedCReq": "eyJ0aHJl<skipped>IuMS4wIn0="
  }
}

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

Для регистрации заказа Samsung Pay используется запрос /samsung/payment.do. См. "Координаты подключения". Этот запрос используется только при оплате из мобильного приложения.

Ниже представлен пример запроса на оплату через Samsung Pay.

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

Обязательность Название Тип Описание
Обязательно

merchant String Логин продавца в системе платежного шлюза.
Обязательно

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

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

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

additionalParameters Object Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
Необязательно

preAuth Boolean Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
  • true - включена двухстадийная оплата;
  • false - включена одностадийная оплата (деньги списываются сразу).
Если параметр отсутствует, производится одностадийная оплата.
Необязательно

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

paymentToken String [1..8192] Содержимое параметра 3ds.data из ответа, полученного от Samsung Pay.
Необязательно

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Необязательно

currencyCode String [3] Цифровой код валюты платежа ISO 4217. Если не указан, считается равным 643 (российский рубль).
Необязательно

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

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

Обязательность Название Тип Описание
Обязательно

success Boolean Основной параметр, который напрямую указывает на то, что запрос прошел успешно. Доступны следующие значения:
  • true - запрос успешно обработан;
  • false - запрос не прошел.

Обратите внимание, что значение true означает, что запрос был обработан, а не что заказ был оплачен. Статус платежа отражается значением другого параметра — orderStatus.
Условие data Object Этот параметр возвращается только в случае успешной обработки платежа. См. описание ниже.
Условие error Object Этот параметр возвращается только в случае ошибки платежа. См. описание ниже.

Блок data содержит следующие элементы.

Обязательность Название Тип Описание
Обязательно

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

Блок error содержит следующие элементы.

Обязательность Название Тип Описание
Обязательно

code Integer [1..3] Код как информационный параметр, сообщающий об ошибке.
Обязательно

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

description String [1..598] Подробное техническое объяснение ошибки - содержимое этого параметра не предназначено для отображения пользователю.

Примеры

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

curl --location --request POST 'https://abby.rbsuat.com/payment/samsung/paymentDirect.do' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchant": "sandbox_merchant_test",
    "orderNumber": "1218637308",
    "language": "en",
    "preAuth": true,
    "description": "Test description",
    "additionalParameters": {
        "firstParamName": "firstParamValue",
        "secondParamName": "secondParamValue"
    },
    "paymentToken": "ew0KICB7DQoJICA...0KICB9DQp9",
    "ip": "127.0.0.1"
}'

Ответ в случае успешной оплаты

{
"success":true,
"data": {
    "orderId": "12312312123"
  }
}

Ответ в случае неудачной оплаты

{
  "error": {
    "code": 1,
    "description": "Processing Error",
    "message": "Not enough money"
  },
  "success": false
}

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

Для регистрации заказа используется запрос /samsungWeb/payment.do. Этот запрос используется для оплаты через сайт, когда платежная форма находится на странице продавца.

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

Обязательность Название Тип Описание
Обязательно

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

onFailedPaymentBackUrl String URL-адрес, на который будет перенаправлен покупатель в случае ошибки или превышения срока ожидания.
Необязательно

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

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

Обязательность Название Тип Описание
Обязательно

successful String [1] Указывает, что операция была успешно обработана, доступны следующие значения:
  • 1 (успех);
  • 0 (ошибка).
Обязательно

transactionId String [1..512] Значение, которое необходимо передать в Samsung Pay, вызовом функции connect.
Обязательно

href String Значение, которое необходимо передать в Samsung Pay, вызовом функции connect.
Обязательно

mod String Значение, которое необходимо передать в Samsung Pay, вызовом функции connect.
Обязательно

exp String Значение, которое необходимо передать в Samsung Pay, вызовом функции connect.
Обязательно

keyId String Значение, которое необходимо передать в Samsung Pay, вызовом функции connect.
Обязательно

serviceId String Значение, которое необходимо передать в Samsung Pay, вызовом функции connect.
Обязательно

callbackUrl String Значение, которое необходимо передать в Samsung Pay, вызовом функции connect.
Обязательно

cancelUrl String Значение, которое необходимо передать в Samsung Pay, вызовом функции connect.
Обязательно

countryCode String Значение, которое необходимо передать в Samsung Pay, вызовом функции connect.
Обязательно

resultType String Значение, которое необходимо передать в Samsung Pay, вызовом функции connect.
Необязательно

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

Для передачи этого параметра у вас должны быть достаточные права в платежном шлюзе.

Samsung Pay Direct

Запрос, используемый для осуществления прямого платежа через Samsung Pay, - samsung/paymentDirect.do. Этот запрос можно использовать для интеграций, предполагающих расшифровку платежных данных на стороне продавца.

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

Обязательность Название Тип Описание
Обязательно

merchant String Логин продавца в системе платежного шлюза.
Обязательно

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

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

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

feeInput String Размер комиссии в минимальных единицах валюты. Функциональность должна быть включена на уровне продавца в шлюзе.
Необязательно

additionalParameters Object Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
Необязательно

preAuth Boolean Параметр, определяющий необходимость предварительной авторизации (блокирования средств на счете клиента до их списания). Доступны следующие значения:
  • true - включена двухстадийная оплата;
  • false - включена одностадийная оплата (деньги списываются сразу).
Если параметр отсутствует, производится одностадийная оплата.
Необязательно

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

paymentToken String [1..8192] Токен, полученный от Samsung Pay и закодированный в Base64. Example:
{"amount": "100", "currency_code": "USD", "utc": "1490687350988", "eci_indicator": "07", "tokenPAN": "5599014702854883", "tokenPanExpiration": "0420", "cryptogram": "ACF9prZs2wsTAAGysReaAoACFA=="}
Необязательно

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Необязательно

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

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

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

Для передачи этого параметра у вас должны быть достаточные права в платежном шлюзе.
Необязательно

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 означает, что запрос был обработан, а не что заказ был оплачен. Статус платежа отражается значением другого параметра — orderStatus.
Обязательно*

data Object Возвращается только в случае успешной оплаты.
Обязательно*

error Object Этот параметр возвращается только в случае ошибки платежа.

Блок data содержит следующие элементы.

Обязательность Название Тип Описание
Обязательно

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

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

Параметры в блоке error:

Обязательность Название Тип Описание
Обязательно

code Integer [1..3] Код как информационный параметр, сообщающий об ошибке.
Обязательно

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

description String [1..598] Подробное техническое объяснение ошибки - содержимое этого параметра не предназначено для отображения пользователю.

Примеры

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

curl --request POST \
--url https://abby.rbsuat.com/payment/samsung/paymentDirect.do \
--header 'Content-Type: application/json' \
--data-raw '{
"merchant": "OurBestMerchantLogin",
"orderNumber": "UAF-203974-DE",
"language": "EN",
"preAuth": true,
"description" : "Test description",
"additionalParameters":
{
"firstParamName": "firstParamValue",
"secondParamName": "secondParamValue"
},
"paymentToken": "ew0KICB7DQoJICA...0KICB9DQp9",
"ip" : "127.0.0.1"
}'

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

Пример ответа (успешный платеж)

{
  "success": true,
  "data": {
    "orderId": "12312312123"
  }
}

Пример ответа (ошибка платежа)

{
  "error": {
    "code": 1,
    "description": "Processing Error",
    "message": "Insufficint amount on card"
  },
  "success": false
}

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

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

  1. Сделать вызов getOrderStatusExtended.do;
  2. Проверить поле 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 Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.
Обязательно

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

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

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

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

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

Версия Обязательность Название Тип Описание
Все Необязательно

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, возвращаемое процессингом банка.
Все Необязательно

userMessage String [1..512] Сообщению пользователю с описанием кода результата.
Все Обязательно

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

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

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

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

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

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
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] Идентификатор терминала в системе, обрабатывающей платеж.

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

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

date String Дата регистрации заказа (Unix)
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. Возможные значения: "2.1.0", "2.2.0" для 3DS2.
Если в запросе не передается threeDSProtocolVersion, то для авторизации 3D Secure будет использоваться значение по умолчанию (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] Адрес доставки.

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

Версия Обязательность Название Тип Описание
22+ Необязательно

originalCurrencyAlphaCode String [3] Валюта (буквенный код) изначальной суммы.
22+ Необязательно

originalCurrencyNumericCode String Числовой код валюты ISO 4217 изначальной суммы.
22+ Необязательно

originalAmount String [1..12] Первоначальная сумма.
22+ Необязательно

formattedvalue String Первоначальная сумма для конвертации.
22+ Необязательно

value String Сумма в минимальных денежных единицах.
22+ Необязательно

convertedCurrencyAlphaCode String Валюта (буквенный код) конвертированной суммы.
22+ Необязательно

convertedCurrencyNumericCode String Числовой код валюты ISO 4217 конвертированной суммы.
22+ Необязательно

convertedAmount String Сумма конвертации.
22+ Необязательно

formattedvalue String Отформатированная сумма.
22+ Необязательно

conversionRate String Курс конвертации.
22+ Необязательно

feePercentage String Размер комиссии в процентах.
29+ Необязательно

directConversionRate String Курс прямой конвертации.
29+ Необязательно

additionalParams Object Набор дополнительных параметров для конвертации валюты, структура:
{имя1:значение1,…,имяN:значениеN}. Содержит следующие параметры.
  • diffOverECB - разница между предлагаемым курсом валюты и базовым курсом валюты ЕЦБ. Пример: "2.85".

Элемент 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 Объект, содержащий атрибуты адреса доставки. Описание вложенных элементов приведено ниже.

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

Обязательность Название Тип Описание
Необязательно

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

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

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

postAddress String [1..255] Адрес доставки.

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

Обязательность Название Тип Описание
Обязательно

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

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

Обязательность Название Тип Описание
Обязательно

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

measure String [1..20] Единица измерения количества по позиции.

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

Обязательность Название Тип Описание
Необязательно

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

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

Обязательность Название Тип Описание
Обязательно

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

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

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

Обязательность Название Тип Описание
Обязательно

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

interestValue Integer [1..20] Значение агентской комиссии.

Примеры

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

curl --request POST \
  --url https://abby.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": "933",
  "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. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.
Необязательно

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 Объект, содержащий атрибуты описания агентского вознаграждения за продажу товаров. Описание вложенных элементов приведено ниже.

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

Обязательность Название Тип Описание
Необязательно

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

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

Обязательность Название Тип Описание
Обязательно

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

measure String [1..20] Единица измерения количества по позиции.

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

Обязательность Название Тип Описание
Обязательно

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

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

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

Обязательность Название Тип Описание
Обязательно

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

interestValue Integer [1..20] Значение агентской комиссии.

Описание параметров в объекте 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 Объект, содержащий атрибуты описания агентского вознаграждения за продажу товаров. Описание вложенных элементов приведено ниже.

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

Обязательность Название Тип Описание
Необязательно

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

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

Примеры

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

curl --request POST \
  --url https://abby.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. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.
Необязательно

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

jsonParams String Поля для хранения дополнительных данных необходимо передавать следующим образом: {"param":"value","param2":"value2"}.
Необязательно

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://abby.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. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.
Необязательно

jsonParams String Поля для хранения дополнительных данных необходимо передавать следующим образом: {"param":"value","param2":"value2"}.
Необязательно

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

expectedDepositedAmount Integer [1..12] Параметр служит для определения того, что запрос является повторным. Если параметр передан, его значение сравнивается с текущим значением depositedAmount в заказе. Операция будет выполнена только в том случае, если значения совпадают. Если два возврата приходят с одинаковым expectedDepositedAmount, будет выполнен только один возврат. Этот возврат изменит значение depositedAmount, а затем второй возврат будет отклонен.
Необязательно

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

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

Описание параметров в объекте 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 Объект, содержащий атрибуты описания агентского вознаграждения за продажу товаров. Описание вложенных элементов приведено ниже.

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

Обязательность Название Тип Описание
Необязательно

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

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

Примеры

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

curl --request POST \
  --url https://abby.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. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.
Обязательно

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

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

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

Обязательность Название Тип Описание
Обязательно

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

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

userMessage String [1..512] Сообщению пользователю с описанием кода результата.

Примеры

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

curl --request POST \
  --url https://abby.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. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.
Необязательно

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Необязательно

cvc Integer Этот параметр обязателен, если для мерчанта не выбрано разрешение Может проводить оплату без подтверждения CVC.
Необязательно

email String Электронная почта для выставления счетов владельца карты
Необязательно

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

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

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

threeDSProtocolVersion String Версия протокола 3DS. Возможные значения: "2.1.0", "2.2.0" для 3DS2.
Если в запросе не передается threeDSProtocolVersion, то для авторизации 3D Secure будет использоваться значение по умолчанию (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 см. здесь.

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

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

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

Обязательность Название Тип Описание
Обязательно

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.

Примеры

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

curl --request POST \
  --url https://abby.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://abby.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://abby.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. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.
Обязательно

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://abby.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://abby.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://abby.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://abby.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. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.

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

Обязательность Название Тип Описание
Необязательно

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

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

Примеры

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

curl --request POST \
  --url https://abby.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",
}

Рекуррентный платеж

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

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

Обязательность Название Тип Описание
Обязательно

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

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

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

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

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 означает, что запрос был обработан, а не что заказ был оплачен. Статус платежа отражается значением другого параметра — orderStatus.
Условие 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://abby.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" : "933",
  "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": "933",
        "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
}

Платеж по рассрочке

Для проведения платежа по рассрочке используется запрос 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. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.
Обязательно

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

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

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

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

additionalParameters Object Дополнительные параметры заказа, которые хранятся в личном кабинете продавца для последующего просмотра. Каждая новая пара имени параметра и его значения должна быть разделена запятой. Ниже приведен пример использования.
{ "firstParamName": "firstParamValue", "secondParamName": "secondParamValue"}
Обязательно

email String Электронная почта для выставления счетов владельца карты
Обязательно

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

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 символов).
Необязательно

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://abby.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": "933",
  "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": "933",
    "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
}

3DS

Завершение платежа 3DS2 через API

Для завершения заказа 3DS2 через API используется метод finish3dsVer2Payment.do.

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

Обязательность Название Тип Описание
Обязательно

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

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

threeDSServerTransId String Идентификатор транзакции, созданный на сервере 3DS.
Условие

threeDSVer2MdOrder String Номер заказа, который был зарегистрирован в первой части запроса в рамках 3DS 2.0 операции.
Если данный параметр присутствует в запросе, то используется mdOrder, который передается в настоящем параметре. В таком случае регистрация заказа не происходит, а происходит сразу оплата заказа. Для транзакций Google Pay этот параметр является обязательным.
Необязательно

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

threeDSSDK String Возможные значения: 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://abby.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://abby.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] Маскированный номер карты, которая использовалась для оплаты. Этот параметр указывается только после оплаты заказа. При оплате через Apple Pay в качестве номера карты используется DPAN - это номер, привязанный к мобильному устройству клиента, который функционирует как номер платежной карты в системе Apple Pay.
Необязательно

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
Необязательно

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

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

email String Электронная почта для выставления счетов владельца карты
Необязательно

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

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

threeDSServerTransId String Идентификатор транзакции, созданный на сервере 3DS.
Необязательно

threeDSVer2FinishUrl String URL-адрес, по которому клиент должен быть перенаправлен после аутентификации на сервере ACS.
Условие

threeDSVer2MdOrder String Номер заказа, который был зарегистрирован в первой части запроса в рамках 3DS 2.0 операции.
Если данный параметр присутствует в запросе, то используется mdOrder, который передается в настоящем параметре. В таком случае регистрация заказа не происходит, а происходит сразу оплата заказа. Для транзакций Google Pay этот параметр является обязательным.
Необязательно

threeDSSDK String Возможные значения: 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.
Необязательно

userMessage String [1..512] Сообщению пользователю с описанием кода результата.

Примеры

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

curl --request POST \
  --url https://abby.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": "933"
}

Уведомления обратного вызова

API платежного шлюза позволяет получать callback-уведомления об изменении статусов платежей.

Общая информация

События, о которых могут приходить уведомления

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

Наиболее распространенные уведомления описывают изменения статуса заказа, например:

Более сложные интеграции могут подразумевать дополнительные триггеры обратного вызова, такие как:

Тип триггера передается в параметре operation уведомления обратного вызова (см. подробности ниже). Для удобства уведомления для дополнительных триггеров могут быть направлены на другой URL-адрес с помощью параметра dynamicCallbackUrl в запросах на регистрацию заказа.

Интеграция через уведомления обратного вызова (callback)

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

Использовать returnUrl

Когда код вашего сайта, расположенный по адресу returnUrl (например, https://mybestmerchantreturnurl.com/?back&amp;orderId=61c33664-85a0-7d6b-af26-09ee009c4000&amp;lang=en), идентифицирует перенаправляемого из шлюза держателя карты посде попытки оплаты, вы можете проверить статус заказа с помощью API-запроса getOrderStatusExtended.
Этот вариант является самым простым, но он не совсем надежен, поскольку перенаправление держателя карты может завершиться ошибкой (например, в результате обрыва соединения или закрытия браузера держателем карты), а returnUrl может не получить триггер для вызова getOrderStatusExtended.

getOrderStatusExtended.do

curl --request POST \
  --url https://abby.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": "933",
  "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.
Поддерживаемые центры сертификации. Ниже приведены примеры организаций, которые регистрируют цифровые сертификаты:

Формат 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

Алгоритм обработки уведомлений о состоянии заказов

В разделах ниже представлен алгоритм обработки уведомлений о состоянии заказов в зависимости от типа таких уведомлений.

Уведомление без контрольной суммы

  1. Платежный шлюз отправляет на сервер продавца следующий запрос.
    https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&amp;orderNumber=0987&amp;operation=deposited&amp;status=0
  2. Сервер продавца возвращает HTTP-сообщение 200 OK платежному шлюзу.

Уведомление с контрольной суммой

  1. Платежный шлюз отправляет HTTPS-запрос следующего вида на сервер мерчанта, при этом:

    • при использовании симметричной криптографии контрольная сумма формируется с помощью ключа, общего для платежного шлюза и продавца;
    • при использовании асимметричной криптографии контрольная сумма формируется с помощью закрытого ключа, известного только платежному шлюзу.
      https://mybestmerchantreturnurl.com/path?amount=123456&amp;orderNumber=10747&amp;checksum=DBBE9E54D42072D8CAF32C7F660DEB82086A25C14FD813888E231A99E1220AB3&amp;mdOrder=3ff6962a-7dcc-4283-ab50-a6d7dd3386fe&amp;operation=deposited&amp;status=1
      Порядок параметров в уведомлении может быть произвольным.

  2. На стороне мерчанта из строки параметров уведомления удаляется параметр checksum, а значение этого параметра (контрольная сумма) сохраняется для проверки подлинности уведомления.

  3. Оставшиеся параметры и их значения используются для создания следующей строки.
    имя_параметра1;значение_параметра1;имя_параметра2;значение_параметра2;…;имя_параметраN;значение_параметраN;
    В этом случае пары имя_параметра;значение_параметра должны быть отсортированы в прямом алфавитном порядке (по возрастанию) по именам параметров.
    Пример сгенерированной строки параметров:
    amount;123456;mdOrder;3ff6962a-7dcc-4283-ab50-a6d7dd3386fe;operation;deposited;orderNumber;10747;status;1;

  4. Контрольная сумма рассчитывается на стороне мерчанта, способ расчета зависит от способа ее формирования:

    • при использовании симметричной криптографии - с помощью алгоритма HMAC-SHA256 и общего с платежным шлюзом закрытого ключа;
    • при использовании асимметричной криптографии - с помощью алгоритма хеширования, который зависит от способа создания ключевой пары, и открытого ключа, который связан с закрытым ключом, находящимся на стороне платежного шлюза.

  5. В получившейся строке контрольной суммы все буквы нижнего регистра заменяются на буквы верхнего регистра.

  6. Происходит сравнение полученного значения с контрольной суммой, извлеченной ранее из параметра checksum.

  7. Если контрольные суммы совпадают, сервер отправляет в платежный шлюз HTTP-код 200 OK.

Если контрольные суммы совпадают, это уведомление подлинно и было отправлено платежным шлюзом. В противном случае вероятно, что злоумышленник пытается выдать свое уведомление за уведомление платежного шлюза.

Уведомление о статусе платежа

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

  1. Проверить подпись (параметр checksum в уведомлении);
  2. Проверять два параметра уведомления обратного вызова: operation и status.

Если значение параметра operation отличается от approved или deposited, то уведомление обратного вызова относится к статусу оплаты.

Неуспешные уведомления

Если в платежный шлюз возвращается ответ, отличный от HTTP-кода 200 OK, отправка уведомления считается неуспешной. В этом случае платежный шлюз повторяет уведомление с интервалом в 30 секунд до тех пор, пока не будет выполнено одно из следующих условий:

При достижении одного из указанных выше условий попытки отправки 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
avsCode Код ответа верификации AVS (проверка адреса и почтового индекса держателя карты). Возможные значения:
  • -1 – почтовый индекс и адрес совпадают.
  • 1 – адрес совпадает, почтовый индекс не совпадает.
  • 2 - почтовый индекс совпадает, адрес не совпадает.
  • 3 - почтовый индекс и адрес не совпадают.
  • 50 - запрошена проверка данных, но результат неуспешен.
  • 51 - некорректный формат запроса AVS/AVV проверки.
 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";
?>
  1. Присвойте строковое значение переменной data.
  2. Присвойте значение закрытого ключа переменной key.
  3. Функция hash_hmac ( 'sha256', $data, $key) вычисляет контрольную сумму от переданной строки, с помощью закрытого ключа по алгоритму SHA-256.
  4. Сохраните результат работы функции в переменной hmac.
  5. Выведите результат работы функции командой echo.
  6. Сравните это значение с тем, что передано в уведомлении о состоянии заказа.

Асимметричная криптография

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";
}
?>
Категории:
eCommerce API V1
Категории
Результаты поиска
Навигация
Перейти
Закрыть
Категории
Результаты поиска