Overview

You can use our Merchant API to create a payment flow you need. For example, you can design your own fully customized payment page and connect it to our Payment Gateway.

You can download Postman collection of some basic API methods below. Make sure to send requests as POST with attributes in the body.

Mandatory parameters

The mandatory presence of a parameter in a request/response may have the following values:

• Mandatory - the parameter must always be included. If it is not provided, an empty value should be passed, depending on the expected format;
• Optional - the parameter may be included or excluded, and its excessive inclusion will not cause a system error;
• Conditional - the parameter can either be included (be mandatory) or excluded, depending on one or more specified conditions.

The mandatory transmission of a parameter in the request/response description is indicated in the "Required" column.

Authentication

For merchant authentication in the payment gateway two methods can be used.

• Using login and password of the merchant's API user (account with -api postfix) received on registration. These values are passed in userName and password parameters correspondingly (see the table below).

• Using a special token - you can request its value in the technical support service. In requests its value is passed in token parameter (see the table below).

API URLs

TEST: https://mts.rbsuat.com/payment/rest/
PROD: https://oplata.mtsbank.ru/payment/rest/

Errors

HTTP status codes:

• 200 - in case of the Payment Gateway API calls the JSON payload from the response must be inspected to determine whether processing was successful or not. Success is indicated by either:
  - the success parameter value being true
  
  - the errorCode parameter value being 0
  
  If both parameters are present, success overrides errorCode.

• 400 - an internal error occurred in the system.

• 404 - error while calling API - URL is incorrect (does not exist).

• 429 - this code means that the system is overloaded. Most often the main reason is that the limit of requests per second or limit of simultaneous requests is reached. But it may also be due to the fact that the system as a whole is overloaded (regardless of your requests).

• 500 or 502 - this code means that something went wrong on our side.

If the request, associated with an order payment, is processed successfully, it does not directly mean that the payment itself was successful.

To determine whether the payment was successful or not, you may refer to the description of the request used, where the intepretation of the payment success is thoroughly described, or you may follow the rule of thumb here:

1. Call getOrderStatusExtended.do;
2. Check the orderStatus field in the response: the order is considered to be payed only if the orderStatus value is 1 or 2.

API request signature

Facing insecure integration, you may be requested to implement an asymmetric request signature. Usually, this requirement is applied only if you carry out P2P/AFT/OCT requests.

To have a possibility to sign requests, you need to perform the following steps:

1. Generate and upload a certificate.
2. Calculate a hash and a signature using your private key and pass the generated hash (X-Hash) and the signature value (X-Signature) in the request header.

These steps are described below in details.

Generating and uploading a certificate

1. Generate 2048-bit RSA private key. The way of generation depends on privacy policy in your company. For example, you can do it using OpenSSL:

   openssl genrsa -des3 -out private.key 2048

2. Generate public CSR (Certificate Signing Request) using the generated private key:

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

3. Generate a certificate using the generated private key and CSR. The example of generating a certificate for 5 years:

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

4. Upload the generated certificate in the Personal Area. To do this, go to Wallet certificates > Merchant API, click Add a certificate and upload the generated public certificate.

   
   

Calculating a hash and a signature

1. Calculate SHA256 hash of the request body as follows:

   1. Use request body as a string (in our example it is amount=10000&password=gcjgcW1&returnUrl=http&userName=signature-api).
   2. Calculate SHA256 hash from this string, in raw bytes.
   3. Convert the raw bytes into base64 encoding.

2. Generate a signature for the calculated SHA256 hash with RSA algorythm using the private key.

   In our example we use the following private key with the password 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-----

   and get the signature: pJ/gM4PR1/mKGuIxMvTl5pYDDjJslb0BcXFnIxijFn5qKdPd7W+2ueoctziU7omnkYp01/BlracukH1GOPWMSO+9zKuTDdFueFm1utsS0zaPFU+dmc1niGDRWE0CbCXcti/rGSTDPsnR58mwqgVkbCWxKyCDtuo5LxiKPK9mzgWTUuJ8LX6f6u42MURi5tRG6a9dc8l/+J94g0YOk911R6Lqv2jcluEvZ9ZeMMt8hyxowb0eDaCHlussu2CAyqpE9V+EUAc81Jkwv96MMSsA6UnFwEaCV/k+kwYd0jHCx94m2yWX734p9cWsBW7Fr5F0zox9Yck4GOjqe9nJMMB9jQ==

