NAV Navbar

For any question, we are one click away

Contact us

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:

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:

Payment Method Supported
Bank card Yes
Binding (stored bank card) Yes
Apple Pay Yes

More about iOS SDK

Android

Payment methods supported by the SDK:

Payment Method Supported
Bank card Yes
Binding (stored bank card) Yes
Google Pay Yes

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

sequenceDiagram participant C as Client participant MA as Store Mobile App participant SDK as SDK participant SDK2 as 3DS2 SDK participant PG as Payment Gateway participant 3DS as 3DSS/ACS/DS C ->> 3DS: 1. register.do MA ->> SDK: 2. init(mdOrder) SDK ->> PG: 3. getSesstionStatus.do SDK ->> SDK: 4. render loop Multiple tries C ->> SDK: 5. Click the Pay button SDK ->> PG: 6. Relevant payment method in Payment Gateway alt a. Payment finihed PG ->> SDK: 7a. response with payment status (Go to 21) else b. 3DS2 required PG ->> SDK: 7b. response with payment status SDK ->> SDK2: 8. init(key) SDK2 ->> SDK: 9. get device data SDK ->> PG: 10. request with device data alt Frictionless PG ->> SDK: 11a. data for ACS (success/fail) else Challenge Flow PG ->> SDK: 11b. data for ACS SDK ->> SDK2: 12. Call to 3DS2 SDK SDK2 ->> 3DS: 13. get initial form C ->> SDK2: 14. Client submits verification code SDK2 ->> 3DS: 15 Code is sent to ACS 3DS ->> SDK2: 16. ACS returns verification status SDK2 ->> SDK: 17. status SDK ->> PG: 18. finish3dsVer2PaymentAnonymous.do PG ->> PG: 19. payment PG ->> SDK: 20. data about payment result end end SDK ->> PG: 21. getSessionStatus.do end SDK ->> PG: 22. getFinishedPaymentInfo.do SDK ->> MA: 23. Callback with result

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.

sequenceDiagram participant Client participant MA participant MAB participant PG participant ACS Client->>+MA: 1. initialising payment on own device MA->>+MAB: 2. sending register order request MAB->>+PG: 3. sending register order request PG->>PG: 4. decrypting cryptogram and initiating standard check process PG-->>-MAB: 5. returns unique order identifier MAB-->>-MA: 6. passes unique order identifier MA-->>-Client: 7. presenting request to enter payment data Client->>+MA: 8. input payment data MA->>MA: 9. making cryptogram MA->>+MAB: 10. sending cryptogram MAB->>PG: 11. passing cryptogram as a part of the payment request PG->>PG: 12. decrypting cryptogram and initiating standard check process alt card enrolled in 3DSec PG-->>MAB: 13. sending response MAB-->>-MA: 14. passing redirect to ACS of issuer bank MA->>ACS: 15. asking ACS authentication page ACS-->>Client: 16. presenting authentication page Client->>ACS: 17. doing necessary authentication actions ACS->>ACS: 18. checking client's authentication ACS-->>MA: 19. passing redirect to Payment Gateway (including PARes) end PG->>PG: 20. order authorisation PG-->>MA: 21. passing redirect to finish URL of Merchant (from step 2) MA->>+MAB: 22. asking order information MAB->>PG: 23. initialising request for order information PG-->>MAB: 24. returning order information MAB-->>-MA: 25. passing order information MA-->>Client: 26. presenting order information

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:

graph LR C(Client) --> A A(MA) --> B[MAB] B --> G[PG] style B fill:#0F0 style G fill:#0F0

Request parameters

