Click to Pay

Overview

Introduction

Click to Pay is a payment method which allows you to process payments with the use of American Express, Maestro, Mastercard, and Visa in most countries of the world and in different currencies. Using this method ensures that the payment card data is securely stored in the Click to Pay service and this data can be accessed via various desktop and mobile devices, including Android and iOS ones. Click to Pay supports processing payments in the USA and Canada, the countries of the EEA and most countries in Asia, Africa, and South America. The ecommpay payment platform supports purchases and refunds using the Click to Pay method. It provides wide availability via various desktop and mobile devices, including Android and iOS ones.

This article provides information about working with the Click to Pay method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

General information

Payment method type card payments
Payment instruments payments cards
Countries and regions most countries in the world
Payment currencies most currencies in the world
Currency conversion +
One-time purchases +
Credential-on-file purchases –
Full refunds +
Partial refunds +
Payouts –
Chargebacks +
Notes
  • Global card networks support Click to Pay in a wide range of countries, and this range is constantly growing (for more information, refer to your ecommpay account manager).
  • Whether Click to Pay is supported for customers in specific countries also depends on the card issuers in these countries (for more information, refer to your ecommpay account manager).
  • In the Payment Page user interface, Click to Pay is offered as one of the ways to make a card payment (alongside standard card payments; more information can be found below in the description of processing scenarios).
  • If the payment made with Click to Pay is declined, the customer can make another attempt to pay using standard card payments and, in case of subsequent declines, can be offered to pay with the use of other available payment methods (more information about payment retries can be found in this article).
Onboarding and access fee refer to your ecommpay account manager

Interaction diagram

Payment processing by using the Click to Pay method involves the merchant's web service, the Payment Page interface, the ecommpay payment platform, and technical facilities of the Click to Pay service.

Operations support

Processing Click to Pay payments in the payment platform involves the following interfaces: purchases can be processed by using Payment Page, refunds—by using Gate and Dashboard. Depending on the specifics of the card processing networks and issuers, various amount and time limitations can also apply.

Processing scenarios

Processing scenarios

To perform a purchase by using the Click to Pay method, you need to register the customer and their payment cards in the Click to Pay service and then execute the required steps, while to issue a refund, you need to receive a request from the customer and notify the customer about the result of the refund via the web service. In addition, the customers can be registered in the service not only during checkout but also beforehand via global card networks and issuers (learn more below).

In general, scenarios of purchases and refunds can be represented as follows.

Figure 1. Purchase by using Payment Page
Figure 2. Refund by using Gate

Specific scenarios for performing a purchase with the Click to Pay method can vary depending on what customer, with what device and what browser and with the use of which payment card intends to make a payment. There are four main user scenarios:

  • Returning user checkout (or basic purchase)—the payment is made by the customer already registered in the service. The customer utilises a previously used device, browser, and card and is authenticated via their email.
  • Returning user checkout, unrecognised device (or purchase with a new device)—the payment is made by the customer already registered in the service. The customer utilises a device or a browser that has not been used to make a payment before.
  • Returning user checkout with a new card (or purchase with a new card)—the payment is made by the customer already registered in the service. The customer utilises a card that has not been used to make a payment before.
  • First time user enrolment (or purchase by a new customer)—the payment is made by the new customer following their registration in the Click to Pay service.

One of the special aspects of processing Click to Pay purchases is the use of specialised pages that are shown in the payment form and the data for which is received directly from the Digital Card Facilitators (DCF). Digital card facilitators are global card networks that participate in the Click to Pay service and provide customers with access to digital cards.

Returning user checkout

Below is a user scenario of the basic purchase made via Payment Page.

Figure 3. Proceeding to payment
Figure 4. Opening the payment form
Figure 5. Selecting the card
Figure 6. Payment in progress notification
Figure 7. 3‑D Secure authentication
Figure 8. Redirecting to the payment form
Figure 9. Redirecting to the web service

Returning user checkout, unrecognised device

Below is a user scenario of the purchase made with a new device via Payment Page. Keep in mind that if the initial request contains the customer's phone number and email, the step with the customer's authentication in the service is skipped.

Figure 10. Proceeding to payment
Figure 11. Opening the payment form
Figure 12. Identification
Figure 13. Click to Pay authentication
Figure 14. Selecting the card
Figure 15. Payment in progress notification
Figure 16. 3‑D Secure authentication
Figure 17. Redirecting to the payment form
Figure 18. Redirecting to the web service

Returning user checkout with a new card

Below is a user scenario of the purchase made with a new card via Payment Page. Keep in mind that if the initial request contains the customer's phone number and email, the corresponding fields in the payment form are shown prefilled.

