Mutt
Professional
- Messages
- 1,056
- Reaction score
- 643
- Points
- 113
In this guide, you will learn how to install a merchant (payment gateway) on your website and bypass 3D Secure (disable/block 3D Secure).
What is merchants API
API is designed for merchants interested in accessing a flexible and flexible solution for automating electronic payments with bank cards.
API provides the integration of the merchant's service with merchants payment gateway, which guarantees high reliability and security of customers' payment transactions.
Content:
The basics
Bank cards
You can accept bank cards of International Payment Systems for payment: Visa (including Electron), Mastercard, Maestro, MIR, and optionally JCB, Amex, UnionPay, DinersClub, BelKart, Arka.
By default, the user will enter bank card details on merchants payment gateway page, but you can embed the form on your website or mobile application.
Apple Pay, Google Pay
Thanks to merchant, the user can pay using Apple Pay and Google Pay.
QR Code (SBP)
Thanks to merchant, a user can pay for a product/service using a new method - QR Code payment (QR Code), both from a mobile device and from the Web version.
ApplePay
merchants provides the ability to write off funds from the Buyer's card using the Apple Pay token instead of the card details.
To make a payment using Apple Pay, you must:
Google pay
Google Pay™ allows customers to make payments in your app or website using any credit or debit card stored in their Google account, including from Google Play, YouTube, Chrome, or Android device.
Google Pay™ is fully compatible with merchants products and features, allowing you to use it instead of the traditional form of payment whenever possible. Use it to accept payments for physical or digital goods, donations, subscriptions, and more. Payments for digital goods only apply to Web and mobile Web payments.
Principle of operation
Integration
To receive payments, fill out the registration form, after which a Google representative will contact you and instruct you on the next steps. Integration examples:
WEB-site
An example of tokenization:
An example of installing payment systems supported by Google Pay and merchant:
Android App
An example of tokenization:
An example of installing payment systems supported by Google Pay and merchant:
Interaction with merchant's
As a result of tokenization, you should receive a Google Pay token, which looks something like this:
The token must be Base64 encoded without any modifications and sent to merchant's. An example of a Base64 encoded token:
merchant's API supports the transfer and processing of a token in two methods: Block and Pay in the GooglePayToken parameter. An example of a request for a one-step payment Pay:
As a result of the successful execution of the scenario from the example above, the client's funds will be authorized and debited using merchant's and Google Pay. An example of a successful response:
If you receive an erroneous response, please check the correctness of the Base64-encoded token, the correctness of its transmission and other parameters. If the data is correct, refer to merchant error dictionary
Google Pay Terms of Service
Please read these guidelines to properly use Google Pay technology and brand in mobile apps and websites.
QR Code (SBP)
The UBS QR code is a graphic image, when decrypted, all the necessary payment information becomes available - bank details, the amount and purpose of the payment. Thanks to graphical security, payment information is encrypted and protected from reading without the special software that is available in the mobile phone.
The UBS QR-code can be of two types: QRS - static QR-code ("QR-sticker") and QRD - dynamic QR-code ("QR at the checkout").
Interaction scenarios:
Entering data on the Seller's side
The interface offers the ability to receive a payment link or generate a QR code for payment using the Fast Payment System (FPS).
After confirmation of payment by the Client, the Seller receives a notification of the result of the payment in the form of a POST request.
To make a payment using the UBS QR code, the User must have a mobile application of a bank participating in the Fast Payments System.
Available methods:
Embedded solutions
Installing merchant Widget
In order to start accepting payments, the merchant needs to place a simple script on his page that will create a session and generate a payment page. An example of how the merchant's solution interacts with merchant payment gateway with Easy Integration:
To install the widget, you need to register a script on the site in the head section:
Further, for any event (for example, pressing the payment button), a call to the widget is prescribed. For example:
Calling the widget with the necessary parameters should be placed on the page before the closing tag </body>
Widget options:
Widget parameters that are passed to its constructor
Progress
After launching the constructor with parameters, it checks for the device screen size and checks whether the page is open on a mobile device. The page is scaled for correct and convenient display of the widget.
The HTML code of the widget is generated. The code is embedded in the body section by adding it as a child node to the tag. The elements are given a large z-index style attribute so that they overlap the page when displayed. Initially, all items are hidden.
Loading the widget. A POST request is created with the data contained in the widget. The answer is a template that contains fields to fill out and a payment button. This template is loaded into the <iframe>widget element.
After the payment is made, the widget is closed and sent postMessagewith the result of the payment paymentResult. Its HTML code is removed from the main page.
Marchant payment form
This guide describes how to work with templates for entering payment card data on the gateway side. We have tried to create a flexible tool that will allow you to quickly create your own payment scenarios.
Attention! Templates should not contain links to third-party resources. If you would like to add your own scripts, images or styles, you must send them to merchant support team.
The default payment form template consists of two files:
Form template settings
Payment result template settings
You can make a payment template without entering the cardholder. In this case, in the template settings, you must add a key Holderand set a string with a stub for transferring data to processing. The string must contain at least three Latin characters.
You can change the text on the button, for this you need to pass a parameter ButtonTextwith the text for the session type
or if PayButtonCustomText is specified on Init in CustomParams (For example, )PayButtonCustomText=Activate Promo Code
To display additional parameters on the payment template, transferred during the initialization of the payment session, you must specify the parameter name in quotation marks.
Ready modules for CMS
merchants offers a turnkey solution for online stores based on CMS Bitrix and WordPress (plugin WooCommerce). In order to start accepting payments, the merchant needs to install the merchant Payment plugin on his page, with which the User will be redirected to merchant payment form. Upon successful payment, the User will be returned back to the store's website.
Bitrix
Installation instructions for the CMS 1C-Bitrix module.
Go to Administration Tab, Marketplace Solution Catalog.
Install the merchant payment acceptance module.
After successful installation, go to Store> Settings> Payment systems.
Add payment system.
In the "Handler" field, select merchant.
Payment type - "Non-cash", Encoding - "utf-8"
The values of the parameters "merchant ID", "Password", "Payment gateway address" will be provided in a letter from merchant.
WordPress (WooCommerce plugin)
Installation instructions for CMS WordPress module (WooCommerce plugin).
Download and install the WooCommerce plugin.
Unpack merchant.zip archive.
Go to WooCommerce> Settings> Payments.
Configure merchant Method.
The values of the "Payment gateway address", "merchant ID" and "Password" parameters will be sent in an email from merchant.
Payments
Recurring payments
merchant provides the ability to make regular debits from the user's card without entering the card details. A prerequisite for making recurring payments is preliminary registration of the User in merchant's system and saving the card from which recurring payments will be made. To save the card, the storeCard method is used - in the case of using the payment form on the merchant's side, or the Init, Type = Pay, AddCard = True method - in the case of using the payment form on merchant side. In this case, when saving the map, you must pass the parameters Recurrent = true, as well as OrderId and BlockAmount to perform the first operation that initiates the recurrent.
Subsequent debits are performed without entering the full card details.
Using 3DS Verification
The 3-D Secure technology minimizes the risks of card fraud for merchants, since the issuing bank is responsible for the transaction performed with 3DS verification. At the same time, the payment scheme and the format of requests are slightly changed. When initiating a payment, the payment gateway checks the card's involvement in the 3-D Secure technology and receives the necessary parameters for user authentication. Then the user is redirected to the page of the issuing bank to enter the password, after which the system generates the PaRes parameter to complete the authorization. A detailed description is provided in Block3DS.
Service of notifications
Notifications are notifications (POST) containing information about the performed operation, sent to the URL specified by the merchant in advance in a letter to merchant. The service sends the following types of notifications:
Composition of notification fields:
Based on the result of sending notifications, in agreement with the merchant, an active action on the order can be configured. For example, in case of receipt of the 422nd response code for the Block notification, or failure to receive a response within the specified period, merchant independently initiates the unblocking of funds. The functionality is optional.
Additionally
Order statuses
Error codes
Test Cards
Payment amount - From 0.1 to 1 euro/usd.
Cardholder - any name, in this case only Latin characters or a space should be used. The cardholder's name must be at least three characters long.
Using the parameters of valid bank cards during testing is strictly prohibited!
Description of API methods
Interaction of the merchant's solution with merchant payment gateway during integration is based on a request-response scheme.
A request with the necessary parameters is formed on the Seller's side and is transmitted by the POST method (GET - for the createPayment method) in the JSON or x-www-form-urlencoded format over the HTTPS (TLS 1.2) protocol.
For example: https://{domain}/{Command} where {domain}is the URL address of the payment gateway, {Command}is the name of the command (method).
The results of processing requests are issued by the payment gateway synchronously in JSON format, UTF-8 encoding.
Parameter names in queries are case sensitive.
merchant also provides the ability to use asynchronous notifications.
Block - blocking funds on the card
Performed using the Block command. This request allows you to block funds on the Buyer's card for subsequent debiting. The identifier of the registered card or the full details of the card can be specified as a card. Blocked funds can then be debited by the Charge command or unblocked by the Unblock command.
Request parameters
* - are used only if the card is saved to a specific user ** - when the “Random” value is specified, a random card is selected from those linked to this user *** - are used only if the card is saved for the terminal **** - are used only if the card is kept by the merchant
The composition of the keys of the PayInfo parameter:
Format of the parameter:
Example of transferring Goods:
Request example
Sample POST request: https: // {domain} / Block Key: TestTerminal Amount: 300 OrderId: TestOrder123 PayInfo: PAN% 3D4111111111100023% 3BEMonth% 3D12% 3BEYear% 3D21% 3BCardHolder% 3DTEST% 20TESTOV% 3BSecureBode% 3Dms: Email =user@example.com
An example of implementing a request in the program code:
Response options
Sample response
An example of a response to a successful request:
An example of a response to an unsuccessful request:
Init - Create a payment session
This is done using the Init command. The method is used if the form for entering bank card data is on the side of merchant's. If the method call is successful, a unique identifier is returned, which allows you to call the payment page located on the side of merchant's in the future, and redirect the user to it to enter the card data.
Upon receipt of the session identifier, it is possible to indicate the purpose of using the payment form - to block funds on the card or to save the card in merchant's storage for subsequent debits. If the card is saved, subsequent debits can be made both with the input of CVV2 / CVC2, and without acceptance - without entering any data and the participation of the cardholder. These can be recurrent write-offs or classic transactions without entering CVV2 / CVC2. In the latter case, failures are possible due to the issuer's restrictions due to the need to use 3-D Secure technology.
The payment page can be designed in the Seller's design and is not unique (the Seller can have several data entry pages for different cases).
Request parameters
* - used only if the card is saved / saved to the User
** - used only if the card is saved to the merchant
To save / pay for the saved card behind the terminal, these parameters do not need to be transmitted.
Depending on the business scenario, the card can be saved:
Request example
Sample POST request:
An example of implementing a request in the program code:
Format of the parameter Goods
Response options
Format of the parameter Goods:
Sample response
An example of a response to a successful request:
Example response to an unsuccessful request:
Format of the parameter Goods
Example of transferring Goods:
createPayment - Call a payment form
Performed using the createPayment command. The request is used to redirect the user to the form for entering the card details for subsequent payment or saving the card. As a result of the command execution by the GET / POST method, the template (form) for entering the data (details) of the bank card specified by the parameters specified in the Init command is called.
Request parameters
Request example
Sample POST request:
An example of implementing a request in the program code:
As a result of the method call, the user is redirected to the card data entry template for subsequent payment or saving the card details.
After successful payment or completion of the number of payment attempts, the user will be returned to the Seller's page. The return address (page URL) is indicated by the Seller in advance when connecting. The address can be specified in a parameterized form. In this case, the parameters inserted into the address must be specified in the CustomParams field of the Init method.
As a result of the method call, the user is redirected to the card data entry template for subsequent payment or saving the card details.
Charge - Write-off of blocked funds
The request is executed by the Charge command.
The request is used to write off funds from the User's card, previously blocked by the Block command.
The result of processing the request is the debiting of the blocked amount from the User's card. A write-off can be made for an amount less than the amount of previously blocked funds. Write-off on order can be performed only once.
Attention: for a successful write-off, it is necessary that at the time of execution of the request the payment has the status of Authorized
Request parameters
Request example
Sample POST request:
An example of implementing a request in the program code:
Response options
Sample response
An example of a response to a successful request:
An example of a response to an unsuccessful request:
Unblock - Unlocking funds on the card
The request is executed by the Unblock command.
The request is used to unblock funds from the User's card, previously blocked by the Block command. As a result of successful processing of the request, the unlocked funds become available on the User's card.
Attention: for a successful write-off, it is necessary that at the time of execution of the request the payment has the status of Authorized
Request parameters
Request example
Sample POST request:
An example of implementing a request in the program code:
Response options
Sample response
An example of a response to a successful request:
An example of a response to an unsuccessful request:
Refund
The request is executed by the Refund command.
The request is used to make a refund to the User's card, previously debited by the Charge team. The result of processing the request is the return (full or partial) of the debited funds to the User's card.
Attention: for a successful refund, it is necessary that at the time of execution of the request the payment has the Charged status.
Request parameters
Parameter format Goods
Transfer example Goods
If the Goods parameter is not specified in the request, then:
Request example
Sample POST request:
An example of implementing a request in the program code:
Response options
Sample response
An example of a response to a successful request:
An example of a response to an unsuccessful request:
Pay - One-step payment
This is done using the Pay command.
This request allows you to block and write off funds from the Buyer's card. One-step payment is similar to sequential calls to the Block and Charge methods.
The parameters of the request, response and composition of the fields are similar to the parameters of the Block command.
If a refusal is received at the stage of debiting after successful authorization, the result in the response to the Pay method will not be successful, while the order status is "Authorized":
* Writing off the blocked amount in this case can be done with a separate Charge command.
getState - Get the status of the payment
This is done using the getState command.
This request allows you to get information about the current status of the transaction (payment).
Request parameters
* one of these parameters is passed in the request
Request example
Sample POST request:
An example of implementing a request in the program code:
Response options
Sample response
An example of a response to a successful request:
An example of a response to an unsuccessful request:
createUser - Create a new user
This is done using the createUser command.
The request allows you to register a new user. Together with the saved card, this will allow you to make a payment without entering the bank card details, incl. recurring payments. The result of the request processing is the receipt by the merchant of the user ID in merchant payment gateway.
Request parameters
json
urlencoded
1* Requirements Required parameters are the same for pay channels eCom, AP, GP.
Request example
json
Sample POST request:
An example of implementing a request in the program code:
urlencoded
Sample POST request:
An example of implementing a request in the program code:
Response options
1* Requirements Required parameters are the same for pay channels eCom, AP,GP
2* Transmitted if the reply containsSuccess=true
3* Transmitted if the reply containsSuccess=false
Sample response
An example of a response to a successful request:
An example of a response to an unsuccessful request:
storeCard - Register (save) card
Performed using the storeCard command.
This request allows you to save the details of the User's bank card for subsequent payment without entering the card data. The result of processing the request is the receipt by the merchant of the card ID in merchant.
Depending on the business scenario, the card can be saved:
Request parameters
* - transmitted together. Used only if the card is kept by the User
** - Used only if the card is kept by the terminal
*** - are transferred together. Used only if the card is kept by the merchant
**** - mandatory if the ApplePayToken parameter is absent in the request
Request example
Sample POST request:
An example of implementing a request in the program code:
Response options
Sample response
An example of a response to a successful request:
An example of a response to an unsuccessful request:
Response parameters in case of saving a card involved in 3-D Secure technology are similar to those described in using 3D Secure technology. To obtain a card ID, it is necessary to complete the holder's 3DS authentication (StoreCard3DS method).
removeCard - Remove card
This is done using the removeCard command.
The result of request processing is a change in the status of the linked card from “Active” to “Deleted”. In order to return it to the “Active” status in the future, it is necessary to perform the procedure of saving the card again - in this case, the card will be assigned a new identifier.
Request parameters
json
urlencoded
1* Requirements Required parameters are the same for pay channels eCom, AP, GP.
Request example
json
Sample POST request:
An example of implementing a request in the program code:
urlencoded
Sample POST request:
An example of implementing a request in the program code:
Response options
1* Requirements Required parameters are the same for pay channels eCom, AP, GP.
2* Transmitted if the reply containsSuccess=false
Sample response
An example of a response to a successful request:
An example of a response to an unsuccessful request:
listCard - Request a list of registered cards
Performed using the listCard command.
This request allows you to get a list of cards stored in merchant with the purpose of their further use to pay for services or goods.
Request parameters
* - Used to request a list of cards stored in the terminal or the User
** - Used to request a list of cards stored in the terminal
*** - Used to request a list of cards stored in the User
**** - Used to request a list of cards, saved for the merchant
Request example
Sample POST request:
An example of implementing a request in the program code:
Response options
Sample response
An example of a response to a successful request:
An example of a response to an unsuccessful request:
Block3DS - Using 3D Secure Technology
It is used when the Seller connects the 3-D Secure authentication mechanism. The order of execution - authentication of the cardholder on the side of the issuing bank and reporting the results to the gateway service.
Upon receipt of a request to block funds, the gateway verifies that the card participates in 3-D Secure authentication.
If the User's card is involved in 3-D Secure technology, then the response also contains the ACSUrl, PaReq and ThreeDSKey attributes.
After receiving a response from the gateway, the merchant redirects the cardholder to the site of the issuing bank for additional authentication. For this, a POST request is used to the address specified in the value of the ACSUrl attribute, with the parameters listed below.
Example request:
After authorization on the website of the issuing bank, the user is returned by an HTTPS POST request to the address specified in the value of the TermUrl attribute, with the parameters specified below.
The authorization is completed by the Block3DS command.
Request parameters
Request example
Sample POST request:
An example of implementing a request in the program code:
Response options
Sample response
An example of a response to a successful request:
An example of a response to an unsuccessful request:
In case of a one-step payment (in the case of using the Pay method), you must use the Pay3DS method instead of the Block3DS method to complete the 3-DS operation.
When saving a card involved in 3-D Secure technology, to complete the operation and receive a card ID in response, you must use the StoreCard3DS method.
The request, response parameters and field compositions of the Pay3DS and StoreCard3DS methods are similar to the Block3DS method.
Payout - Crediting funds to the card
Performed using the Payout command.
The request allows you to transfer funds to the User's card from the merchant's current account. A current account must be opened with a bank or an NCO providing funds transfer. The ID of the registered card obtained in response to the storeCard request or the full details of the new card can be specified as a card.
Request parameters
json
urlencoded
1* Parameter is required if there is nouid
2* This parameter is required if there is nopan
Request example
json
Sample POST request:
An example of implementing a request in the program code:
urlencoded
Sample POST request:
An example of implementing a request in the program code:
Response options
1* Transmitted if the reply containsSuccess=true
2* Transmitted if the reply containsSuccess=false
Sample response
An example of a response to a successful request:
An example of a response to an unsuccessful request:
getReceipt - request fiscal data for an order
This is done using the getReceipt command. This request allows you to get fiscal characteristics for an order to generate a check on the side of the merchant.
Request parameters
json
urlencoded
1* If not included in the request, the response will contain fiscal data on the last transaction for the order
Request example
json
Sample POST request:
An example of implementing a request in the program code:
urlencoded
Sample POST request:
An example of implementing a request in the program code:
Response options
Sample response
An example of a response to a successful request:
An example of a response to an unsuccessful request:
Using 3-D Secure technology version 1
It is used when the Seller connects the 3-D Secure authentication mechanism. The order of execution - authentication of the cardholder on the side of the issuing bank and reporting the results to the gateway service.
An example for a two-step payment.
Upon receipt of a request to block funds, the gateway verifies that the card participates in 3-D Secure authentication.
If the User's card is involved in 3-D Secure technology version 1, then the response also contains the ACSUrl, PaReq and ThreeDSKey attributes.
After receiving a response from the gateway, the merchant redirects the cardholder to the site of the issuing bank for additional authentication. For this, a POST request is used to the address specified in the value of the ACSUrl attribute, with the parameters listed below.
Request example:
After authorization on the website of the issuing bank, the user is returned by an HTTPS POST request to the address specified in the value of the TermUrl attribute, with the parameters specified below.
The authorization is completed by the Block3DS command.
Request parameters
json
urlencoded
Request example
json
Sample POST request:
Content-Type: application / json https://{domain}/Block3DS
{
"key":"TestTerminal",
"merchant_order_id":"TestOrder123",
"pares":"JQpr1kEIAQSIEYhdkxiEJOY4esfujenl5b9rPtt2l"
}
An example of implementing a request in the program code:
urlencoded
Sample POST request:
An example of implementing a request in the program code:
Response options
1* Transmitted if the reply containsSuccess=true
2* Transmitted if the reply containsSuccess=false
Sample response
An example of a response to a successful request:
An example of a response to an unsuccessful request:
In case of a one-step payment (in the case of using the Pay method), you must use the Pay3DS method instead of the Block3DS method to complete the 3-DS operation.
When saving a card involved in 3-D Secure technology, to complete the operation and receive a card ID in response, you must use the StoreCard3DS method.
The request, response parameters and field compositions of the Pay3DS and StoreCard3DS methods are similar to the Block3DS method.
Using 3-D Secure technology version 2
It is used when the Seller connects the 3-D Secure authentication mechanism. The order of execution - authentication of the cardholder on the side of the issuing bank and reporting the results to the gateway service.
An example for a two-step payment.
When sending a request for blocking funds, the merchant needs to generate an additional object threeds_ver2:
urlencoded
The generated object must be encoded in base64and passed to the parameter ThreedsVer2merchantData.
An example of a generated object
json
urlencoded
Upon receipt of a request to block funds, the gateway verifies that the card participates in 3-D Secure authentication.
If the User's card is involved in 3-D Secure technology version 2, then the response also contains the attributes ThreedsMethodURL, Is3DSVer2 and ThreedsMethodURLData.
After receiving a response from the gateway, the Seller sends a request through a request hidden iframein the User's browser, the composition of the request:
Upon receipt of the response code 202after being redirected to the URLgateway, the merchant sends a request to Block3DS:
Request parameters
json
urlencoded
Request example
json
An example of request implementation:
urlencoded
An example of request implementation:
Response options
1* Parameter is required if you need to go through the scriptchallenge-flow
1* Transmitted if the reply containsSuccess=true
2* Transmitted if the reply containsSuccess=false
Sample response
An example of a response to a successful request:
An example of a response to an unsuccessful request:
3-D Secure version 2 authentication follows one of two scenarios:, frictionless-flowor challenge-flow. Scenario authenticated, it depends on the availability of the parameters ACSUrl, CReqin response to the request Block3DS.
Walkthrough scenario challenge-flow:
After receiving a response from the gateway, the merchant redirects the cardholder to the site of the issuing bank for additional authentication. To do this, use a POST request to the address specified in the attribute value ACSUrl, the composition of the request:
After authorization on the issuing bank's website, the user is returned by an HTTPS POST request to the address specified in the term_urlrequest Blockparameter with the parameter specified below.
After receiving the parameter, the cresmerchant sends a request to Block3DS to complete the script challenge-flow:
Request parameters
json
urlencoded
1* Parameter is required when passingchallenge-flow
Request example
json
Sample POST request:
An example of implementing a request in the program code:
urlencoded
Sample POST request:
An example of implementing a request in the program code:
Response options
1* Transmitted if the reply containsSuccess=true
2* Transmitted if the reply containsSuccess=false
Sample response
An example of a response to a successful request:
An example of a response to an unsuccessful request:
In case of a one-step payment (in the case of using the Pay method), you must use the Pay3DS method instead of the Block3DS method to complete the 3-DS operation.
When saving a card involved in 3-D Secure technology, to complete the operation and receive a card ID in response, you must use the StoreCard3DS method.
The request, response parameters and field compositions of the Pay3DS and StoreCard3DS methods are similar to the Block3DS method.
Requirements for posting information on the company's website
* to ensure the confidentiality of the information of Cardholders and to ensure the security of the Operations
The requirements below are mandatory for an online store that accepts payments through merchant Processing Center for review and implementation. The compliance of the website of the online store with the requirements presented in the document allows you to minimize the risk of Fraudulent transactions and subsequent financial costs to pay off fines when buyers initiate returns, as well as eliminate the risk of leakage of confidential information of Buyers through the website of the online store. In accordance with the rules and recommendations and acquiring banks, the online store must provide its own methods of control and minimization of risks to prevent fraudulent transactions when accepting payments using bank cards.
1. Contacts and details
1.1. Phone number with hours of operation.
1.2. E-mail address.
1.3. The actual address of the company.
1.4. Full name of the legal entity.
1.5. State registration number of a legal entity or individual entrepreneur.
The presence on the website of the online store of a section containing contact information and company details is mandatory. The data is required to successfully pass the verification at the acquiring bank. Lack of data may become the basis for refusal of the acquiring bank in cooperation with the online store.
2. Description of the payment process, logos of payment systems and merchant
2.1. The website of the online store should contain (it is recommended to place it in the "Payment" section) a list of available payment methods for the order and a description of the payment process for each of the available tools. The description of the process of paying for the order by bank cards must contain information about merchant processing center.
2.2. The website of the online store must contain a description of the process and conditions (including possible penalties) for refunding money to the Buyer's card when the Buyer refuses to order, exchange or provide interchangeable goods or services. If a refund procedure is not provided, the information should be posted on the website of the online store.
2.3. On the website of the online store (in the section "Payment for the order" or in the "basement" of the site), the logos of merchant processing center and payment systems (VISA, MasterCard and MIR) must be placed.
The lack of information on the conditions for the return creates the risk of penalties if the Buyer initiates a refund through the Bank or the Payment System, and the conditions for the return will not be described on the website of the online store.
3. Description of the order delivery process
3.1. The website of the online store must contain the terms, methods, conditions, as well as any other information necessary to obtain a clear and clear idea of the delivery of goods and the provision of services after payment by credit card.
3.2. The website of the online store should contain detailed information about the restrictions on the delivery of goods / services to certain regions, as well as export restrictions and rules for the delivery of goods / services outside the Europa/USA/Asia (if there are such restrictions).
The lack of information on the conditions, cost and delivery time creates the risk of penalties if the Buyer initiates a refund through the Bank or the Payment System due to the failure to provide the service (due to long delivery), and the conditions and delivery times will not be described on the website of the online store.
4. List and description of goods (services)
4.1. Each product or service page should contain a detailed description:
4.3. The list of goods or services sold on the site must fully correspond to the goods and services listed in the merchant's questionnaire, as well as in the agreement with the acquiring bank.
4.4. If the range of goods or services changes, merchant must notify merchantat least 5 working days before the changes are reflected on the website. The notification is sent in the form of an official letter.
A detailed and correct description is necessary to minimize the risk of a forced refund or opposition to payment by the buyer due to insufficient information about the product.
5. Domain and hosting
5.1. The website of the online store must be located on a second-level domain (example: www.shop.com) and contain at least 2 and no more than 11 characters.
5.2. All pages and interfaces related to the operation of the site must be under a single domain name.
5.3. It is allowed to host the connected website on a third-level domain (example: www.internet.shop.com) if the main site of the company is located on the same second-level domain.
5.4. The site should not be located on free servers that provide hosting services or free domains, as well as on social media pages (VK, Facebook, Instagram, etc.).
Placing a site on a third-level domain or on free hosting may become the basis for the acquiring bank's refusal to cooperate with the online store.
6. Security of personal data of Buyers
6.1. It is not allowed to request bank card details (PAN, CVC2 / CVV2, Expiration Date) on the pages of the online store.
6.2. When paying with a bank card, the buyer must be redirected to merchant's's secure payment form to enter their bank card details.
6.3. The secure payment form merchantshould be presented as a standard browser window with all standard features.
6.4. It is not allowed to place a payment form in a pop-up window (Pop-Up).
6.5. Placing a payment form using an Iframe (integrating a payment form into a website page) is not allowed without the approval of merchant.
Violation of the rules for processing personal data of Buyers may result in the imposition of penalties on the online store and the processing center.
7. Functional authorization and personal account of the Buyer
7.1. It is recommended to provide Buyers with the opportunity to register - and provide the ability to make payments by bank cards only to registered Buyers.
7.2. It is recommended to store the database of registered customers on the side of the online store. The minimum storage period for the database is 7 months.
7.3. It is recommended to provide for the possibility of a direct transition from any page of the website of the online store to the registration form and merchant's payment form.
7.4. It is recommended to provide for the sending of registration data to the email address specified by the buyer.
It is recommended to implement the "Personal Account" of the online store client on the site to save the history of user orders. The history of the formation of orders may be required in case of receiving requests for this information from the acquiring bank.
What is merchants API
API is designed for merchants interested in accessing a flexible and flexible solution for automating electronic payments with bank cards.
API provides the integration of the merchant's service with merchants payment gateway, which guarantees high reliability and security of customers' payment transactions.
Content:
- Ways of payment
- The basics
- ApplePay
- Google pay
- QR Code (SBP)
- Embedded solutions
- Installing merchants Widget
- merchants payment form
- Ready modules for CMS
- Bitrix
- WordPress (WooCommerce plugin)
- Payments
- Recurring payments
- Using 3DS Verification
- Additionally
- Order statuses
- Error codes
- Test Cards
- Description of API methods
- Block - blocking funds on the card
- Init - Create a payment session
- createPayment - Call a payment form
- Charge - Write-off of blocked funds
- Unblock - Unlocking funds on the card
- Refund
- Pay - One-step payment
- getState - Get the status of the payment
- createUser - Create a new user
- storeCard - Register (save) card
- removeCard - Remove card
- listCard - Request a list of registered cards
- Block3DS - Using 3D Secure Technology
- Payout - Crediting funds to the card
- getReceipt - request fiscal data for an order
- Using 3-D Secure technology version 1
- Using 3-D Secure technology version 2
- Requirements for posting information on the company's website
The basics
Bank cards
You can accept bank cards of International Payment Systems for payment: Visa (including Electron), Mastercard, Maestro, MIR, and optionally JCB, Amex, UnionPay, DinersClub, BelKart, Arka.
By default, the user will enter bank card details on merchants payment gateway page, but you can embed the form on your website or mobile application.
Apple Pay, Google Pay
Thanks to merchant, the user can pay using Apple Pay and Google Pay.
QR Code (SBP)
Thanks to merchant, a user can pay for a product/service using a new method - QR Code payment (QR Code), both from a mobile device and from the Web version.
ApplePay
merchants provides the ability to write off funds from the Buyer's card using the Apple Pay token instead of the card details.
To make a payment using Apple Pay, you must:
- Register for the Apple Developer Program
- In case of using a mobile app, get Apple approval
- Verify Domain Ownership
- Get a Certificate Signing Request (CSR) file from merchant
- Using the received CSR, create a certificate in the Apple Partner Center
- Submit the generated certificate to merchant
Google pay
Google Pay™ allows customers to make payments in your app or website using any credit or debit card stored in their Google account, including from Google Play, YouTube, Chrome, or Android device.
Google Pay™ is fully compatible with merchants products and features, allowing you to use it instead of the traditional form of payment whenever possible. Use it to accept payments for physical or digital goods, donations, subscriptions, and more. Payments for digital goods only apply to Web and mobile Web payments.
Principle of operation
- The customer selects the Google Pay button. Using the Google API, your system initiates a Google Pay request identifying the cyber resource as your payment gateway, passing your CyberSource merchant ID as the gateway merchant ID.
- The client confirms the payment. The Google API communicates with Google Pay services. A token is generated on the payment network.
- Google generates encrypted payment data using a special gateway key that is provided in the wallet request and includes it in the Google API response.
- Your system prepares Google Pay data to be sent to merchant. The PaymentData received from the Google API is base64 encrypted and passed as a GooglePayToken parameter to the Pay and Block methods.
- merchant returns an authorization response for your system.
- Your system returns an authorization response to the payment application / site. The payment app / site displays a confirmation or opt-out message to the customer.
Integration
To receive payments, fill out the registration form, after which a Google representative will contact you and instruct you on the next steps. Integration examples:
WEB-site
- Website Integration Guide.
- Use the checklist to verify that you have completed all the necessary steps in your Web integration.
- Follow the steps to help you place your Google Pay branding elements on your websites.
An example of tokenization:
Code:
const tokenizationSpecification = {
type: 'PAYMENT_GATEWAY',
parameters: {
'gateway': 'merchant's',
'gatewaymerchantId': 'exampleGatewaymerchantId'
}
}- gateway: merchant's
- gatewaymerchantId: Public ID, issued via merchant's support
An example of installing payment systems supported by Google Pay and merchant:
Code:
const allowedCardNetworks = ["AMEX", "JCB", "MASTERCARD", "VISA"];Android App
- Android Application Integration Guide.
- Use the checklist to check that you have completed all the necessary steps in Android integration.
- Follow the steps to help you correctly place Google Pay brand elements in Android mobile apps.
An example of tokenization:
Code:
private static JSONObject getTokenizationSpecification() {
JSONObject tokenizationSpecification = new JSONObject();
tokenizationSpecification.put("type", "PAYMENT_GATEWAY");
tokenizationSpecification.put(
"parameters",
new JSONObject()
.put("gateway", "themerchantname")
.put("gatewaymerchantId", "examplemerchantId"));
return tokenizationSpecification;
}- gateway: merchant's
- gatewaymerchantId: Public ID, issued via merchant's support
An example of installing payment systems supported by Google Pay and merchant:
Code:
private static JSONArray getAllowedCardNetworks() {
return new JSONArray()
.put("AMEX")
.put("JCB")
.put("MASTERCARD")
.put("VISA");
}Interaction with merchant's
As a result of tokenization, you should receive a Google Pay token, which looks something like this:
Code:
{
"protocolVersion":"ECv2",
"signature":"MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q\u003d\u003d",
"intermediateSigningKey":{
"signedKey": "{\"keyExpiration\":\"1542323393147\",\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/1+3HBVSbdv+j7NaArdgMyoSAM43yRydzqdg1TxodSzA96Dj4Mc1EiKroxxunavVIvdxGnJeFViTzFvzFRxyCw\\u003d\\u003d\"}",
"signatures": ["MEYCIQCO2EIi48s8VTH+ilMEpoXLFfkxAwHjfPSCVED/QDSHmQIhALLJmrUlNAY8hDQRV/y1iKZGsWpeNmIP+z+tCQHQxP0v"]
},
"signedMessage":"{\"tag\":\"jpGz1F1Bcoi/fCNxI9n7Qrsw7i7KHrGtTf3NrRclt+U\\u003d\",\"ephemeralPublicKey\":\"BJatyFvFPPD21l8/uLP46Ta1hsKHndf8Z+tAgk+DEPQgYTkhHy19cF3h/bXs0tWTmZtnNm+vlVrKbRU9K8+7cZs\\u003d\",\"encryptedMessage\":\"mKOoXwi8OavZ\"}"
}The token must be Base64 encoded without any modifications and sent to merchant's. An example of a Base64 encoded token:
Code:
ewogICJwcm90b2NvbFZlcnNpb24iOiJFQ3YyIiwKICAic2lnbmF0dXJlIjoiTUVRQ0lINlE0T3dRMGpBY2VGRWtHRjBKSUQ2c0pOWHhPRWk0cittQTdiaVJ4cUJRQWlBb25kcW9VcFUvYmRzckFPcFpJc3JIUVM5bndpaU53T3JyMjRSeVBlSEEwUVx1MDAzZFx1MDAzZCIsCiAgImludGVybWVkaWF0ZVNpZ25pbmdLZXkiOnsKICAgICJzaWduZWRLZXkiOiAie1wia2V5RXhwaXJhdGlvblwiOlwiMTU0MjMyMzM5MzE0N1wiLFwia2V5VmFsdWVcIjpcIk1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRS8xKzNIQlZTYmR2K2o3TmFBcmRnTXlvU0FNNDN5UnlkenFkZzFUeG9kU3pBOTZEajRNYzFFaUtyb3h4dW5hdlZJdmR4R25KZUZWaVR6RnZ6RlJ4eUN3XFx1MDAzZFxcdTAwM2RcIn0iLAogICAgInNpZ25hdHVyZXMiOiBbIk1FWUNJUUNPMkVJaTQ4czhWVEgraWxNRXBvWExGZmt4QXdIamZQU0NWRUQvUURTSG1RSWhBTExKbXJVbE5BWThoRFFSVi95MWlLWkdzV3BlTm1JUCt6K3RDUUhReFAwdiJdCiAgfSwKICAic2lnbmVkTWVzc2FnZSI6IntcInRhZ1wiOlwianBHejFGMUJjb2kvZkNOeEk5bjdRcnN3N2k3S0hyR3RUZjNOclJjbHQrVVxcdTAwM2RcIixcImVwaGVtZXJhbFB1YmxpY0tleVwiOlwiQkphdHlGdkZQUEQyMWw4L3VMUDQ2VGExaHNLSG5kZjhaK3RBZ2srREVQUWdZVGtoSHkxOWNGM2gvYlhzMHRXVG1adG5ObSt2bFZyS2JSVTlLOCs3Y1pzXFx1MDAzZFwiLFwiZW5jcnlwdGVkTWVzc2FnZVwiOlwibUtPb1h3aThPYXZaXCJ9Igp9merchant's API supports the transfer and processing of a token in two methods: Block and Pay in the GooglePayToken parameter. An example of a request for a one-step payment Pay:
Code:
Key=GooglePayTestTerminal&GooglePayToken=ewogICJwcm90b2NvbFZlcnNpb24iOiJFQ3...&OrderId=GooglePayTestOrder-001&Amount=101As a result of the successful execution of the scenario from the example above, the client's funds will be authorized and debited using merchant's and Google Pay. An example of a successful response:
Code:
{
"Success": true,
"OrderId": "GooglePayTestOrder-001",
"Amount": 101,
"ErrCode": ""
}If you receive an erroneous response, please check the correctness of the Base64-encoded token, the correctness of its transmission and other parameters. If the data is correct, refer to merchant error dictionary
Google Pay Terms of Service
Please read these guidelines to properly use Google Pay technology and brand in mobile apps and websites.
- Google Pay cannot be used to pay for goods / services that are prohibited for sale on the Internet
- Google Pay Brand Guidelines
- Before you start working with Google Pay, you need to go through the registration procedure and check the WEB-site and / or mob. apps on Google.
QR Code (SBP)
The UBS QR code is a graphic image, when decrypted, all the necessary payment information becomes available - bank details, the amount and purpose of the payment. Thanks to graphical security, payment information is encrypted and protected from reading without the special software that is available in the mobile phone.
The UBS QR-code can be of two types: QRS - static QR-code ("QR-sticker") and QRD - dynamic QR-code ("QR at the checkout").
Interaction scenarios:
- Entering data on the Seller's side
- Entering data on merchant payment form
Entering data on the Seller's side
The interface offers the ability to receive a payment link or generate a QR code for payment using the Fast Payment System (FPS).
After confirmation of payment by the Client, the Seller receives a notification of the result of the payment in the form of a POST request.
To make a payment using the UBS QR code, the User must have a mobile application of a bank participating in the Fast Payments System.
Available methods:
- Formation of the QR-code of the SBP
- Obtaining a previously generated QR-code of the UPS
- Refunds
- Receiving payment status
Embedded solutions
Installing merchant Widget
In order to start accepting payments, the merchant needs to place a simple script on his page that will create a session and generate a payment page. An example of how the merchant's solution interacts with merchant payment gateway with Easy Integration:
To install the widget, you need to register a script on the site in the head section:
Code:
<script type="text/javascript" src="https://static-stage.mapisacard.com/static/widget/merchant-widget.js"></script>Further, for any event (for example, pressing the payment button), a call to the widget is prescribed. For example:
Code:
<button id="pay_button" onclick="openWidget()">Pay</button>Calling the widget with the necessary parameters should be placed on the page before the closing tag </body>
Code:
<! - The openWidget function can look like this ->
function openWidget() {
var widget = new merchantWidget({
Token: "Jms7xd95Cv30S3Mri7Xfp3md8cn3lxmD5Xb47Hg8Bl9Dm8cF6Hbsl3VgP21KioIo",
OrderID: "merchant_widget_2021",
Amount: 1999000,
Currency: "EUR",
ProductName: "Telephone",
Receipt: true,
Email: "example@merchant.com",
AutoClose: true
})
}Widget options:
Widget parameters that are passed to its constructor
| Name | Description | Format | Mandatory |
|---|---|---|---|
| Token | Session key | Line | Yes |
| OrderID | Payment ID in the merchant's system | String (maximum 50 characters) | Yes |
| Amount | Transaction amount in minimum currency units | Digits with no decimal or other separators | Yes |
| Currency | Terminal currency | Line | Yes |
| Product | Name of product | String (maximum 50 characters) | Not |
| Receipt | Require the indication of the user's e-mail address in the widget | true / false | Not |
| User email address | Line | Not | |
| AutoClose | Auto-close the widget. Default valuefalse | true / false | Not |
Progress
After launching the constructor with parameters, it checks for the device screen size and checks whether the page is open on a mobile device. The page is scaled for correct and convenient display of the widget.
The HTML code of the widget is generated. The code is embedded in the body section by adding it as a child node to the tag. The elements are given a large z-index style attribute so that they overlap the page when displayed. Initially, all items are hidden.
Loading the widget. A POST request is created with the data contained in the widget. The answer is a template that contains fields to fill out and a payment button. This template is loaded into the <iframe>widget element.
After the payment is made, the widget is closed and sent postMessagewith the result of the payment paymentResult. Its HTML code is removed from the main page.
Marchant payment form
This guide describes how to work with templates for entering payment card data on the gateway side. We have tried to create a flexible tool that will allow you to quickly create your own payment scenarios.
Attention! Templates should not contain links to third-party resources. If you would like to add your own scripts, images or styles, you must send them to merchant support team.
The default payment form template consists of two files:
- index.html (card data entry page)
- result.html (payment result page)
Form template settings
| Name | Description | Format | Default |
|---|---|---|---|
| Secret | Session key. Required parameter. | {{.Secret}} | |
| Amount | Amount of payment. Transmitted during the initialization of the payment session | {{. Amount}} | |
| Currency | Terminal currency. Taken from the terminal settings | {{.Currency}} | EUR |
| SessionType | Session type. Pay - payment session. Add - card binding | {{.SessionType}} | Pay |
| AllowNewCard | Possibility to pay with a new card, if there are linked cards | {{.AllowNewCard}} | true |
| IsReceipt | Includes the email field if the terminal supports data transfer for fiscalization in accordance | {{.IsReceipt}} | false |
| Email that was passed during session initialization in CustomParams. Substituted in the email field | {{.Email}} | ||
| HasUserCred | Determines whether the session is authorized during initialization by user / customer. | {{.HasUserCred}} | false |
| AddCard | A parameter that specifies whether to save the card after payment. The value is taken from the transmitted AddCard value when initializing the session | {{.AddCard}} | false |
| ShowOrderId | Show / hide order number | Boolean | true |
| ShowDescription | Show / hide order description passed in CustomParams | Boolean | true |
| ShowAmount | Show / hide order amount | Boolean | true |
| ShowCVV | Show / hide the CVV field if there is a corresponding setting in the terminal | Boolean | true |
Payment result template settings
| Name | Description | Format | Default |
|---|---|---|---|
| RedirectUrl | The user's return address. Sent when initializing a session (or terminal). Required parameter | {{.RedirectUrl}} | |
| State | Page type | String | Result |
| Result | The result of the payment. Required parameter | {{.Success}} | |
| RedirectDelay | Delay in milliseconds before redirecting the user to the return page | Number | 1000 |
| ResultText | Payment result text | Object | {success: "Payment was successful", fail: "Payment error"} |
You can make a payment template without entering the cardholder. In this case, in the template settings, you must add a key Holderand set a string with a stub for transferring data to processing. The string must contain at least three Latin characters.
Code:
{
...
Holder: "Mr Cardholder",
...
}You can change the text on the button, for this you need to pass a parameter ButtonTextwith the text for the session type
Code:
{
...
ButtonText: {
Pay: "Pay",
Add: "Add card"
}
...
}or if PayButtonCustomText is specified on Init in CustomParams (For example, )PayButtonCustomText=Activate Promo Code
Code:
{
// ...
ButtonText: {
Pay: "{{index .CustomParams "PayButtonCustomText"}}",
}
// ...
}To display additional parameters on the payment template, transferred during the initialization of the payment session, you must specify the parameter name in quotation marks.
Code:
{{index .CustomParams "Test"}}Ready modules for CMS
merchants offers a turnkey solution for online stores based on CMS Bitrix and WordPress (plugin WooCommerce). In order to start accepting payments, the merchant needs to install the merchant Payment plugin on his page, with which the User will be redirected to merchant payment form. Upon successful payment, the User will be returned back to the store's website.
Bitrix
Installation instructions for the CMS 1C-Bitrix module.
Go to Administration Tab, Marketplace Solution Catalog.
Install the merchant payment acceptance module.
After successful installation, go to Store> Settings> Payment systems.
Add payment system.
In the "Handler" field, select merchant.
Payment type - "Non-cash", Encoding - "utf-8"
The values of the parameters "merchant ID", "Password", "Payment gateway address" will be provided in a letter from merchant.
WordPress (WooCommerce plugin)
Installation instructions for CMS WordPress module (WooCommerce plugin).
Download and install the WooCommerce plugin.
Unpack merchant.zip archive.
Go to WooCommerce> Settings> Payments.
Configure merchant Method.
The values of the "Payment gateway address", "merchant ID" and "Password" parameters will be sent in an email from merchant.
Payments
Recurring payments
merchant provides the ability to make regular debits from the user's card without entering the card details. A prerequisite for making recurring payments is preliminary registration of the User in merchant's system and saving the card from which recurring payments will be made. To save the card, the storeCard method is used - in the case of using the payment form on the merchant's side, or the Init, Type = Pay, AddCard = True method - in the case of using the payment form on merchant side. In this case, when saving the map, you must pass the parameters Recurrent = true, as well as OrderId and BlockAmount to perform the first operation that initiates the recurrent.
Subsequent debits are performed without entering the full card details.
Using 3DS Verification
The 3-D Secure technology minimizes the risks of card fraud for merchants, since the issuing bank is responsible for the transaction performed with 3DS verification. At the same time, the payment scheme and the format of requests are slightly changed. When initiating a payment, the payment gateway checks the card's involvement in the 3-D Secure technology and receives the necessary parameters for user authentication. Then the user is redirected to the page of the issuing bank to enter the password, after which the system generates the PaRes parameter to complete the authorization. A detailed description is provided in Block3DS.
Service of notifications
Notifications are notifications (POST) containing information about the performed operation, sent to the URL specified by the merchant in advance in a letter to merchant. The service sends the following types of notifications:
| Notification type | Description |
|---|---|
| Block | Funds blocking notification |
| Block3DS | Notice of blocking funds in case of using 3D Secure technology |
| Unblock | Unlock notification |
| Charge | Debit notification |
| Refund | Return notice |
| Pay | One-step debit notification (Pay method) |
| Pay3DS | Notification of a one-stage write-off in case of using 3D Secure technology (Pay3DS method) |
| AddCard | Card save notification |
Composition of notification fields:
| Parameter | Description | Format |
|---|---|---|
| merchantContract | Seller ID. | Line |
| OriginalOrderId | Payment ID in the merchant's system | Line |
| merchantOrderId | Unique payment identifier in merchant's system | Line |
| Amount | Transaction amount | Corresponds to the one passed in the request |
| AuthCode | Authorization code | Line |
| RRN | RRN operations | Line |
| Success | Operation success flag | true / false |
| CardNumber | Masked card number | 411111xxxxxx1111 |
| BankName | The parameter is optional. Issuing bank name | Line |
| ErrCode | Error code | Line |
| State | Order status at the time of sending the notification | Line |
| Notification | Notification type | Line |
| CardUID | ID of the card in the merchant's system. Notifications with the AddCard type are transmitted, as well as in the case of payment using CardUID | Line |
| CustomParams | The parameter is optional. List of additional parameters of the operation | Line |
| FeePercent | The parameter is optional. Acquiring commission rate | Number (hundredths of a percent) |
| TerminalID | The parameter is optional. Id of the terminal in the merchant's system, on which the operation was actually performed | Number |
| Signature | The parameter is optional. String - the result of hashing according to the HMAC-SHA-256 algorithm, URL encoded parameter strings that are sent in notifications, sorted alphabetically | Line |
Based on the result of sending notifications, in agreement with the merchant, an active action on the order can be configured. For example, in case of receipt of the 422nd response code for the Block notification, or failure to receive a response within the specified period, merchant independently initiates the unblocking of funds. The functionality is optional.
Additionally
Order statuses
| Status | Order status in LC | Description |
|---|---|---|
| New | New | The payment was registered in the gateway, but its processing in processing has not started |
| PreAuthorized3DS | 3DS pre-authorization | The user started authentication using the 3-D Secure protocol, at which the payment operations were completed |
| Authorizing | Authorization | Funds blocking process started |
| Authorized | Authorized | Funds are blocked, but not debited (2-stage payment) |
| Voiding | Cancellation | Funds unblocking process started |
| Voided | Canceled | Funds on the card have been blocked and unblocked (2-stage payment) |
| Charging | Write-off | The process of debiting the blocked amount has been started |
| Charged | Decommissioned | The funds were debited from the User's card, the payment was completed successfully |
| Refunding | Returns | The process of returning the debited amount has been launched |
| Refunded | Returned | A full refund has been successfully made to the User's card |
| Verifying payout opportunity | Checking the possibility of payment | Card verification for enrollment |
| Payout ready | Ready to pay | Card verification for enrollment has been successfully completed |
| Paying | Pay | Payment process started |
| Paid | Paid out | Enrollment to the card has been successfully completed |
| Rejected | Rejected | Order declined |
Error codes
| Error | Description |
|---|---|
| ACCESS_DENIED | Access from the current IP or the specified parameters is denied |
| AMOUNT_ERROR | Incorrect transaction amount |
| AMOUNT_EXCEED | The transaction amount exceeds the available balance of the selected account |
| AMOUNT_EXCEED_BALANCE | The transaction amount exceeds the available balance of the selected account |
| AUTHENTICATION_ERROR | 3DS Authentication Error |
| CARD_NOT_ACTIVE | Card is not active |
| COMMUNICATE_ERROR | An error occurred when transferring data to the MPS |
| CUSTOMER_NOT_FOUND | Card holder not found |
| DATABASE_TIMEOUT | Database timeout |
| DUPLICATE_CARD | Card is already registered |
| DUPLICATE_ORDER_ID | The order number has already been used before |
| DUPLICATE_PROCESSING_ORDER_ID | The order number was previously used in bank processing |
| DUPLICATE_TERMINAL | Terminal is duplicated |
| DUPLICATE_TRANSACTION_TRACE | Duplicate transaction status |
| EMPTY_RESPONSE | Processing error |
| ENCODING_ERROR | Error decoding secondary system response |
| FRAUD_ERROR | Invalid transaction according to anti-fraud filter settings |
| ILLEGAL_ORDER_STATE | An attempt was made to perform an invalid operation for the current state of the payment |
| INTERNAL_ERROR | Incorrect transaction format from the point of view of the network |
| INVALID_AUTHENTICATION | Invalid authentication |
| INVALID_ENROLLMENT | The card has not passed the 3D Secure engagement test |
| INVALID_FORMAT | Incorrect transaction format from the point of view of the network |
| ISSUER_BLOCKED_CARD | The cardholder is trying to perform a transaction that is not allowed for him by the issuing bank, or an internal issuer error has occurred |
| ISSUER_CARD_FAIL | The issuing bank has banned Internet card transactions |
| ISSUER_FAIL | The cardholder is trying to perform a transaction that is not allowed for him by the issuing bank, or an internal error of the issuer |
| ISSUER_LIMIT_AMOUNT_FAIL | An attempt was made to complete a transaction in excess of the (daily) limit set by the issuing bank |
| ISSUER_LIMIT_COUNT_FAIL | Exceeded the limit on the number of transactions: the client has completed the maximum allowed number of transactions during the limit cycle and is trying to conduct another |
| ISSUER_LIMIT_FAIL | An attempt was made to exceed the limits of the issuing bank by the amount or the number of transactions in a certain period of time |
| ISSUER_TIMEOUT | No connection with the issuing bank |
| LIMIT_EXCHAUST | Time or number of attempts allotted for data entry is exhausted |
| merchant_NOT_FOUND | merchant not found |
| merchant_RESTRICTION | The Store limit has been exceeded or transactions are prohibited by the Store |
| NO_CHAIN | Initiating recurrent not found |
| NO_SESSION | Session not found |
| NO_TRANSACTION_ID | Transaction_id not found |
| NONE | Operation completed without errors |
| NOT_ALLOWED | Refusal of the issuer to conduct the transaction. Most often occurs when prohibitions are imposed on the map |
| NOT_AUTHED | Authentication error |
| NOT_FOUND | Not found |
| ORDER_NOT_FOUND | Transaction not found |
| SESSION_EXPIRED | Payment (session) timed out |
| PAYMENT_ENGINE_ERROR | Unidentified payment gateway error |
| PROCESSING_ERROR | A general error in the functioning of the system. Fixed by the payment network or the issuing bank |
| PROCESSING_FRAUD_ERROR | Invalid transaction according to the Antifraud filter settings in the Acquiring Bank |
| PROCESSING_TIME_OUT | Processing timeout |
| REAUTH_NOT_ALOWED | Authorization amount change cannot be performed |
| REFUND_NOT_ALOWED | Refund could not be completed |
| TERMINAL_NOT_FOUND | Terminal not found |
| THREE_DS_FAIL | Unable to execute 3DS transaction |
| THREE_DS_TIME_OUT | The validity period of the transaction was exceeded by the time the card data was entered |
| TRANSACTION_NOT_3DS_PREAUTHORIZED | Attempted 3DS authorization with a card that does not support 3DS technology |
| TRANSACTION_NOT_AUTHORIZED | Transaction not authorized |
| TRANSACTION_NOT_CHARGED | Transaction not debited |
| TRANSACTION_NOT_FOUND | Transaction not found |
| TRANSACTION_REFUNDED_OR_REFUNDING | Transaction has been returned or is in the process of being returned |
| TRANSACTION_STATE_CHARGED_OR_CHARGING | Transaction status has been debited or in the process of being debited |
| TRANSACTION_STATE_REJECTED | Transaction declined |
| TRANSACTION_TRACE_NOT_FOUND | Transaction status not found |
| TRANSACTION_VOIDED_OR_VOIDING | The transaction is unlocked or in the process of unlocking |
| UNKNOWN_STATE | Unknown status |
| USER_NOT_FOUND | User is not found |
| WRONG_AMOUNT | Invalid amount |
| WRONG_CARD | Invalid card parameters were transferred, or the card is in an invalid state |
| WRONG_CARD_EXP | Incorrect card expiration date |
| WRONG_CARD_INFO | Incorrect card information |
| WRONG_CARD_PAN | Invalid card number |
| WRONG_CARDHOLDER_NAME | Invalid cardholder name |
| WRONG_CURRENCY | Invalid currency |
| WRONG_PARAMS | Invalid parameter set or format |
| WRONG_PAY_INFO | Incorrect PayInfo parameter (incorrectly formed or broken cryptogram) |
| WRONG_PHONE | Invalid phone number |
Test Cards
Payment amount - From 0.1 to 1 euro/usd.
Cardholder - any name, in this case only Latin characters or a space should be used. The cardholder's name must be at least three characters long.
Using the parameters of valid bank cards during testing is strictly prohibited!
| Card number | CVV | Validity | Result |
|---|---|---|---|
| 4111111111111112 | 123 | 2021/12 | successful payment without 3DS |
| 4111111111100031 | 123 | 2021/12 | successful payment without 3DS |
| 4111111111100023 | 123 | 2021/12 | successful payment without 3DS |
| 5486732058864471 | 123 | 2021/12 | successful payment with 3DS |
| 4111111111111111 | 123 | 2021/12 | successful payment with 3DS |
| 4111111111111114 | 123 | 2021/12 | unsuccessful payment with 3DS |
| 4111111111111115 | 123 | 2021/12 | unsuccessful payment with 3DS |
| 4111101000000046 | 123 | 2021/12 | unsuccessful payment ("insufficient funds") during blocking (if the amount exceeds 1 euro (Amount = 101)) |
| 4111111111100627 | 123 | 2021/12 | "PROCESSING_ERROR" during unlocking |
Description of API methods
Interaction of the merchant's solution with merchant payment gateway during integration is based on a request-response scheme.
A request with the necessary parameters is formed on the Seller's side and is transmitted by the POST method (GET - for the createPayment method) in the JSON or x-www-form-urlencoded format over the HTTPS (TLS 1.2) protocol.
For example: https://{domain}/{Command} where {domain}is the URL address of the payment gateway, {Command}is the name of the command (method).
The results of processing requests are issued by the payment gateway synchronously in JSON format, UTF-8 encoding.
Parameter names in queries are case sensitive.
merchant also provides the ability to use asynchronous notifications.
Block - blocking funds on the card
Performed using the Block command. This request allows you to block funds on the Buyer's card for subsequent debiting. The identifier of the registered card or the full details of the card can be specified as a card. Blocked funds can then be debited by the Charge command or unblocked by the Unblock command.
Request parameters
| Name | Description | Format | Mandatory |
|---|---|---|---|
| Key | Seller ID. Issued to the Seller with test / combat access parameters | Line | Yes |
| PayInfo | Parameters for making a transaction | Url Encoded string containing pairs of keys and their command values, separated by ";" (semicolon). Keys and values are separated by "=" (equal) | Mandatory if there is no CardUID |
| OrderId | Payment ID in the merchant's system | String (maximum 50 characters) | Yes |
| Amount | Blocked amount in minimum currency units | Digits with no decimal or other separators | Yes |
| Login * | Login of the cardholder registered in the merchant's system | String (maximum 50 characters) | Not |
| Password * | Password of the cardholder registered in the merchant's system | String (maximum 50 characters | Not |
| CardUId | Map ID in merchant's system or "Random" value ** | String (maximum 50 characters) | Mandatory if PayInfo is absent |
| TerminalPassword *** | Terminal password for transactions | String (maximum 50 characters | Not |
| merchant **** | Seller name | String (maximum 50 characters | Not |
| merchantPassword **** | merchant password for transactions | String (maximum 50 characters | Not |
| Goods | List of names of goods / services to be sent to the OFD (54-FZ) | A string containing pairs of keys and their command values, separated by ";" (semicolon). Keys and values are separated by "=" (equal). The total amount of all goods must correspond to the Amount. Length of one name - no more than 128 characters | Not |
| Params | List of additional parameters of the operation | A string containing pairs of keys and their command values, separated by ";" (semicolon). Keys and values are separated by "=" (equal) | Not |
| Split | Used to divide the amount of the write-off made into its component parts for subsequent settlements with counterparties | A string containing groups of key-value pairs, where groups are enclosed in curly braces {}, key-value pairs are separated by a “,” (comma). Key and value are separated by ":" (colon). The line is enclosed by square brackets "[]". The parameters of keys and values are issued to the Seller with the parameters of test / combat access. The total sum of all components must correspond to the Amount | Not |
The composition of the keys of the PayInfo parameter:
| Name | Description | Format |
|---|---|---|
| PAN | Card number or its identifier | PAN - digits without spaces |
| EMonth | Card expiration month | 2 digits with a leading zero |
| EYear | Card expiration year | 2 digits (last digits of the year) |
| CardHolder | Surname and name of the cardholder | string (maximum 30 characters, Latin letters or space) |
| SecureCode | CVC2 / CVV2. The parameter is optional | Numbers |
Format of the parameter:
Code:
Goods Goods = Price, Characteristic of the subject of calculation, VAT rate | {Supplier data}| Name | Description | Format |
|---|---|---|
| Price | Blocked amount in minimum currency units | Digits with no decimal or other separators |
| Calculation subject attribute | 1 - Goods, 2 - Excisable goods, 3 - Work, 4 - Service, 5 - Gambling rate, 6 - Winning a gambling, 7 - Lottery ticket, 8 - Winning a lottery, 9 - Provision of RID, 10 - Payment, 11 - Agency fee, 12 - Composite subject of calculation, 13 - Other subject of calculation | Number from 1 to 13. The parameter is optional. If not in the request, the value is taken from the terminal settings |
| VAT rate | 1 - VAT rate 20%, 2 - VAT rate 10%, 3 - VAT rate calc. 20/120, 4 - VAT rate calc. 10/110, 5 - VAT rate 0%, 6 - VAT exempt | Number from 1 to 6. This parameter is optional. If not in the request, the value is taken from the terminal settings |
| Supplier data | "name" - Name, "phoneNumbers" - list of phone numbers, "supplierINN" - supplier's INN | JSON string. The parameter is optional |
Example of transferring Goods:
Code:
Service = 100,4,1 | {"name": "LLC Name", "phoneNumbers": {["+11111111111"]}, "supplierSNN": "77777777"}; Service = 810,2 | {"name" : "LLC Name", "phoneNumbers": {["+11111114859"]}, "supplierSNN": "777757777"}; Service2 = 20.4; Product = 30Request example
Sample POST request: https: // {domain} / Block Key: TestTerminal Amount: 300 OrderId: TestOrder123 PayInfo: PAN% 3D4111111111100023% 3BEMonth% 3D12% 3BEYear% 3D21% 3BCardHolder% 3DTEST% 20TESTOV% 3BSecureBode% 3Dms: Email =user@example.com
An example of implementing a request in the program code:
Code:
curl -X POST \
https://https://{domain}/Block \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'Key=TestTerminal&Amount=300&OrderId=TestOrder123&PayInfo=PAN%253D4111111111100023%253BEMonth%253D04%253BEYear%253D21%253BCResponse options
| Name | Description | Format |
|---|---|---|
| Success | Operation success flag | true / false |
| OrderId | Payment ID in the merchant's system | Corresponds to the one passed in the request |
| Amount | Blocked amount. Transmitted if "Success = true" | Corresponds to the one passed in the request |
| AuthCode | Authorization code. The parameter is optional | String (maximum 6 characters) |
| ErrCode | Description of the error. Passed empty if "Success = true" | see error codes |
| ErrMessage | Optional parameter. Additional error description | Line |
| ACSUrl | Address (URL / URI) of the 3-D Secure authentication server | Line. None if the card is not involved in 3-D Secure technology |
| PaReq | 3-D Secure Authentication Request | Line. None if the card is not involved in 3-D Secure technology |
| ThreeDSKey | Unique identifier for the transaction | Line. None if the card is not involved in 3-D Secure technology |
| RRN | The parameter is optional. RRN operations | Line |
| PANMask | The parameter is optional. Masked card number in the format 123456xxxxxx1234 | Line |
| BankName | The parameter is optional. Name of the Issuing Bank | Line |
| ProcessingResponse | The parameter is optional. Acquiring original refusal | Line |
| CustomParams | The parameter is optional. List of additional parameters of the operation | Matches the Params passed in the request |
| FeePercent | The parameter is optional. Acquiring commission rate | Number |
| TerminalID | The parameter is optional. Id of the terminal in the merchant's system, on which the operation was actually performed | Number |
| SourceOffice | This parameter is optional. Organization ID when paying in GDS | Line |
Sample response
An example of a response to a successful request:
Code:
{
"Success": true,
"OrderId": "TestOrder123",
"Amount": 300,
"ErrCode": ""
}An example of a response to an unsuccessful request:
Code:
{
"Success": false,
"OrderId": "TestOrder123",
"ErrCode": "DUPLICATE_ORDER_ID"
}Init - Create a payment session
This is done using the Init command. The method is used if the form for entering bank card data is on the side of merchant's. If the method call is successful, a unique identifier is returned, which allows you to call the payment page located on the side of merchant's in the future, and redirect the user to it to enter the card data.
Upon receipt of the session identifier, it is possible to indicate the purpose of using the payment form - to block funds on the card or to save the card in merchant's storage for subsequent debits. If the card is saved, subsequent debits can be made both with the input of CVV2 / CVC2, and without acceptance - without entering any data and the participation of the cardholder. These can be recurrent write-offs or classic transactions without entering CVV2 / CVC2. In the latter case, failures are possible due to the issuer's restrictions due to the need to use 3-D Secure technology.
The payment page can be designed in the Seller's design and is not unique (the Seller can have several data entry pages for different cases).
Request parameters
| Name | Description | Format | Mandatory |
|---|---|---|---|
| Key | Seller ID. Issued to the Seller with test / combat access parameters | Line | Yes |
| Password | Terminal password. Issued to the Seller with test / combat access parameters | Line | Yes |
| OrderId | Payment ID in the merchant's system | String (maximum 50 characters) | Not |
| Amount | Blocked amount in minimum currency units | Digits with no decimal or other separators | Not |
| CustomParams | Additional payment parameters to display on the template and to compose the user's return address if it is parameterized | A string containing pairs of keys and their command values, separated by ";" (semicolon). Keys and values are separated by "=" (equal). The list of possible parameters: Email - the client's email address for sending a fiscal receipt; successUrl - the address for redirecting the User from the payment page in case of success, failUrl - the address for redirecting the User from the payment page in case of failure; Description - an additional description of the order to be displayed on the payment form; PayButtonCustomText - text to be reflected on the button to initiate payment on the form. The possibility of using these parameters should be checked with support@mapcard.pro | Not |
| AddCard | A parameter that specifies whether to save the card after payment. Used in conjunction with the Type = Pay parameter. The default value for this parameter is "False". "True" - the card is saved. "False" - the card is not saved | True / False | Not |
| Type | The type of session to create. Pay - a payment session is created. Add - a session is created to save the map | Pay / Add | Yes |
| PaymentType | The parameter specifying the type of payment. OneStep is one step. TwoStep - two-stage. In the case of a one-step operation, as a result of success, the money will be debited from the user's card | OneStep / TwoStep. The default is OneStep | Not |
| Action | Additional action with a blocked amount. "Unblock" - unlocking | Only available for TwoStep | Not |
| Recurrent | It must be used if the saved card will be used for recurrent write-offs. The possibility of use must be specified additionally | true / false | Not |
| Lifetime | Session validity period after which payment for this session will be impossible. If not transmitted, the session lifetime is set to one week | Number in seconds | Not |
| Goods | List of names of goods / services to be sent to the OFD | A string containing pairs of keys and their command values, separated by ";" (semicolon). Keys and values are separated by "=" (equal). The total amount of all goods must correspond to the Amount. Length of one name - no more than 128 characters | Not |
| CardUId * | Card ID. Used to pay with a saved card | String (maximum 50 characters) | Not |
| UserLogin * | Login of the cardholder registered in the merchant's system | String (maximum 50 characters) | Not |
| UserPassword * | Password of the cardholder registered in the merchant's system | String (maximum 50 characters | Not |
| merchant ** | Seller name | String (maximum 50 characters | Not |
| merchantPassword ** | merchant password for transactions | String (maximum 50 characters | Not |
| Split | Used to divide the amount of the write-off made into its component parts for subsequent settlements with counterparties | A string containing groups of key-value pairs, where groups are enclosed in curly braces {}, key-value pairs are separated by a “,” (comma). Key and value are separated by ":" (colon). The line is enclosed by square brackets "[]". The parameters of keys and values are issued to the Seller with the parameters of test / combat access. The total sum of all components must correspond to the Amount | Not |
** - used only if the card is saved to the merchant
To save / pay for the saved card behind the terminal, these parameters do not need to be transmitted.
Depending on the business scenario, the card can be saved:
- linked to the User Login
- tied to the Terminal
- linked to the merchant
Depending on who the card is saved to, it is necessary to pass various parameters in the request for saving the card, request for the list of saved cards, and blocking funds on the card. A standard case for saving a card on the side of merchant's - with a link to the User's Login. If the card is saved at the Terminal or at the merchant, the correspondence of the saved cards with the Users is made on the side of the merchant. In response to a request for a list of saved cards, in this case, the entire array of saved maps will be contained.
Code:
Goods = Price, Attribute of the subject of calculation, VAT rate, Attribute of the calculation method | {Supplier data}| Name | Description | Format |
|---|---|---|
| Price | Blocked amount in minimum currency units | Digits with no decimal or other separators |
| Calculation subject attribute | 1 - Goods, 2 - Excisable goods, 3 - Work, 4 - Service, 5 - Gambling rate, 6 - Winning a gambling, 7 - Lottery ticket, 8 - Winning a lottery, 9 - Provision of RID, 10 - Payment, 11 - Agency fee, 12 - Composite subject of calculation, 13 - Other subject of calculation | Number from 1 to 13. The parameter is optional. Default value 1 - Product |
| VAT rate | 1 - VAT rate 20%, 2 - VAT rate 10%, 3 - VAT rate calc. 20/120, 4 - VAT rate calc. 10/110, 5 - VAT rate 0%, 6 - VAT exempt | Number from 1 to 6. This parameter is optional. If not in the request, the value is taken from the terminal settings |
| Calculation method attribute | 1 - Prepayment 100%, 2 - Partial prepayment, 3 - Advance payment, 4 - Full settlement, 5 - Partial settlement and credit, 6 - Transfer on credit, 7 - loan payment | Number from 1 to 7. This parameter is optional. If it is absent in the request, the value 4 will be transmitted - Full calculation |
| Supplier data | "name" - Name, "phoneNumbers" - list of phone numbers, "supplierINN" - supplier's INN | JSON string. The parameter is optional |
Request example
Sample POST request:
Code:
https: // {domain} / Init
Key: TestTerminal
Password: 123
Amount: 300
OrderId: TestOrder123
AddCard: True
Type: Pay
PaymentType: TwoStep
CustomParams: successUrl = https://merchant.com; failUrl = https://merchant.com;Email=user@example.com;PayButtonCustomText=Subscribe for 0.1 EURAn example of implementing a request in the program code:
Code:
curl -X POST \ https: // https: // {domain} / Init \
-H 'Content-Type: application / x-www-form-urlencoded' \
-d 'Key = TestTerminal & Amount = 300 & OrderId = TestOrder123 & CustomParams = CustomParams% 3AsuccessUrl% 3Dhttps% 3A% 2F% 2Fmapcard.pro% 3BfailUrl% 3Dhttps% 3A% 2F% 2Fmapisacard.com% 3BEmail% 3Duser% 40example0% DText1% 9Custom% % D0% BE% D1% 80% D0% BC% D0% B8% D1% 82% D1% 8C% 20% D0% BF% D0% BE% D0% B4% D0% BF% D0% B8% D1% 81 % D0% BA% D1% 83% 20% D0% B7% D0% B0% 201% 20% D1% 80% D1% 83% D0% B1. 'Format of the parameter Goods
Code:
Goods = Price, Attribute of the subject of calculation, VAT rate, Attribute of the calculation method | {Supplier data}| Name | Description | Format |
|---|---|---|
| Price | Blocked amount in minimum currency units | Digits with no decimal or other separators |
| Calculation subject attribute | 1 - Goods, 2 - Excisable goods, 3 - Work, 4 - Service, 5 - Gambling rate, 6 - Winning a gambling, 7 - Lottery ticket, 8 - Winning a lottery, 9 - Provision of RID, 10 - Payment, 11 - Agency fee, 12 - Composite subject of calculation, 13 - Other subject of calculation | Number from 1 to 13. The parameter is optional. Default value 1 - Product |
| VAT rate | 1 - VAT rate 20%, 2 - VAT rate 10%, 3 - VAT rate calc. 20/120, 4 - VAT rate calc. 10/110, 5 - VAT rate 0%, 6 - VAT exempt | Number from 1 to 6. This parameter is optional. If not in the request, the value is taken from the terminal settings |
| Calculation method attribute | 1 - Prepayment 100%, 2 - Partial prepayment, 3 - Advance payment, 4 - Full settlement, 5 - Partial settlement and credit, 6 - Transfer on credit, 7 - loan payment | Number from 1 to 7. This parameter is optional. If it is absent in the request, the value 4 will be transmitted - Full calculation |
| Supplier data | "name" - Name, "phoneNumbers" - list of phone numbers, "supplierSNN" - supplier's SNN | JSON string. The parameter is optional |
Response options
| Name | Description | Format |
|---|---|---|
| Success | Operation success flag | true / false |
| OrderId | Payment ID in the merchant's system | Corresponds to the one passed in the request |
| Amount | Blocked amount. Transmitted if "Success = true" | Corresponds to the one passed in the request |
| Type | pay / add | Corresponds to the one passed in the request |
| ErrCode | Description of the error. Passed empty if "Success = true" | see error codes |
| ErrMessage | Additional error description. Passed empty if "Success = true" | Line |
| SessionGUID | Unique session identifier | Line |
Format of the parameter Goods:
Code:
Goods = Price, Attribute of the subject of calculation, VAT rate, Attribute of the calculation method | {Supplier data}| Name | Description | Format |
|---|---|---|
| Price | Blocked amount in minimum currency units | Digits with no decimal or other separators |
| Calculation subject attribute | 1 - Goods, 2 - Excisable goods, 3 - Work, 4 - Service, 5 - Gambling rate, 6 - Winning a gambling, 7 - Lottery ticket, 8 - Winning a lottery, 9 - Provision of RID, 10 - Payment, 11 - Agency fee, 12 - Composite subject of calculation, 13 - Other subject of calculation | Number from 1 to 13. The parameter is optional. Default value 1 - Product |
| VAT rate | 1 - VAT rate 20%, 2 - VAT rate 10%, 3 - VAT rate calc. 20/120, 4 - VAT rate calc. 10/110, 5 - VAT rate 0%, 6 - VAT exempt | Number from 1 to 6. This parameter is optional. If not in the request, the value is taken from the terminal settings |
| Calculation method attribute | 1 - Prepayment 100%, 2 - Partial prepayment, 3 - Advance payment, 4 - Full settlement, 5 - Partial settlement and credit, 6 - Transfer on credit, 7 - loan payment | Number from 1 to 7. This parameter is optional. If it is absent in the request, the value 4 will be transmitted - Full calculation |
| Supplier data | "name" - Name, "phoneNumbers" - list of phone numbers, "supplierINN" - supplier's INN | JSON string. The parameter is optional |
Sample response
An example of a response to a successful request:
Code:
{
"Success": true,
"OrderId": "TestOrder123",
"Amount": 300,
"ErrCode": ""
"Type": "pay"
"SessionGUID": "1ILZMU42Zs8YivEsYXOA67ijRYs"}Example response to an unsuccessful request:
Code:
{
"Success": false,
"ErrCode": "WRONG_PARAMS"
}Format of the parameter Goods
Code:
Goods = Price, Attribute of the subject of calculation, VAT rate, Attribute of the calculation method | {Supplier data}| Name | Description | Format |
|---|---|---|
| Price | Blocked amount in minimum currency units | Digits with no decimal or other separators |
| Calculation subject attribute | 1 - Goods, 2 - Excisable goods, 3 - Work, 4 - Service, 5 - Gambling rate, 6 - Winning a gambling, 7 - Lottery ticket, 8 - Winning a lottery, 9 - Provision of RID, 10 - Payment, 11 - Agency fee, 12 - Composite subject of calculation, 13 - Other subject of calculation | Number from 1 to 13. The parameter is optional. Default value 1 - Product |
| VAT rate | 1 - VAT rate 20%, 2 - VAT rate 10%, 3 - VAT rate calc. 20/120, 4 - VAT rate calc. 10/110, 5 - VAT rate 0%, 6 - VAT exempt | Number from 1 to 6. This parameter is optional. If not in the request, the value is taken from the terminal settings |
| Calculation method attribute | 1 - Prepayment 100%, 2 - Partial prepayment, 3 - Advance payment, 4 - Full settlement, 5 - Partial settlement and credit, 6 - Transfer on credit, 7 - loan payment | Number from 1 to 7. This parameter is optional. If it is absent in the request, the value 4 will be transmitted - Full calculation |
| Supplier data | "name" - Name, "phoneNumbers" - list of phone numbers, "supplierSNN" - supplier's SNN | JSON string. The parameter is optional |
Example of transferring Goods:
Code:
Service=100,4,1,3|{"name": "LLC Name", "phoneNumbers": ["+11111111111"],"supplierSNN": "77777777"};Goods=810,1|{"name": "LLC Name", "phoneNumbers": ["+11111114859"],"supplierSNN": "777757777"};Service2=20,4;Goods2=30createPayment - Call a payment form
Performed using the createPayment command. The request is used to redirect the user to the form for entering the card details for subsequent payment or saving the card. As a result of the command execution by the GET / POST method, the template (form) for entering the data (details) of the bank card specified by the parameters specified in the Init command is called.
Request parameters
| Name | Description | Format | Mandatory |
|---|---|---|---|
| SessionId | Session ID obtained as a result of Init request | Line |
Request example
Sample POST request:
Code:
https:{domain}/createPayment
SessionID:1EWlFnYuojSEVAjkEys2341An example of implementing a request in the program code:
Code:
curl -X GET 'https:{domain}/createPayment?SessionID=1EWlFnYuojSEVAjkEys2341'As a result of the method call, the user is redirected to the card data entry template for subsequent payment or saving the card details.
After successful payment or completion of the number of payment attempts, the user will be returned to the Seller's page. The return address (page URL) is indicated by the Seller in advance when connecting. The address can be specified in a parameterized form. In this case, the parameters inserted into the address must be specified in the CustomParams field of the Init method.
As a result of the method call, the user is redirected to the card data entry template for subsequent payment or saving the card details.
Charge - Write-off of blocked funds
The request is executed by the Charge command.
The request is used to write off funds from the User's card, previously blocked by the Block command.
The result of processing the request is the debiting of the blocked amount from the User's card. A write-off can be made for an amount less than the amount of previously blocked funds. Write-off on order can be performed only once.
Attention: for a successful write-off, it is necessary that at the time of execution of the request the payment has the status of Authorized
Request parameters
| Name | Description | Format | Mandatory |
|---|---|---|---|
| Key | Seller ID. Issued to the Seller with test / combat access parameters | Line | Yes |
| OrderId | Payment ID in merchant's system | String (maximum 50 characters) | Yes |
| Amount | Amount to be debited in minimum currency units | Digits with no decimal or other separators |
Request example
Sample POST request:
Code:
https: // {domain} / Charge
Key: TestTerminal
Amount: 300
OrderId: TestOrder123An example of implementing a request in the program code:
Code:
curl -X POST \ https: // https: // {domain} / Charge \
-H 'Content-Type: application / x-www-form-urlencoded' \
-d 'Key = TestTerminal & Amount = 300 & OrderId = TestOrder123 'Response options
| Name | Description | Format |
|---|---|---|
| Success | Operation success flag | true / false |
| OrderId | Payment ID in the merchant's system | Corresponds to the one passed in the request |
| Amount | Amount written off | Corresponds to the one given in the request. "0" is transmitted if "Success = false" |
| ErrCode | Description of the error. Passed empty if "Success = true" | see error codes |
| ErrMessage | Optional parameter. Additional error description. Passed empty if "Success = true" | Line |
| CustomParams | The parameter is optional. List of additional parameters of the operation | Matches the Params passed in the Block request |
| FeePercent | The parameter is optional. Acquiring commission rate, in tenths of the number | Number |
| Fee | The parameter is optional. Acquiring fee amount | Number |
| TerminalID | The parameter is optional. Id of the terminal in the merchant's system, on which the operation was actually performed | Number |
| RRN | The parameter is optional. RRN operations | Line |
| PANMask | The parameter is optional. Masked card number in the format 123456xxxxxx1234 | Line |
| BankName | The parameter is optional. Name of the Issuing Bank | Line |
| Key | Seller ID. Matches the one passed in the request | Line |
| ProcessingResponse | The parameter is optional. Acquiring original refusal | Line |
| TerminalID | The parameter is optional. Id of the terminal in the merchant's system, on which the operation was actually performed | Numb |
Sample response
An example of a response to a successful request:
Code:
{
"Success": true,
"OrderId": "TestOrder123",
"Key": "TestTerminal",
"Amount": 300,
"ErrCode": ""
}An example of a response to an unsuccessful request:
Code:
{
"Success": false,
"OrderId": "TestOrder123",
"Key": "TestTerminal",
"Amount": 0,
"ErrCode": "ILLEGAL_ORDER_STATE"
}Unblock - Unlocking funds on the card
The request is executed by the Unblock command.
The request is used to unblock funds from the User's card, previously blocked by the Block command. As a result of successful processing of the request, the unlocked funds become available on the User's card.
Attention: for a successful write-off, it is necessary that at the time of execution of the request the payment has the status of Authorized
Request parameters
| Name | Description | Format | Mandatory |
|---|---|---|---|
| Key | Seller ID. Issued to the Seller with test / combat access parameters | Line | Yes |
| OrderId | Unique payment identifier in merchant system | String (maximum 50 characters) | Yes |
| Amount | Amount to unlock in minimum currency units | Digits with no decimal or other separators |
Request example
Sample POST request:
Code:
https: // {domain} / Unblock
Key: TestTerminal
Amount: 300
OrderId: TestOrder123An example of implementing a request in the program code:
Code:
curl -X POST \ https: // https: // {domain} / Unblock \
-H 'Content-Type: application / x-www-form-urlencoded' \
-d 'Key = TestTerminal & Amount = 300 & OrderId = TestOrder123 'Response options
| Name | Description | Format |
|---|---|---|
| Success | Operation success flag | true / false |
| OrderId | Payment ID in the merchant's system | Corresponds to the one passed in the request |
| NewAmount | Changed blocked amount | Digits with no decimal or other separators |
| ErrCode | Description of the error. Passed empty if "Success = true" | see error codes |
| ErrMessage | Optional parameter. Additional error description. Passed empty if "Success = true" | Line |
| CustomParams | The parameter is optional. List of additional parameters of the operation | Matches the Params passed in the Block request |
| FeePercent | The parameter is optional. Acquiring commission rate, in tenths of the number | Number |
| TerminalID | The parameter is optional. Id of the terminal in the merchant's system, on which the operation was actually performed | Number |
| ProcessingResponse | The parameter is optional. Acquiring original refusal | Line |
Sample response
An example of a response to a successful request:
Code:
{
"Success": true,
"OrderId": "TestOrder123",
"NewAmount": 0,
"ErrCode": ""
}An example of a response to an unsuccessful request:
Code:
{
"Success": false,
"OrderId": "TestOrder123",
"NewAmount": 0,
"ErrCode": "AMOUNT_EXCEED"
}Refund
The request is executed by the Refund command.
The request is used to make a refund to the User's card, previously debited by the Charge team. The result of processing the request is the return (full or partial) of the debited funds to the User's card.
Attention: for a successful refund, it is necessary that at the time of execution of the request the payment has the Charged status.
Request parameters
| Name | Description | Format | Mandatory |
|---|---|---|---|
| Key | Seller ID. Issued to the Seller with test / combat access parameters | Line | Yes |
| OrderId | Payment ID in merchant system | String (maximum 50 characters) | Yes |
| Amount | Refund amount in minimum currency units | Digits with no decimal or other separators | Yes |
| Goods | List of names of goods / services to be sent to the OFD | A string containing pairs of keys and their command values, separated by ";" (semicolon). Keys and values are separated by "=" (equal). The total of all items must match Amount. Length of one name - no more than 128 characters | Not |
Parameter format Goods
Code:
Item = Price, Attribute of the subject of calculation, VAT rate, Attribute of the calculation method | {Supplier data}| Name | Description | Format |
|---|---|---|
| Price | Refund amount in minimum currency units | Digits with no decimal or other separators |
| Calculation subject attribute | 1 - Goods, 2 - Excisable goods, 3 - Work, 4 - Service, 5 - Gambling rate, 6 - Winning a gambling, 7 - Lottery ticket, 8 - Winning a lottery, 9 - Provision of RID, 10 - Payment, 11 - Agency fee, 12 - Composite subject of calculation, 13 - Other subject of calculation | Number from 1 to 13. The parameter is optional. Default value 1 - Product |
| VAT rate | 1 - VAT rate 20%, 2 - VAT rate 10%, 3 - VAT rate calc. 20/120, 4 - VAT rate calc. 10/110, 5 - VAT rate 0%, 6 - VAT exempt | Number from 1 to 6. This parameter is optional. If not in the request, the value is taken from the terminal settings |
| Calculation method attribute | 1 - Prepayment 100%, 2 - Partial prepayment, 3 - Advance payment, 4 - Full settlement, 5 - Partial settlement and credit, 6 - Transfer on credit, 7 - loan payment | Number from 1 to 7. This parameter is optional. If it is absent in the request, the value 4 will be transmitted - Full calculation |
| Supplier data | "name" - Name, "phoneNumbers" - list of phone numbers, "supplierSNN" - supplier's SNN | JSON string. The parameter is optional |
Transfer example Goods
Code:
Service=100,4,1,3|{"name": "LLC Name", "phoneNumbers": ["+11111111111"],"supplierSNN": "77777777"};Goods=810,1|{"name": "LLC Name", "phoneNumbers": ["+11111114859"],"supplierSNN": "777757777"};Service2=20,4;Goods2=30If the Goods parameter is not specified in the request, then:
- in the case of a full refund, the check will indicate the items from the write-off on the order;
- in case of partial refund, the fiscal receipt will contain the position "Partial refund" with parameters for fiscalization by default (from the terminal settings).
Request example
Sample POST request:
Code:
https: // {domain} / Refund
Key: TestTerminal
Amount: 300
OrderId: TestOrder123An example of implementing a request in the program code:
Code:
curl -X POST \ https: // https: // {domain} / Refund \
-H 'Content-Type: application / x-www-form-urlencoded' \
-d 'Key = TestTerminal & Amount = 300 & OrderId = TestOrder123 'Response options
| Name | Description | Format |
|---|---|---|
| Success | Operation success flag | true / false |
| OrderId | Payment ID in the merchant's system. Transmitted if "Success = true" | Corresponds to the one passed in the request |
| Key | merchant ID in merchant system. Transmitted if "Success = true" | Corresponds to the one passed in the request |
| NewAmount | Changed written off amount. Transmitted if "Success = true" | Digits with no decimal or other separators |
| ErrCode | Description of the error. Passed empty if "Success = true" | See error codes |
| ErrMessage | Optional parameter. Additional error description. Passed empty if "Success = true" | Line |
| CustomParams | The parameter is optional. List of additional parameters of the operation | Matches the Params passed in the Block request |
| FeePercent | The parameter is optional. Acquiring commission rate, in tenths of the number | Number |
| TerminalID | The parameter is optional. Id of the terminal in the merchant's system, on which the operation was actually performed | Number |
| BankName | The parameter is optional. Name of the Issuing Bank | Line |
| ProcessingResponse | The parameter is optional. Acquiring original refusal | Line |
| RRN | The parameter is optional. RRN operations | Line |
Sample response
An example of a response to a successful request:
Code:
{
"Success": true,
"OrderId": "TestOrder123",
"NewAmount": 0,
"ErrCode": ""
}An example of a response to an unsuccessful request:
Code:
{
"Success": false,
"OrderId": "TestOrder123",
"Key": "TestTerminal",
"NewAmount": 0,
"ErrCode": "AMOUNT_EXCEED"
}Pay - One-step payment
This is done using the Pay command.
This request allows you to block and write off funds from the Buyer's card. One-step payment is similar to sequential calls to the Block and Charge methods.
The parameters of the request, response and composition of the fields are similar to the parameters of the Block command.
If a refusal is received at the stage of debiting after successful authorization, the result in the response to the Pay method will not be successful, while the order status is "Authorized":
Code:
{
"Success": false,
"State": "Authorized"
}getState - Get the status of the payment
This is done using the getState command.
This request allows you to get information about the current status of the transaction (payment).
Request parameters
| Name | Description | Format | Mandatory |
|---|---|---|---|
| Key | Seller ID. Issued to the Seller with test / combat access parameters | Line | Yes |
| OrderId * | Unique payment identifier in merchat's system | String (maximum 50 characters) | Yes |
| SessionOrderId * | Payment ID in the merchant's system | String (maximum 50 characters) | Yes |
Request example
Sample POST request:
Code:
https: // {domain} / getState
Key: TestTerminal
SessionOrderId: TestOrder123An example of implementing a request in the program code:
Code:
curl -X POST \ https: // https: // {domain} / getState \
-H 'Content-Type: application / x-www-form-urlencoded' \
-d 'Key = TestTerminal & SessionOrderId = TestOrder123 'Response options
| Name | Description | Format |
|---|---|---|
| Success | Operation success flag | true / false |
| ErrCode | Description of the error. Passed empty if "Success = true" | see error codes |
| ErrMessage | Optional parameter. Additional error description | Line |
| OrderId | Payment ID in the merchant's system | Line |
| Amount | Order amount in minimum currency units | Digits with no decimal or other separators |
| State | Payment status. Transmitted if "Success = true" | For possible values, see Order Statuses. |
| merchantOrderId | Unique payment identifier in merchant's system | Line |
| CustomParams | The parameter is optional. List of additional parameters of the operation | Matches the Params passed in the Block or Charge request (or Params from the Init request) |
| FeePercent | The parameter is optional. Acquiring commission rate, in tenths of a number. Passed empty if "Success = false" | Number |
| TerminalID | The parameter is optional. Id of the terminal in the merchant's system, on which the operation was actually performed | Number |
| AuthCode | The parameter is optional. Authorization code | String (maximum 6 characters) |
| Fee | The parameter is optional. Acquiring fee amount | Number |
| CardHolder | The parameter is optional. Full name of the cardholder | Number |
| CardType | The parameter is optional. Card type | Number |
Sample response
An example of a response to a successful request:
Code:
{
"Success": true,
"OrderId": "TestOrder123",
"State": "Charged",
"Amount": 300,
"merchantOrderId": "1IPAaOFn24UijYp6xqwmx"
}An example of a response to an unsuccessful request:
Code:
{
"Success": false,
"OrderId": "",
"State": "",
"Amount": 0,
"ErrCode": "NOT_FOUND"
}createUser - Create a new user
This is done using the createUser command.
The request allows you to register a new user. Together with the saved card, this will allow you to make a payment without entering the bank card details, incl. recurring payments. The result of the request processing is the receipt by the merchant of the user ID in merchant payment gateway.
Request parameters
json
| Name | Description | Format | Mandatory 1 |
|---|---|---|---|
| key | Seller ID. Issued with test / combat access parameters | Line | |
| credential | An object | ||
| +- login | Username (cardholder). Used to identify the user | String (maximum 50 characters) | |
| +- password | User (cardholder) password. Used to identify the user | String (maximum 50 characters) | |
| ip | User's IP address | A string in the form of four octets (8-bit numbers) from 0 to 255, separated by dots (for example, 172.14.255.1) | |
| phone | User phone number | String (maximum 50 characters) | |
| User's email address | String (maximum 50 characters) |
urlencoded
| Name | Description | Format | Mandatory 1 |
|---|---|---|---|
| Key | Seller ID. Issued to the Seller with test / combat access parameters | Line | |
| Login | Username (cardholder). Used to identify the user | String (maximum 50 characters) | |
| Password | User (cardholder) password. Used to identify the user | String (maximum 50 characters) | |
| IP | User's IP address | A string in the form of four octets (8-bit numbers) from 0 to 255, separated by dots (for example, 172.14.255.1) | |
| Phone | User phone number | String (maximum 50 characters) | |
| User's email address | String (maximum 50 characters |
Request example
json
Sample POST request:
Code:
Content-Type: application / json https:{domain}/createUser
{
"key": "TestTerminal",
"credential": {
"login": "UserLogin_1",
"password": "UserPass_1"
},
"ip": "192.162.1.1",
"phone": "",
"email": ""
}An example of implementing a request in the program code:
Code:
curl -X POST \
https:https:{domain}/createUser \
-H 'Content-Type: application/json' \
-d '{"key":"TestTerminal","credential":{"login":"UserLogin_1","password":"UserPass_1"},"ip":"192.162.1.1","phone":"","email":""}'urlencoded
Sample POST request:
Code:
Content-Type: application / x-www-form-urlencoded https:{domain}/createUser
Key:TestTerminal
Login:TestUser
Password:123An example of implementing a request in the program code:
Code:
curl -X POST \
https:https:{domain}/createUser \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'Key=TestTerminal&Login=TestUser&Password=123'Response options
| Name | Description | Format | Mandatory 1 |
|---|---|---|---|
| Success | Operation success flag | true / false | |
| UserId | merchant user ID | number | 2 |
| AlreadyCreated | The flag of the presence of a user in merchant's system | true / false | |
| ErrCode | Error description | see error codes | 3 |
2* Transmitted if the reply containsSuccess=true
3* Transmitted if the reply containsSuccess=false
Sample response
An example of a response to a successful request:
Code:
{
"Success": true,
"UserId": 11,
"AlreadyCreated": false,
"ErrCode": ""
}An example of a response to an unsuccessful request:
Code:
{
"Success": false,
"UserId": 11,
"AlreadyCreated": true,
"ErrCode": ""
}
{
"Success": false,
"ErrCode": "WRONG_PARAMS"
}storeCard - Register (save) card
Performed using the storeCard command.
This request allows you to save the details of the User's bank card for subsequent payment without entering the card data. The result of processing the request is the receipt by the merchant of the card ID in merchant.
Depending on the business scenario, the card can be saved:
- linked to the User Login
- tied to the Terminal
- linked to the merchant
Depending on who the card is saved to, it is necessary to pass various parameters in the request for saving the card, request for the list of saved cards, and blocking funds on the card.
Request parameters
| Name | Description | Format | Mandatory |
|---|---|---|---|
| Key | Seller ID. Issued to the Seller with test / combat access parameters | Line | Yes |
| OrderId | Payment ID in the merchant's system. Transmitted together with Amount | String (maximum 50 characters) | Not |
| Amount | The blocking amount in the minimum currency units. When using it, funds from the client's card are blocked | Digits with no decimal or other separators | Not |
| Login * | User login. Used to identify cards | String (maximum 50 characters) | Not |
| Password * | Password of the cardholder registered in the merchant's system | String (maximum 50 characters | Not |
| PAN | Card number | Numbers without spaces | Yes**** |
| EMonth | Card expiration month | 2 digits with a leading zero | Yes**** |
| EYear | Card expiration year | 2 digits (last digits of the year) | Yes**** |
| CardHolder | Surname and name of the cardholder | string (maximum 30 characters, Latin letters or space) | Yes**** |
| SecureCode | CVC2 / CVV2 | Numbers without spaces | Yes**** |
| ApplePayToken | A one-time token received in Apple Pay when a payment is initiated from an Apple device | Line | Not |
| Params | List of additional parameters of the operation | A string containing pairs of keys and their command values, separated by ";" (semicolon). Keys and values are separated by "=" (equal) | Not |
| Recurrent | It must be used if the saved card will be used for recurrent write-offs. The possibility of use must be specified additionally | true / false | Not |
| Action | Additional action with a blocked amount. "Charge" - write-off, "Unblock" - unblocking | Charge / Unblock | Not |
| Enrollment | Sign of the card's involvement in 3D Secure technology. In this case, only the card of the specified type is saved. "3DS" - the card is involved in 3D Secure technology, "Non-3DS" - the card is not involved in 3D Secure technology. The possibility of use must be specified additionally | 3DS / Non-3DS | Not |
| TerminalPassword ** | Terminal password for transactions | String (maximum 50 characters | Not |
| merchant *** | Seller name | String (maximum 50 characters | Not |
| merchantPassword *** | merchant password for transactions | String (maximum 50 characters | Not |
| Goods | List of names of goods / services to be sent to the OFD (54-FZ) | A string containing pairs of keys and their command values, separated by ";" (semicolon). Keys and values are separated by "=" (equal). The total amount of all goods must match the Amount | Not |
| Split | Used to divide the amount of the write-off made into its component parts for subsequent settlements with counterparties | A string containing groups of key-value pairs, where groups are enclosed in curly braces {}, key-value pairs are separated by a “,” (comma). Key and value are separated by ":" (colon). The line is enclosed by square brackets "[]". The parameters of keys and values are issued to the Seller with the parameters of test / combat access. The total sum of all components must correspond to the Amount | Not |
** - Used only if the card is kept by the terminal
*** - are transferred together. Used only if the card is kept by the merchant
**** - mandatory if the ApplePayToken parameter is absent in the request
Request example
Sample POST request:
Code:
https: // {domain} / storeCard
Key: TestTerminal
Login: TestUser
Password: 123
PAN: 4111111111111111
EMonth: 12
EYear: 21
CardHolder: John Smith
SecureCode: 123An example of implementing a request in the program code:
Code:
curl -X POST \ https: // https: // {domain} / storeCard \
-H 'Content-Type: application / x-www-form-urlencoded' \
-d 'Key = TestTerminal & Login = TestUser & Password = 123 & PAN = 4111111111111111 & EMonth = 12 & EYear = 21 & CardHolder = John% 20Smith & SecureCode = 123 'Response options
| Name | Description | Format |
|---|---|---|
| Success | Operation success flag | true / false |
| CardUId | ID of the card in the merchant's system | GUID |
| PANMask | Masked card number in the format 123456xxxxxx1234 | String 13-19 characters |
| OrderId | Payment ID in the merchant's system | Matches the one passed in the request |
| AuthCode | The parameter is optional. Authorization code | String (maximum 6 characters) |
| RRN | The parameter is optional. RRN operations | Line |
| IsActive | Card status | "True" / "False" |
| ErrCode | Description of the error. Passed empty if "Success = true" | see error codes |
| ErrMessage | Optional parameter. Additional error description | Line |
| CustomParams | The parameter is optional. List of additional parameters of the operation | Matches the Params passed in the request |
| FeePercent | The parameter is optional, in tenths of a number | Number |
| TerminalID | The parameter is optional. Id of the terminal in the merchat's system, on which the operation was actually performed | Number |
| ProcessingResponse | The parameter is optional. Acquiring original refusal | Line |
| ACSUrl | Address (URL / URI) of the 3-D Secure authentication server | Line. None if the card is not involved in 3-D Secure technology |
| PaReq | 3-D Secure Authentication Request | Line. None if the card is not involved in 3-D Secure technology |
| ThreeDSKey | Unique identifier for the transaction | Line. None if the card is not involved in 3-D Secure technology |
Sample response
An example of a response to a successful request:
Code:
{
"Success": true,
"CardUId": "7sTwecksRSs1fIpUQw8su",
"PANMask": "411111xxxxxx1111",
"IsActive": true,
"ErrCode": ""
}An example of a response to an unsuccessful request:
Code:
{
"Success": false,
"ErrCode": "INVALID_AUTHENTICATION"
}Response parameters in case of saving a card involved in 3-D Secure technology are similar to those described in using 3D Secure technology. To obtain a card ID, it is necessary to complete the holder's 3DS authentication (StoreCard3DS method).
removeCard - Remove card
This is done using the removeCard command.
The result of request processing is a change in the status of the linked card from “Active” to “Deleted”. In order to return it to the “Active” status in the future, it is necessary to perform the procedure of saving the card again - in this case, the card will be assigned a new identifier.
Request parameters
json
| Name | Description | Format | Mandatory 1 |
|---|---|---|---|
| key | Seller ID. Issued with test / combat access parameters | Line | |
| card | Card data for making a transaction | An object | |
| +- uid | Card ID in merchant's system | Line | |
| credential | An object | ||
| +- login | Login of the cardholder registered in the merchant's system. Used only if the card is saved to a specific user | String (maximum 50 characters) | |
| +- password | Password of the cardholder registered in the merchant's system. Used only if the card is saved to a specific user | String (maximum 50 characters) | |
| +- merchant_name | Seller name. Used only if the card is saved for the merchant | String (maximum 50 characters) | |
| +- merchant_password | merchant password for transactions. Used only if the card is saved for the merchant | String (maximum 50 characters) | |
| +- terminal_password | Terminal password for performing operations. Used only if the card is stored in the terminal | String (maximum 50 characters) |
urlencoded
| Name | Description | Format | Mandatory 1 |
|---|---|---|---|
| Key | Seller ID. Issued to the Seller with test / combat access parameters | Line | |
| CardUId | The ID of the card to be removed in merchant's system | Line | |
| UsrLogin | Login of the cardholder registered in the merchant's system. Used only if the card is saved to a specific user | String (maximum 50 characters) | |
| UsrPassword | Password of the cardholder registered in the merchant's system. Used only if the card is saved to a specific user | String (maximum 50 characters) | |
| merchant | Seller name. Used only if the card is saved for the merchant | String (maximum 50 characters | |
| merchantPassword | merchant password for transactions. Used only if the card is saved for the merchant | String (maximum 50 characters | |
| TerminalPassword | Terminal password for performing operations. Used only if the card is stored in the terminal | String (maximum 50 characters |
Request example
json
Sample POST request:
Code:
Content-Type: application / json https:{domain}/removeCard
{
"credential": {
"login": "TestUser",
"password": "123",
},
"card": {
"uid": "456ceFOFYXmjlZraP12nfP"
}
}An example of implementing a request in the program code:
Code:
curl -X POST \
https:https:{domain}/removeCard \
-H 'Content-Type: application/json' \
-d '{"credential":{"login":"TestUser","password":"123",},"card":{"uid":"456ceFOFYXmjlZraP12nfP"}}'urlencoded
Sample POST request:
Code:
Content-Type: application / x-www-form-urlencoded https:{domain}/removeCard
UsrLogin : TestUser
UsrPassword : 123
CardUId: 456ceFOFYXmjlZraP12nfPAn example of implementing a request in the program code:
Code:
curl -X POST \
https:https:{domain}/removeCard \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'UsrLogin=TestUser&UsrPassword=123&CardUId=456ceFOFYXmjlZraP12nfP'Response options
| Name | Description | Format | Mandatory 1 |
|---|---|---|---|
| Success | Operation success flag | true / false | |
| CardUId | The identifier of the card to be removed in merchant's system | matches request | 2 |
| ErrCode | Error description | see error codes | 2 |
2* Transmitted if the reply containsSuccess=false
Sample response
An example of a response to a successful request:
Code:
{
"Success": true,
"CardUId": "7sTwecksRSs1fIpUQw8su",
}An example of a response to an unsuccessful request:
Code:
{
"Success": false,
"ErrCode": "INVALID_AUTHENTICATION"
}listCard - Request a list of registered cards
Performed using the listCard command.
This request allows you to get a list of cards stored in merchant with the purpose of their further use to pay for services or goods.
Request parameters
| Name | Description | Format | Mandatory |
|---|---|---|---|
| Key * | Seller ID. Issued to the Seller with test / combat access parameters | Line | Not |
| TerminalPassword ** | Terminal password for transactions | String (maximum 50 characters | Not |
| Login *** | User login. Used to identify cards | String (maximum 50 characters) | Not |
| Password *** | Password of the cardholder registered in the merchant's system | String (maximum 50 characters | Not |
| merchant **** | Seller name | String (maximum 50 characters | Not |
| merchantPassword **** | merchant password for transactions | String (maximum 50 characters | Not |
** - Used to request a list of cards stored in the terminal
*** - Used to request a list of cards stored in the User
**** - Used to request a list of cards, saved for the merchant
Request example
Sample POST request:
Code:
https: // {domain} / listCard
Login: TestUser
Password: 123An example of implementing a request in the program code:
Code:
curl -X POST \ https: // https: // {domain} / listCard \
-H 'Content-Type: application / x-www-form-urlencoded' \
-d 'Login = TestUser & Password = 123 & CardUId = 456ceFOFYXmjlZraP12nfP 'Response options
| Name | Description | Format |
|---|---|---|
| Success | Operation success flag | true / false |
| CardUId | The identifier of the card to be removed in merchant's system. Transmitted if "Success = true" | GUID |
| PANMask | Masked card number in 6..4 format. Transmitted if "Success = true" | String 13-19 characters |
| BankName | The parameter is optional. Issuing bank name | String, 50 characters |
| CardHolder | Surname, name of the cardholder, indicated on the face of the card | String, 50 characters |
| Status | Card status. Active - the card is active and can be used for debiting. Transmitted if "Success = true" | String, 50 characters |
| ErrCode | Error code. Not transmitted if "Success = true" | See error codes |
Sample response
An example of a response to a successful request:
Code:
{
"PanMask": "411111xxxxxx1111",
"CardUId": "Gnxs8dXqhObnvKwy38djkG",
"EMonth": 12,
"EYear": 21,
"Status": "Active",
"CardHolder": "John Smith"
},
{
" PanMask ":" 411111xxxxxx0023 ",
" CardUId ":" flsWu82F7j8UUMmbcPws89Nx3 ",
" EMonth ": 12,
" EYear ": 22,
" Status ":" Active ",
" CardHolder ":"John Smith"
}An example of a response to an unsuccessful request:
Code:
{
"Success": false,
"ErrCode": "INVALID_AUTHENTICATION"
}Block3DS - Using 3D Secure Technology
It is used when the Seller connects the 3-D Secure authentication mechanism. The order of execution - authentication of the cardholder on the side of the issuing bank and reporting the results to the gateway service.
Upon receipt of a request to block funds, the gateway verifies that the card participates in 3-D Secure authentication.
If the User's card is involved in 3-D Secure technology, then the response also contains the ACSUrl, PaReq and ThreeDSKey attributes.
| Name | Description | Format |
|---|---|---|
| ACSUrl | Address (URL / URI) of the 3-D Secure authentication server | Line |
| PaReq | 3-D Secure Authentication Request | Line |
| ThreeDSKey | Unique identifier for the transaction | Line |
After receiving a response from the gateway, the merchant redirects the cardholder to the site of the issuing bank for additional authentication. For this, a POST request is used to the address specified in the value of the ACSUrl attribute, with the parameters listed below.
| Name | Description | Format |
|---|---|---|
| ACSUrl | Address (URL / URI) of the 3-D Secure authentication server | Line |
| TermUrl | Redirect address after successful 3-D Secure authentication | Line |
| MD | Unique identifier for the transaction | Corresponds to the ThreeDSKey parameter from the response to the previous request |
| PaReq | 3-D Secure Authentication Request | Line |
Example request:
Code:
<body onload="document.form.submit()" >
<form name="form" action="{ACSUrl}" method="post" >
<input type="hidden" name="TermUrl" value="{TermUrl}" >
<input type="hidden" name="MD" value="{ThreeDSKey}" >
<input type="hidden" name="PaReq" value="{PaReq}" >
</form>
</body>After authorization on the website of the issuing bank, the user is returned by an HTTPS POST request to the address specified in the value of the TermUrl attribute, with the parameters specified below.
| Name | Description | Format |
|---|---|---|
| MD | Unique identifier for the transaction | Matches the one passed in the request |
| PaRes | An encrypted string containing the results of 3-D Secure authentication | Line |
Request parameters
| Name | Description | Format | Mandatory |
|---|---|---|---|
| Key | Seller ID. Issued to the Seller with test / combat access parameters | Line | Yes |
| OrderId | Payment ID in the merchant's system | String (maximum 50 characters) | Yes |
| PaRes | An encrypted string containing the results of 3-D Secure authentication | Corresponds to the answer from ACS | Yes |
Request example
Sample POST request:
Code:
https: // {domain} / Block3DS
Key: TestTerminal
OrderId: TestOrder123
PaRes: JQpr1kEIAQSIEYhdkxiEJOY4esfujenl5b9rPtt2lAn example of implementing a request in the program code:
Code:
curl -X POST \ https: // https: // {domain} / Block3DS \
-H 'Content-Type: application / x-www-form-urlencoded' \
-d 'Key = TestTerminal & OrderId = TestOrder123 & PaRes = JQpr1kEIAQSIEYhdkxiEJOY4esfujenl5b9rPtt2l 'Response options
| Name | Description | Format |
|---|---|---|
| Success | Operation success flag | true / false |
| OrderId | Payment ID in the merchant's system | Corresponds to the one passed in the request |
| Amount | Blocked amount. Transmitted if "Success = true" | Corresponds to the one passed in the request |
| CardUId | ID of the card in the merchant's system. Passed in response to the StoreCard3DS method | GUID |
| PANMask | Masked card number in the format 123456xxxxxx1234. Passed in response to the StoreCard3DS method | String 13-19 characters |
| Status | Card status. Passed in response to the StoreCard3DS method | isActive - the card is active and can be used for debiting |
| AuthCode | Authorization code. The parameter is optional | String (maximum 6 characters) |
| ErrCode | Description of the error. Passed empty if "Success = true" | see error codes |
| CustomParams | The parameter is optional. List of additional parameters of the operation | Matches the Params passed in the request |
| fee_percent | The parameter is optional. Acquiring commission rate, in tenths of the number | Number |
| terminal_id | The parameter is optional. Id of the terminal in the merchant system, on which the operation was actually performed |
Sample response
An example of a response to a successful request:
Code:
{
"Success": true,
"OrderId": "TestOrder123",
"Amount": 300,
"ErrCode": ""
}An example of a response to an unsuccessful request:
Code:
{
"Success": false,
"OrderId ":" TestOrder123 ",
" ErrCode ":" AMOUNT_EXCEED "In case of a one-step payment (in the case of using the Pay method), you must use the Pay3DS method instead of the Block3DS method to complete the 3-DS operation.
When saving a card involved in 3-D Secure technology, to complete the operation and receive a card ID in response, you must use the StoreCard3DS method.
The request, response parameters and field compositions of the Pay3DS and StoreCard3DS methods are similar to the Block3DS method.
Payout - Crediting funds to the card
Performed using the Payout command.
The request allows you to transfer funds to the User's card from the merchant's current account. A current account must be opened with a bank or an NCO providing funds transfer. The ID of the registered card obtained in response to the storeCard request or the full details of the new card can be specified as a card.
Request parameters
json
| Name | Description | Format | eCom |
|---|---|---|---|
| key | Seller ID. Issued to the Seller with test / combat access parameters | Line | |
| merchant_order_id | Payment ID in the merchant's system | String (maximum 50 characters) | |
| amount | Amount to be transferred | Digits with no decimal or other separators | |
| card | Card data for making a transaction | An object | |
| +- pan | Card number. Used in case of transferring funds by card number | String: numbers without spaces | 1 |
| +- uid | ID of the card in merchant system. Used in case of transferring funds by card ID | String (maximum 30 characters, Latin letters or space) | 2 |
| custom_params_rdy | List of additional parameters of the operation in the "key-value" format | An object | |
| credential | An object | ||
| login | Login of the cardholder registered in the merchant's system. Used in case of transferring funds by the identifier of the card saved by the user | String (maximum 50 characters) | |
| password | Password of the cardholder registered in the merchant's system. Used in case of transferring funds by the identifier of the card saved by the user | String (maximum 50 characters) | |
| merchant | Seller name. Used in case of transferring funds by the identifier of the card saved by the merchant | String (maximum 50 characters | |
| merchant_password | merchant password for transactions. Used in case of transferring funds by the identifier of the card saved by the merchant | String (maximum 50 characters | |
| terminal_password | Terminal password for performing operations. Used in case of transferring funds by the identifier of the card stored in the terminal | String (maximum 50 characters |
urlencoded
| Name | Description | Format | eCom |
|---|---|---|---|
| Key | Seller ID. Issued to the Seller with test / combat access parameters | Line | |
| OrderId | Payment ID in the merchant's system | String (maximum 50 characters) | |
| Amount | Amount to be transferred | Digits with no decimal or other separators | |
| PAN | Card number. Used in case of transferring funds by card number | Numbers without spaces | 1 |
| CardUId | ID of the card in merchant's system. Used in case of transferring funds by card ID | Line | 1 |
| Login | Login of the cardholder registered in the merchant's system. Used in case of transferring funds by the identifier of the card saved by the user | String (maximum 50 characters) | |
| Password | Password of the cardholder registered in the merchant's system. Used in case of transferring funds by the identifier of the card saved by the user | String (maximum 50 characters) | |
| merchant | Seller name. Used in case of transferring funds by the identifier of the card saved by the merchant | String (maximum 50 characters | |
| merchantPassword | merchant password for transactions. Used in case of transferring funds by the identifier of the card saved by the merchant | String (maximum 50 characters | |
| TerminalPassword | Terminal password for performing operations. Used in case of transferring funds by the identifier of the card stored in the terminal | String (maximum 50 characters | |
| Params | List of additional parameters of the operation | A string containing pairs of keys and their command values, separated by ";" (semicolon). Keys and values are separated by "=" (equal) |
2* This parameter is required if there is nopan
Request example
json
Sample POST request:
Code:
Content-Type: application / json https:{domain}/Payout
{
"key": "TestTerminal",
"merchant_order_id": "TestOrder123",
"card": {
"pan": "4111111111111111"
}
}An example of implementing a request in the program code:
Code:
curl -X POST \
https:https:{domain}/Payout \
-H 'Content-Type: application/json' \
-d '{"key":"TestTerminal","merchant_order_id":"TestOrder123","card":{"pan":"4111111111111111"}}'urlencoded
Sample POST request:
Code:
Content-Type: application / x-www-form-urlencoded https:{domain}/Payout
Key:TestTerminal
Amount:300
OrderId:TestOrder123
PAN:4111111111111111An example of implementing a request in the program code:
Code:
curl -X POST \
https:https:{domain}/Payout \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'Key=TestTerminal&Amount=300&OrderId=TestOrder123&PAN=4111111111111111'Response options
| Name | Description | Format | eCom |
|---|---|---|---|
| Success | Operation success flag | true / false | |
| OrderId | Payment ID in the merchant's system | Matches the one passed in the request | |
| Amount | Amount credited | Matches the one passed in the request | 1 |
| ErrCode | Error description | See error codes | 2 |
| ErrMessage | Additional error description | Line | |
| RRN | RRN operations | Line | |
| BankName | Name of the Issuing Bank | Line | |
| ProcessingResponse | Acquiring original refusal | Line | |
| CustomParams | List of additional parameters of the operation | Matches the Params passed in the request | |
| TerminalID | ID of the terminal in the merchant's system on which the operation was actually performed | Number |
2* Transmitted if the reply containsSuccess=false
Sample response
An example of a response to a successful request:
Code:
{
"Status": "True",
"OrderId": "TestOrder123",
"Amount": "300",
"ErrCode": "NONE",
"BankName": "TestBank",
},An example of a response to an unsuccessful request:
Code:
{
"Success": false,
"ErrCode": "INVALID_AUTHENTICATION"
}getReceipt - request fiscal data for an order
This is done using the getReceipt command. This request allows you to get fiscal characteristics for an order to generate a check on the side of the merchant.
Request parameters
json
| Name | Description | Format | Mandatory |
|---|---|---|---|
| key | Seller ID. Issued to the seller with test / combat access parameters | Line | |
| map_order_id | Card data for making a transaction | String (maximum 50 characters) | |
| receipt_id | Check ID | String (maximum 50 characters) | 1 |
urlencoded
| Name | Description | Format | Mandatory |
|---|---|---|---|
| Key | Seller ID. Issued to the Seller with test / combat access parameters | Line | |
| OrderId | Unique payment identifier in merchant's system | String (maximum 50 characters) | |
| ReceiptId | Check ID | String (maximum 50 characters) |
Request example
json
Sample POST request:
Code:
Content-Type: application / json
https:{domain}/getReceipt
{
"key": "AutoTest_54FZ(OrangeData)",
"merchant_order_id": "52cc5355-775b-4903-bd86-5b1e5e259065TestOrgD5",
"receipt_id": "1atY16Z3wr62fhMogQmFwIDaa4C"
}An example of implementing a request in the program code:
Code:
curl -X POST \
https:{domain}/getReceipt \
-H 'Content-Type: application/json' \
-d '{"key": "AutoTest_54FZ(OrangeData)","merchant_order_id": "52cc5355-775b-4903-bd86-5b1e5e259065TestOrgD5","receipt_id": "1atY16Z3wr62fhMogQmFwIDaa4C"}'urlencoded
Sample POST request:
Code:
Content-Type: application / x-www-form-urlencoded
https:{domain}/getReceipt
Key:AutoTest_54FZ(OrangeData)
OrderId:52cc5355-775b-4903-bd86-5b1e5e259065TestOrgD5
ReceiptId: 1atY16Z3wr62fhMogQmFwIDaa4CAn example of implementing a request in the program code:
Code:
curl -X POST \
https:{domain}/getReceipt \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'Key=AutoTest_54FZ(OrangeData)&OrderId52cc5355-775b-4903-bd86-5b1e5e259065TestOrgD5&ReceiptId=1atY16Z3wr62fhMogQmFwIDaa4C'Response options
| Name | Description | Fromat |
|---|---|---|
| Id | Document ID | String from 1 to 64 characters |
| DeviceSN | Serial number of the device that punched the check | String up to 20 characters |
| DeviceRN | Registration number of the device that made the check | String up to 20 characters |
| FsNumber | Fiscal accumulator number | String 16 characters |
| OFDName | OFD name | String up to 256 characters |
| OFDWebsite | CRF website | String up to 58 characters |
| OFDINN | INN OFD | String 12 characters |
| FNSWebsite | FTS website | String up to 256 characters |
| CompanyINN | User's TIN | String 12 characters |
| CompanyName | User name | String up to 256 characters |
| DocumentNumber | FD number | Number |
| ShiftNumber | Shift number | Number |
| DocumentIndex | Check number per shift | Number |
| ProcessedAt | Time of registration of a fiscal document in the FN | Time as a string in ISO8601 format |
| Content | Document content | An object |
| +- Type | Calculation attribute
| Number |
| +- Positions | List of items of calculation | Array of objects |
| +-- Quantity | The number of the subject of calculation | Number |
| +-- Price | Unit price of the subject of calculation, taking into account discounts and margins | Number |
| +-- Tax | VAT rate. An integer from 1 to 6.
| Number |
| +-- Text | Calculation subject name | String up to 128 characters |
| +-- SubjectType | Calculation subject attribute
| Number |
| +- CheckClose | Check closing options | An object |
| +-- Payments | Payment | Array of objects |
| +--- Type | Payment type
| Number |
| +--- Amount | The value of the additional user attribute | Number |
| +-- TaxationSystem | Tax system
| Number |
| +- CustomerContact | Buyer's phone or email address | String up to 64 characters |
| change | Surrender | Decimal number up to 2 characters after the dot |
| fp | Fiscal sign | String 10 characters |
Sample response
An example of a response to a successful request:
Code:
{
"Id": "1atY16Z3wr62fhMogQmFwIDaa4C",
"DeviceSN": "1400000000001093",
"DeviceRN": "0000000400054952",
"FsNumber": "9999078900001341",
"OFDName": "ООО \"Ярус\" (\"ОФД-Я\")",
"OFDWebsite": "www.ofd-ya.ru",
"OFDINN": "7728699517",
"FNSWebsite": "www.nalog.ru",
"CompanyINN": "9701015273",
"CompanyName": "AutoTestmerchant",
"DocumentNumber": 1586,
"ShiftNumber": 5776,
"DocumentIndex": 313,
"ProcessedAt": "2020-04-22T14:47:00",
"Content": {
"Type": 1,
"Positions": [
{
"Quantity": 1,
"Price": 500,
"Tax": 3,
"Text": "Mock3",
"SubjectType": 6
},
{
"Quantity": 1,
"Price": 500,
"Tax": 5,
"Text": "Mock2",
"SubjectType": 5
},
{
"Quantity": 1,
"Price": 500,
"Tax": 4,
"Text": "Mock1",
"SubjectType": 3
},
{
"Quantity": 1,
"Price": 500,
"Tax": 3,
"Text": "Mock4",
"SubjectType": 1
}
],
"CheckClose": {
"Payments": [
{
"Type": 2,
"Amount": 2000
}
],
"TaxationSystem": 0
},
"CustomerContact": "s.davydov@mapcard.pro"
},
"Change": 0,
"Fp": "505358752"
}An example of a response to an unsuccessful request:
Code:
{
"Success": false,
"ErrCode": "NOT_FOUND"
}Using 3-D Secure technology version 1
It is used when the Seller connects the 3-D Secure authentication mechanism. The order of execution - authentication of the cardholder on the side of the issuing bank and reporting the results to the gateway service.
An example for a two-step payment.
Upon receipt of a request to block funds, the gateway verifies that the card participates in 3-D Secure authentication.
If the User's card is involved in 3-D Secure technology version 1, then the response also contains the ACSUrl, PaReq and ThreeDSKey attributes.
| Name | Description | Format |
|---|---|---|
| ACSUrl | Address (URL / URI) of the 3-D Secure authentication server | Line |
| PaReq | 3-D Secure Authentication Request | Line |
| ThreeDSKey | Unique identifier for the transaction | Line |
After receiving a response from the gateway, the merchant redirects the cardholder to the site of the issuing bank for additional authentication. For this, a POST request is used to the address specified in the value of the ACSUrl attribute, with the parameters listed below.
| Name | Description | Format |
|---|---|---|
| ACSUrl | Address (URL / URI) of the 3-D Secure authentication server | Line |
| TermUrl | Redirect address after successful 3-D Secure authentication | Line |
| MD | Unique identifier for the transaction | Corresponds to the ThreeDSKey parameter from the response to the previous request |
| PaReq | 3-D Secure Authentication Request | Line |
Request example:
Code:
<body onload="document.form.submit()" >
<form name="form" action="{ACSUrl}" method="post" >
<input type="hidden" name="TermUrl" value="{TermUrl}" >
<input type="hidden" name="MD" value="{ThreeDSKey}" >
<input type="hidden" name="PaReq" value="{PaReq}" >
</form>
</body>After authorization on the website of the issuing bank, the user is returned by an HTTPS POST request to the address specified in the value of the TermUrl attribute, with the parameters specified below.
| Name | Description | Format |
|---|---|---|
| MD | Unique identifier for the transaction | Matches the one passed in the request |
| PaRes | An encrypted string containing the results of 3-D Secure authentication | Line |
Request parameters
json
| Name | Description | Format | eCom |
|---|---|---|---|
| key | Seller ID. Issued with test / combat access parameters | Line | |
| merchant_order_id | Payment ID in merchant's system | String (maximum 50 characters) | |
| pares | An encrypted string containing the results of 3-D Secure authentication | Line: Matches the answer from ACS |
urlencoded
| Name | Description | Format | eCom |
|---|---|---|---|
| Key | Seller ID. Issued to the Seller with test / combat access parameters | Line | |
| OrderId | Payment ID in the merchant's system | String (maximum 50 characters) | |
| PaRes | An encrypted string containing the results of 3-D Secure authentication |
Request example
json
Sample POST request:
Content-Type: application / json https://{domain}/Block3DS
{
"key":"TestTerminal",
"merchant_order_id":"TestOrder123",
"pares":"JQpr1kEIAQSIEYhdkxiEJOY4esfujenl5b9rPtt2l"
}
An example of implementing a request in the program code:
Code:
curl -X POST \
https://https://{domain}/Block3DS \
-H 'Content-Type: application/json' \
-d '{"key":"TestTerminal","merchant_order_id":"TestOrder123","pares":"JQpr1kEIAQSIEYhdkxiEJOY4esfujenl5b9rPtt2l"}'urlencoded
Sample POST request:
Code:
Content-Type: application / x-www-form-urlencoded https://{domain}/Block3DS
Key:TestTerminal
OrderId:TestOrder123
PaRes:JQpr1kEIAQSIEYhdkxiEJOY4esfujenl5b9rPtt2lAn example of implementing a request in the program code:
Code:
curl -X POST \
https://https://{domain}/Block3DS \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'Key=TestTerminal&OrderId=TestOrder123&PaRes=JQpr1kEIAQSIEYhdkxiEJOY4esfujenl5b9rPtt2l'Response options
| Name | Description | Format | eCom |
|---|---|---|---|
| Success | Operation success flag | true / false | |
| OrderId | Payment ID in the merchant's system | Matches the one passed in the request | |
| Amount | Blocked amount | Matches the one passed in the request | 1 |
| AuthCode | Authorization code | String (maximum 6 characters) | |
| ErrCode | Error description | See error codes | 2 |
| ErrMessage | Optional parameter. Additional error description | Line | |
| CardUId | Card ID in merchant's system. Passed in response to a methodStoreCard3DS | GUID | |
| PANMask | Masked card number in the format 123456xxxxxx1234 | Line | |
| Status | Card status. Passed in response to the StoreCard3DS method | isActive - the card is active and can be used for debiting | |
| CustomParams | List of additional parameters of the operation | Matches the Params passed in the request | |
| FeePercent | Acquiring commission rate | Number | |
| TerminalID | ID of the terminal in the merchant's system on which the operation was actually performed | Number |
2* Transmitted if the reply containsSuccess=false
Sample response
An example of a response to a successful request:
Code:
{
"Success": true,
"OrderId": "TestOrder123",
"Amount": 300,
"ErrCode": ""
}An example of a response to an unsuccessful request:
Code:
{
"Success": false,
"OrderId": "TestOrder123",
"ErrCode": "AMOUNT_EXCEED"
}In case of a one-step payment (in the case of using the Pay method), you must use the Pay3DS method instead of the Block3DS method to complete the 3-DS operation.
When saving a card involved in 3-D Secure technology, to complete the operation and receive a card ID in response, you must use the StoreCard3DS method.
The request, response parameters and field compositions of the Pay3DS and StoreCard3DS methods are similar to the Block3DS method.
Using 3-D Secure technology version 2
It is used when the Seller connects the 3-D Secure authentication mechanism. The order of execution - authentication of the cardholder on the side of the issuing bank and reporting the results to the gateway service.
An example for a two-step payment.
When sending a request for blocking funds, the merchant needs to generate an additional object threeds_ver2:
- Object shaping method
- An example of a generated object
| Name | Description | Format |
|---|---|---|
| term_url | URLto get CReswhen going through the challenge-flowscript | Line |
| browser_info | An object containing information and the User's browser | JSON object |
| +- accept_header | The content of the HTTP headers sent to the Internet acquiring system from the client's browser. The maximum value is 2048 characters. For example application / json, application / jose; charset = utf-8 | Line |
| +- color_depth | A value that represents the bit depth of the color palette for displaying images, in bits per pixel. For example 24 (screen.colorDepth) | String (maximum length - 2 characters) |
| +- java_enabled | Ability to execute java in browser (novigator.javaEnabled) | true / false |
| +- javascript_enabled | Indicator that JavaScript can be executed in the cardholder's browser | true / false |
| +- language | The browser language specified by the IETF BCP47 standard. For example, ru-RU | String (maximum length - 8 characters) |
| +- height | The total height (in pixels) of the screen displayed to the cardholder. The maximum value is 6 characters. For example 1080 (screen.height) | Line |
| +- width | The total width (in pixels) of the screen displayed to the cardholder. The maximum value is 6 characters. For example 1920 (screen.width) | Line |
| +- timezone | The time difference between UTC and the user's local (browser) time in minutes. For example, if UTC is -5, then you need to specify +300, and if UTC +5, then you need to specify -300 | String (maximum length - 5 characters) |
| +- useragent | Content of the User-Agent HTTP header. For example: Mozilla / 5.0 (X11; Linux x86_64) AppleWebKit / 537.36 (KHTML, like Gecko) Chrome / 64.0.3282.140 Safari / 537.36 | String (maximum length - 2048 characters) |
| +- window_height | The height of the browser window (in pixels) in which the page for entering authentication data will be displayed (for example, the page for entering a one-time password). The optimal value for a desktop browser is 500. | Line |
| +- window_width | The width of the browser window (in pixels) in which the page for entering authentication data will be displayed (for example, the page for entering a one-time password). The optimal value for a desktop browser is 600. | Line |
urlencoded
| Name | Description | Format |
|---|---|---|
| term_url | URLto get CReswhen going through the challenge-flowscript | Line |
| browser_info | An object containing information and the User's browser | JSON object |
| +- accept_header | The content of the HTTP headers sent to the Internet acquiring system from the client's browser. The maximum value is 2048 characters. For example application / json, application / jose; charset = utf-8 | Line |
| +- color_depth | A value that represents the bit depth of the color palette for displaying images, in bits per pixel. For example 24 (screen.colorDepth) | String (maximum length - 2 characters) |
| +- java_enabled | Ability to execute java in browser (novigator.javaEnabled) | true / false |
| +- javascript_enabled | Indicator that JavaScript can be executed in the cardholder's browser | true / false |
| +- language | The browser language specified by the IETF BCP47 standard. For example, ru-RU | String (maximum length - 8 characters) |
| +- height | The total height (in pixels) of the screen displayed to the cardholder. The maximum value is 6 characters. For example 1080 (screen.height) | Line |
| +- width | The total width (in pixels) of the screen displayed to the cardholder. The maximum value is 6 characters. For example 1920 (screen.width) | Line |
| +- timezone | The time difference between UTC and the user's local (browser) time in minutes. For example, if UTC is -5, then you need to specify +300, and if UTC +5, then you need to specify -300 | String (maximum length - 5 characters) |
| +- useragent | Content of the User-Agent HTTP header. For example: Mozilla / 5.0 (X11; Linux x86_64) AppleWebKit / 537.36 (KHTML, like Gecko) Chrome / 64.0.3282.140 Safari / 537.36 | String (maximum length - 2048 characters) |
| +- window_height | The height of the browser window (in pixels) in which the page for entering authentication data will be displayed (for example, the page for entering a one-time password). The optimal value for a desktop browser is 500. | Line |
| +- window_width | The width of the browser window (in pixels) in which the page for entering authentication data will be displayed (for example, the page for entering a one-time password). The optimal value for a desktop browser is 600. | Line |
An example of a generated object
json
Code:
"threeds_ver2": {
"term_url": "https://cres-listener.ru/",
"browser_info": {
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9",
"color_depth": "24",
"java_enabled": true,
"javascript_enabled": true,
"language": "ru-RU",
"height": "1080",
"width": "1920",
"timezone": "-180",
"useragent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.135 YaBrowser/20.8.3.115 Yowser/2.5 Safari/537.36",
"window_height": "600",
"window_width": "500"
}
}urlencoded
Code:
1. {"term_url":"https://cres-listener.ru/","browser_info":{"accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9","color_depth":"24","java_enabled":true,"javascript_enabled":true,"language":"ru-RU","height":"1080","width":"1920","timezone":"-180","useragent":"Mozilla/5.0(WindowsNT10.0;Win64;x64)AppleWebKit/537.36(KHTML,likeGecko)Chrome/84.0.4147.135YaBrowser/20.8.3.115Yowser/2.5Safari/537.36","window_height":"600","window_width":"500"}}
Code:
2. eyJ0ZXJtX3VybCI6Imh0dHBzOi8vY3Jlcy1saXN0ZW5lci5ydS8iLCJicm93c2VyX2luZm8iOnsiYWNjZXB0X2hlYWRlciI6InRleHQvaHRtbCxhcHBsaWNhdGlvbi94aHRtbCt4bWwsYXBwbGljYXRpb24veG1sO3E9MC45LGltYWdlL3dlYnAsaW1hZ2UvYXBuZywqLyo7cT0wLjgsYXBwbGljYXRpb24vc2lnbmVkLWV4Y2hhbmdlO3Y9YjM7cT0wLjkiLCJjb2xvcl9kZXB0aCI6IjI0IiwiamF2YV9lbmFibGVkIjp0cnVlLCJqYXZhc2NyaXB0X2VuYWJsZWQiOnRydWUsImxhbmd1YWdlIjoicnUtUlUiLCJoZWlnaHQiOiIxMDgwIiwid2lkdGgiOiIxOTIwIiwidGltZXpvbmUiOiItMTgwIiwidXNlcmFnZW50IjoiTW96aWxsYS81LjAoV2luZG93c05UMTAuMDtXaW42NDt4NjQpQXBwbGVXZWJLaXQvNTM3LjM2KEtIVE1MLGxpa2VHZWNrbylDaHJvbWUvODQuMC40MTQ3LjEzNVlhQnJvd3Nlci8yMC44LjMuMTE1WW93c2VyLzIuNVNhZmFyaS81MzcuMzYiLCJ3aW5kb3dfaGVpZ2h0IjoiNjAwIiwid2luZG93X3dpZHRoIjoiNTAwIn19Cg==
Code:
3. ThreedsVer2merchantData=eyJ0ZXJtX3VybCI6Imh0dHBzOi8vY3Jlcy1saXN0ZW5lci5ydS8iLCJicm93c2VyX2luZm8iOnsiYWNjZXB0X2hlYWRlciI6InRleHQvaHRtbCxhcHBsaWNhdGlvbi94aHRtbCt4bWwsYXBwbGljYXRpb24veG1sO3E9MC45LGltYWdlL3dlYnAsaW1hZ2UvYXBuZywqLyo7cT0wLjgsYXBwbGljYXRpb24vc2lnbmVkLWV4Y2hhbmdlO3Y9YjM7cT0wLjkiLCJjb2xvcl9kZXB0aCI6IjI0IiwiamF2YV9lbmFibGVkIjp0cnVlLCJqYXZhc2NyaXB0X2VuYWJsZWQiOnRydWUsImxhbmd1YWdlIjoicnUtUlUiLCJoZWlnaHQiOiIxMDgwIiwid2lkdGgiOiIxOTIwIiwidGltZXpvbmUiOiItMTgwIiwidXNlcmFnZW50IjoiTW96aWxsYS81LjAoV2luZG93c05UMTAuMDtXaW42NDt4NjQpQXBwbGVXZWJLaXQvNTM3LjM2KEtIVE1MLGxpa2VHZWNrbylDaHJvbWUvODQuMC40MTQ3LjEzNVlhQnJvd3Nlci8yMC44LjMuMTE1WW93c2VyLzIuNVNhZmFyaS81MzcuMzYiLCJ3aW5kb3dfaGVpZ2h0IjoiNjAwIiwid2luZG93X3dpZHRoIjoiNTAwIn19Cg==Upon receipt of a request to block funds, the gateway verifies that the card participates in 3-D Secure authentication.
If the User's card is involved in 3-D Secure technology version 2, then the response also contains the attributes ThreedsMethodURL, Is3DSVer2 and ThreedsMethodURLData.
| Name | Description | Format | eCom |
|---|---|---|---|
| ThreedsMethodURL | Address (URL / URI) of the 3-D Secure authentication server to collect information about the client's browser | Line | |
| ThreedsMethodURLData | Base64 encoded string | Line | |
| Is3DSVer2 | Operation flag using 3DS technology version 2 | true / false |
After receiving a response from the gateway, the Seller sends a request through a request hidden iframein the User's browser, the composition of the request:
- POST ThreedsMethodURL
- Content-Type: application / x-www-form-urlencoded
- Parameter threeDSMethodDatawith the value ThreedsMethodURLDatareceived in the response
Upon receipt of the response code 202after being redirected to the URLgateway, the merchant sends a request to Block3DS:
Request parameters
json
| Name | Description | Format | eCom |
|---|---|---|---|
| key | Seller ID. Issued with test / combat access parameters | Line | |
| merchant_order_id | Payment ID in merchant's system | String (maximum 50 characters) |
urlencoded
| Name | Description | Format | eCom |
|---|---|---|---|
| Key | Seller ID. Issued to the Seller with test / combat access parameters | Line | |
| OrderId | Payment ID in the merchant's system | String (maximum 50 characters) |
Request example
json
Code:
Sample POST request:
Content-Type: application / json
{{endpoint}}/Block3DS
{
"key":"TestTerminal",
"merchant_order_id":"TestOrder123"
}An example of request implementation:
Code:
curl -X POST {{endpoint}}/Block3DS -H 'Content-Type: application/json' -d '{"key":"TestTerminal","merchant_order_id":"TestOrder123"}'urlencoded
Code:
Sample POST request:
Content-Type: application / x-www-form-urlencoded
{{endpoint}}/Block3DS
Key=TestTerminal
OrderId=TestOrder123An example of request implementation:
Code:
curl -X POST {{endpoint}}/Block3DS -H 'Content-Type: application/x-www-form-urlencoded' -d 'Key=TestTerminal&OrderId=TestOrder123'Response options
| Name | Description | Format | eCom |
|---|---|---|---|
| Success | Operation success flag | true / false | |
| ACSUrl | The address (URL / URI) of the 3-D Secure authentication server when the script passes challenge-flow | Line | 1 |
| CReq | 3-D Secure Authentication Request When Passing a Scenario challenge-flow | Line | 1 |
| OrderId | Payment ID in the merchant's system | Matches the one passed in the request | |
| Amount | Blocked amount | Matches the one passed in the request | 1 |
| AuthCode | Authorization code | String (maximum 6 characters) | |
| ErrCode | Error description | See error codes | 2 |
| ErrMessage | Optional parameter. Additional error description | Line | |
| CardUId | Card ID in merchant's system. Passed in response to a methodStoreCard3DS | GUID | |
| PANMask | Masked card number in the format 123456xxxxxx1234 | Line | |
| Status | Card status. Passed in response to the StoreCard3DS method | isActive - the card is active and can be used for debiting | |
| CustomParams | List of additional parameters of the operation | Matches the Params passed in the request | |
| FeePercent | Acquiring commission rate | Number | |
| TerminalID | ID of the terminal in the merchant's system on which the operation was actually performed | Number |
| Name | Description | Format |
|---|---|---|
| ACSUrl | Address (URL / URI) of the 3-D Secure authentication server | Line |
| PaReq | 3-D Secure Authentication Request | Line |
| ThreeDSKey | Unique identifier for the transaction | Line |
2* Transmitted if the reply containsSuccess=false
Sample response
An example of a response to a successful request:
Code:
{
"Success": true,
"OrderId": "TestOrder123",
"Amount": 300,
"ErrCode": ""
}An example of a response to an unsuccessful request:
Code:
{
"Success": false,
"OrderId": "TestOrder123",
"ErrCode": "AMOUNT_EXCEED"
}3-D Secure version 2 authentication follows one of two scenarios:, frictionless-flowor challenge-flow. Scenario authenticated, it depends on the availability of the parameters ACSUrl, CReqin response to the request Block3DS.
- In the absence of parameters ACSUrl, the CReqscript is considered frictionless-flowand does not require additional steps for authentication.
- If parameters are present ACSUrl, the CReqscript is considered challenge-flowand requires additional steps for authentication.
Walkthrough scenario challenge-flow:
After receiving a response from the gateway, the merchant redirects the cardholder to the site of the issuing bank for additional authentication. To do this, use a POST request to the address specified in the attribute value ACSUrl, the composition of the request:
- POST ACSUrl
- Content-Type: application / x-www-form-urlencoded
- Parameter creqwith the value CReqreceived in the response
After authorization on the issuing bank's website, the user is returned by an HTTPS POST request to the address specified in the term_urlrequest Blockparameter with the parameter specified below.
| Name | Description | Format |
|---|---|---|
| cres | An encrypted string containing the results of 3-D Secure authentication | Line |
Request parameters
json
| Name | Description | Format | eCom |
|---|---|---|---|
| key | Seller ID. Issued with test / combat access parameters | Line | |
| merchant_order_id | Payment ID in merchant's system | String (maximum 50 characters) | |
| cres | An encrypted string containing the results of 3-D Secure authentication | Line: Matches the answer from ACS | 1 |
urlencoded
| Name | Description | Format | eCom |
|---|---|---|---|
| Key | Seller ID. Issued to the Seller with test / combat access parameters | Line | |
| OrderId | Payment ID in the merchant's system | String (maximum 50 characters) | |
| CRes | An encrypted string containing the results of 3-D Secure authentication | Line: Matches the answer from ACS |
Request example
json
Sample POST request:
Code:
Content-Type: application / json https://{domain}/Block3DS
{
"key":"TestTerminal",
"merchant_order_id":"TestOrder123",
"cres":"JQpr1kEIAQSIEYhdkxiEJOY4esfujenl5b9rPtt2l"
}An example of implementing a request in the program code:
Code:
curl -X POST {{endpoint}}/Block3DS -H 'Content-Type: application/json' -d '{"key":"TestTerminal","merchant_order_id":"TestOrder123", "cres":"JQpr1kEIAQSIEYhdkxiEJOY4esfujenl5b9rPtt2l"}'urlencoded
Sample POST request:
Code:
Content-Type: application / x-www-form-urlencoded https://{domain}/Block3DS
Key:TestTerminal
OrderId:TestOrder123
CRes:JQpr1kEIAQSIEYhdkxiEJOY4esfujenl5b9rPtt2lAn example of implementing a request in the program code:
Code:
curl -X POST {{endpoint}}/Block3DS -H 'Content-Type: application/x-www-form-urlencoded' -d 'Key=TestTerminal&OrderId=TestOrder123&CRes=JQpr1kEIAQSIEYhdkxiEJOY4esfujenl5b9rPtt2l'Response options
| Name | Description | Format | eCom |
|---|---|---|---|
| Success | Operation success flag | true / false | |
| OrderId | Payment ID in the merchant's system | Matches the one passed in the request | |
| Amount | Blocked amount | Matches the one passed in the request | 1 |
| AuthCode | Authorization code | String (maximum 6 characters) | |
| ErrCode | Error description | See error codes | 2 |
| ErrMessage | Optional parameter. Additional error description | Line | |
| CardUId | Card ID in merchant's system. Passed in response to a methodStoreCard3DS | GUID | |
| PANMask | Masked card number in the format 123456xxxxxx1234 | Line | |
| Status | Card status. Passed in response to the StoreCard3DS method | isActive - the card is active and can be used for debiting | |
| CustomParams | List of additional parameters of the operation | Matches the Params passed in the request | |
| FeePercent | Acquiring commission rate | Number | |
| TerminalID | ID of the terminal in the merchant's system on which the operation was actually performed | Number |
2* Transmitted if the reply containsSuccess=false
Sample response
An example of a response to a successful request:
Code:
{
"Success": true,
"OrderId": "TestOrder123",
"Amount": 300,
"ErrCode": ""
}An example of a response to an unsuccessful request:
Code:
{
"Success": false,
"OrderId": "TestOrder123",
"ErrCode": "AMOUNT_EXCEED"
}In case of a one-step payment (in the case of using the Pay method), you must use the Pay3DS method instead of the Block3DS method to complete the 3-DS operation.
When saving a card involved in 3-D Secure technology, to complete the operation and receive a card ID in response, you must use the StoreCard3DS method.
The request, response parameters and field compositions of the Pay3DS and StoreCard3DS methods are similar to the Block3DS method.
Requirements for posting information on the company's website
* to ensure the confidentiality of the information of Cardholders and to ensure the security of the Operations
The requirements below are mandatory for an online store that accepts payments through merchant Processing Center for review and implementation. The compliance of the website of the online store with the requirements presented in the document allows you to minimize the risk of Fraudulent transactions and subsequent financial costs to pay off fines when buyers initiate returns, as well as eliminate the risk of leakage of confidential information of Buyers through the website of the online store. In accordance with the rules and recommendations and acquiring banks, the online store must provide its own methods of control and minimization of risks to prevent fraudulent transactions when accepting payments using bank cards.
1. Contacts and details
1.1. Phone number with hours of operation.
1.2. E-mail address.
1.3. The actual address of the company.
1.4. Full name of the legal entity.
1.5. State registration number of a legal entity or individual entrepreneur.
The presence on the website of the online store of a section containing contact information and company details is mandatory. The data is required to successfully pass the verification at the acquiring bank. Lack of data may become the basis for refusal of the acquiring bank in cooperation with the online store.
2. Description of the payment process, logos of payment systems and merchant
2.1. The website of the online store should contain (it is recommended to place it in the "Payment" section) a list of available payment methods for the order and a description of the payment process for each of the available tools. The description of the process of paying for the order by bank cards must contain information about merchant processing center.
2.2. The website of the online store must contain a description of the process and conditions (including possible penalties) for refunding money to the Buyer's card when the Buyer refuses to order, exchange or provide interchangeable goods or services. If a refund procedure is not provided, the information should be posted on the website of the online store.
2.3. On the website of the online store (in the section "Payment for the order" or in the "basement" of the site), the logos of merchant processing center and payment systems (VISA, MasterCard and MIR) must be placed.
The lack of information on the conditions for the return creates the risk of penalties if the Buyer initiates a refund through the Bank or the Payment System, and the conditions for the return will not be described on the website of the online store.
3. Description of the order delivery process
3.1. The website of the online store must contain the terms, methods, conditions, as well as any other information necessary to obtain a clear and clear idea of the delivery of goods and the provision of services after payment by credit card.
3.2. The website of the online store should contain detailed information about the restrictions on the delivery of goods / services to certain regions, as well as export restrictions and rules for the delivery of goods / services outside the Europa/USA/Asia (if there are such restrictions).
The lack of information on the conditions, cost and delivery time creates the risk of penalties if the Buyer initiates a refund through the Bank or the Payment System due to the failure to provide the service (due to long delivery), and the conditions and delivery times will not be described on the website of the online store.
4. List and description of goods (services)
4.1. Each product or service page should contain a detailed description:
- for a product - characteristics, dimensions, photographs, equipment, material, price;
- for software - system requirements;
- for services - description, methods and terms of service provision.
4.3. The list of goods or services sold on the site must fully correspond to the goods and services listed in the merchant's questionnaire, as well as in the agreement with the acquiring bank.
4.4. If the range of goods or services changes, merchant must notify merchantat least 5 working days before the changes are reflected on the website. The notification is sent in the form of an official letter.
A detailed and correct description is necessary to minimize the risk of a forced refund or opposition to payment by the buyer due to insufficient information about the product.
5. Domain and hosting
5.1. The website of the online store must be located on a second-level domain (example: www.shop.com) and contain at least 2 and no more than 11 characters.
5.2. All pages and interfaces related to the operation of the site must be under a single domain name.
5.3. It is allowed to host the connected website on a third-level domain (example: www.internet.shop.com) if the main site of the company is located on the same second-level domain.
5.4. The site should not be located on free servers that provide hosting services or free domains, as well as on social media pages (VK, Facebook, Instagram, etc.).
Placing a site on a third-level domain or on free hosting may become the basis for the acquiring bank's refusal to cooperate with the online store.
6. Security of personal data of Buyers
6.1. It is not allowed to request bank card details (PAN, CVC2 / CVV2, Expiration Date) on the pages of the online store.
6.2. When paying with a bank card, the buyer must be redirected to merchant's's secure payment form to enter their bank card details.
6.3. The secure payment form merchantshould be presented as a standard browser window with all standard features.
6.4. It is not allowed to place a payment form in a pop-up window (Pop-Up).
6.5. Placing a payment form using an Iframe (integrating a payment form into a website page) is not allowed without the approval of merchant.
Violation of the rules for processing personal data of Buyers may result in the imposition of penalties on the online store and the processing center.
7. Functional authorization and personal account of the Buyer
7.1. It is recommended to provide Buyers with the opportunity to register - and provide the ability to make payments by bank cards only to registered Buyers.
7.2. It is recommended to store the database of registered customers on the side of the online store. The minimum storage period for the database is 7 months.
7.3. It is recommended to provide for the possibility of a direct transition from any page of the website of the online store to the registration form and merchant's payment form.
7.4. It is recommended to provide for the sending of registration data to the email address specified by the buyer.
It is recommended to implement the "Personal Account" of the online store client on the site to save the history of user orders. The history of the formation of orders may be required in case of receiving requests for this information from the acquiring bank.