Name
Data type
Mandatory
Description Example
userName
AN..30
Conditional
Merchant login received during store registration. If token is used (token parameter) for authentication instead of userName and password, do not pass the userName parameter. merchant_api_username
password
AN..30
Conditional
Merchant password received duringn store registration. If token is used (token parameter) for authentication instead of userName and password, do not pass the password parameter. merchant_api_password
token
AN..30
Conditional
Public key that can be used for order registration. If userName and password are used for authentication, do not pass the token parameter.
orderNumber
AN..32
Conditional
Number (identifier) of the order in the store system. It is unique for every store within the Payment Gateway. If the order number is generated by the Payment Gateway it is not required to pass this parameter 1
amount
N..12
Mandatory
Payment amount in minimum denomination of the used currency (for example, in cents) 12345
currency
N3
Optional
Payment currency code ISO 4217. If not specified, then, the default valude is used - 978 810
returnUrl
ANS..512
Mandatory
The URL address that the customer must be redirected to in case of a successful payment. The URL address must be full, including the used protocol https://www.shop.com/?result=return
failUrl
ANS..512
Optional
The URL address the customer must be redirected to in case of an unsuccessful payment. The URL address must be full, including the used protocol https://www.shop.com/?result=fail
description
ANS..512
Optional
Order description. Only the first 24 characters of this field are passed to the bank processing for financial reporting Item of goods. Online store
language
A2
Optional
Language code in ISO 639-1 Alpha-2. If the parameter is not set, the language that is selected in merchant settings as default will be used en
pageView
ANS..20
Optional
Prefix of the payment page that is displayed to the customer mobile
clientId
ANS..255
Conditional
Customer identifier in the store system. Used for binding functionality. It is mandatory to pass this parameter when making payment by binding, otherwise the payment will be unsuccessful. 123
merchantLogin
AN..255
Optional
Specify a child merchant login to register the order on their behalf merchant_1
jsonParams
Block
Optional
Block for passing addition order parameters. See more. {"backUrl":"https://ya.com/"}
jsonParams.name
ANS..255
Conditional
jsonParams.value
ANS..255
Conditional
bindingId
AN..255
Optional
Identifier of and existing binding. If passed, then the order can be payed only by binding, only CVC is required on the payment page.
features
ANS...255
Optional
Special parameters of the operation behavior link to features FORCE_FULL_TDS, VERIFY
email
ANS..40
Optional
Customer's email customer@mail.com
phone
ANS..12
Optional
Customer's phone number 79991234567

Response parameters

Name
Data type
Mandatory
Description Example
errorCode
N1
Mandatory
Error code 2
error
AN..512
Conditional
Error code No order found
errorMessage
AN..512
Conditional
Error code No order found
info
AN..512
Conditional
Payment attempt result Payment processed, redirecting...
redirect
AN..512
Conditional
Return address after payment is made https://merchant-site.com/
termUrl
AN..512
Conditional
Not used when no authentication against the ACS is needed https://server/context/rest/finish3ds.do?lang=en
acsUrl
AN..512
Conditional
Not used when no authentication against the ACS is needed https://web.rbsuat.com/acs/auth/start.do
paReq
AN..512
Conditional
Not used when no authentication against the ACS is needed eJxVUttygjAQ/RWGdwzBBNRZ41jpdePN85A3vC4DlVUoZrGTdKMpjLquJv0s...

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:

graph LR C(Client) --> A A(MA) --> A(MA) style A fill:#0F0

Step 3. Passing card data for authorization

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

graph LR C(Client) --> A A(MA) --> B[MAB] B --> G[PG] style B fill:#0F0 style G fill:#0F0

Request parameters

Name
Data type
Mandatory
Description Example
userName
AN..30
Mandatory
Merchant login received during store registration. merchant_api_username
password
AN..30
Mandatory
Merchant password received during store registration. merchant_api_password
seToken
AN..30
Mandatory
Encrypted message with card data Dduur6hWg9dfp9aXos1QC8s/C6ZVujOc3qySy0VJEP1...
language
A2
Mandatory
Language code in ISO 639-1 Alpha-2. If the parameter is not set, the language that is selected in merchant settings as default will be used en
ip
AN..30
Optional
IP address of the payer 255.255.255.1
email
ANS..40
Optional
Customer's email customer@mail.com
bindingNotNeeded
boolean
Optional
Whether it is required to create a binding as a result of the operation true
jsonParams
Block
Optional
Block for additional parameters of the order. See more. {"email":"ivanov@ivan.com", "phone":"9001234567"}
jsonParams.name
ANS..255
Conditional
jsonParams.value
ANS..255
Conditional

