Payler API
Search…
General information
Introduction
General
API methods
Payments
Transfers
Saving Cards
Failed requests
Answers in case of failed requests
Error codes
Server error codes
Terms and abbreviations
Terms and abbreviations
Powered By GitBook
General

Types of operations

Payment

Operation of funds transfer from the user's card account to the merchant's account.
  • One-stage payment—after authorization, payment amount is blocked on cardholder's account and automatically debited after 24 hours. This type of payment is set by default for all merchants integrated in the system.
  • Two-stage payment—after authorization, payment amount is blocked on the cardholder's account, but writing off happens only after operation approval by the merchant. This payment type is set by merchant request.

Transfer

Operation of funds transfer from the merchant's account to the user's card one.

Operation performing process

GATE SCHEME

Payment (gapi)

Payment process is as follows:
  1. 1.
    Merchant calls StartSession API method to create a payment session;
  2. 2.
    Merchant redirects the user to the payment page (PayGate);
  3. 3.
    User enters card details and sends them. By default, up to 5 payment attempts are available to the user. Number of attempts can be individually changed by merchant's request. If necessary, the payment gateway redirects the user to the issuing bank page for entering a confirmation code (3-D Secure);
  4. 4.
    After payment is completed, the user is redirected to the merchant’s website, a predefined address;
  5. 5.
    When the user is returned, the merchant calls GetStatus API method to check the status of the order.

Transfer (cgapi)

Process of transferring funds is as follows:
  1. 1.
    Merchant calls StartCreditSession method to create a transfer session;
  2. 2.
    Merchant redirects the user to the transfer page (CreditGate).
  3. 3.
    User enters card details and sends them;
  4. 4.
    After transfer is completed, the user is returned back to to merchant’s website, a pre-determined address;
  5. 5.
    When the user is returned, the merchant calls GetStatus method to check the status of the transferring.

MERCHANT SCHEME

Payment (mapi)

Payment process is as follows:
  1. 1.
    User enters card details on the merchant’s website.
  2. 2.
    Merchant calls PayMerchant or Block method, depending on the type of payment.
  3. 3.
    If it is necessary to pass additional authentication using 3D-Secure, depending on the 3DS protocol used, the merchant makes additional Send3DS, ThreeDsMethodComplete, ChallengeComplete requests.
  4. 4.
    After payment is completed, merchant calls the GetStatus method to check the status of the order.

Transfer (cmapi)

Process of transferring funds is as follows:
  1. 1.
    User enters card details on the merchant’s website.
  2. 2.
    Merchant calls CreditMerchant method.
  3. 3.
    After payment is completed, the merchant calls the GetStatus method to check the status of the transfer. In rare cases, the user may not return to the merchant's website, for example, if they close the browser window immediately after payment, or they lose access to the Internet. To always find out about changes in the status of an order, the merchant can set up receiving guaranteed notifications (callback).

Payment methods

​
Method
Description
Card
Payment via bank card
ApplePay
Payment via ApplePay
GooglePay
Payment via GooglePay

Operation statuses

​
Status
Meaning
Created
Payment is registered in the gateway, but processing in the processing center is not finished
PreAuthorized3DS
The user started the authentication using the 3-D Secure protocol
Authorized
Funds are blocked, but are not charged off (two-stage payment)
Reversed
The funds on the card were blocked and fully unlocked
Charged
The money is charged off from the user’s card, the payment is completed successfully
Refunded
Full refund of funds to the user’s card has been successfully completed
Rejected
The last payment operation was declined
Pending
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
Credited
The money is credited to the user’s card, the transfer is completed successfully

Data types

API method descriptions use the following data type notation:
Sign
Description
A
String
A*
String with a fixed number of characters. The number indicates the number of characters
A..*
Character limited string. The number indicates the maximum number of characters allowed
Ar
Array
Ar..*
Array with a limited number of elements. The number indicates the maximum number of elements allowed
B
Boolean
D
Dictionary
F
Fractional number
N
Integer number
N*
Integer number with a fixed number of characters. The number indicates the number of characters

