Payment is registered in the gateway, but processing in the processing center
is not finished
The user started the authentication using the 3-D Secure protocol
Funds are blocked, but are not charged off (two-stage payment)
The funds on the card were blocked and fully unlocked
The money is charged off from the user’s card, the payment is completed successfully
Full refund of funds to the user’s card has been successfully completed
The last payment operation was declined
The operation is in processing. In this case, it is advisable to make the status requests through time intervals in geometrical progression in order to know the final status of the payment
The money is credited to the user’s card, the transfer is completed successfully
API method descriptions use the following data type notation:
String with a fixed number of characters. The number indicates the number of characters
Character limited string. The number indicates the maximum number of characters allowed
Array with a limited number of elements. The number indicates the maximum number of elements allowed
Integer number with a fixed number of characters. The number indicates the number of characters
The merchant can sign up to receive guaranteed notifications (callback) about successful or unsuccessful payments. The notifications work as follows: after changing the order status, the payment gateway sends a POST request to a predefined URL. In the query parameters, order_id
• In case the successful response code (2xx) is received, then the notification processing is completed;
• In case an error is received, or the server is unavailable, then the attempt is repeated after 10 seconds, 1 minute, 15 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 6 hours, 8 hours.
To receive callback, the merchant’s service must be available at one of the following ports: 80, 433, 8080, 4443, 8443, 9443, 14405, 4405.
Outbound IP Address: 22.214.171.124
The merchant specifies the URL for sending guaranteed notifications in the Merchant Account, section «Settings» → «Notifications».
Сreating customer accounts and saving cards
For convenience of regular customers, the merchant can save their card details for subsequent payments. The data of the customer's payment card can be entered both on the side of the merchant and on the web page of the secure Payler gateway. In the first case, the merchant must comply with the PCI DSS security standard.
For a detailed description of the procedure and methods for managing user accounts and payment cards, see API Methods: Saving Cards
At subsequent payments by the user, the merchant specifies the customer_id, and the user can select one of his previously saved cards or specify a new card on the payment page.
Removal of the card (RemoveCard) and removal of the customer (CustomerDelete) are irreversible, if you delete the customer, all the cards added will also be deleted.
For subsequent Payment operations, you need to store and use reccurent_template_id. For subsequent Credit operations (transfer), it is required to store and use card_id.
Saving card when paying
Merchant calls StartSession method with key parameters reccurrent = true and customer_id.
Merchant sends the user to the payment page (PayGate method).
User enters and sends card data.
After payment is completed, the user is redirected to merchant’s website, at a predefined address. Callback is sent (optional).
At user redirection or receiving a callback, merchant can call the GetAdvancedStatus method to the check status of the order and receive card_id/reccurent_template_id.
If there is no 3DS on the payment (card is not involved in 3D ‑ Secure), the card will not be saved;
If the payment is rejected because of the balance or is successful, then for subsequent debiting (RepeatPay method) a recurrence template is created and the card is saved for funds withdrawal operations (RepeatCredit method). The template data is sent only into callback.
Saving a card with verification of the amount and automatic refund (unlock)
In this scenario, a block or write-off of funds in amount of 1 RUB is carried out. It is followed by automatic cancellation of the operation. Operation type performed (locking / write-off) depends on the processing settings.
At user redirection or receiving a callback, the merchant can call the GetAdvancedStatus to check the order status and receive card_id/reccurent_template_id.
If there is no 3DS on the payment (card is not involved in 3Dsecure), card will not be saved;
If the payment is rejected because of the balance or is successful, then form is shown with information that the card was saved successfully. A form template can be customized.
If the operation is completed successfully, then funds are automatically refunded (unlocked).
If the payment is rejected because of the balance or is successful, then a recurrence template is created for subsequent payments and the card is saved for the operations of issuing funds (Credit). Template data (_template_id) is sent only to callback.
To save card data with the subsequent possibility of debiting or issuing funds, it is recommended to use script with call of StartSaveCardSession method. In this case, either upon successful completion of the test payment (blocking) or upon a deviation in the balance, the card data will be saved and a page with information on successful saving of the card will be displayed for the user.
Recurrent (regular, recurring) payments are payments that do not require re-entering card details. The user makes payment once and agrees to conditions of regular debiting; subsequent write-off occurs without their participation. When making the first payment in a series, a recurring payment template is registered in the database. The template is assigned with a unique identifier that is given to the merchant. When making a recurring payment, the merchant performs a request indicating the received template identifier.
The first payment is performed with the input of all card details, including card security code (CVV2 / CVC2) and authorization through the 3D Secure protocol. Subsequent payments are made without entering card details and participation of the cardholder.
When making payment, the merchant may pass a special parameter, which will mean that this payment is the first payment in the queue of recurring payments. If the payment is successful, the merchant will receive the identifier of the created template. Repeated payments will be made using this identifier.
The validity period of the template is set equal to the card expiration date to which it is attached. Information about registered recurring payment patterns can be obtained as a result of GetTemplate request; however, the template identifier must be specified.
Activation or deactivation of the template is performed as a result of ActivateTemplate request; however, you must specify the template identifier. Automatic deletion of templates through the Payler API is not available. You can delete the template upon request to Payler technical support.
Amount of re-payments can be both greater and less than the amount of the initial payment. The initial payment can be cancelled (return the money to the user), but the ability to make recurring payments will remain. The initial payment in the series can be either one-stage or two-stage. In case of a two-stage payment, the template is created when funds are blocked, but becomes active only after the write-off of the blocked funds is successfully completed. Repeated payments are always one-step.
Payment execution scenarios After successful payment execution, the merchant receives the identifier of the created recurrent payment template (parameter recurrent_template_id) in the callback. To use HTTPS protocol for callback is required. The merchant needs preliminary configure the callback for the charge or block trigger. The callback can be set by the merchant in the Merchant’s account or by contacting Payler technical support.
Payment execution Create a payment session (request StartSession) with the specified parameter recurrent = true. Redirect user to PayGate request. Other way (only for Merchant scheme)—perform request PayMerchant or Block with the specified parameter recurrent = true.
Saving recurrent payment template After successful payment execution, Payler sends merchant an identifier of the created template recurrent_template_id with help of сallback. After receiving the callback, it is required to request payment status (request GetStatus). This is necessary to ensure that the payment execution is successful. In case of a successful write-off, the merchant saves received recurrent_template_id. If the payment status is different from the charged\ authorized one, the reccurent template must be considered invalid. It is required to contact Payler technical support.
Performing recurrent payment To perform recurrent payment, you must perform RepeatPay request with the specified recurrent_template_id.
The IPS rules limit the number of attempts to write off funds on a recurring basis.
• If the recurring payment by VISA card is declined, a repeated request for authorization can be sent no more than 4 times within 16 calendar days;
• If a recurring MasterCard payment is declined, a repeated authorization request can be sent no more than once a day for 31 days. In case the merchant violates the rules of recurring payment attempts, a dispute on a transaction (chargeback) may be resolved in favour of the payer.
4. Request recurrent payment status
It is necessary to get the status of a recurrent payment using GetStatus request with the parameters key, order_id.
Scheme of performing payment with recurrent payment template creation
During the integration process, the merchant is required to inform Payler technical support about the necessity to connect and set for recurring payments on their account.
3-D Secure is an XML-based protocol designed to be an additional security layer for online credit and debit card transactions. Name 3DS comes from “3 Domains” (three domains), since organizations on three domains participate in verification of payments under this protocol:
Issuer domain (the bank which issued the card being used),
Merchant/acquirer domain (IPS) domain (the bank and the merchant to which the money is being paid),
Interoperability domain (MPI) (the infrastructure provided by the card scheme, credit, debit, prepaid or other types of a payment card, to support the 3-D Secure protocol).
There are two versions of the 3D Secure protocol - 3DS 1.0 and a more innovative one that is currently being implemented by issuing banks 3DS 2.0. The transition to the version 2.0 is carried out gradually, since some issuers do not support 3DS 2.0. If it is not possible to perform authentication using the new protocol, authentication is performed using 3DS 1.0. The fundamental difference between the new version of the protocol is:
in the possibility to authenticate without the direct user participation (frictionless flow),
in using 3DS Method for authentication with verification of the cardholder. In this case, the issuer gains access to the hidden iframe in the user’s browser and independently collects the browser data required for authentication.
When a request is received to make a payment or save the card, for further execution of the operation, Payler checks the card's involvement in 3D-Secure and determines the supported protocol version.
Brief authentication scenario according to 3DS 1.0 version (3DS 1.0 Flow): The cardholder makes a payment on the merchant website, enters the card details. The cardholder is sent to the issuing bank's page to enter a unique code. The code is sent to the user by the issuing bank via another channel (for example, to phone). If the code is entered correctly, the issuing bank reports the successful completion of the verification and the operation is completed successfully.
3DS 2.0 allows the issuer to use several modes of client authentication, including the input of a one-time code sent by the issuer in sms.
But unlike 3DS 1.0, entering a password is optional. The decision to confirm the transaction is made on the basis of data about the device from which the payment is made, browser settings, IP address, e-mail, etc. The card issuer uses this information to assess the level of risk and the need to perform additional verification of the user. Depending on the results of the risk analysis, the issuer makes a decision on further authentication:
Frictionless flow — if the risk of fraud is below a predetermined threshold, then the issuer does not request additional verification of the payer and considers that the cardholder's authentication is passed. In this case, the stage of "manual verification" with the input of the additional code by the payer is excluded.
Challenge flow — if the risk of fraud is higher than a predetermined threshold, an additional verification of the cardholder is performed in the same way as in 3DS 1.0.
3D-Secure schematic diagram
Possible scenarios of 3D-Secure 2.0 authentication
Currently 3D-Secure version 2.2.0 is supported.
The description below refers to the payment services provision using Apple Pay in a mobile application or on the website of the merchant. To make payment using Apple Pay through the Payler payment form, no additional integration steps are required; to enable this payment method, just contact Payler Technical Support.
Accepting payments in mobile applications
To use Apple Pay technology the merchant needs to register Merchant ID and generate a payment certificate:
Payler creates a CSR and sends it to the merchant.
Merchant uploads the certificate to their Apple developer account, as described in Apple documentation.
Merchant sends the received certificate and the Merchant ID to Payler.
Scheme includes 3 steps:
Device compatibility check—if the device is supported, then you need to show Apple Pay button to the user.
Confirmation of payment—payment confirmation by fingerprint.
Payment processing—after confirmation, Apple generates an encrypted token that must be transferred to Payler API. This requires:
Page with Apple Pay button should be sent via HTTPS using a valid SSL certificate and TLS 1.2 protocol.
Get file “apple-developer-merchantid-domain-association” from Payler,
Place the received file on the merchant’s server at: https:///.well-known/apple-developer-merchantid-domain-association.
Scheme includes 4 steps:
Device compatibility check—if the device is supported, then you need to show Apple Pay button to the user.
Merchant validation—it is necessary to perform AppleValidateMerchant request to validate the merchant in Apple.
Confirmation of payment—payment confirmation by fingerprint.
Payment processing—after confirmation, Apple generates an encrypted token that must be transferred to Payler API by ApplePay request.
Apple Pay Button display
An example of CSS and HTML for adding an Apple Pay button on a page can be found in Apple documentation. Initially, Apple Pay button should be invisible (display: none), and displayed only if it is possible to pay using Apple Pay from this device.
First, you need to check the possibility of making payments through Apple Pay on this device:
var promise = ApplePaySession.canMakePaymentsWithActiveCard(merchantIdentifier);
The description below refers to the payment services provision using Google Pay in a mobile application or on the website of the merchant. To make payment using Google Pay through the Payler payment form, no additional integration steps are required; to enable this payment method, just contact Payler Technical Support.
Merchant can choose the types of cards (authentication methods), which can be used to pay in Google Pay.
There are two authentication methods available:
CRYPTOGRAM 3DS—for tokenized cards, which data is stored in the form of tokens on the client device, only available on the device on which they were added to the Google Pay app.
PAN ONLY—for non-tokenized cards, which data is stored in the Google account, available on any client device. The authentication type is specified in the settings when integrating with Google Pay in allowedAuthMethods property.
PAN ONLY method is not available for all merchants. The possibility of using this method must be specified individually.
Gateway parameter in the script has the constant value "payler";
Merchant receives the value of gatewayMerchantId parameter from Payler;
MerchantId parameter value is received by the merchant from Google;
Value of merchantName parameter corresponds to the name of an online store specified
when registered in Google.
In response, Google should return the PaymentData element, and paymentMethodData.tokenizationData.token field should contain a securely encrypted Google Pay token (character string).