Response parameters

Name
Data type
Mandatory
Description Example
errorCode
N1
Mandatory
Error code 2
error
AN..512
Conditional
Error code No order found
errorMessage
AN..512
Conditional
Error code No order found
info
AN..512
Conditional
Payment attempt result Payment processed, redirecting...
redirect
AN..512
Conditional
Return address after payment is made https://merchant-site.com/
termUrl
AN..512
Conditional
Not used when no authentication against the ACS is needed https://server/context/rest/finish3ds.do?lang=en
acsUrl
AN..512
Conditional
Not used when no authentication against the ACS is needed https://web.rbsuat.com/acs/auth/start.do
paReq
AN..512
Conditional
Not used when no authentication against the ACS is needed eJxVUttygjAQ/RWGdwzBBNRZ41jpdePN85A3vC4DlVUoZrGTdKMpjLquJv0s...

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:

graph LR C(Client) --> A A(MA) --> B[MAB] B --> G[PG] style B fill:#0F0 style G fill:#0F0

Request parameters

Name
Data type
Mandatory
Description Example
userName
AN..30
Conditional
Merchant login received during store registration. If token is used (token parameter) for authentication instead of userName and password, do not pass the userName parameter. merchant_api_username
password
AN..30
Conditional
Merchant password received duringn store registration. If token is used (token parameter) for authentication instead of userName and password, do not pass the password parameter. merchant_api_password
token
AN..30
Conditional
Public key that can be used for order registration. If userName and password are used for authentication, do not pass the token parameter. 567uijkfdjv12erfd9vjn
orderId
ANS36
Conditional
Unique ID of the order in the Payment Gateway d9378a7a-5215-7eab-9d94-d5910007cc4a
orderNumber
AN..32
Conditional
Unique number (identifier) of the order in the store system. order_15
language
A2
Conditional
Language code in ISO 639-1 Alpha-2. If the parameter is not set, the language that is selected in merchant settings as default will be used en

Response parameters

Name
Data type
Mandatory
Description Example
orderNumber
AN..32
Conditional
Number (identifier) of the order in the store system
orderStatus
N2
Conditional
The value of this parameter defines the state od the order in the Payment Gateway
actionCode
N3
Mandatory
Response code
actionCodeDescription
AN..512
Mandatory
Error code description passed in the language defined in the language parameter of the request
errorCode
N1
Mandatory
Error code 2
errorMessage
AN..512
Conditional
Error code No order found
amount
N..20
Mandatory
Payment sum in minimum currency units (for example, cents)
currency
N3
Conditional
Payment currency code in ISO 4217
date
ANS
Mandatory
Order registration date.
orderDescription
AN..512
Conditional
Order description passed during its registration
ip
ANS..39
Mandatory
IP address of the payer.
authRefNum
AN..24*Conditional*
Order authorization reference number that is assigned during the registration
refundedDate
ANS
Conditional
Date and time of the refund
cardAuthInfo
Блок
Conditional
Contains a structure of secureAuthInfo elements and other parameters
cardAuthInfo.maskedPan
NS..19
Conditional
Masked number of the card used for paying
cardAuthInfo.expiration
N6
Conditional
Card expiry in the following format: YYYYMM 201912
cardAuthInfo.cardholderName
A..64
Conditional
Cardholder name John Doe
cardAuthInfo.approvalCode
AN6
Payment authorization code
cardAuthInfo.chargeback
A..5
Conditional
Whether the payment was returned to the customer by the Bank action: true/false
cardAuthInfo.paymentSystem
N..10
Conditional
Name of the payment system: VISA/MASTERCARD/AMEX/JCB/CUP/MIR
cardAuthInfo.product
AN..255
Mandatory
Additional information about corporate cards
cardAuthInfo.paymentWay
AS..14
Conditional
Payment method (entering card data, payment by binding etc. ).
cardAuthInfo.secureAuthInfo
Block
This element contains eci element and threeDSInfo element
cardAuthInfo.secureAuthInfo.eci
N..4
Conditional
Electronic commerce indicator
cardAuthInfo.secureAuthInfo.threeDSInfo
Блок
Conditional
This element is a list of cavv and xid parameters
cardAuthInfo.secureAuthInfo.threeDSInfo.xid
ANS..80
Conditional
ECI transaction identificator MDAwMDAwMDEzODM4MTk0MzAzMjM="
cardAuthInfo.secureAuthInfo.threeDSInfo.cavv
ANS..200*Conditional*
CArdholder authentication check value
bindingInfo
Block
Conditional
This element contains binding information
clientId
ANS..255
Conditional
Customer's ID in the store system passed during the order registration
bindingId
ANS..255
Conditional
Binding ID created during order creation or used for paying
authDateTime
ANS
Conditional
Authorization date/time
terminalId
AN..10
Conditional
Terminal ID
paymentAmountInfo
Block
Conditional
This element contains information about amounts
approvedAmount
N..20
Conditional
Amount on hold (used in two-phase payments)
depositedAmount
N..20
Conditional
Amount approved for charging
refundedAmount
N..20
Conditional
Refund amount
paymentState
A..10
Conditional
Payment state
feeAmount
N..20
Conditional
Fee amount
bankInfo
Block
Conditional
This element contains information about the card issuing bank
bankInfo.bankName
A..200
Conditional
Name of the issuing bank
bankCountryCode
AN..4
Conditional
Country code of the issuing bank
bankCountryName
AN..160
Conditional
Name of the country of the issuing bank in the language passed in the language parameter of the request or in the user language if the language was not specified
payerData
Block
Conditional
This element contains information about the payer
email
AN..255
Conditional
Customer's email

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:

graph LR C(Client) --> A(MA) A --> B[MAB] B --> G[PG] style B fill:#0F0 style G fill:#0F0
graph LR B[MAB] --> G[PG] style B fill:#0F0 style G fill:#0F0

Request parameters

Name
Data type
Mandatory
Description Example
userName
AN..30
Conditional
Merchant login received during store registration. If token is used (token parameter) for authentication instead of userName and password, do not pass the userName parameter. merchant_api_username
password
AN..30
Conditional
Merchant password received duringn store registration. If token is used (token parameter) for authentication instead of userName and password, do not pass the password parameter merchant_api_password
orderId
ANS36
Conditional
Unique order ID in the Payment Gateway d9378a7a-5215-7eab-9d94-d5910007cc4a
jsonParams
Block
Optional
This block is for passing additional order parameters. See more. {"email":"ivanov@ivan.com", "phone":"9001234567"}
jsonParams.name
ANS..255
Conditional
jsonParams.value
ANS..255
Conditional
language
A2
Optional
Language code in ISO 639-1 Alpha-2. If the parameter is not set, the language that is selected in merchant settings as default will be used en

Response parameters

Name
Data type
Mandatory
Description Example
errorCode
N3
Mandatory
Error code 2
errorMessage
AN..512
Conditional
Error description No order found

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:

graph LR C(Client) --> A(MA) A --> B[MAB] B --> G[PG] style B fill:#0F0 style G fill:#0F0
graph LR B[MAB] --> G[PG] style B fill:#0F0 style G fill:#0F0

Request parameters

Name
Data type
Mandatory
Description Example
userName
AN..30
Conditional)
Merchant login received during store registration. If token is used (token parameter) for authentication instead of userName and password, do not pass the userName parameter merchant_api_username
password
AN..30
Conditional)
Merchant password received duringn store registration. If token is used (token parameter) for authentication instead of userName and password, do not pass the password parameter merchant_api_password
orderId
ANS36
Conditional)
unique order ID in the Payment Gateway d9378a7a-5215-7eab-9d94-d5910007cc4a
amount
N..12
Mandatory
Refund amount in minimum currency units (for example, in cents) 8800
jsonParams
Block
Optional
This block is for passing additional order parameters. See more. {"email":"ivanov@ivan.com", "phone":"9001234567"}
jsonParams.name
ANS..255
Conditional
jsonParams.value
ANS..255
Conditional
language
A2
Optional
Language code in ISO 639-1 Alpha-2. If the parameter is not set, the language that is selected in merchant settings as default will be used en

