Introduction

Internet acquiring is a modern way of selling services or goods through the public Internet using bank cards.

Regarding the peculiarities of making purchases on the Internet, we need to ensure the safe interaction of the parties involved in the sale of goods/services - a client, a store and an acquiring bank.

An online store planning to sell services or goods on the Internet using bank cards must follow the formal procedures to ensure the security of payments:

• Interaction with the client at the time of the transfer of key data (personal data, data on the details of payment cards) should be carried out using cryptographic tools (SSL/TLS).
• Information on the payment made (amount, currency, description of the order), as well as the result of the payment, must be well protected from intruders.
• At the time of payment, the procedures for checking the card should be done.

• To fulfill these requirements, the acquiring bank uses a specialized technology for ensuring the safety of payments on the Internet, developed by the International Payment Systems Visa International and MasterCard - 3D Secure (Verified by Visa and MasterCard SecureCode).

• As a technology platform, the Payment Gateway is used, which allows the online store to perform the necessary security procedures without significantly restructuring the online store site and existing business processes.

Mobile SDK

To integrate mobile devices with the Payment Gateway you can use our Mobile SDK to embed card data entry forms into your mobile app.

Mobile SDK is part of Payment Gateway API ecosystem and allows to accept online payments from mobile devices. Mobile SDK makes it possible to embed our payment form into your iOS or Android app. Mobile SDK is responsible for the security of the payment data entry process. This article will help you to receive your first payment — and all payment methods you will configure will be available to your customers.

Implementation example:

1. A user selects a payment method in your mobile app, enters the required data, and proceeds to payment;
2. The mobile app encrypts the payment data creating a seToken (self encrypted Token);
3. The mobile app passes the seToken to the Payment Gateway for authorization.

iOS

Payment methods supported by the SDK:

• Requirements: iOS 10.0 or newer

More about iOS SDK

Android

Payment methods supported by the SDK:

• Requirements: Android 5.0 or newer

More about Android SDK

Checklist

To accept payments via your mobile app you must do the following:

1. Register your online store in the Bank;
2. Receive test credentials to access merchant console;
3. Receive test credentials for calling API methods;
4. Integrate with the Payment Gateway in test mode;
5. When test integration is configured, contact bank support to check readiness;
6. Receive production credentials to access merchant console;
7. Receive production credentials for calling API methods;
8. Agree with the Bank on switching your system to the production mode;
9. Sign a agreement with a bank representative that your online store is ready to work in production mode;
10. Begin working in production mode.

SDK payment process

The diagram below shows the SDK payment process

Step 1. Client registers an order in Mobile App and gets an mdOrder (rest/register.do). If bindings are to be used, clientId must be passed.

Step 2. Mobile App initiates the mobile SDK by passing mdOrder to it.

Step 3. Mobile SDK uses the getSessionStatus.do method to get all the necessary information about the order.

Step 4. Mobile SDK renders a card data entry form (possibly with bindings and Apple Pay).

Step 5. Client chooses the required payment method: card, binding, tokenized payment.

Step 6. SDK sends payment request. * a. SDK calls the Payment Gateway method for card payment (processform.do). If the checkbox for saving the card is ticked, then bindingNotNeeded=false should be passed, and if it is not ticked – bindingNotNeeded=true (note that the value false must be passed instead of ignoring the parameter). * b. SDK calls the Payment Gateway method for payment by binding (processBindingForm.do). Note that the order number is passed not in mdOrder, but in orderId. * c. SDK calls the Payment Gateway method for payment by token (/applepay/payment.do OR /google/payment.do).

Step 7. Payment data are received in response. Step 7a.If the payment is finished, go to status check (Step 21). Step 7b. If 3DS2 is required, then go to the next step.

Step 8. SDK initiates the 3DS2 SDK.

Step 9. SDK receives encrypted data about device.

Step 10. SDK calls the Payment Gateway again, but this time additionally passes the encrypted data.

Step 11a. In case of Frictionless, the process may end with a successful or unsuccessful payment and goes to Step 21. Step 11b. In case of Challenge Flow, the SDK receives all the necessary data to be passed to 3DS2 SDK for ACS.

Step 12. SDK calls 3DS2 SDK for confirmation form.

Step 13. 3DS2 SDK interacts with ACS to get the initial form.

Step 14. Client submits the verification code.

Step 15. 3DS2 SDK sends the verification code to ACS.

Step 16. ACS responds with success/failure of the operation.

Step 17. 3DS2 SDK calls SDK with notification.

Step 18. SDK calls the finish3dsVer2PaymentAnonymous.do method of Payment Gateway. See method description here.

Step 19. Payment Gateway credits the funds.

Step 20. SDK receives response from Payment Gateway.

Step 21. SDK checks order status. If the status does NOT contain the redirect field AND remainingSecs > 0, then another payment attempt can be made.

Step 22. SDK collects the final order data (whether the operation is successful, operation attributes) to be transferred in the callback.

Step 23. SDK notifies Mobile App that payment is finished.

Processing operations

All payments in the Payment Gateway are processed as special entities - Orders. To complete an operation one has to register an Order and the pass authorization data.