Guaranteed notifications

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 is passed:
• 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, 1 hour, 2 hours, 4 hours, 8 hours, 24 hours. T
o 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: 178.20.235.180
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​

Process of storing card data

Card linking is executed as follows:
  1. 1.
    Merchant creates the customer in the Payler system CustomerRegister.
  2. 2.
    Merchant adds cards to the created customer, the cards are saved during payment:
  3. 3.
    when specifying customer_id in StartSession; - with verification of the amount and automatic return of funds (unlock); - method StartSaveCardSession (Gate scheme) or PaySaveCard (Merchant scheme).
  4. 4.
    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.
  5. 5.
    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

Execution script:
  1. 1.
    Merchant calls StartSession method with key parameters reccurrent = true and customer_id.
  2. 2.
    Merchant sends the user to the payment page (PayGate method).
  3. 3.
    User enters and sends card data.
  4. 4.
    After payment is completed, the user is redirected to merchant’s website, at a predefined address. Callback is sent (optional).
  5. 5.
    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.
Features:
  • 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.
Execution script (for Gate scheme):
  1. 1.
    Merchant calls StartSaveCardSession to create a saving card session.
  2. 2.
    Merchant sends the user to card save the page (Save method).
  3. 3.
    User enters and sends card data.
  4. 4.
    After payment is completed the user is redirected to the merchant’s website, at a predefined address. Callback is sent (optional).
  5. 5.
    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.
Execution script (for Merchant scheme):
  1. 1.
    Merchant calls PaySaveCard.
  2. 2.
    User enters and sends card data.
  3. 3.
    After payment completing, the debited amount is automatically unlocked or refunded.
  4. 4.
    ​Callback is sent (optional).
  5. 5.
    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.
Features:
  • 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.

Recurring payments

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.

Work principles

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.
Scenario steps
  1. 1.
    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.
  2. 2.
    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.
  3. 3.
    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.

3D Secure

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:
  1. 1.
    Issuer domain (the bank which issued the card being used),
  2. 2.
    Merchant/acquirer domain (IPS) domain (the bank and the merchant to which the money is being paid),
  3. 3.
    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.

3DS 1.0

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

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.

3DS Scenarios

3D-Secure schematic diagram
Currently 3D-Secure version 2.2.0 is supported.

ApplePay payments

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

Merchant Registration

To use Apple Pay technology the merchant needs to register Merchant ID and generate a payment certificate:
  1. 1.
    Payler creates a CSR and sends it to the merchant.
  2. 2.
    Merchant uploads the certificate to their Apple developer account, as described in Apple documentation.
  3. 3.
    Merchant sends the received certificate and the Merchant ID to Payler.

Payment execution

Scheme includes 3 steps:
  1. 1.
    Device compatibility check—if the device is supported, then you need to show Apple Pay button to the user.
  2. 2.
    Confirmation of payment—payment confirmation by fingerprint.
  3. 3.
    Payment processing—after confirmation, Apple generates an encrypted token that must be transferred to Payler API. This requires:
  • call the StartSession method to initialize payment session; • after payment is confirmed by the user, the paymentData parameter from PKPaymentToken object should be transferred to Payler using ApplePay method;
  • call completion in the application by passing the payment status to it.
Apple Pay integration to mobile apps is described in Apple documentation.

Accepting payments on the merchant’s website

Page with Apple Pay button should be sent via HTTPS using a valid SSL certificate and TLS 1.2 protocol. This requires:
  1. 1.
    Get file “apple-developer-merchantid-domain-association” from Payler,
  2. 2.
    Place the received file on the merchant’s server at: https:///.well-known/apple-developer-merchantid-domain-association.

Payment execution

Scheme includes 4 steps:
  1. 1.
    Device compatibility check—if the device is supported, then you need to show Apple Pay button to the user.
  2. 2.
    Merchant validation—it is necessary to perform AppleValidateMerchant request to validate the merchant in Apple.
  3. 3.
    Confirmation of payment—payment confirmation by fingerprint.
  4. 4.
    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.