Figure 19. Proceeding to payment
Figure 20. Opening the payment form
Figure 21. Proceeding to add the card
Figure 22. Entering data
Figure 23. Card added notification
Figure 24. 3‑D Secure authentication
Figure 25. Redirecting to the payment form
Figure 26. Redirecting to the web service

First time user enrolment

Below is a user scenario of the purchase made via Payment Page by the new customer. Keep in mind that if the initial request contains the customer's phone number and email, the corresponding fields in the payment form are shown prefilled.

Figure 27. Proceeding to payment
Figure 28. Opening the payment form
Figure 29. Identification
Figure 30. Entering data
Figure 31. Registration complete notification
Figure 32. 3‑D Secure authentication
Figure 33. Redirecting to the payment form
Figure 34. Redirecting to the web service

Provisional enrolment

First time customers can be enrolled in the Click to Pay service not only during checkout (as in scenarios described above), but also beforehand:

  • Via global card networks.
    • An American Express cardholder can access their Click to Pay profile with the email that was used for creating their user account on the American Express website or in the Amex mobile application.
    • A Mastercard cardholder can enrol on the Mastercard website.
    • A Visa cardholder can enrol on the Visa website.
  • Via payment card issuers: an issuer can enrol customers by bulk pre-provisioning or can prompt customers to create a Click to Pay profile in their mobile banking application and on the website.

Purchases by using Payment Page

General information

To process a purchase through Payment Page by using the Click to Pay method, the merchant's web service is required to send a request with all required parameters and signature to the ecommpay URL and receive a callback with the result. The full sequence and special aspects of purchase processing are provided below.

Figure 35. Standard purchase processing by using Payment Page: step-by-step description
  1. A customer initiates a purchase in the web service.
  2. The web service sends the request for opening Payment Page to the specified ecommpay URL.
  3. The request for opening Payment Page is sent to the payment platform.
  4. The payment platform receives the request and validates the required parameters and signature.
  5. The payment platform requests the Click to Pay service to identify the customer.
  6. The Click to Pay service processes the request.
  7. The Click to Pay service informs the payment platform that the customer has been identified.
  8. The payment platform sends a request to Click to Pay to obtain information about the customer's cards associated with the Click to Pay account.
  9. The Click to Pay service processes the request.
  10. The Click to Pay service sends the list of available cards to the payment platform.
  11. Payment Page is generated based on the project and request parameters.
  12. The customer is shown the payment form with the list of cards associated with the customer's Click to Pay account.
  13. The customer selects the card from the list and confirms the payment.
  14. The request for processing a payment with the selected card is passed to the Click to Pay service.
  15. The Click to Pay service processes the request.
  16. Payment Page receives the data from the Click to Pay service for displaying the preloader page to the customer.
  17. The service preloader page is displayed to the customer.
  18. The Click to Pay service sends a confirmation to the payment platform that the purchase with the selected card can be processed.
  19. Payment Page receives the payment confirmation data from the payment platform.
  20. The Payment Page preloader is displayed to the customer.
  21. The payment platform processes the request and sends it to the card organisation service.
  22. The purchase is processed in the card organisation service.
  23. The card organisation service sends a notification about the result to the payment platform.
  24. The payment platform sends the payment result callback to the web service.
  25. The payment platform sends the result information to Payment Page.
  26. The result information is displayed to the customer on Payment Page.

In other user scenarios, the interaction between the customer and the Payment Page interface is the same as described above while the web service executes the same actions. In addition, if the capability of payment retries is enabled and one of the Click to Pay purchase scenarios is declined, the customer can retry the payment while using their card (standard card payments), and in case of subsequent declines, can be offered to pay with the use of other available payment methods (more information about payment retries can be found in this article).

Information about the formats of requests and callbacks used for processing payments by using the Click to Pay method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in Interaction concepts.

Request format

There are several things you need to consider when sending purchase requests by using the Click to Pay method:

  1. The following parameters required for any payment must be specified:
    • project_id—project identifier obtained from ecommpay during integration
    • payment_id—payment identifier unique within the project
    • payment_currency—payment currency code in the ISO-4217 alpha-3 format
    • payment_amount—payment amount in the smallest currency unit
    • customer_id—customer identifier unique within the project
  2. The following parameters required for any payment must be specified: project_id, payment_id, payment_currency, payment_amount, customer_id.
  3. Additionally, it is recommended that you specify the customer's country calling code, phone number, and email in parameters customer_phone_country, customer_phone, and customer_email.

    Specifying these parameters in the request makes it possible to authenticate the customer in the Click to Pay service seamlessly, without asking the customer to enter this information into custom fields of the payment form, even if the customer uses the device or the browser that has not been used previously.

    If these parameters have not been passed in the request while the customer uses a new device or a browser, then the payment form will show the corresponding custom fields to collect required information, and the authentication of the user in the service will include the step of entering the OTP code that is sent to the provided phone number or email of the customer.

    Figure 36. Example of data passed to authenticate the customer in the service
    "customer_phone_country": "44",