3. Now you should pass the generated hash (X-Hash) and the signature value (X-Signature) in the request header. The request will look like this:

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

The request should meet the following requirements:

• All the request parameters are included into the request body (not into the URL).

• If the request parameters are in JSON format, then the following header should be used:

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

• If the request parameters are in Query format (like parameterA=valueA&parameterB=valueB), then the following header should be used:

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

• The request contains correct login and password of the API user.

• The X-Hash header contains SHA256 hash of the request body (calculated at step 1).

• The X-Signature header contains the signature for the calculated SHA256 hash with RSA algorythm using the private key (generated at step 2).

Java code example

Below is the Java code example that loads a private key, calculates SHA256 hash, signs it using the private key with the password 12345, and then sends a correct register.do request:

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 code example

Below is the Python code example that generates the signature:

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)

The private key file for the Python example should have the format:

Order registration

Order registration

To register an order, use https://mts.rbsuat.com/payment/rest/register.do request.

When sending the request, you should use the header: Content-Type: application/x-www-form-urlencoded

Request parameters

A block with the client's registration data (address, postal code).

Description of parameters in shippingPayerData object:

Description of parameters in preOrderPayerData object:

Description of parameters in orderPayerData object:

Description of parameters in orderBundle object:

Below are the parameters of the agent block (agent data).

Description of parameters in customerDetails object:

Checking the customer's data when passing the shopping cart

According to FTS (Federal Tax Service) requirements, in case of passing the customer's full name, it is necessary to pass either the customer's INN, OR their passport data.

With that, if the request with a shopping cart contains either of the following parameters (in orderBundle or additionalOfdParams blocks):

• Full name – customerDetails.fullname or client.name
• INN – customerDetails.inn or client.inn
• Document data – customerDetails.passport or client.passport_number
• Document code – client.document_code
• Birth date – client.birth_date
• Citizenship – client.citizenship

the request is checked for passing either INN of the customer OR the following set of parameters: Birth date, Document code, Document data. If this condition is not met, the request results in an error.

Description of parameters in deliveryInfo object.

Description of parameters in cartItems object.

Description of parameters in items object.

Description of parameters in quantity object.

Possible values of measure parameter:

Description of parameters in itemDetails object.

Description of parameters in itemDetailsParams object.

Description of parameters in tax object:

Description of parameters in itemAttributes object:

itemAttributes parameter must include attributes array, where the item attributes should be located (see the example and table below).

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

Description of parameters in markQuantity object.

Description of parameters in additionalOfdParams object:

Response parameters

Examples

Request example

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

Response example - success

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

Response example - fail

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

Order pre-authorization

The method used for registration of an order with preauthorization is https://mts.rbsuat.com/payment/rest/registerPreAuth.do.

When sending the request, you should use the header: Content-Type: application/x-www-form-urlencoded

Request parameters

A block with the client's registration data (address, postal code).

Description of parameters in shippingPayerData object:

Description of parameters in preOrderPayerData object:

Description of parameters in orderPayerData object:

Description of parameters in orderBundle object:

Description of parameters in customerDetails object:

Checking the customer's data when passing the shopping cart

According to FTS (Federal Tax Service) requirements, in case of passing the customer's full name, it is necessary to pass either the customer's INN, OR their passport data.

With that, if the request with a shopping cart contains either of the following parameters (in orderBundle or additionalOfdParams blocks):

• Full name – customerDetails.fullname or client.name
• INN – customerDetails.inn or client.inn
• Document data – customerDetails.passport or client.passport_number
• Document code – client.document_code
• Birth date – client.birth_date
• Citizenship – client.citizenship

the request is checked for passing either INN of the customer OR the following set of parameters: Birth date, Document code, Document data. If this condition is not met, the request results in an error.

Description of parameters in deliveryInfo object.

Description of parameters in cartItems object.

Description of parameters in items object.

Description of parameters in quantity object.

Description of parameters in itemDetails object.

Description of parameters in itemDetailsParams object.

Description of parameters in tax object:

Description of parameters in itemAttributes object:

itemAttributes parameter must include attributes array, where the item attributes should be located (see the example and table below).

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

Possible values of measure parameter:

Description of parameters in markQuantity object.

Description of parameters in additionalOfdParams object:

Response parameters

Examples

Request example

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

Response example

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

Direct payments

Payment for order

To initiate payment on earlier registered order https://mts.rbsuat.com/payment/rest/paymentorder.do request is used.
Request is used in Internal 3DS Server mode, you don't need any additional permissions and/or certifications.
Request is used in External 3DS Server mode if you have agreement with Payment System or special Certificate, which alows you to perform 3DS authentacation on your own. It means, that you can use your own 3DS Server to authenticate your client using 3D Secure technology. Read more about payment with your own 3DS Server here.

When sending the request, you should use the header: Content-Type: application/x-www-form-urlencoded

Payment for order (internal 3DS Server)

Payment is initiated using payment card data and using 3DS authentication (authentication is regulated by permissions, managed by Support).

Request parameters

A block with the client's registration data (address, postal code).

Description of parameters in shippingPayerData object:

Description of parameters in preOrderPayerData object:

Description of parameters in orderPayerData object:

Possible values of tii (read about the stored credential types supported by the Payment Gateway here):