Step 1. Customer initiates payment on their own device in a mobile app;

Step 2. Mobile app sends registration request to the Backend of the store Mobile App;

Step 3. Backend of the store Mobile App sends order registration request to the Payment Gateway;

Step 4. Payment Gateway registers the order and creates a unique identifier;

Step 5. Payment Gateway returns to Backend of the store Mobile App the unique order identifier as a response to request received on Step 3;

Step 6. Backend of the store Mobile App passes the identifier to the Mobile App;

Step 7. The Mobile App displays payment data entry form;

Step 8. The customer enters payment data;

Step 9. The Mobile App creates an encrypted message;

Step 10. The Mobile App sends the encrypted message to the Backend of the store Mobile App;

Step 11. Backend of the store Mobile App sends the encrypted message to the Payment Gateway as part of the payment operation request;

Step 12. The Payment Gateway decrypts the encrypted message and initiates standard checks;

Step 13. The Payment Gateway sends response to the request received on Step 11;

Step 14. Backend of the store Mobile App passes to the Mobile App redirect to the ACS of the issuing bank;

Step 15. The Mobile App requests the authentication page from the ACS of the issuing bank;

Step 16. The ACS of the issuing bank passes to the customer an authentication page;

Step 17. The customer submits authentication data;

Step 18. ACS of the issuing bank authenticates the cardholder;

Step 19. ACS of the issuing bank passes to the Mobile App redirect to the Payment Gateway, together with PARes;

Step 20. If the authentication was successful the Payment Gateway authorizes the order;

Step 21. The Payment Gateway passes to the Mobile App redirect to the finish URL of the online store received in Step 2;

Step 22. The Mobile App requests the Backend of the store Mobile App the information about the order;

Step 23. Backend of the store Mobile App requests the Payment Gateway for the information about the order;

Step 24. The Payment Gateway passes to the Backend of the store Mobile App the information about the order;

Step 25. The Backend of the store Mobile App passes the information about the order to the Mobile App;

Step 26. The Mobile App displays the results of the operation.

Step 1. Order registration

To register an Order register.do request must be sent using server-server interaction:

Request parameters

Response parameters

Request examples

Bash

curl -X POST "__API_PREFIX__/rest/register.do?
userName=username&
password=password&
orderNumber=1&
amount=12345&
currency=978&
returnUrl=https%3A%2F%2Fwww.merchant.com&
description=description&
language=en&
clientId=1&
jsonParams=%7B%22name%22%3A%20%22value%22%7D&
features=VERIFY"

Node.js

const request = require("request")

request.post({
  url: "__API_PREFIX__/rest/register.do",
  form: {
    userName: "username",
    password: "password",
    orderNumber: "1",
    amount: 1234,
    currency: 978,
    returnUrl: "https://www.merchant.com",
    description: "description",
    language: "en",
    clientId: "1",
    features: "VERIFY"
  }
})

PHP

<?php

$data = array(
    "userName" => "username",
    "password" => "password",
    "orderNumber" => "1",
    "amount" => 1234,
    "currency" => 978,
    "returnUrl" => "https://www.merchant.ru",
    "description" => "description",
    "language" => "en",
    "clientId" => "1",
    "features" => "VERIFY"
);

$data_string = json_encode($data);

$ch = curl_init("__API_PREFIX__/rest/register.do");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

Response example

{
  "orderId":"70906e55-7114-41d6-8332-4609dc6590f4",
  "formUrl":"__API_PREFIX__/merchants/test/payment_ru.html?mdOrder=70906e55-7114-41d6-8332-4609dc6590f4"
}

Step 2. Getting the encrypted message

To get the encrypted message one has to use the Mobile SDK:

Step 3. Passing card data for authorization

To pass the card data for authorization use paymentOrder.do request, server-server interaction:

Request parameters

Response parameters

Request examples

Bash

curl -X POST "__API_PREFIX__/rest/paymentorder.do?
userName=username&
password=password&
MDORDER=f1dc9771-7244-7fea-84f4-58905e249650&
seToken=530mMcGg36q703D4LrKicakmVzwyPPJ0LpXU4iPS...ZY3NZyKrZVNM&
language=en"

Node.js

const request = require("request")

request.post({
  url: "__API_PREFIX__/rest/paymentorder.do",
  form: {
    userName: "username",
    password: "password",
    MDORDER: "f1dc9771-7244-7fea-84f4-58905e249650",
    seToken: "530mMcGg36q703D4LrKicakmVzwyPPJ0LpXU4iPSZY3NZyKrZVNM...",
    language: "en"
  }
})

PHP

<?php

$data = array(
    "userName" => "username",
    "password" => "password",
    "MDORDER" => "f1dc9771-7244-7fea-84f4-58905e249650",
    "seToken" => "530mMcGg36q703D4LrKicakmVzwyPPJ0LpXU4iPSZY3NZyKrZVNM...",
    "language": "en"
);

$ch = curl_init("__API_PREFIX__/rest/paymentorder.do");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

Response example

{
  "errorCode":0,
  "info":"Ваш платёж обработан, происходит переадресация...",
  "acsUrl":"https://web.rbsuat.com/acs/auth/start.do",
  "termUrl":"__API_PREFIX__/rest/finish3ds.do?lang=en",
  "paReq":"eJxVUttygjAQ/RWGdwzBBNRZ41jpdUZ0tHbqYyShYCvQAB3L1zdRaWue9uzl7O7ZwOR4+LC+pKqyIh/buOfalszjQmT529=..."
}

Step 4. Getting info about the order

To get the information on the state of the registered order use getOrderStatusExtended.do request, server-server interaction:

Request parameters

Response parameters

Request examples

Bash

curl -X POST "__API_PREFIX__/rest/getOrderStatusExtended.do?
orderId=b9054496-c65a-4975-9418-1051d101f1b9&
language=en"

Node.js

const request = require("request")
request.post({
  url: "__API_PREFIX__/rest/getOrderStatusExtended.do",
  form: {
    orderId: "b9054496-c65a-4975-9418-1051d101f1b9",
    language: "en"
  }
})

PHP

<?php

$data = array(
    "orderId" => "b9054496-c65a-4975-9418-1051d101f1b9",
    "language" => "en"
);

$ch = curl_init("__API_PREFIX__/rest/getOrderStatusExtended.do");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

Response example

{
  "expiration":"201512",
  "cardholderName":"NIKOLA TESLA",
  "depositAmount":789789,
  "currency":"978",
  "approvalCode":"123456",
  "authCode":2,
  "clientId":"69",
  "bindingId":"07a90a5d-cc60-4d1b-a9e6-ffd15974a74f",
  "ErrorCode":"0",
  "ErrorMessage":"Success",
  "OrderStatus":2,
  "OrderNumber":"ordernumber_42",
  "Pan":"411111**1111",
  "Amount":789789
}

Order reversal

To reverse an order, use the reverse.do request, server-server interaction:

Request parameters

Response parameters

Request examples

Bash

curl -X POST "__API_PREFIX__/rest/reverse.do?
  orderId=b9054496-c65a-4975-9418-1051d101f1b9&
  language=en"

Node.js

const request = require("request")
request.post({
  url: "__API_PREFIX__/rest/reverse.do",
  form: {
    orderId: "b9054496-c65a-4975-9418-1051d101f1b9",
    language: "en"
  }
})

PHP

<?php

$data = array(
    "orderId" => "b9054496-c65a-4975-9418-1051d101f1b9",
    "language" => "en"
);

$ch = curl_init("__API_PREFIX__/rest/reverse.do");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

Response example

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

Order refund

To refund use the refund.do response, server-server interaction:

Request parameters

Response parameters

Features

You can use special parameters for your operations:

Request examples

Bash

curl -X POST "__API_PREFIX__/rest/refund.do?
  amount=500&
  currency=978&
  language=en&
  orderId=5e97e3fd-1d20-4b4b-a542-f5995f5e8208"

Node.js

const request = require("request")

request.post({
  url: "__API_PREFIX__/rest/refund.do",
  form: {
    amount: "500",
    currency: "978",
    language: "en",
    orderId: "5e97e3fd-1d20-4b4b-a542-f5995f5e8208"
  }
})

PHP

<?php

$data = array(
    "amount" => "500",
    "currency" => "978",
    "orderId" => "5e97e3fd-1d20-4b4b-a542-f5995f5e8208",
    "language" => "en"
  );

$ch = curl_init("__API_PREFIX__/rest/refund.do");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

Response example

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

Finishing a 3DS2 order via API

The method used for finishing a 3DS2 order via API is Finish3dsVer2PaymentAnonymous.do

Request parameters

Response parameters

Additional info

Using features

You can use special parameters for your operations:

Using jsonParams

You can use jsonParams to pass additional order information for further usage and storage. You can view additional parameters in the merchant console of the payment gateway.

Additional parameters are passed as follows {"<name1>":"<value1>",...,"<nameN>":"<valueN>"} These fields can be passed to the bank registries.

As additional parameters you can, in particular, pass the following:

orderStatus statuses

errorCode values

Security requirements

Implementation of the features described in this document must meet the security requirements:

1. Passing explicit card data is strictly forbidden;
2. Encryption must be made on customer's device;
3. Do not store encrypted messages after payment is made and/or reuse them
4. Card binding is made as required by PCI-DSS. Card data (matching IDs) for binding is stored in the Payment Gateway.
5. Web page of the issuing ACS for 3DSec authentication is displayed to customers via the WebView of the mobile platform. URL calls must be disabled from the address bar as well as from active elements that can be contained on the ACS page;

PCI DSS security requirements

In PCI DSS documentation using encrypted messages is described as:

that is, processing payment data is done by a third party but the store site is also responsible for card data security.

To meet the standard, the online store must comply with SAQ-EP and undergo ASV approval quarterly. No other special requirements.

1: By default the following field are passed to the bank processing:

orderNumber – order ID in the store system,

description – order description (not more than 24 characters, forbidden characters are: %, +, carriage return \r, and line feed \n).