Saving Cards
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.
Initialization of the card save session request. Performed before the user is redirected to the Payler payment gateway page.
Available for: gapi, cgapi
Request method:
POSTRequest 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 | request |
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 | |
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:
{
"session_id": "dOadCwvzuHxJVKNX4peVZpzTRulVG4OJwomj",
"order_id": "kqonTcrezjZHhNxs619HYoVE737N7JNXYadb"
}
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:
GETRequest 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.
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 method:
POSTThe use of this method assumes that the merchant's system must comply with the PCI DSS requirements.
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 | О | |
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 |
browserJavascriptEnabled | B | O | Indicator that JavaScript can be executed in the user’s device browser. By default—true |
browserScreenHeight | A | R | Total height of the user's device screen in pixels |
browserScreenWidth | A | R | Total width of the user's device screen in pixels |
browserColorDepth | A | R | Color rendering depth in bits |
browserTZ | A | R | Time zone — time difference between UTC time and the local browser time on the user's device (in minutes) |
threeDsNotificationUrl | A | R | Redirect Url after performing ChallengeComplete |
Response format
Corresponds to the result of PayMerchant.
Request for the status of the saved card.
Available for: gapi, mapi, cgapi, cmapi
Request method:
POSTRequest 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:
{
"card_status": "Saved",
"card_id": "ZRzroTofO42UkBv5vsMmckgU3Dowz7J4UhMZ",
"card_number": "400000xxxxxx0093",
"card_holder": "NONAME",
"expired_year": 25,
"expired_month": 12,
"customer_id": "BCaFGEp8gQhT1XXFs1HEf5LRFstC4efydqxv"
}
Request for a list of saved cards.
Available for: gapi, mapi, cgapi, cmapi
Request method:
POSTRequest 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:
{
"cards": [
{
"card_status": "Saved",
"card_id": "Zk8ou8tcfiitc31DwJPOIIOwC8oFZOlIDknL",
"customer_id": "jsdlf8sDD9LhO19sVYotkJ2gHSPs5E4Qph14"
"card_number": "452427xxxxxx1232",
"card_holder": "IVAN PETROV",
"expired_year": 17,
"expired_month": 7
},
{
"card_status": "Saved",
"card_id": "OvzLAlY3twt5GYnm2ddGiixha1tNSHJcXk2k",
"customer_id": "sdkKhnf23ds987K8bsdj79ldn23fsldmMJ",
"card_number: "415432xxxxxx8564",
"card_holder": "PETR IVANOV",
"expired_year": 16,
"expired_month": 9
}
]
}
Request to delete the saved card.
Available for: gapi, mapi, cgapi, cmapi
Request method:
POSTRequest 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:
{
"changed": true
}
The request to save the card data transmitted via the API, without redirecting to the Payler payment gateway page.
Available for: mapi, cmapi
Request method:
POSTRequest 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 | |
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:
{
"card_id": "z5RkjN4OiQ6I1UwTlpHJKBKj5Kf99D4T8r1c",
"card_status": "Saved",
"customer_id": "wsdj24DDgs34fsfDfs24Dr45L98klkm9kknc",
"card_number": "400000xxxxxx0002",
"card_holder": "NONAME",
"expired_year": 18,
"expired_month": 7
}
Request for registration of a new customer.
Available for: gapi, mapi, cgapi, cmapi
Request method:
POSTRequest 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:
{
"customer_id": "Wkl7nBsMhwQICc2I9wXncMeSwnIaucQ5BHyo"
}
Request to update the customer data.
Available for: gapi, mapi, cgapi, cmapi
Request method:
POSTRequest 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:
{
"customer_id": "Wkl7nBsMhwQICc2I9wXncMeSwnIaucQ5BHyo"
}
Customer removal request.
Available for: gapi, mapi, cgapi, cmapi
Request method:
POSTRequest 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:
{
"changed": true
}
Request to check if the customer is registered.
Available for: gapi, mapi, cgapi, cmapi
Request method:
POSTRequest 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:
{
"status": "Active"
}
Last modified 22d ago