Payler API
Search…
General information
API methods
Failed requests
Error codes
Terms and abbreviations
Payments
When sending requests, unless something else is specified, use the POST method with the header "Content-Type: application / x-www-form-urlencoded
Characters case and parameters order in requests are not important.
Characters case in url addresses of the requests are important.
The response to the request is transmitted in JSON format, encoding UTF-8.
StartSession
Payment initialization request. Performed before the user redirects to the Payler payment gateway page.
Available for: gapi
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 (RUB, USD, EUR, GBP, PLN, TJS, KGS). 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
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:
1
{
2
“amount”: 30000,
3
“session_id”: “FE6nrdcfw4Zy88Crki6sjc1mRxW9xcv7m7CS”,
4
“order_id”: “d1434908-7260-483e-8254-fa43af1b835d”
5
}
Copied!
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
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 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 (RUB, USD, EUR, GBP, PLN, TJS, KGS). 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:
1
{
2
“id”: “VlaFQpI88NpCncTA1TkhlX6HtkhzwQAKhxvz”,
3
“created”: “2015-10-26 17:11:30”,
4
“valid_through”: “2015-10-26 17:11:30”,
5
“type”: “OneStep”,
6
“order_id”: “ad7ad8b4-d50e-4b68-72f4-ca1264a8fae4”,
7
“amount”: 30000,
8
“product”: “el-ticket”,
9
“currency”: “RUB”,
10
“pay_page_params”: {“pay_page_param_phone”: “+790012345678”, “pay_page_param_city”:”Moscow””},
11
“userdata”: “data”,
12
“lang”: “RU”,
13
“recurrent”: true,
14
“customer_id”: “kfRWk8nbT9LhO19sVYotkJ2gHSPs5E4Qph35”,
15
“session_type”: “0”
16
}
Copied!
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 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. 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
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:
1
{
2
"threeDS_server_transID":"9f7f012d-d6d0-38fe-9bfd-70a727c7473a",
3
"threeDS_method_url":"https://someurl.com",
4
"auth_type":1,
5
"amount":2050,
6
"order_id":"c8ebb763-5b75-4c5e-a731-2489220b4f2a"
7
}
Copied!
1
{
2
"acs_url":"https://someurl.com",
3
"creq":"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImE3ZTYzZWRkLTYwYTgtMzE0Yi
4
04MzJlLTU3YTFhNzg2NTZjZSIsImFjc1RyYW5zSUQiOiJhM2MxMDQwYS05OGUxLTQ0
5
N2EtOTE4Ni0zYzY3N2MyODMxNmEiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLC
6
JtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0=",
7
"auth_type":1,
8
"amount":2050,
9
"card_number":"411111xxxxxx1111",
10
"card_holder":"NONAME",
11
"expired_year":20,
12
"expired_month":12,
13
"order_id":"201d6446-c351-4df6-8f46-8f5b24be76aa"
14
}
Copied!
If the card is involved in 3DS 1.0:
1
{
2
"acs_url": "https://web.rbsuat.com/acs/auth/start.do",
3
"pareq": "eJxVUdluwjAQ/BWU9+ADhwBajNICAlUBWkKl9i3HFlKRAxMq4OtrByhU8sPMejRjz8LgmG0bP6j2aZH3LdakVgPzuEjSfN23VsHY7lgDCcFGIQ6XGB8USvBxvw/X2EiTvvXluOi6HWFjRIUtusyxIx4Lm1FkPBKUJu3IkrDw3nAn4RokdU6TA7lR7ajiTZhXEsJ49zSdScHdNqVArhQyVNOhZLwlnLYL5EIhDzOUZXjaogJSE4iLQ16pk2yLFpAbgYPayk1VlT1CLvJmXGRAzBjIPXxxMGivbY5pIv3g9eyf13wejNjs2xezs8f84ciZD70+EKOAJKxQcsq61OWtBu30uD4MSD2HMDP50qk/csFQmgjv4eJxALpfpeu/Pf/GAI9lkaNW6NL+MJD7e58nprq40q2UbiZoNFpUbjUOJi/55/sqGe/Ws6WHH6bQWmQcU90M67KLpSFAjA257opc16zRv/X/Aj0Rt1Q=",
4
"md": "949cdebb-b7a7-46b0-874e-bd11f410992c",
5
"auth_type": 1,
6
"amount": 500,
7
"card_number": "411111xxxxxx1111",
8
"card_holder": "IVAN",
9
"expired_year": 19,
10
"expired_month": 12,
11
"order_id": "test_example_002"
12
}
Copied!
If the card is not involved in 3DS, or the authentication is successful via frictionless flow, and the 3DSMethod is not required:
1
{
2
"auth_type": 0,
3
"amount": 500,
4
"recurrent_template_id": "rec-pay-42301e79-b92d-4753-b248-b92ad552fdfd",
5
"card_number": "555555xxxxxx5599",
6
"card_holder": "IVAN",
7
"expired_year": 19,
8
"expired_month": 12,
9
"order_id": "test_example_003",
10
"status": "Charged"
11
}
12
Copied!
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 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
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.
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:
1
<!DOCTYPE html>
2
<html>
3
<head>
4
<meta charset="utf-8" />
5
<title>3DS Method</title>
6
<script type="text/javascript"
7
language="javascript">function moveWindow() { document.returnform.submit(); } /script>
8
</head>
9
<body onLoad="javascript:moveWindow()">
10
<form name="returnform" action="' + threeDsMethodUrl + '" method="POST">
11
<input type="hidden" name="threeDSMethodData" value="' + threeDSMethodData + '" />
12
<noscript>
13
<center>Please click the submit button below.<br /><input type="submit" name="submit" value="Submit" />
14
</center>
15
</noscript>
16
</form>
17
</body>
18
</html>
Copied!
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.
ThreeDsMethodComplete
Available for: gapi, mapi
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
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:
1
{
2
"acs_url":"https://someurl.com",
3
"creq":"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImE3ZTYzZWRkLTYwYTgtMzE0Yi
4
04MzJlLTU3YTFhNzg2NTZjZSIsImFjc1RyYW5zSUQiOiJhM2MxMDQwYS05OGUxLTQ0
5
N2EtOTE4Ni0zYzY3N2MyODMxNmEiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLC
6
JtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0=",
7
"auth_type":1,
8
"amount":2050,
9
"card_number":"411111xxxxxx1111",
10
"card_holder":"NONAME",
11
"expired_year":20,
12
"expired_month":12,
13
"order_id":"201d6446-c351-4df6-8f46-8f5b24be76aa"
14
}
Copied!
If the card is involved in 3DS 2.0 and ChallengeComplete call is required:
1
{
2
"auth_type": 0,
3
"amount": 500,
4
"recurrent_template_id": "rec-pay-42301e79-b92d-4753-b248-b92ad552fdfd",
5
"card_number": "555555xxxxxx5599",
6
"card_holder": "IVAN",
7
"expired_year": 19,
8
"expired_month": 12,
9
"order_id": "test_example_003",
10
"status": "Charged"
11
}
Copied!
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
- 1.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.
- 2.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, PaySaveCard or ThreeDsMethodComplete request. Parameter: cres.
Available for: mapi
Request parameters
Name
Format
R/O
Description
cres
A
R
Creq value obtained in response to PayMerchant, Block, PaySaveCard, or ThreeDsMethodComplete request
key
A
R
Merchant's payment key
Response format
Send3DS
Verifying card participation in the 3-D Secure authentication 1.0 procedure when locking or debiting funds from the card.
Scenario
- 1.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.
- 2.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.
- 3.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.
Available for: mapi
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:
1
{
2
"auth_type": 0,
3
"amount": 500,
4
"recurrent_template_id": "rec-pay-42301e79-b92d-4753-b248-b92ad552fdfd",
5
"card_number": "555555xxxxxx5599",
6
"card_holder": "IVAN",
7
"expired_year": 19,
8
"expired_month": 12,
9
"order_id": "test_example_003",
10
"status": "Charged"
11
}
Copied!
Charge
The result of processing the request is the charging-off of blocked funds from the user's card.
Available for: gapi, mapi
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:
1
{
2
"amount": 3457500,
3
"order_id": "sk-d97b9c351818d820fdd3d5d33e6c1edf",
4
"status": "Charged"
5
}
Copied!
Retrieve
The result of processing the request is to change (full or partial) the blocked amount on the user's card.
Available for: gapi, mapi
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:
1
{
2
"new_amount": 10000,
3
"order_id": "4c1552c5-11bb-465f-8564-62ac933ae15d"
4
}
Copied!
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.
Available for: gapi, mapi
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:
1
{
2
"amount": 0,
3
"order_id": "4c1552c5-11bb-465f-8564-62ac933ae15d"
4
}
Copied!
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.
Available for: gapi, mapi
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
recurrent_template_id
A..100
R
Recurring payment template identifier received in the callback
currency
A3
О
Operation currency (RUB, USD, EUR, GBP, PLN, TJS, KGS). By default—RUB
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
Currency parameter
If the merchant uses more than one currency, the parameter currency is required!
For example, if a recurring payment template is created for a payment made in USD, then you must specify USD when re-debiting. Otherwise, the payment will be made through the ruble terminal, with currency conversion and the calculation of an additional fee.
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:
1
{
2
"amount": 50000,
3
"order_id": "3e31f52f-84bd-4a98-b798-8aafd325a229",
4
"status": "Charged"
5
}
Copied!
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.
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.
Available for: gapi, mapi
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:
1
{
2
"recurrent_template_id": "rec-pay-2160e16c-849d-42c5-a224-19f302ce4806",
3
"created": "2014-08-21 18:22:03",
4
"card_holder": "TEST USER",
5
"card_number": "510047xxxxxx0401",
6
"expiry": "03/15",
7
"active": true
8
}
Copied!
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 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: