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.
Request URL: https://{host}.payler.com/gapi/StartSession
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
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
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.
Request URL: https://{host}.payler.com/gapi/Pay
Available for: gapi
Request method: GET
Request parameters
Name
Format
R/O
Description
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).
Request URL: https://{host}.payler.com/{api}/FindSession
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
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.
Request URL: https://{host}.payler.com/mapi/v1/Pay
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
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]
product
A..256
O
Name of the product to be paid for
lang
A2
О
Preferred language of the payment form responses. en—English; ru—Russian. By default—Russian
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
URL to get the 3DS challenge result
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)
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.
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.
Request URL: https://{host}.payler.com/mapi/v1/Block
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]
product
A..256
O
Name of the product to be paid for
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
URL to get the 3DS challenge result
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
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_server_transID parameter.
ACS sends a page with a script to collect information about the browser on the user's side;
ACS collects information about the user's browser;
The collected information about the browser is sent to ACS;
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.
Request URL: https://{host}.payler.com/{api}/ThreeDsMethodComplete
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
A
R
Merchant's payment key
threeDS_server_transID
A
R
ThreeDSServerTransID value received in response to PayMerchant, Block or PaySaveCard request
Response parameters
Name
Format
R/O
Description
acs_url
A
O
URL to redirect the user to pass 3DS (access control service)
creq
A
O
Data for authorization in 3DS 2.0 after completing the Challenge
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
amount
N
R
Operation amount in minimum currency units (kopecks, cents etc). Corresponds to the one sent in the request
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_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. Decimal digits without delimiters [0–9] and the masking character ‘x’
card_holder
A..100
R
Name of the cardholder
expired_year
N2
R
Card expiration year
expired_month
N2
R
Card expiration month
order_id
A..100
R
ID of the order to be paid for in the merchant system
status
A..10
O
Status of the operation
Examples of responses to successful requests:
If the card is involved in 3DS 2.0 and 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 2.0 and ChallengeComplete call is 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"
}ChallengeComplete
Passing an additional stage to verify the authenticity of the 3D-Secure 2.0 payment when blocking or debiting funds from the card account.
Scenario
If an additional stage of 3D-Secure 2.0 payment authentication is required, then the response of the PayMerchant, Block, PaySaveCard or ThreeDsMethodComplete method contains the string parameters acs_url and creq.
After receiving a response from the gateway, the merchant redirects the user to the site of the issuing bank for additional authentication. Redirect format: POST request to the address specified in the value of the acs_url parameter. Parameter: creq. Response format as a result of redirection: the user return by a POST request to the address specified in the threeDsNotificationUrl parameter of the PayMerchant, Block or PaySaveCard request. Parameter: cres.
Request URL: https://{host}.payler.com/mapi/ChallengeComplete
Available for: mapi
Request method: POST
Request parameters
Name
Format
R/O
Description
cres
A
R
Cres value received from the issuing bank on the threeDsNotificationUrl (transmitted in the PayMerchant, Block, PaySaveCard requests)
key
A
R
Merchant's payment key
Response format
The response format matches the Send3DS response format
Send3DS
Verifying card participation in the 3-D Secure authentication 1.0 procedure when locking or debiting funds from the card.
Scenario
If the user card has the 3D-Secure authentication mechanism, then the value of the auth_type parameter in the response to PayMerchant, Block or PaySaveCard request becomes equal to ThreeDS (1). In this case, the response also contains the line parameters acs_url, pareq and md.
After receiving the gateway response, the merchant redirects the user to the issuing bank site for additional authentication. Redirection format: POST request to the address specified in the value of the parameter acs_url. Parameters: PaReq, TermUrl, MD. Response format as a result of redirection: the user return by a POST request to the address specified in the value of the TermUrl attribute. Parameters: PaRes, MD.
After receiving the authentication results from the issuing bank to complete the blockage or payment, the merchant performs an additional request to the Payler gateway.
Request URL: https://{host}.payler.com/mapi/v1/Send3DS
Available for: mapi
Request method: POST
Request parameters
Name
Format
R/O
Description
PaRes
A
R
Value received on the TermUrl page from the issuer bank
Response format
Name
Format
R/O
Description
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
amount
N
R
Amount charged off in minimum currency units (kopecks, cents etc). Corresponds to the one sent in the request
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_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. Decimal digits without delimiters [0–9] and the masking character ‘x’
card_holder
A..100
R
Name of the cardholder
expired_year
N2
R
Card expiration year
expired_month
N2
R
Card expiration month
order_id
A..100
R
ID of the order to be paid for in the merchant system
status
A..10
O
Status of the operation
Example of the response to a successful request:
{
"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"
}Charge
The result of processing the request is the charging-off of blocked funds from the user's card.
The request is executed after successful PayGate or Block command in the two-stage payment scheme. The payment status must be Authorized. For the Gate scheme, type parameter must be set to TwoStep in the StartSession request.
Request URL: https://{host}.payler.com/{api}/Charge
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
password
A..100
R
Merchant’s password for operations. It is issued to the merchant with the parameters of access
order_id
A..100
R
Identifier of the order in the system of the merchant. Must match order_id of StartSession or Block operation
amount
N
R
Amount to be charged-off in minimum currency units (kopecks, cents etc). Must be exactly the same as the amount of blocked funds
Response parameters
Name
Format
R/O
Description
order_id
A..100
R
Order ID in the merchant system. Corresponds to the one sent in the request
amount
N
R
Amount charged off in minimum currency units (kopecks, cents etc). Corresponds to the one sent in the request
status
A..10
R
Status of the operation
Example of the response to a successful request:
{
"amount": 3457500,
"order_id": "sk-d97b9c351818d820fdd3d5d33e6c1edf",
"status": "Charged"
}Retrieve
The request is executed after successful PayGate or Block command in the two-stage payment scheme. The status of the payment must be Authorized.
The result of processing the request is to change (full or partial) the blocked amount on the user's card.
Request URL: https://{host}.payler.com/{api}/Retrieve
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
password
A..100
R
Merchant’s password for operations. It is issued to the merchant with the parameters of access
order_id
A..100
R
Identifier of the order in the system of the merchant. Must match order_id of StartSession or Block operation
amount
N
R
Amount to be charged-off in minimum currency units (kopecks, cents etc). Must not exceed the value specified in StartSession or PayMerchant request
Response parameters
Name
Format
R/O
Description
order_id
A..100
R
Order ID in the merchant system. Corresponds to the one sent in the request
new_amount
N
R
New amount of payment in minimum currency units (kopecks, cents etc)
Example of the response to a successful request:
{
"new_amount": 10000,
"order_id": "4c1552c5-11bb-465f-8564-62ac933ae15d"
}Refund
The request is executed after successful PayGate or PayMerchant command in a one-stage scheme or after successful Charge command in a two-stage scheme. The status of the payment must be Charged. The result of processing the request is a refund (full or partial) of charged-off funds to the user's card.
Request URL: https://{host}.payler.com/{api}/Refund
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
password
A..100
R
Merchant’s password for operations. It is issued to the merchant with the access parameters
order_id
A..100
R
Order ID in the merchant system. Must match the order_id of StartSession, PayMerchant or Block operation
amount
N
R
Amount to be returned in minimum currency units (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
Balance of the charged-off amount in minimum currency units (kopecks, cents etc)
Example of the response to a successful request:
{
"amount": 0,
"order_id": "4c1552c5-11bb-465f-8564-62ac933ae15d"
}RepeatPay
Request for re-payment within the recurring payment series. The result of the processing of the request is the charging-off of the funds without the cardholder indicating the card data.
Request URL: https://{host}.payler.com/{api}/v1/RepeatPay
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 operation in the merchant system.
For each payment (session), it is required to use a unique identifier. Only printed ASCII-signs are allowed
amount
N
R
Payment amount in minimum currency units (kopecks, cents etc). It can differ from the payment amount made in the operation, on the basis of which the recurring payment template is created
product
A..256
O
Name of the product to be paid for
recurrent_template_id
A..100
R
Recurring payment template identifier received in the callback
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
Response parameters
Name
Format
R/O
Description
order_id
A..100
R
Identifier of the paid order in the merchant system. Corresponds to the one sent in the request
amount
N
R
Payment amount in minimum currency units (kopecks, cents etc)
status
A..10
R
Status of the operation
Example of the response to a successful request:
{
"amount": 50000,
"order_id": "3e31f52f-84bd-4a98-b798-8aafd325a229",
"status": "Charged"
}GetTemplate
Request for information about the recurring payment template. It is recommended to use it to get full information about the registered recurring payment template.
Request URL: https://{host}.payler.com/{api}/GetTemplate
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
recurrent_template_id
A..100
R
Recurring payment template identifier received in callback
Response parameters
Name
Format
R/O
Description
recurrent_template_id
A..100
R
Recurring payments template ID
created
A
R
Date and time of the registration of the recurring payment template in the format "yyyy-MM-dd HH:mm:ss"
card_holder
A..100
R
Name of the cardholder to which the template is attached. Indicates when the first payment is made in a series of recurring payments
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.
Decimal digits without delimiters [0–9] and the masking character ‘x’
expiry
A..5
R
Period of validity of the recurring payment template. The month and year in the format "MM/yy"
active
B
R
Indicates whether the template is active. true—template is active; false—template is not active
Example of the response to a successful request:
{
"recurrent_template_id": "rec-pay-2160e16c-849d-42c5-a224-19f302ce4806",
"created": "2014-08-21 18:22:03",
"card_holder": "TEST USER",
"card_number": "510047xxxxxx0401",
"expiry": "03/15",
"active": true
}ActivateTemplate
Request activation / deactivation of the recurring payment template. It is recommended to use it for temporarily disabling the ability to make payments by the template.
Request URL: https://{host}.payler.com/{api}/ActivateTemplate
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
recurrent_template_id
A..100
R
Recurring payment template identifier
active
B
R
Indicates whether to activate or deactivate the recurring payment template. true or 1—the template needs to be activated; false or 0—the template needs to be deactivated
Response parameters
Name
Format
R/O
Description
recurrent_template_id
A..100
R
Recurring payments template ID. Corresponds to the one sent in the request
created
A
R
Date and time of the registration of the recurring payment template in the Payler system. The date and time in the format "yyyy-MM-dd HH:mm:ss"
card_holder
A..100
R
Name of the cardholder to which the template is attached. Indicates when the first payment is made in a series of recurring payments
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. Decimal digits without delimiters [0–9] and the masking character ‘x’
expiry
A..5
R
Period of validity of the recurring payment template. Containing the month and year in the format "MM/yy"
active
B
R
Indicates whether the template is active. true—template active; false—template is not active
Example of the response to a successful request:
{
"recurrent_template_id": "rec-pay-2160e16c-849d-42c5-a224-19f302ce4806",
"created": "2014-08-21 18:22:03",
"card_holder": "TEST USER",
"card_number": "510047xxxxxx0401",
"expiry": "03/15",
"active": true
}GetStatus
The result of processing the request is to obtain current payment status. It is recommended to use it if you do not receive a response from the Payler gateway while making other payment requests.
Request URL: https://{host}.payler.com/{api}/GetStatus
Available for: gapi, mapi, cgapi, cmapi
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
Order ID in the merchant system
Response parameters
Name
Format
R/O
Description
order_id
A..100
R
Payment identifier in the merchant system. Corresponds to the one sent in the request
amount
N
R
Payment amount in minimum currency units (kopecks, cents etc)
status
A..10
R
Payment Status. See Operation statuses
recurrent_template_id
A..100
O
Recurring payment template identifier.
It is present if within the current operation a template of recurring payments is created, or it is carried out according to the template
payment_type
A
O
Payment Methods. See Payment Methods
Example of the response to a successful request:
{
"status": "Charged",
"amount": 30000,
"recurrent_template_id": "rec-pay-02e20707-eed4-4cb4-9a45-03b5465f8e92",
"order_id": "a0c799a6-a3df-47cc-b452-63b19d95bb59",
"payment_type": "Card"
}If the transaction status is "Pending", then a status request should be repeated until the status changes. Request frequency is needed to be changed exponentially
If in StartSession, Block or PayMerchant requests the value of the recurrent parameter is set to true, and the operation is successful, but the template ID is not returned in response to the GetStatus request, then the operation has gone through the normal scheme without creating a recurring payment template.
GetAdvancedStatus
The result of the request is to obtain an extended operation status. It is recommended to use it to get detailed information about the operation in case the answer to GetStatus request is not enough to solve business tasks.
Request URL: https://{host}.payler.com/{api}/GetAdvancedStatus
Available for: gapi, mapi, cgapi, cmapi
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
Order ID in the merchant system
Response parameters
Name
Format
R/O
Description
order_id
A..100
R
Payment identifier in the merchant system. Corresponds to the one sent in the request
amount
N
R
Payment amount in minimum currency units (kopecks, cents etc)
status
A..10
R
Payment status. See Operation statuses
product
A..256
O
Operation description
recurrent_template_id
A..100
O
Recurring payment template identifier. It is present if within the current operation a template of recurring payments is created, or it is carried out according to the template
card_number
A..19
R
Masked card number used to make the payment
card_holder
A..100
R
Name of the cardholder with which payment was made
dt
A
R
Time of operation registration in the Payler system. The date and time in the format "yyyy-MM-dd HH:mm:ss"
from
A
O
IP-address from which the payment request was made
approval_code
A..6
O
Alphanumeric code assigned by the issuing bank to authenticate the authorization request
rrn
A..6
O
Number assigned to the operation in the payment system
type
A..7
O
Determines the number of payment stages.
OneStep—one-stage payment;
TwoStep—two-stage payment
processing
A
O
Gets the name of the processing that handles this payment
processing_order_id
A
O
Payment ID in the processing center
card_bankname
A
R
Name of the bank. Can be an empty value
card_paymentsystem
A
R
Payment system. Can be an empty value
card_product
A
R
Card type. Can be an empty value
card_id
A..100
O
Identifier of the card used to make the payment. Not available if the payment was not made on a saved card
card_status
A..10
O
Card status.
Saved—card is saved and ready to use;
Invalid—card is not valid (for example, it has expired)
user_entered_params
D
R
When paying, you can specify additional input 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
Example of the response to a successful request (payment):
{
"card_number": "554781xxxxxx4672",
"card_holder": "NO NAME",
"expired_year": 22,
"expired_month": 3,
"dt": "2019-06-26 12:59:05",
"from": "127.0.0.1",
"approval_code": "598101",
"rrn": "917791485893",
"processing": "PSB",
"currency": "RUB",
"user_entered_params":
{
"user_entered_documentSeria": "1500",
"user_entered_documentNumbers": "aB"
},
"type": "OneStep",
"card_bankname": "PUBLIC JOINT STOCK COMPANY PROMSVYAZBANK",
"card_paymentsystem": "MASTERCARD",
"card_product": "GOLD",
"card_country_code": "RU",
"processing_order_id": "1561543145757000",
"status": "Charged",
"amount": 500,
"recurrent_template_id": "rec-pay-da24a6e3-8b9e-4bf2-8fa5-45e5365f5222",
"payment_type": "Card",
"order_id": "Dr24ake3-875e-4bf2-8fa5-45e5365f6773"
}If in StartSession, Block or PayMerchant request the value of the recurrent parameter is set to true, and the operation is successful, but the template ID is not returned in response to the GetAdvancedStatus request, then the operation has gone through the normal scheme without creating a recurring payment template.
GetAdvancedStatusBulk
The result of the request is to obtain an extended operation statuses for several operations. It is recommended to use it for reconciliation or mass repeated requests.
Request URL: https://{host}.payler.com/{api}/GetAdvancedStatusBulk
Available for: gapi, mapi, cgapi, cmapi
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
Ar
R
An array containing a list of identifiers in the merchant's system.
Limitation: no more than 100 identifiers in one request
Response parameters
The response sends an "orders" array containing a model similar to the response to the GetAdvancedStatus.
Example of the response to a successful request (payment):
{
"orders": [
{
"card_number": "557805xxxxxx3717",
"card_holder": "NONAME",
"expired_year": 22,
"expired_month": 12,
"dt": "2022-11-16 22:41:39",
"processing": "SNGB2",
"currency": "RUB",
"user_entered_params": {},
"type": "TwoStep",
"card_bankname": "JOINT STOCK COMPANY SURGUTNEFTEGASBANK",
"card_paymentsystem": "MASTERCARD",
"card_product": "GOLD",
"card_country_code": "US",
"processing_order_id": "a32da2ec-bce9-4518-a9d7-ed6a34742ee1",
"card_id": "vmGRYqk7cPiJj2COqnxPcUSNqJiy5ybq09bd",
"card_status": "Saved",
"status": "Charged",
"amount": 100,
"recurrent_template_id": "rec-pay-3e996e77-77e4-4cfb-ae68-531f36cb25c8",
"payment_type": "Card",
"order_id": "5211e525-fdbc-444e-b5dc-ba685f258b7b",
"from": "192.168.0.104",
"userdata": ""
},
{
"card_number": "557805xxxxxx3717",
"card_holder": "NONAME",
"expired_year": 22,
"expired_month": 12,
"dt": "2022-11-18 09:39:49",
"processing": "SNGB2",
"currency": "RUB",
"user_entered_params": {},
"type": "TwoStep",
"card_bankname": "JOINT STOCK COMPANY SURGUTNEFTEGASBANK",
"card_paymentsystem": "MASTERCARD",
"card_product": "GOLD",
"card_country_code": "US",
"processing_order_id": "0c15078e-70a2-4809-9cfe-a24d60200686",
"status": "Rejected",
"amount": 100,
"payment_type": "Card",
"order_id": "862a643b-1edf-4b7e-b8b9-2ac429a3e2e2",
"from": "192.168.0.104",
"userdata": "",
"error_code": "THREE_DS_FAIL",
"error_message": "Payment Confirmation on the side of the bank issuing the card canceled or it's impossible to perform due to an error."
},
{
"card_number": "220058xxxxxx0913",
"card_holder": "NONAME",
"expired_year": 22,
"expired_month": 9,
"dt": "2022-11-18 14:14:22",
"rrn": "130930416142",
"processing": "SNGB2",
"currency": "RUB",
"user_entered_params": {},
"type": "OneStep",
"card_bankname": "",
"card_paymentsystem": "NSPK MIR",
"card_product": "",
"card_country_code": "RU",
"processing_order_id": "93e522a8-a8db-4ca8-ae54-b29be699bc9a",
"card_id": "mSkjBEsCRDM97LJyx1a0z6HumKuA59k4dG5S",
"card_status": "Deleted",
"status": "Credited",
"amount": 100,
"payment_type": "Card",
"order_id": "f120c06b-8390-4eef-8f30-17d0a2b8fe2c",
"from": "51.250.11.77",
"userdata": ""
}
]
}AppleValidateMerchant
Merchant validation in Apple.
Request URL: https://{host}.payler.com/{gapi}/applevalidatemerchant
Content-Type: application/json
Available for: gapi
Request method: POST
Request parameters
Name
Format
R/O
Description
key
A
R
Merchant payment key
apple_pay_type
N1
R
Payment type. Possible values: 3—Apple Pay button on the merchant`s site
Response parameters
Name
Format
R/O
Description
validation_object
A
R
Object obtained from Apple. It must be passed to completeMerchantValidation method.
Example of the response to a successful request:
{
"validation_object": "..."
}ApplePay
Payment processing using Apple Pay through a mobile application or on the merchant’s website using encrypted payment data. The result of processing the request is debiting or blocking funds on the user's card.
Request URL: https://{host}.payler.com/{api}/ApplePay
Content-Type: application/json
Available for: gapi, mapi
Request method: POST
Request parameters
Name
Format
R/O
Description
session_id
A..100
R
Session identifier received via a call StartSession
apple_payment_data
A
R
Encrypted payment data from the parameter paymentData of the object PKPaymentToken
A..100
R
User email
apple_pay_type
N1
R
Payment type. Possible values: 1—payment from the application, 3—Apple Pay button on the merchant`s site
payer_ip
A
O
User`s IP-address
Response parameters
Name
Format
R/O
Description
order_id
A..100
R
Identifier of the paid order in the merchant system. Corresponds to the one sent in StartSession request
amount
N
R
Operation amount in minimum currency units (kopecks, cents etc). Corresponds to the one sent in StartSession request
Example of the response to a successful request:
{
"amount": 30000,
"order_id": "d1434908-7260-483e-8254-fa43af1b835d",
}ApplePayDecrypted
Payment processing using Apple Pay through a mobile application or on the merchant’s website using decrypted payment data. The result of processing the request is debiting or blocking funds on the user's card.
Request URL: https://{host}.payler.com/mapi/ApplePay/Decrypted
Content-Type: application/json
Available for: mapi
Request method: POST
Request parameters
Name
Format
R/O
Description
apple_pay_payload
A
R
Decrypted payment data from the parameter paymentData of the object PKPaymentToken
A..100
R
User email
apple_pay_type
N1
R
Payment type. Possible values: 1—payment from the application, 3—Apple Pay button on the merchant`s site
payer_ip
A
O
User`s IP-address
Response parameters
Name
Format
R/O
Description
order_id
A..100
R
Identifier of the paid order in the merchant system. Corresponds to the one sent in StartSession request
amount
N
R
Operation amount in minimum currency units (kopecks, cents etc). Corresponds to the one sent in StartSession request
Example of the response to a successful request:
{
"amount": 30000,
"order_id": "d1434908-7260-483e-8254-fa43af1b835d",
}GooglePay
Payment processing using Google Pay through a mobile application or on the merchant’s website using encrypted payment data. The result of processing the request is debiting or blocking funds on the user's card.
To use GooglePay method, the merchant must configure Google Pay API in advance.
See above for setup information.
Request URL: https://{host}.payler.com/{api}/GooglePay
Available for: gapi, mapi
Content-Type: application/json
Request method: POST
Request parameters
Name
Format
R/O
Description
google_pay_token
A
R
Encrypted payment data "paymentMethodData", "tokenizationData", "token" from PaymentData object received from Google (can be obtained in handlePaymentSuccess method) by calling paymentData, getPaymentMethodToken, getToken
A..100
O
User email
payer_ip
A
O
User`s IP-address
Response parameters
Name
Format
R/O
Description
order_id
A..100
R
Identifier of the paid order in the merchant system. Corresponds to the one sent in StartSession request
amount
N
R
Payment amount in minimum currency units (kopecks, cents etc). Corresponds to the one sent in StartSession request
Example of the response to a successful request:
{
"amount": 30000,
"order_id": "d1434908-7260-483e-8254-fa43af1b835d",
}GooglePayDecrypted
Payment processing using Google Pay through a mobile application or on the merchant’s website using decrypted payment data. The result of processing the request is debiting or blocking funds on the user's card. To use GooglePay method, the merchant must configure Google Pay API in advance. See above for setup information.
Request URL: https://{host}.payler.com/mapi/GooglePay/Decrypted
Available for: mapi
Content-Type: application/json
Request method: POST
Request parameters
Name
Format
R/O
Description
google_pay_token
A
R
Decrypted payment data "paymentMethodData", "tokenizationData", "token" from PaymentData object received from Google (can be obtained in handlePaymentSuccess method) by calling paymentData, getPaymentMethodToken, getToken.
Only "CRYPTOGRAM_3DS" is supported as authentication method ("authMethod" property)
A..100
O
User email
payer_ip
A
O
User`s IP-address
Response parameters
Name
Format
R/O
Description
order_id
A..100
R
Identifier of the paid order in the merchant system. Corresponds to the one sent in StartSession request
amount
N
R
Payment amount in minimum currency units (kopecks, cents etc). Corresponds to the one sent in StartSession request
Example of the response to a successful request:
{
"amount": 30000,
"order_id": "d1434908-7260-483e-8254-fa43af1b835d",
}Last updated