"customer_phone": "1172345678",
"customer_email": "test@test.com"
  4. Additionally, any other parameters available for working with Payment Page can be used (details).
  5. After all target parameters are specified, generate a signature (details).

Thus, a correct request for opening the payment form using the Click to Pay method must contain the project identifier, basic payment information (identifier, amount, and currency code), customer identifier and signature.

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
Figure 37. Example of sufficient data in a purchase request
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

At the same time, the recommended data to be included in the request for opening Payment Page should be as follows.

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "GBP",
   "customer_id": "customer1",
   "customer_phone_country": "44", 
   "customer_phone": "1172345678",
   "customer_email": "test@test.com",
   "signature": "oMg2x9dgASNAFUldOcZzUCwX6R\/ekpsdfkIFf=="
}

Callback format

The Click to Pay method uses the standard format for callbacks to deliver purchase results. For more information, see Callbacks.

The following is the example of a callback with information about a 10.00 USD purchase made by the cust123 customer in the 1204 project.

Figure 38. Example of callback data indicating that the purchase has been processed
{
        "project_id": 1204,
        "payment": {
            "id": "Payment_15671726468667687",
            "type": "purchase",
            "status": "success",
            "date": "2024-08-30T13:58:12+0000",
            "method": "etoken-click2pay",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": "Purchase"
        },
        "customer": {
            "id": "cust123"
        },
        "account": {
            "number": "518600******8785"
        },
        "operation": {
            "id": 47478000001698,
            "type": "sale",
            "status": "success",
            "date": "2024-08-30T13:58:12+0000",
            "created_date": "2024-08-30T13:58:06+0000",
            "request_id": "0a5cb476be3a55010fb050ec1c1cbd35361ac912a3",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "provider": {
                "id": 120461,
                "payment_id": "24fb3f30-000f-5000-8000-1c329d900c68",
                "date": "2024-08-30T13:58:09+0000",
                "auth_code": "591748"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "5DtWEGy+dMGZZnm3Owjgw9ly67Mb9siv7+WD1u7AyIYdQ=="
}

The following is the example of a callback with information about a declined purchase.

Figure 39. Example of callback data indicating that the purchase has been declined
{
        "account": {
            "number": "518600******8785"
        },
        "customer": {
            "id": "cust123"
        },
        "payment": {
            "date": "2024-08-06T12:57:03+0000",
            "id": "10906183900",
            "method": "etoken-click2pay",
            "status": "decline",
            "sum": {
                "amount": 1030000,
                "currency": "USD"
            },
            "type": "purchase",
            "description": "test"
        },
        "project_id": 312,
        "country": "GB",
        "operation": {
            "id": 45047000000055,
            "type": "sale",
            "status": "decline",
            "date": "2024-08-06T12:57:03+0000",
            "created_date": "2024-08-06T12:57:00+0000",
            "request_id": "f92c3dfdf76133d5e1a9d26279b3b77b7da32e",
            "sum": {
                "amount": 1030000,
                "currency": "USD"
            },
            "provider": {
                "id": 120461,
                "payment_id": "5cb2f2fb-e4df-4807-8839-067f9366d506",
                "auth_code": ""
            },
            "code": "10105",
            "message": "Insufficient funds on card"
        },
        "signature": "9CIXvWMsKOcQsWEHKLsSVSRo8YNjIxHPjEEQSmLAtClQ=="
}

Useful links

The following articles can be useful when implementing purchases via Payment Page:

Refunds by using Gate

General information

To perform a refund through Gate by using the Click to Pay method, send a request with all required parameters and signature to the ecommpay URL and receive a callback with the result. The full sequence and special aspects of refund performing are provided below.

Figure 40. Refund performing by using Gate: step-by-step description
  1. A customer initiates a refund.
  2. The web service sends the request for performing the refund by using Gate to the specified ecommpay URL.
  3. The payment platform receives the request.
  4. The payment platform validates the required parameters and signature in the request.
  5. The payment platform sends the response to the web service with information about the receipt of the request and its validity (details).
  6. The payment platform performs further processing of the request (with parameter consistency check) and sends it to the card organisation service.
  7. The refund is processed on the side of the card organisation service.
  8. The card organisation service sends the result notification to the payment platform.
  9. The payment platform processes the result notification and informs the Click to Pay service about the result, following which the payment platform sends the result callback to the web service.
  10. The customer receives the refund result information from the web service.

Information about the formats of requests and callbacks used for performing refunds by using the Click to Pay method via Gate is presented further in this section. General information about working with the Gate API is presented in Interaction concepts.

Request format

There are several things you need to consider when sending refund requests by using the Click to Pay method:

  1. To initiate each refund, send a separate POST request to the /v2/payment/refund endpoint.
  2. Each request must include the following objects and parameters:
    • Object general—general refund information:
      • project_id—project identifier obtained from ecommpay during integration
      • payment_id—identifier of the payment that needs to be refundedpayment identifier
      • signature—request signature generated after all required parameters are specified (details—in the Signature generation and verification)
    • Object payment—refund information:
      • description—refund description or comment
      • amount—refund amount in the smallest currency unit (required for a partial refund)
      • currency—refund currency code in the ISO-4217 alpha-3 format (required for a partial refund)
    • Object customer—customer information:
      • ip_address—customer IP address relevant for the initiated refund
  3. Additionally, any other parameters included in the specification can be used.

Thus, a correct refund request by using the Click to Pay method must contain the project and payment identifiers, description of the refund, the customer IP address, signature, and, if necessary, currency code and refund amount.

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}
Figure 41. Example of sufficient data in a refund request
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}

Callback format

The Click to Pay method uses the standard format for callbacks to deliver refund results. For more information, see Callbacks.

The following is the example of a callback with information about a 10.00 USD refund made for the cust123 customer in the 424242 project.

Figure 42. Example of callback data indicating that the refund has been processed
{
        "project_id": 424242,
        "payment": {
            "id": "payment_15792507735",
            "type": "purchase",
            "status": "refunded",
            "date": "2024-01-20T08:31:36+0000",
            "method": "etoken-click2pay",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": "purchase"
        },
        "customer": {
            "id": "cust123"
        },
        "account": {
            "number": "518600******8785"
        },
        "operation": {
            "id": 69512000019571,
            "type": "refund",
            "status": "success",
            "date": "2024-01-20T08:31:36+0000",
            "created_date": "2024-01-20T08:31:35+0000",
            "request_id": "e0069513",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 120461,
                "payment_id": "0000438583",
                "auth_code": ""
                }
            },
        "signature": "beJ1deUiEDd+7zuo6YrfSRzgEQj34sKAStuW8Fg=="
    }

The following is the example of a callback with information about a declined refund.

Figure 43. Example of callback data indicating that the refund has been declined
{
        "project_id": 424242,
        "payment": {
            "id": "Payment_1579250773501",
            "type": "purchase",
            "status": "success",
            "date": "2024-01-20T08:31:36+0000",
            "method": "etoken-click2pay",
            "sum": {
                "amount": 100,
                "currency": "USD"
            },
            "description": ""
        },
        "customer": {
            "id": "cust123"
        },
        "account": {
            "number": "518600******8785"
        },
        "operation": {
            "sum": {
                "amount": 100000,
                "currency": "USD"
            },
            "code": "3283",
            "message": "Refund amount more than init amount",
            "provider": {
                "id": 120461,
                "payment_id": "0000438582",
                "auth_code": ""
            },
            "id": 69512000019571,
            "type": "refund",
            "status": "decline",
            "date": "2024-01-20T08:31:36+0000",
            "created_date": "2024-01-20T08:31:35+0000",
            "request_id": "e0069142"
        },
        "signature": "beJ1deUiEDd+7zuooJzgEQj34sKAStuW8Fg=="
    }
}

Useful links

The following articles can be useful when implementing refunds via Gate:

Refunds by using Dashboard

When working with Dashboard, you can perform single and mass refunds by using the Click to Pay method.

  • To perform a single refund, select the target purchase, open its information tab, specify the amount of the refund, send a request and verify that the refund has been performed.

  • To perform a mass refund, prepare and upload a file with information about all target refunds, send a batch request, and verify that the refunds have been performed.

    Use a CSV file structured according to the requirements presented in the Mass payments data section. The refund parameters must comply with the requirements (you do not have to generate a signature because it is specified by Dashboard).

More information Information about performing refunds by using Dashboard is presented in a separate section.

Analysis of payments results

To analyse information about payments made with the Click to Pay method and other methods, you can use:

  • Dashboard interface toolkit with various lists and analytic panels.
  • Reports in CSV file format, available via the Reports section (one-time and periodically).
  • Data in JSON format, sent by program requests to a specified URL available by using the Data API interface.

If you have any questions, refer to the documentation (Dashboard and Using Data API) and ecommpay technical support.