Payments
When sending requests, use the header "Content-Type: application / x-www-form-urlencoded
Parameters order in requests is not important.
Characters case in url addresses and query parameters is important.
The response to the request is transmitted in JSON format, encoding UTF-8.
API responses may contain undocumented fields. While processing responses, such fields should be ignored by the client code.
Payment initialization request. Performed before the user redirects to the Payler payment gateway page.
Available for: gapi
Request method:
POSTRequest parameters
Name | Format | R/O | Description |
key | A..100 | R | Merchant ID. Issued to the merchant with the access parameters |
type | A | R | Operation type. Determines the number of payment stages. OneStep (1)—one-stage payment;
TwoStep (2)—two-stage payment |
session_type | N1 | O | Session type regarding to the storage of card data. If this parameter is 1, then customer_id must be passed. 0—normal transfer page; 1—payment page with the parameter of selecting from stored cards or entering complete card data for payment by a card not listed. When selecting a saved card, the user only needs to enter CVV; By default—0 |
order_id | A..100 | R | ID of the order to be paid for in the merchant system. For each transfer (session), it is required to use a unique identifier. Only printed ASCII-signs are allowed |
customer_id | A..100 | O | Customer ID. Defines the customer whose list of cards will be available for selection (if session_type is 1), or for which the card used for payment will be saved. The customer is automatically created if this field is left blank |
currency | A3 | O | |
amount | N | R | Operation amount in minimum currency units (kopecks, cents etc) |
product | A..256 | O | Name of the product to be paid for |
template | A..100 | O | Payment page template specified by the merchant. If there is no template, the "Default" template is used |
lang | A2 | O | Preferred language of the payment form.
en—English; ru—Russian. By default—Russian |
userdata | A..1000 | O | User data. In this line, you can pass any information that you need to save with the payment, and then get it using the GetAdvancedStatus |
recurrent | N1 | O | Indicates whether you want to create a recurring payment template based on the current one. Bool type value.
true or 1—you need to create a template;
false or 0—no template is required |
pay_page_param_* | A..100 | O | Parameters to display on the payment page. You can pass any parameters that begin with pay_page_param_, and then display them on the payment page. To do this, you must use the page template (see parameter template) |
pay_page_param_addtoreport3 | A | O | When using split payments: the payment amounts for each recipient need to be indicated in the smallest currency unit (kopecks, cents, etc.) separated by commas |
pay_page_param_addtoreport4 | A | O | When using split payments: recipient IDs need to be separated by commas. IDs are registered by Payler technical support |
antifraud_* | A..100 | O | Additional parameters for antifraud. You can pass any parameters that begin with antifraud_ |
payment_methods | A..500 | O | Methods of payment for this session. If the parameter is not specified, then all the methods allowed to the merchant will be available. The comma separated list of available payment methods for this session. See Payment methods |
email | A..100 | R | User email |
return_url_success | A..1000 | O | URL to which the user will be redirected in case of a successful payment |
return_url_decline | A..1000 | O | URL to which the user will be redirected in case of an unsuccessful payment |
lifetime | N | O | Session lifetime in minutes, from 1 minute or more |
Response parameters
Name | Format | R/O | Description |
order_id | A..100 | R | ID of the order to be paid for in the merchant system. Corresponds to the one sent in the request |
amount | N | R | Operation amount in minimum currency units (kopecks, cents etc). Corresponds to the one sent in the request |
session_id | A..100 | R | Payment session ID |
Example of the response to a successful request:
{
“amount”: 30000,
“session_id”: “FE6nrdcfw4Zy88Crki6sjc1mRxW9xcv7m7CS”,
“order_id”: “d1434908-7260-483e-8254-fa43af1b835d”
}
Charge funds request with the user redirect to the gateway page. Runs after StartSession command. The result of the processing of the request is the writing-off of funds under a one-stage payment scheme, or the blocking of funds on the user’s card under a two-stage payment scheme.
Available for: gapi
Request method:
GETRequest parameters
Name | Format | R/O | Description |
session_id | A..100 | R |
After processing the PayGate request on the side of the payment gateway, the user will be redirected to the page with payment results and returned to the merchant's site in 3 seconds.
The return address of the user (URL of the page) is indicated by the merchant in advance as a URL. Example of the return address: http://myshop.ru/complete?order_id={order_id}
To obtain operation results, you should use the data obtained within the operation status request (see GetStatus method). It should be noted that the return to the specified URL can be made several times, for example, when the user is confused, they click the "Back" button in the browser and entered their card data several times for payment. If the user mistakenly tries to save the card again within one session, they see a message stating that the card has already been saved. The user is redirected to the merchant's website.
Search for a payment session by payment ID (order_id).
Available for: gapi, mapi
Request method:
POSTRequest parameters
Name | Format | R/O | Description |
key | A..100 | R | Merchant ID. Issued to the merchant with the access parameters |
order_id | A..100 | R | ID of the order to be paid for in the merchant system.
Only printed ASCII-signs are allowed |
Response parameters
Name | Format | R/O | Description |
id | A..100 | R | Payment session ID |
created | A | R | Session creation time in the format "yyyy-MM-dd HH:mm:ss" |
valid_through | A | R | Duration of the session in the format "yyyy-MM-dd HH:mm:ss" |
type | A | R | Operation type. Determines the number of payment stages. OneStep (1)—one-stage payment;
TwoStep (2)—two-stage payment |
customer_id | A..100 | O | Customer ID |
order_id | A..100 | R | ID of the order to be paid for in the merchant system. ASCIIsigns are allowed |
amount | N | R | Operation amount in minimum currency units (kopecks, cents etc) |
product | A..256 | R | Name of the product to be paid for |
currency | A..3 | R | |
pay_page_params | D | R | Parameters to display on the payment page |
userdata | A..10000 | R | User data |
lang | A2 | R | Preferred language of the payment form responses.
en—English; ru—Russian |
recurrent | B | R | Indicates whether you want to create a recurring payment template based on the current one. Bool type value.
true or 1—you need to create a template;
false or 0—no template is required |
session_type | A | R | Session type regarding to the storage of card data. If this parameter is 1, then customer_id must be passed. 0—normal transfer page; 1—payment page with the parameter of selecting from stored cards or entering complete card data for payment by a card not on the list. When selecting a saved card, the user only needs to enter CVV; By default—0 |
Example of the response to a successful request:
{
“id”: “VlaFQpI88NpCncTA1TkhlX6HtkhzwQAKhxvz”,
“created”: “2015-10-26 17:11:30”,
“valid_through”: “2015-10-26 17:11:30”,
“type”: “OneStep”,
“order_id”: “ad7ad8b4-d50e-4b68-72f4-ca1264a8fae4”,
“amount”: 30000,
“product”: “el-ticket”,
“currency”: “RUB”,
“pay_page_params”: {“pay_page_param_phone”: “+790012345678”, “pay_page_param_city”:”Moscow””},
“userdata”: “data”,
“lang”: “RU”,
“recurrent”: true,
“customer_id”: “kfRWk8nbT9LhO19sVYotkJ2gHSPs5E4Qph35”,
“session_type”: “0”
}
The request is executed within the confines of a one-stage payment scheme. The result of the processing of the request is the charging-off of funds from the user’s card.
Available for: mapi
Request method:
POSTRequest parameters
Name | Format | R/O | Description |
key | A..100 | R | Merchant ID. Issued to the merchant with the access parameters |
order_id | A..100 | R | ID of the order to be paid for in the merchant system. For each operation (session), it is required to use a unique identifier. Only printed ASCII-signs are allowed |
currency | A3 | О | |
amount | N | R | Operation amount in minimum currency units (kopecks, cents etc) |
card_number | A..19 | O | Card number. A line containing decimal digits without delimiters [0–9] |
card_holder | A..100 | О | Cardholder name. The line (maximum 26 signs) containing Latin signs, decimal digits or a space character [a-zA-Z0–9] |
expired_year | N2 | O | Card expiration year |
expired_month | N2 | O | Card expiration month |
secure_code | A | R | Card authentication code (CVC2/CVV2). The line containing decimal digits [0–9] |
lang | A2 | О | Preferred language of the payment form responses.
en—English; ru—Russian.
By default—Russian |
email | A..100 | R | User email |
userdata | A..1000 | О | User data. In this line, you can pass any information that you need to save with the payment and then get it using GetAdvancedStatus |
recurrent | N1 | О | Indicates whether you want to create a recurring payment template based on the current one. Bool type value.
true or 1—you need to create a template;
false or 0—no template is required |
card_id | A..100 | О | ID of the saved card. If specified, you may not specify card_number, expired_year, expired_month, just specify secure_code |
save_card | B | О | Indicates whether you should save card data. If this parameter is passed, then the customer_id is to be passed, too.
true or 1—you want to save the card;
false or 0—you do not need to save the card |
customer_id | A..100 | О | Customer ID. If the save_card parameter is set to true or 1, it indicates for which client the card will be saved. If the parameter card_id is passed, it shows which client the card belongs to (the value must match the one specified when saving the card). Generated by the merchant. The customer is automatically created if this field is left blank |
antifraud_* | A..100 | О | Additional parameters for antifraud. You can pass any parameters that begin with antifraud_ |
user_entered_* | A..100 | О | You can specify additional payment fields that begin with user_entered_. The maximum length of each parameter is 100 symbols. Then all these fields are returned to GetAdvancedStatus in the field user_entered_params |
payer_ip | A | R | User`s browser IP address |
browserAccept | A | R | Accept header from the user`s browser |
browserLanguage | A | R | User`s browser device language. En—English; ru—Russian |
browserUserAgent | A | R | Content of the User-Agent header in the user's browser |
browserJavaEnabled | B | R | Indicator that Java can be executed in the user’s device browser |
browserJavascriptEnabled | B | O | Indicator that JavaScript can be executed in the user’s device browser. By default—true |
browserScreenHeight | A | R | Total height of the user’s device screen in pixels |
browserScreenWidth | A | R | Total width of the user’s device screen in pixels |
browserColorDepth | A | R | Color rendering depth in bits |
browserTZ | A | R | Time zone — time difference between UTC time and the local browser time on the user's device (in minutes) |
threeDsNotificationUrl | A | R | |
pay_page_param_addtoreport3 | A | O | When using split payments: the payment amounts for each recipient need to be indicated in the smallest currency unit (kopecks, cents, etc.) separated by commas |
pay_page_param_addtoreport4 | A | O | When using split payments: recipient IDs need to be separated by commas. IDs are registered by Payler technical support |
fee | N | O | Commission amount in minimum currency unit (kopecks, cents etc) |
Response parameters
Name | Format | R/O | Description |
order_id | A..100 | R | ID of the order to be paid for in the merchant system. Corresponds to the one sent in the request |
amount | N | R | Operation amount in minimum currency unit (kopecks, cents etc). Corresponds to the one sent in the request |
auth_type | N1 | R | Value indicating whether additional authorization is required for payment. None (0)—Additional authorization is not required;
ThreeDS (1)—3-D Secure authorization |
recurrent_template_id | A..100 | О | Recurring payment template identifier. It is present if within the current operation a template of recurring payments is created |
card_id | A..100 | О | Saved card ID |
card_status | A | О | Card status. Saved—card is saved and ready to use. Invalid—card is not valid (for example, it has expired) |
card_number | A..19 | R | Masked number of the bank card to which the template is attached. Indicates when the first payment is made in a series of recurring payments. String, which contains decimal digits without delimiters [0–9] and the masking character ‘x’ |
card_holder | A..100 | R | Name of the cardholder |
expired_month | N2 | R | Card expiration month |
expired_year | N2 | R | Card expiration year |
acs_url | A..2048 | O | URL to redirect the user to pass 3DS (access control service) |
md | A* | O | Transaction number at the IPS for identification during the completion of 3DS 1.0 (Merchant Data) |
pareq | A* | O | Transaction data for completing 3DS 1.0 (Payment Authentication Request) |
threeDS_server_transID | A | O | |
threeDS_method_url | A | O | |
creq | A | O | Data for authorization on 3DS 2.0 after completing the Challenge |
status | A..10 | O | Status of the operation |
Examples of responses to successful requests:
{
"threeDS_server_transID":"9f7f012d-d6d0-38fe-9bfd-70a727c7473a",
"threeDS_method_url":"https://someurl.com",
"auth_type":1,
"amount":2050,
"order_id":"c8ebb763-5b75-4c5e-a731-2489220b4f2a"
}
{
"acs_url":"https://someurl.com",
"creq":"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImE3ZTYzZWRkLTYwYTgtMzE0Yi
04MzJlLTU3YTFhNzg2NTZjZSIsImFjc1RyYW5zSUQiOiJhM2MxMDQwYS05OGUxLTQ0
N2EtOTE4Ni0zYzY3N2MyODMxNmEiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLC
JtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0=",
"auth_type":1,
"amount":2050,
"card_number":"411111xxxxxx1111",
"card_holder":"NONAME",
"expired_year":20,
"expired_month":12,
"order_id":"201d6446-c351-4df6-8f46-8f5b24be76aa"
}
If the card is involved in 3DS 1.0:
{
"acs_url": "https://web.rbsuat.com/acs/auth/start.do",
"pareq": "eJxVUdluwjAQ/BWU9+ADhwBajNICAlUBWkKl9i3HFlKRAxMq4OtrByhU8sPMejRjz8LgmG0bP6j2aZH3LdakVgPzuEjSfN23VsHY7lgDCcFGIQ6XGB8USvBxvw/X2EiTvvXluOi6HWFjRIUtusyxIx4Lm1FkPBKUJu3IkrDw3nAn4RokdU6TA7lR7ajiTZhXEsJ49zSdScHdNqVArhQyVNOhZLwlnLYL5EIhDzOUZXjaogJSE4iLQ16pk2yLFpAbgYPayk1VlT1CLvJmXGRAzBjIPXxxMGivbY5pIv3g9eyf13wejNjs2xezs8f84ciZD70+EKOAJKxQcsq61OWtBu30uD4MSD2HMDP50qk/csFQmgjv4eJxALpfpeu/Pf/GAI9lkaNW6NL+MJD7e58nprq40q2UbiZoNFpUbjUOJi/55/sqGe/Ws6WHH6bQWmQcU90M67KLpSFAjA257opc16zRv/X/Aj0Rt1Q=",
"md": "949cdebb-b7a7-46b0-874e-bd11f410992c",
"auth_type": 1,
"amount": 500,
"card_number": "411111xxxxxx1111",
"card_holder": "IVAN",
"expired_year": 19,
"expired_month": 12,
"order_id": "test_example_002"
}
If the card is not involved in 3DS, or the authentication is successful via frictionless flow, and the 3DSMethod is not required:
{
"auth_type": 0,
"amount": 500,
"recurrent_template_id": "rec-pay-42301e79-b92d-4753-b248-b92ad552fdfd",
"card_number": "555555xxxxxx5599",
"card_holder": "IVAN",
"expired_year": 19,
"expired_month": 12,
"order_id": "test_example_003",
"status": "Charged"
}
If the request specified the value of the recurrent parameter is set to true, the operation is successful, but the template ID is not returned in response, then the operation has gone through the normal scheme without creating a recurring payment template.
After making PayMerchant request, you need to call GetStatus to get the current status of the operation.
Maestro cards
Rules of the IPS prohibit recurring payments on Maestro cards. We can set up your account so that when you try to pay a payment session with the creation of a recurring payment (in the StartSession request, the value of the recurrent parameter is set to true), the payment is declined, and the user receives a message that this type of card is not supported.
The request is executed within the confines of a two-stage payment scheme.
The result of processing the request is the blocking of funds on the user's card.
Available for: mapi
Request method:
POSTRequest parameters
Name | Format | R/O | Description |
key | A..100 | R | Merchant ID. Issued to the merchant with the access parameters |
order_id | A..100 | R | ID of the order to be paid for in the merchant system. For each operation (session), it is required to use a unique identifier. Only printed ASCII-signs are allowed |
currency | A3 | О | Operation currency (RUB, USD, EUR, GBP, PLN, TJS, KGS). By default—RUB |
amount | N | R | Operation amount in minimum currency units (kopecks, cents etc) |
card_number | A..19 | O | Card number. Decimal digits without delimiters [09] |
card_holder | A..100 | О | Cardholder name. Latin signs, decimal digits or a space character [a-zA-Z0–9] |
expired_year | N2 | O | Card expiration year |
expired_month | N2 | O | Card expiration month. Integer two-digit number in the format with leading zero |
secure_code | A | R | Card authentication code (CVC2/CVV2). Decimal digits [0–9] |
email | A..100 | R | User email |
lang | A2 | О | Preferred language of the payment form responses. en—English; ru—Russian.
By default—Russian |
userdata | A..10000 | О | User data. In this line, you can pass any information that you need to save with the payment and then get it using GetAdvancedStatus |
recurrent | A..100 | О | Indicates whether you want to create a recurring payment template based on the current one. Bool type value.
true or 1—you need to create a template;
false or 0—no template is required |
card_id | A..100 | О | ID of the saved card. If specified, you may not specify card_number, expired_year, expired_month, just specify secure_code |
save_card | N1 | О | Indicates whether you should save card data. If this parameter is passed, then the customer_id is to pass, too.
true or 1—you want to save the card;
false or 0—you do not need to save the card |
customer_id | A..100 | О | Customer ID. If the save_card parameter is set to true or 1, it indicates for which client the card will be saved. If the parameter card_id is passed, it shows which client the card belongs to (the value must match the one specified when saving the card). Generated by the merchant |
user_entered_* | A..100 | О | You can specify additional payment fields that begin with user_entered_. The maximum length of each parameter is 100 symbols. Then all these fields are returned to GetAdvancedStatus in the field user_entered_params |
pay_page_param_addtoreport3 | A | O | When using split payments: the payment amounts for each recipient need to be indicated in the smallest currency unit (kopecks, cents, etc.) separated by commas |
pay_page_param_addtoreport4 | A | O | When using split payments: recipient IDs need to be separated by commas. IDs are registered by Payler technical support |
antifraud_* | A..100 | O | Additional parameters for antifraud. You can pass any parameters that begin with antifraud_ |
payer_ip | A | O | User`s browser IP address |
browserAccept | A | R | Accept the header from the user`s browser |
browserLanguage | A | R | User`s browser device language. en—English; ru—Russian |
browserUserAgent | A | R | Content of the User-Agent header in the user's browser |
browserJavaEnabled | B | R | Indicator that Java can be executed in the user’s device browser |
browserJavascriptEnabled | B | O | Indicator that JavaScript can be executed in the user’s device browser. By default—true |
browserScreenHeight | A | R | Total height of the user's device screen in pixels |
browserScreenWidth | A | R | Total width of the user's device screen in pixels |
browserColorDepth | A | R | Color rendering depth in bits |
fee | N | O | Commission amount in minimum currency unit (kopecks, cents etc) |
browserTZ | A | R | Time zone—time difference between UTC time and the local browser time on the user's device (in minutes) |
threeDsNotificationUrl | A | R |
Response
If the request specified the value of the recurrent parameter to be true, and the operation is successful, but the template ID is not returned in response, then the operation has gone through the normal scheme without creating a recurring payment template.
This method is called on the issuing bank side if the threeDS_server_transID and threeDS_method_url values are returned in the PayMerchant, Block or PaySaveCard response.
The merchant needs to add javascript to the user's page— iframe with html-form with threeDSMethodData. Javascript submits this form by making a POST request to threeDSmethodUrl (see the value of threeDS_method_url in PayMerchant, Block or PaySaveCard response).
Example of iframe content:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>3DS Method</title>
<script type="text/javascript"
language="javascript">function moveWindow() { document.returnform.submit(); } /script>
</head>
<body onLoad="javascript:moveWindow()">
<form name="returnform" action="' + threeDsMethodUrl + '" method="POST">
<input type="hidden" name="threeDSMethodData" value="' + threeDSMethodData + '" />
<noscript>
<center>Please click the submit button below.<br /><input type="submit" name="submit" value="Submit" />
</center>
</noscript>
</form>
</body>
</html>
Execution scenario
- 1.The merchant's system in a hidden iframe sends the threeDSMethodData parameter to the ThreeDSMethodURL using the POST method. At this step, threeDSMethodData is a base64url encoded json object with fields:threeDSMethodNotificationURL—the address to which ACS will send a POST request after collecting information about the user's browser;threeDSServerTransID—the value of the threeDS_method_url parameter.
- 2.ACS sends a page with a script to collect information about the browser on the user's side;
- 3.ACS collects information about the user's browser;
- 4.The collected information about the browser is sent to ACS;
- 5.ACS sends a POST request to threeDSMethodNotificationURL and passes threeDSMethodData parameter in the request. At this step, threeDSMethodData is a base64url encoded json object with a threeDSServerTransID field.
After receiving a POST request from ACS to the address threeDSMethodNotificationURL, or if the request has not been received within the timeout specified in the protocol (10 seconds), the merchant's system performs the ThreeDsMethodComplete request.
Available for: gapi, mapi
Request method:
POSTRequest parameters
Name | Format | R/O | Description |
threeDs_comp_ind | A1 | R | Result of completing 3DS 2.0 authentication.
Possible values: Y—success (callback from ACS was received), N—deviation (callback from ACS was not received) |
key | A | R | Merchant's payment key |