Payment processing in JavaScript

First, you need to check the possibility of making payments through Apple Pay on this device:
1
var promise = ApplePaySession.canMakePaymentsWithActiveCard(merchantIdentifier);
2
promise.then(function (canMakePayments) {
3
if (canMakePayments) {
4
// if possible – display the button
5
document.getElementById(“apple-pay-button”).style.display = “block”;
6
}
7
});
Copied!
By click on the button, create a payment session:
1
document.getElementById(“apple-pay-button”).onclick = function(evt) {
2
var paymentRequest = {
3
currencyCode: ‘RUB’,
4
countryCode: ‘RU’,
5
total: {
6
label: ‘Product Description’,
7
amount: 100.00 // price in rubles
8
},
9
supportedNetworks: [‘masterCard’, ‘visa’, ‘mir’],
10
merchantCapabilities: [ ‘supports3DS’, ‘supportsCredit’, ‘supportsDebit’]
11
};
12
var session = new ApplePaySession(2, paymentRequest);
Copied!
Next, add event handlers to the object session:
Merchant validation
1
session.onvalidatemerchant = function (event) {
2
// event.validationURL needs to be sent to your server, call
3
//Payler from it method AppleValidateMerchant, and send the received response to
4
//session.completeMerchantValidation method
5
session.completeMerchantValidation(JSON.parse(response.validation_object));
6
}
Copied!
Payment processing
1
session.onpaymentauthorized = function (event) {
2
// event.payment.token.paymentData needs to be sent to your server, call
3
// Payler StartSession method from it, than ApplePay.
4
// Result of the payment must be sent back to the client.
5
6
// If the payment is successful, call:
7
session.completePayment(ApplePaySession.STATUS_SUCCESS);
8
9
// If the payment is unsuccessful, call:
10
session.completePayment(ApplePaySession.STATUS_FAILURE);
11
}
Copied!
Apple Pay form display
1
session.begin();
Copied!
More details on methods and events ApplePaySession can be found in Apple documntation.

GooglePay payments

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.
In case of using Google Pay, the merchant must comply with the following rules: https://payments.developers.google.com/terms/merchanttos Overview: https://developers.google.com/pay/api/web​
Merchant can choose the types of cards (authentication methods), which can be used to pay in Google Pay.
There are two authentication methods available:
  1. 1.
    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.
  2. 2.
    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.

Accepting payments in mobile applications

Customization Google Pay API
1
1. package com.google.android.gms.samples.wallet;
2
2.
3
3. import com.google.android.gms.wallet.WalletConstants;
4
4. import java.util.Arrays;
5
5. import java.util.HashMap;
6
6. import java.util.List;
7
7.
8
8. public class Constants {
9
9.
10
10. public static final int PAYMENTS_ENVIRONMENT =
11
WalletConstants.ENVIRONMENT_TEST; // WalletConstants.ENVIRONMENT_PRODUCTION for production environment.
12
11.
13
12. public static final List<String> SUPPORTED_NETWORKS = Arrays.asList(
14
13. «MASTERCARD»,
15
14. «VISA»);
16
15.
17
16. public static final List<String> SUPPORTED_METHODS =
18
17. Arrays.asList(
19
18. “PAN_ONLY”, //payment by card data from Google account);
20
“CRYPTOGRAM_3DS”); //Payment only if the device Google Pay. It is a more
21
secure way. You can use both methods, or any one of them.
22
19.
23
20. public static final String CURRENCY_CODE = “RUB”; // Or USD, EUR.
24
Must match the currency in StartSession.
25
21.
26
22. public static final String PAYMENT_GATEWAY_TOKENIZATION_NAME = “payler”;
27
23.
28
24. public static final HashMap<String, String>
29
PAYMENT_GATEWAY_TOKENIZATION_PARAMETERS =
30
25. new HashMap<String, String>() {
31
26. {
32
27. put(“gateway”, PAYMENT_GATEWAY_TOKENIZATION_NAME);
33
28. put(“gatewayMerchantId”, “ Your identifier in Payler system “);
34
29. }
35
30. }; }
36
31. private Constants() {}
37
32.}
Copied!
In file PaymentsUtil.java type of tokenization must be set to “PAYMENT_GATEWAY”.

Payment execution

Scheme includes 2 steps:
  1. 1.
    Call StartSession method to initialize a payment session.
  2. 2.
    In the handler for Google Pay button clicking, if successful, call GooglePay method, passing:
  • session_id from StartSession response,
  • "tokenizationData.token" string from a received Google PaymentData object (google_pay_token),
  • user's mail address (email).
Token Example:
1
{
2
«signature»: «MEYCIQCkSQPbDN5lKh1Y+l6W3A5fdW3Patf0hoBrXmTudQZSSQIhAMX8G54mswpbw07t1adHhNfZAkWUvQ6YyQP8Zzhc68pR»,
3
«intermediateSigningKey»: {
4
«signedKey»: «{\»keyValue\»:\»MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEzHwfz1Vq1Zif9fiZVyBI33CnXRwBP2hJ1CYvzx5x6adfBXfYv0krbQU1bEv9DNKwStIlRKhzQhIdeJZBGFl96w\\u003d\\u003d\»,\»keyExpiration\»:\»1551450347229\»}»,
5
«signatures»: [
6
«MEYCIQC6Cws1WbyrGnoijw0MWcjvq16aYCL+JH/+5Y3DAMbJiwIhAL6+RWUJo+j9cqaP71UsZs18GPVU0kq/CLOB0Qb8rBgr»
7
]
8
},
9
«protocolVersion»: «Ecv2»,
10
«signedMessage»: «{\»encryptedMessage\»:\»WBGMAnIuhwyGROX6c4q/Ux6Gupm/US2FVnq7wKZEp7C6E5OkiHqv/2vd+PW4/XVY1VlKhh+Pot6RY66Q3OX/Q2apalv+4OcxWJhlsP4sZ0NZCCiJEfWY5P9ayjNbzJJnoJerfwykn2cDItHHjerHtNObMUkqCFkW7Yj0X5uZTfx1Alr2k4knLWtMrlfHuh9RhiAei/pcppWerYmNPrLzU615ypqinwtifq+iVldnz2oYJpDzQyZukFU51Xu5BqhzHUtqly9Y1Lt1hCfCeLY4fqrz/V10oiXmgeY9gUrJOy6zzSdAq5VsdiZlUJCbspK2lThXG9Hg/ZPQ7o0fxdSnLI3BvkjFLvFtLgDtnk9o8Di9kx2intm/5YJS0RB1wOfjicn5JzwuDiur/RXYMPjhAh0L+Zuts3knWMNlgiVXAuEPwRm5oU/2RiThV3du3BNJSQbybflvSIhH12Pwua1tFLRKzESBnhfrP/OFN52PaazQQ4Jv7PG+tpVuvWEErdifoGuVXQw89vloCYKYBBEdlNG85DSkMYq/hAfmsgFrDrs7spA1Sb26s5oJRomL76x90X8\\u003d\»,\»ephemeralPublicKey\»:\»BLVkBHOrk1we3aAqbHeMfnL3dfGUmM9MQJ8CJtLwQn6KUnpySSSY0os+PHDbqfIHVVa8jqzgx1gynofubTsqgTA\\u003d\»,\»tag\»:\»5lc6cXbwEd9obykJ+qbAj+O6fHFwP85Lgnihp4//zDg\\u003d\»}»
11
}
Copied!

Accepting payments on the merchant’s website

Merchant’s site must be HTTPS and support the TLS protocol version 1.2. The site domain must be pre-registered and verified by Google by filling out a registration form. After submitting form, a Google representative contacts the merchant for instructions on further actions. Integration includes the use of server and client (javascript) parts. Client checks the device compatibility and receives payment data, the server sends a request for payment execution.
Settings
  • 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.
Js-code example:
1
//**
2
* Define the version of the Google Pay API referenced when creating your
3
* configuration
4
*
5
* @see {@link https://developers.google.com/pay/api/web/reference/object#PaymentDataRequest|apiVersion in PaymentDataRequest}
6
*/
7
var baseRequest = {
8
apiVersion: 2,
9
apiVersionMinor: 0,
10
};
11
12
var allowedCardNetworks = [‘MASTERCARD’, ‘VISA’];
13
// CRYPTOGRAM_3DS – Payment only if Google Pay is available on the device. It is a more secure way. Currently works only in Chrome browser on Android.
14
// PAN_ONLY – Payment by card data from Google account. Available in most modern browsers.
15
//You can use both methods, or any one of them.
16
Var allowedCardAuthMethods = [“PAN_ONLY”,’CRYPTOGRAM_3DS’];
17
var tokenizationSpecification = {
18
type: ‘PAYMENT_GATEWAY’,
19
parameters: {
20
gateway: ‘payler’,
21
gatewayMerchantId: ‘ваш Id в системе Payler’,
22
},
23
};
24
​
25
/**
26
* Describe your site’s support for the CARD payment method and its required
27
* fields
28
*
29
* @see {@link https://developers.google.com/pay/api/web/reference/object#CardParameters|CardParameters}
30
*/
31
var baseCardPaymentMethod = {
32
type: ‘CARD’,
33
parameters: {
34
allowedAuthMethods: allowedCardAuthMethods,
35
allowedCardNetworks: allowedCardNetworks,
36
},
37
};
38
​
39
/**
40
* Describe your site’s support for the CARD payment method including optional
41
* fields
42
*
43
* @see {@link https://developers.google.com/pay/api/web/reference/object#CardParameters|CardParameters}
44
*/
45
var cardPaymentMethod = Object.assign({}, baseCardPaymentMethod, {
46
tokenizationSpecification: tokenizationSpecification,
47
});
48
​
49
var paymentsClient = null;
50
​
51
/**
52
* Configure your site’s support for payment methods supported by the Google Pay
53
* API.
54
*
55
* Each member of allowedPaymentMethods should contain only the required fields,
56
* allowing reuse of this base request when determining a viewer’s ability
57
* to pay and later requesting a supported payment method
58
*
59
* @returns {object} Google Pay API version, payment methods supported by the site
60
*/
61
function getGoogleIsReadyToPayRequest() {
62
return Object.assign({}, baseRequest, {
63
allowedPaymentMethods: [baseCardPaymentMethod],
64
});
65
}
66
​
67
/**
68
* Configure support for the Google Pay API
69
*
70
* @see {@link https://developers.google.com/pay/api/web/reference/object#PaymentDataRequest|PaymentDataRequest}
71
* @returns {object} PaymentDataRequest fields
72
*/
73
function getGooglePaymentDataRequest() {
74
var paymentDataRequest = Object.assign({}, baseRequest);
75
paymentDataRequest.allowedPaymentMethods = [cardPaymentMethod];
76
paymentDataRequest.transactionInfo = getGoogleTransactionInfo();
77
paymentDataRequest.merchantInfo = {
78
// @todo a merchant ID is available for a production environment after approval by Google
79
// See {@link https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist|Integration checklist}
80
merchantId: ‘Ваш Id GooglePay’,
81
merchantName: ‘Ваше наименование,
82
};
83
return paymentDataRequest;
84
}
85
​
86
/**
87
* Return an active PaymentsClient or initialize
88
*
89
* @see {@link https://developers.google.com/pay/api/web/reference/client#PaymentsClient|PaymentsClient constructor}
90
* @returns {google.payments.api.PaymentsClient} Google Pay API client
91
*/
92
function getGooglePaymentsClient() {
93
if (paymentsClient === null) {
94
paymentsClient = new google.payments.api.PaymentsClient({
95
environment: ‘TEST’, // For product environment PRODUCTION
96
});
97
}
98
return paymentsClient;
99
}
100
​
101
/**
102
* Initialize Google PaymentsClient after Google-hosted JavaScript has loaded
103
*
104
* Display a Google Pay payment button after confirmation of the viewer’s
105
* ability to pay.
106
*/
107
function onGooglePayLoaded() {
108
{
109
var paymentsClient = getGooglePaymentsClient();
110
​
111
paymentsClient
112
.isReadyToPay(getGoogleIsReadyToPayRequest())
113
.then(function(response) {
114
if (response.result) {
115
addGooglePayButton();
116
// @todo prefetch payment data to improve performance after confirming site functionality
117
// prefetchGooglePaymentData();
118
}
119
})
120
.catch(function(err) {
121
// show error in developer console for debugging
122
console.error(err);
123
});
124
}
125
}
126
​
127
/**
128
* Add a Google Pay purchase button alongside an existing checkout button
129
*
130
* @see {@link https://developers.google.com/pay/api/web/reference/object#ButtonOptions|Button options}
131
* @see {@link https://developers.google.com/pay/api/web/guides/brand-guidelines|Google Pay brand guidelines}
132
*/
133
function addGooglePayButton() {
134
var paymentsClient = getGooglePaymentsClient();
135
var button = paymentsClient.createButton({onClick: onGooglePaymentButtonClicked});
136
var changeBlock = document.querySelector(‘.change-js’);
137
document.getElementById(‘container’).appendChild(button);
138
changeBlock.style.display = ‘block’;
139
}
140
​
141
/**
142
* Provide Google Pay API with a payment amount, currency, and amount status
143
*
144
* @see {@link https://developers.google.com/pay/api/web/reference/object#TransactionInfo|TransactionInfo}
145
* @returns {object} transaction info, suitable for use as transactionInfo property of PaymentDataRequest
146
*/
147
function getGoogleTransactionInfo() {
148
return {
149
currencyCode: ‘RUB’, //Currency of payment
150
totalPriceStatus: ‘FINAL’,
151
// set to cart total
152
totalPrice: ‘11.20’, //Amount of payment
153
};
154
}
155
​
156
/**
157
* Prefetch payment data to improve performance
158
*
159
* @see {@link https://developers.google.com/pay/api/web/reference/client#prefetchPaymentData|prefetchPaymentData()}
160
*/
161
function prefetchGooglePaymentData() {
162
var paymentDataRequest = getGooglePaymentDataRequest();
163
// transactionInfo must be set but does not affect cache
164
paymentDataRequest.transactionInfo = {
165
totalPriceStatus: ‘NOT_CURRENTLY_KNOWN’,
166
currencyCode: ‘RUB’,
167
};
168
var paymentsClient = getGooglePaymentsClient();
169
paymentsClient.prefetchPaymentData(paymentDataRequest);
170
}
171
​
172
/**
173
* Show Google Pay payment sheet when Google Pay payment button is clicked
174
*/
175
function onGooglePaymentButtonClicked() {
176
var paymentDataRequest = getGooglePaymentDataRequest();
177
paymentDataRequest.transactionInfo = getGoogleTransactionInfo();
178
​
179
var paymentsClient = getGooglePaymentsClient();
180
paymentsClient
181
.loadPaymentData(paymentDataRequest)
182
.then(function(paymentData) {
183
// handle the response
184
processPayment(paymentData);
185
})
186
.catch(function(err) {
187
// show error in developer console for debugging
188
console.error(err);
189
});
190
}
191
​
192
function sendPaymentData(paymentToken) {
193
return new Promise(function(resolve, reject) {
194
var xhr = new XMLHttpRequest();
195
xhr.onload = function() {
196
var data = JSON.parse(this.responseText);
197
resolve(data);
198
};
199
xhr.onerror = reject;
200
xhr.open(
201
‘POST’,
202
‘https:/secure.payler.com/gapi/GooglePay?session_id=’ + // https:/secure.payler.com for test environment
203
encodeURIComponent(window.params_payler.session_id) +
204
‘&google_pay_token=’ +
205
encodeURIComponent(paymentToken)
206
);
207
xhr.send();
208
});
209
}
210
​
211
/**
212
* Process payment data returned by the Google Pay API
213
*
214
* @param {object} paymentData response from Google Pay API after user approves payment
215
* @see {@link https://developers.google.com/pay/api/web/reference/object#PaymentData|PaymentData object reference}
216
*/
217
function processPayment(paymentData) {
218
// show returned data in developer console for debugging
219
// console.log(paymentData);
220
// @todo pass payment token to your gateway to process payment
221
paymentToken = paymentData.paymentMethodData.tokenizationData.token;
222
​
223
var promise = sendPaymentData(paymentToken);
224
promise.then(function(response) {
225
if (response.error) {
226
// console.log(response.error);
227
} else {
228
);
229
}
230
});
231
}
232
}
233
​
Copied!
In response, Google should return the PaymentData element, and paymentMethodData.tokenizationData.token field should contain a securely encrypted Google Pay token (character string).
Google Pay Token Example:
1
{
2
«signature»: «MEUCIQDY3wBQyHB4sZcktRoJXKxm+OlcjHzCvdDeGn23oX0kkwIgKznRFZZL+sDMv1b5cuD+YurXMZraYBsr9hbravVY5Ro\u003d»,
3
«protocolVersion»: «Ecv2»,
4
«signedMessage»: «{\»encryptedMessage\»:\»cI87tLqzqTGyCFnMMCVWcTHw3xhYIK+CenuQ74K+nlLpCgOlfpScib9jds4sxDtN6CunCqCSMfd/3yHeeRy6aCx1yyqcT4ey6NueeBznprJpkmVVgI1JHWLQt4hzAXMUAcYASYLOabKP9fUZvHkOBDytD531jpzNXa+Spc/zrpGzFKx2C4VU9sC95q9i+ey+kr7ZMNVCOFJPWXu7lKZ105IOOqozJ6/70MKmxP3jM89eeq+/19QnyHjQLXfnQPvQjiUJKGCcRKDLlrb3XoY5ZUUzGfN5eZCLzCVg0hWEbwU+6J7KWYJyW+Wr1r8bagN9zWsrMKhDpsQbHfyzb+yBzFUoxeUgL4a7FeVvEllIcHtqsvTCf6FENV20aF5VLDv5qzUkV+PzTAIbFEuabA0God9UbVCVVv7nM8QFzvRPhzYYFVFTn4JHvL2qZ4pAR9lE+w\\u003d\\u003d\»,\»ephemeralPublicKey\»:\»BPHLC4sBHpenY1M0ixmiDMuWJTaTJOqggRUwtgBJMcBp28VsxHD7zPI7985x4F5EjMP5y8j/cuUzbe/cGPjOKGk\\u003d\»,\»tag\»:\»RaXrPOUuc5iw3oxDa0C2MOjaKxgxIRQvwOspmtFV0zU\\u003d\»}»
5
}
Copied!

Payment execution

The procedure is similar to payment execution when executing payment from a mobile application (see above).
General information - Previous
Introduction
Next - API methods
Payments
Last modified 1mo ago
Copy link
Contents
Types of operations
Payment
Transfer
Operation performing process
GATE SCHEME
MERCHANT SCHEME
Payment methods
Operation statuses
Data types
Guaranteed notifications
Сreating customer accounts and saving cards
Process of storing card data
Saving card when paying
Saving a card with verification of the amount and automatic refund (unlock)
Recurring payments
Work principles
3D Secure
3DS 1.0
3DS 2.0
3DS Scenarios
ApplePay payments
Accepting payments in mobile applications
Accepting payments on the merchant’s website
GooglePay payments
Accepting payments in mobile applications