Payler API
Search…
General information
API methods
Failed requests
Error codes
Terms and abbreviations
Saving Cards
When sending requests, 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 is important.
The response to the request is transmitted in JSON format, encoding UTF-8.
StartSaveCardSession
Initialization of the card save session request. Performed before the user is redirected to the Payler payment gateway page.
Available for: gapi, cgapi
Request parameters
Name
Format
R/O
Description
key
A..100
R
Merchant ID. Issued to the merchant with the access parameters
template
A..100
O
Payment page template specified by the merchant. If not, the default template is used
lang
A2
O
Preferred language of the payment form responses.
en—English; ru—Russian. By default—Russian
currency
A3
O
Operation currency (RUB, USD, EUR, GBP, PLN, TJS, KGS).
Default RUB
pay_page_param_*
A..100
O
Options 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 template parameter)
return_url_success
A..1000
O
URL to which the user will be redirected in case the card is saved successfully
lifetime
N
O
Session lifetime in minutes, from 1 minute or more
Response parameters
Name
Format
R/O
Description
session_id
A..100
R
Session ID
order_id
A..100
R
ID of the order to be paid for in the merchant system.
Generated automatically
Example of the response to a successful request:
1
{
2
"session_id": "dOadCwvzuHxJVKNX4peVZpzTRulVG4OJwomj",
3
"order_id": "kqonTcrezjZHhNxs619HYoVE737N7JNXYadb"
4
}
Copied!
Save
Request to save the card with the user redirection to the gateway page.
Runs after StartSaveCardSession. After the user fills in form fields, the gateway automatically performs a request to the issuer bank. The result is saving user card data.
Available for: gapi, cgapi
Request method: GET
Request parameters
Name
Format
R/O
Description
session_id
A..100
R
After processing Save request on the side of the payment gateway, the user will be redirected to the page displaying the result of saving the card and returned to the merchant's website 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://mysite.ru/complete?session_id={session_id}
To obtain operation results, you should use the data received within the operation status request (see GetStatusSaveCard method).
It should be noted that the return to the specified URL can be made several times, for example, when the user is confused, click the Back button in the browser. 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.
PaySaveCard
Saving card data by debiting or blocking (depending on the merchant’s settings) the checksum on the card account with subsequent automatic unlocking or refund of the debited amount.
The result is saving user card data.
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
card_number
A..19
R
Card number. The 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
R
Card expiration year
expired_month
N2
R
Card expiration month
secure_code
A
R
Card Authentication Code (CVC2/CVV2). The line containing decimal digits [0–9]
lang
A2
О
Preferred language of payment form responses.
en—English; ru—Russian language. By default—Russian
email
A..100
R
User email
userdata
A..1000
О
User data. You can pass in this line any information that you need to save with the payment and then get it using GetAdvancedStatus
customer_id
A..100
О
Customer ID. Indicates for which client the card will be saved
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 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
Response format
Corresponds to the result of PayMerchant.
GetStatusSaveCard
Request for the status of the saved card.
Available for: gapi, mapi, cgapi, cmapi
Request parameters
Name
Format
R/O
Description
key
A..100
R
Merchant ID. Issued to the merchant with the access parameters
session_id
A..100
O
Session identifier for which information is required. If not specified,
the card_id parameter must be specified
card_id
A..100
O
Card ID which you want to receive information about. If not specified,
the session_id parameter must be specified
Response parameters
Name
Format
R/O
Description
card_id
A..100
R
Card ID
card_status
A
R
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 card number. The first 6 and the last 4 digits are left, the rest are replaced by ‘x’
card_holder
A..100
R
Cardholder name
expired_year
N2
R
Card expiration year
expired_month
N2
R
Card expiration month
recurrent_template_id
A..100
O
Recurring payment template identifier
customer_id
A..100
R
Customer Id
Example of the response to a successful request:
1
{
2
"card_status": "Saved",
3
"card_id": "ZRzroTofO42UkBv5vsMmckgU3Dowz7J4UhMZ",
4
"card_number": "400000xxxxxx0093",
5
"card_holder": "NONAME",
6
"expired_year": 25,
7
"expired_month": 12,
8
"customer_id": "BCaFGEp8gQhT1XXFs1HEf5LRFstC4efydqxv"
9
}
Copied!
GetCardList
Request for a list of saved cards.
Available for: gapi, mapi, cgapi, cmapi
Request parameters
Name
Format
R/O
Description
key
A..100
R
Merchant ID. Issued to the merchant with the access parameters
customer_id
A..100
R
Customer ID. Cards belonging to the customer will be returned
Response parameters
Name
Format
R/O
Description
cards
Ar
R
List of cards
cards/card_id
A..100
R
Card ID
cards/customer_id
A..100
R
Customer ID
cards/card_status
A
R
Card status.
· Saved—card is saved and ready to use,
· Invalid— card is not valid (for example, it has expired)
cards/card_number
A..19
R
Masked card number. The first 6 and the last 4 digits are left, the rest are replaced by ‘x’.
cards/card_holder
A..100
R
Cardholder name
cards/expired_year
N2
R
Card expiration year
cards/expired_month
N2
R
Card expiration month
cards/recurrent_template_id
A..100
O
Identifier of the recurring payment template. It is present if the recurring payment template is created on the card
Example of the response to a successful request:
1
{
2
"cards": [
3
{
4
"card_status": "Saved",
5
"card_id": "Zk8ou8tcfiitc31DwJPOIIOwC8oFZOlIDknL",
6
"customer_id": "jsdlf8sDD9LhO19sVYotkJ2gHSPs5E4Qph14"
7
"card_number": "452427xxxxxx1232",
8
"card_holder": "IVAN PETROV",
9
"expired_year": 17,
10
"expired_month": 7
11
},
12
{
13
"card_status": "Saved",
14
"card_id": "OvzLAlY3twt5GYnm2ddGiixha1tNSHJcXk2k",
15
"customer_id": "sdkKhnf23ds987K8bsdj79ldn23fsldmMJ",
16
"card_number: "415432xxxxxx8564",
17
"card_holder": "PETR IVANOV",
18
"expired_year": 16,
19
"expired_month": 9
20
}
21
]
22
}
Copied!
RemoveCard
Request to delete the saved card.
Available for: gapi, mapi, cgapi, cmapi
Request parameters
Name
Format
R/O
Description
key
A..100
R
Merchant ID. Issued to the merchant with the access parameters
card_id
A..100
R
Card ID which you want to get information about
Response parameters
Name
Format
R/O
Description
changed
B
R
Indicates whether the request makes changes to the system.
true—the card was deleted as a result of this request,
false—the card was deleted earlier
Example of the response to a successful request:
1
{
2
"changed": true
3
}
Copied!
SaveCard
The request to save the card data transmitted via the API, without redirecting to the Payler payment gateway page.
Available for: mapi, cmapi
Request parameters
Name
Format
R/O
Description
key
A..100
R
Merchant ID. Issued to the merchant with the access parameters
card_number
A..19
R
Card number. Decimal digits without separators [0–9]
card_holder
A..100
O
Cardholder Name. Latin characters, decimal digits or a space character [a-zA-Z0–9]
expired_year
N2
R
Card expiration year
expired_month
N2
R
Card expiration month. Integer two-digit number in the format with leading zero
lang
A2
O
Preferred language of the payment form responses.
en—English; ru—Russian. By default—Russian
Response parameters
Name
Format
R/O
Description
card_id
A..100
R
Card ID
card_status
A
R
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 card number. The first 6 and the last 4 digits are left, the rest are replaced by ‘x’
card_holder
A..100
R
Cardholder name
expired_year
N2
R
Card expiration year
expired_month
N2
R
Card expiration month
Example of the response to a successful request:
1
{
2
"card_id": "z5RkjN4OiQ6I1UwTlpHJKBKj5Kf99D4T8r1c",
3
"card_status": "Saved",
4
"customer_id": "wsdj24DDgs34fsfDfs24Dr45L98klkm9kknc",
5
"card_number": "400000xxxxxx0002",
6
"card_holder": "NONAME",
7
"expired_year": 18,
8
"expired_month": 7
9
}
Copied!
CustomerRegister
Request for registration of a new customer.
Available for: gapi, mapi, cgapi, cmapi
Request parameters
Name
Format
R/O
Description
key
A..100
R
Merchant ID. Issued to the merchant with the access parameters
customer_name
A..100
O
Name of the customer
customer_phone
A..100
O
Phone number of the customer
customer_email
A..100
O
E-mail address of the customer
customer_fullName
A..100
O
Full name of the customer
customer_address
A..100
O
Customer address
customer_documentType
A..60
O
Customer document type
customer_documentSeria
A..60
O
Customer document series
customer_documentNumber
A..60
O
Customer document number
Response parameters
Name
Format
R/O
Description
customer_id
A..100
R
Customer ID
Example of the response to a successful request:
1
{
2
"customer_id": "Wkl7nBsMhwQICc2I9wXncMeSwnIaucQ5BHyo"
3
}
Copied!
CustomerUpdate
Request to update the customer data.
Available for: gapi, mapi, cgapi, cmapi
Request parameters
Name
Format
R/O
Description
key
A..100
R
Merchant ID. Issued to the merchant with the access parameters
customer_id
A..100
R
Customer ID
customer_name
A..100
O
Name of the customer
customer_phone
A..100
O
Phone number of the customer
customer_email
A..100
O
E-mail address of the customer
customer_fullName
A..100
O
Full name of the customer
customer_address
A..100
O
Customer address
customer_documentType
A..60
O
Customer document type
customer_documentSeria
A..60
O
Customer document series
customer_documentNumber
A..60
O
Customer document number
Response parameters
Name
Format
R/O
Description
customer_id
A..100
R
Customer ID
Example of the response to a successful request:
1
{
2
"customer_id": "Wkl7nBsMhwQICc2I9wXncMeSwnIaucQ5BHyo"
3
}
Copied!
CustomerDelete
Customer removal request.
Available for: gapi, mapi, cgapi, cmapi
Request parameters
Name
Format
R/O
Description
key
A..100
R
Merchant ID. Issued to the merchant with the access parameters
customer_id
A..100
R
Customer ID
Response parameters
Name
Format
R/O
Description
changed
B
R
Indicates whether the request makes changes to the system.
true or 1—the payer was deleted as a result of this request,
false or 0—the payer was removed earlier
Example of the response to a successful request:
1
{
2
"changed": true
3
}
Copied!
CustomerGetStatus
Request to check if the customer is registered.
Available for: gapi, mapi, cgapi, cmapi
Request parameters
Name
Format
R/O
Description
key
A..100
R
Merchant ID. Issued to the merchant with the access parameters
customer_id
A..100
R
Customer ID
Response parameters
Name
Format
R/O
Description
status
A..10
R
Indicates whether the customer is active.
Active—the customer is registered in the system.
If the customer is not registered, an error will be returned in response to the request
Example of the response to a successful request:
1
{
2
"status": "Active"
3
}
Copied!
Copy link
Contents
StartSaveCardSession
Request parameters
Response parameters
Save
Request parameters
PaySaveCard
Request parameters
Response format
GetStatusSaveCard
Request parameters
Response parameters
GetCardList
Request parameters
Response parameters
RemoveCard
Request parameters
Response parameters
SaveCard
Request parameters
Response parameters
CustomerRegister
Request parameters
Response parameters
CustomerUpdate
Request parameters
Response parameters
CustomerDelete
Request parameters
Response parameters
CustomerGetStatus
Request parameters
Response parameters