Response parameters

Name
Data type
Mandatory
Description Example
errorCode
N3, Mandatory
Error code 2
errorMessage
AN..512
Conditional
Error description No order found

Features

You can use special parameters for your operations:

Specuial parameter Description
AUTO_PAYMENT (Payment is processed without cardholder authentication (without CVC and 3D-Secure). To make such payments the store must have sufficient privileges
FORCE_TDS Force customer to make payment with 3-D Secure. If the customer's card does not support 3-D Secure, then the transaction will fail
FORCE_SSL Force SSL payment (without using 3-D Secure)
FORCE_FULL_TDS After 3-D Secure authentication PaRes status must be Y only - that guarantees successful user authentication. Othereise the transaction will fail
VERIFY If you use this feature, order registration request will result in cardholder verification, with no payment made. Verification allows to make sure that the payment card is in its legal cardholder's posession, and further on you can receive payments from this card without CVC or 3D-Secure. After successful registration and verification the order status is immediately changed to REVERSED

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

Mandatory Name Type Description
Yes

threeDSServerTransId String Transaction identifier created on 3DS Server.
Yes

threeDSSDK String Possible values: true or false. Flag showing that payment comes from 3DS SDK.
Yes (SDK only)

threeDSSDKAppId String Unique identifier of SDK.
Yes (SDK only)

threeDSSDKTransId String Unique identifier of transaction within SDK.
Yes (SDK only)

threeDSSDKEncData String Encrypted data about device.
Yes (SDK only)

threeDSSDKEphemPubKey String Public part of ephemral key. Required to etablish session with ACS.

Response parameters

Mandatory Name Type Description
Yes

threeDSServerTransId String Transaction identifier created on 3DS Server.
Yes (SDK only)

threeDSSDKKey String Device data encryption key.
Yes (SDK only)

threeDSAcsSignedContent String Signed content for SDK, content includes ACS URL.
Yes (SDK only)

threeDSDsTransID String Unique identifier of transaction witin IPS.
Yes (SDK only)

threeDSSDKKey String Device data encryption key.

Additional info

Using features

You can use special parameters for your operations:

Special parameter Description
AUTO_PAYMENT (Payment is processed without cardholder authentication (without CVC and 3D-Secure). To make such payments the store must have sufficient privileges.
FORCE_TDS Force customer to make payment with 3-D Secure. If the customer's card does not support 3-D Secure, then the transaction will fail.
FORCE_SSL Force SSL payment (without using 3-D Secure).
FORCE_FULL_TDS After 3-D Secure authentication PaRes status must be Y only - that guarantees successful user authentication. Otherwise the transaction will fail
VERIFY If you use this feature, order registration request will result in cardholder verification, with no payment made. Verification allows to make sure that the payment card is in its legal cardholder's posession, and further on you can receive payments from this card without CVC or 3D-Secure. After successful registration and verification the order status is immediately changed to REVERSED.

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:

Name
Data type
Mandatory
Description Example
email
ANS..255
Conditional
Email to be displayed on the payment page. Customer's email must be passed if client notification is configured for the merchant {"email": "client_mail@email.com"}
phone
AN..11
Mandatory)
Customer's phone number - it will be displayed on the payment page {"phone": "9001234567"}
backToShopUrl
ANS..255
Optional)
To display a button tha would allow a customer to return to the online store the address of the store must be specified in this parameter {"backToShopUrl": "http://shop.com"}
backToShopName
ANS..255
Conditional
Name of the button that would allow a customer to return back to the online store (if backToShopUrl parameter is used) {"backToShopName": "Cancel"}

orderStatus statuses

Value Description
0 Orders is registered but not payed
1 Pre-authorized amount is held (for two-phase payments)
2 Full order amount is authorized
3 Authorization canceled
4 Order refunded
5 Authorization via the ACS of the issuing bank initiated
6 Authorization declined

errorCode values

Value Description
0 Request processed without errors.
1 orderId or orderNumber expected.
5 Access denied.
5 User must change password.
6 Order not found.
7 System error.

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).