Below are the parameters of the clientBrowserInfo block (data about the client's browser).

Example of clientBrowserInfo block:

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

The following parameters are also passed during the authentication via the 3DS2 protocol:

Response parameters

When authenticating via the 3DS2 protocol, the following parameters are returned during the initial request:

Below are the parameters to be present in the response, after a repeated request for the payment and the need to redirect the client to the ACS during the authentication via the 3DS2 protocol:

Examples

Request example

Example of the first request:

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

Example of the second request:

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

Example of a request with a cryptogram (seToken):

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

Response examples

Example of the response to the first request:

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

Example of the response to the second request:

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

Payment for order (external 3DS Server)

In order to use paymenOrder.do request in external 3DS Server mode, you need to perform 3DS authentication using your own 3DS Server.
Also, you need an additional permission managed by Support.

Request parameters

A block with the client's registration data (address, postal code).

Description of parameters in shippingPayerData object:

Description of parameters in preOrderPayerData object:

Description of parameters in orderPayerData object:

Possible values of tii (read about the stored credential types supported by the Payment Gateway here):

Below are the parameters of the clientBrowserInfo block (data about the client's browser).

Example of clientBrowserInfo block:

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

Response parameters

Examples

Request example

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

Response example

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

Redirect to ACS (simplified)

If 3-D Secure is required, then, after receiving payment response, the customer must be redirected to ACS. In this case, the payment response contains the acsUrl parameter that will be used for the redirect.

The https://mts.rbsuat.com/payment/acsRedirect.do?orderId={orderId} request allows to redirect a customer to the ACS authentication page in a simplified way - just using orderId parameter received after an order registration.

It is also possible to redirect a customer to ACS with a POST request (regular redirect). The description of this method can be found here.

Without other actions required from customer, the payment gateway redirects them to the ACS page, where customer authenticates.

Then, depending on the authentication result, the customer is redirected to the following URL:

• if authentication succeeds - returnUrl with appended orderId parameter;
• if authentication fails - failUrl (or returnUrl if failUrl was not passed) with appended orderID parameter.

To redirect a customer to the ACS, use the following URL:

https://mts.rbsuat.com/payment/acsRedirect.do?orderId={Order number in the payment gateway}

Request parameters

Response parameters

Example

Request example

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

Redirect URL example

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

Payment status

The most straightforward way to know the status of the payment is to use a dedicated API call:

1. Call getOrderStatusExtended.do;
2. Check the orderStatus field in the response: the order is considered to be payed only if the orderStatus value is 1 or 2.

Another way to check whether the payment was successful or not is to refer to the callback notification.

Order status

The request used to get the order status is https://mts.rbsuat.com/payment/rest/getOrderStatusExtended.do.

When sending the request, you should use the header: Content-type: application/x-www-form-urlencoded

Learn more about Refusal reasons.

Request parameters

Response parameters

There are several sets of the response parameters. Which set of parameters is returned in the response, depends on the version of getOrderStatusExtended specified in the merchant's settings in the payment gateway.

Description of the versions

Values of paymentWay:

• CARD – Payment with entering card data
• CARD_BINDING – Stored-credential payment
• FILE_BINDING – Payment via file
• P2P – Card-to-card transfer
• P2P_BINDING – Card-to-card transfer via stored credential
• APPLE_PAY – Apple Pay payment
• APPLE_PAY_BINDING – Payment via Apple pay stored credential
• GOOGLE_PAY_CARD – Payment by a non-tokenized Google Pay card
• GOOGLE_PAY_CARD_BINDING – Stored-credential payment with a non-tokenized Google Pay card
• GOOGLE_PAY_TOKENIZED – Payment by a tokenized Google Pay card
• GOOGLE_PAY_TOKENIZED_BINDING – Stored-credential payment with a tokenized Google Pay card
• SAMSUNG_PAY – Samsung Pay payment
• SAMSUNG_PAY_BINDING – Payment via Samsung Pay stored credential
• SBP_C2B – SBP payment (Faster Payment System) for C2B
• SBP_C2B_BINDING – Payment via SBP (Faster Payment System) stored credential for C2B
• SBP_B2C – SBP payment (Faster Payment System) for B2C
• TOKEN_PAY – Payment by token directly
• TOKEN_PAY_BINDING – Payment via tokenized stored credential
• YANDEX_PAY_CARD – Payment by a non-tokenized Yandex Pay card
• YANDEX_PAY_TOKENIZED – Payment by a tokenized Yandex Pay card
• YANDEX_PAY_CARD_BINDING – Stored-credential payment with a non-tokenized Yandex Pay card
• YANDEX_PAY_TOKENIZED_BINDING – Stored-credential payment with a tokenized Yandex Pay card
• MTS_PAY – MTS Pay
• MTS_PAY_TOKEN – MTS Pay payment token
• MIR_PAY – Mir payment using a tokenized cryptogram
• MIR_PAY_BINDING – Mir payment via stored credential

Description of objects in the ofdOrderBundle array:

The itemAttributes array consists of the objects:

• paymentMethod - Payment type. Is mandatory if passed on registration. Possible values:

  • 1 - full prepayment;
  • 2 - partial prepayment;
  • 3 - advance payment;
  • 4 - full payment;
  • 5 - partial payment with further installment payments;
  • 6 - no payment with further installment payments;
  • 7 - payment with further installment payments.

  The value passing is prioritized according to the following principle (listed in descending order of priority):
  

  1. Order bundle of API request.
     
  2. Fiscalization settings in Personal Area.
     
  3. Default values.

  For paymentMethod, the default value is 1 (full prepayment).

• paymentObject - Payment object. Is mandatory if passed on registration. Possible values:

  • 1 - product (default value);
  • 2 - excisable product;
  • 3 - job;
  • 4 - service;
  • 5 - gambling stake;
  • 6 - gain at gambling;
  • 7 - lottery ticket;
  • 8 - gain in lottery;
  • 9 - provision of intellectual property;
  • 10 - payment;
  • 11 - agent fee;
  • 12 - complex payment object;
  • 13 - other payment object;
  • 14 - property rights;
  • 15* - non-operating gain;
  • 16* - insurance premiums;
  • 17 - sales tax;
  • 18 - resort tax.

  The value passing is prioritized according to the following principle (listed in descending order of priority):
  

  1. Order bundle of API request.
     
  2. Fiscalization settings in Personal Area.
     
  3. Default values.

  For paymentObject, the default value is 1 (product).

Description of parameters in quantity object.

Possible values of name parameters:

• When passing paymentObject=15 the name must have a value from 1 to 25.

• When passing paymentObject=16 the name must have a value from 26 до 31.

Possible values of tii (read about the stored credential types supported by the Payment Gateway here):

The refunds block contains the following parameters:

attributes block contains information on the order number in the payment gateway. name parameter contains the word mdOrder, and value parameter contains the actual order number in the payment gateway.

transactionAttributes block contains the set of additional attributes of the transaction. Used for version 14 and later. Below is the list of the included parameters.

merchantOrderParams block is passed in the response, if the order contains merchant additional parameters. Each additional parameter is passed in a separate merchantOrderParams element.

Some predefined attributes in merchantOrderParams:

• originalResponseCode - original response code, received from NSPK. Is present if was passed by NSPK in response to order payment, registration, or completion request.

cardAuthInfo element contains a structure consisting of secureAuthInfo element list and the following parameters.

secureAuthInfo element consists of the following elements (cavv and xid parameters are included into the threeDSInfo element).

bindingInfo element contains the following parameters.

paymentAmountInfo element contains the following parameters.

bankInfo element contains the following parameters.

payerData element contains the following parameters.

The efectyOrderInfo block contains the following parameters.

pluginInfo element (which is JSON object) is present in response if payment was made through payment plugin. Contains the following parameters.

Description of parameters in orderBundle object:

Description of parameters in the loyalties object:

Description of parameters in customerDetails object:

Checking the customer's data when passing the shopping cart

According to FTS (Federal Tax Service) requirements, in case of passing the customer's full name, it is necessary to pass either the customer's INN, OR their passport data.

With that, if the request with a shopping cart contains either of the following parameters (in orderBundle or additionalOfdParams blocks):

• Full name – customerDetails.fullname or client.name
• INN – customerDetails.inn or client.inn
• Document data – customerDetails.passport or client.passport_number
• Document code – client.document_code
• Birth date – client.birth_date
• Citizenship – client.citizenship

the request is checked for passing either INN of the customer OR the following set of parameters: Birth date, Document code, Document data. If this condition is not met, the request results in an error.

Description of parameters in deliveryInfo object.

Description of parameters in cartItems object.

Description of parameters in items object.

Description of parameters in quantity object.

Description of parameters in itemDetails object.

Description of parameters in tax object:

Description of parameters in itemAttributes object:

itemAttributes parameter must include attributes array, where the item attributes should be located (see the example and table below).

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

Description of parameters in agent_info object:

Description of parameters in paying object:

Description of parameters in paymentsOperator object:

Description of parameters in MTOperator object:

Description of parameters in supplier_info object:

Examples

Request example

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

Response example

{
  "errorCode": "0",
  "errorMessage": "Success",
  "orderNumber": "7005",
  "orderStatus": 2,
  "actionCode": 0,
  "actionCodeDescription": "",
  "amount": 2000,
  "currency": "643",
  "date": 1617972915659,
  "orderDescription": "",
  "merchantOrderParams": [],
  "transactionAttributes": [],
  "attributes": [
    {
      "name": "mdOrder",
      "value": "01491d0b-c848-7dd6-a20d-e96900a7d8c0"
    }
  ],
  "cardAuthInfo": {
    "maskedPan": "411111**1111",
    "expiration": "203412",
    "cardholderName": "TEST CARDHOLDER",
    "approvalCode": "12345678",	
    "pan": "411111**1111"
  },
  "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": "Unknown"
  }
}

Order management

Deposit order

To complete a pre-authorized order use https://mts.rbsuat.com/payment/rest/deposit.do request.

When sending the request, you should use the header: content-type: application/x-www-form-urlencoded

Request parameters

Description of parameters in deposititems object.

Description of parameters in items object.

Description of parameters in itemDetails object.

Description of parameters in itemDetailsParams object.

Description of parameters in quantity object.

Description of parameters in tax object:

Description of parameters in itemAttributes object:

itemAttributes parameter must include attributes array, where the item attributes should be located (see the example and table below).

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

Description of parameters in agent_info object:

Description of parameters in paying object:

Description of parameters in paymentsOperator object:

Description of parameters in MTOperator object:

Description of parameters in supplier_info object: