Payler API
Search
K

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.

StartSession

Payment initialization request. Performed before the user redirects to the Payler payment gateway page.
Available for: gapi
Request method: POST
Request 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
Operation currency (see Currencies directory). By default—RUB
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”
}

PayGate

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: GET
Request parameters
Name
Format
R/O
Description
session_id
A..100
R
Payment session ID. Contained in response to a query StartSession
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.

FindSession

Search for a payment session by payment ID (order_id).
Available for: gapi, mapi
Request method: POST
Request 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
Operation currency (see Currencies directory). By default—RUB
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
}

PayMerchant

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: POST
Request 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 (see Currencies directory). By default—RUB
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
Redirect Url after performing ChallengeComplete
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
Unique identifier assigned by the 3DS server. 3DSMethod call required
threeDS_method_url
A
O
Value to be passed in the request to 3DSMethod
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:
If the card is involved in 3DS 2.0 and a 3DSMethod call is required:
{
"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"
}
If the card is involved in 3DS 2.0 and a ChallengeComplete call is required:
{
"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.

Block

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: POST
Request 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
Redirect Url after performing ChallengeComplete
Response
Response format corresponds to the result of PayMerchant.
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.

3DSMethod

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. 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. 2.
    ACS sends a page with a script to collect information about the browser on the user's side;
  3. 3.
    ACS collects information about the user's browser;
  4. 4.
    The collected information about the browser is sent to ACS;
  5. 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.

ThreeDsMethodComplete

Completion of authentication using the 3DS 2.0 protocol. Executed after calling 3DSMethod.
Available for: gapi, mapi
Request method: POST
Request 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