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:
- A user selects a payment method in your mobile app, enters the required data, and proceeds to payment;
- The mobile app encrypts the payment data creating a seToken (self encrypted Token);
- 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 |
- Requirements:
iOS 10.0 or newer
Android
Payment methods supported by the SDK:
Payment Method | Supported |
---|---|
Bank card | Yes |
Binding (stored bank card) | Yes |
Google Pay | Yes |
- Requirements:
Android 5.0 or newer
Checklist
To accept payments via your mobile app you must do the following:
- Register your online store in the Bank;
- Receive test credentials to access merchant console;
- Receive test credentials for calling API methods;
- Integrate with the Payment Gateway in test mode;
- When test integration is configured, contact bank support to check readiness;
- Receive production credentials to access merchant console;
- Receive production credentials for calling API methods;
- Agree with the Bank on switching your system to the production mode;
- Sign a agreement with a bank representative that your online store is ready to work in production mode;
- 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
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:
Step 3. Passing card data for authorization
To pass the card data for authorization use paymentOrder.do
request, server-server interaction:
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:
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:
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:
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:
- Passing explicit card data is strictly forbidden;
- Encryption must be made on customer's device;
- Do not store encrypted messages after payment is made and/or reuse them
- Card binding is made as required by PCI-DSS. Card data (matching IDs) for binding is stored in the Payment Gateway.
- 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
).