Options for redirecting customers to the web service

Overview

After the payment form opens, different variants of customer redirection to the web service can be relevant. Within the work with Payment Page, there are three such variants:

Within the work with Payment Page different variants of customer redirection to the web service can be relevant:

preliminary redirection from the payment form—when the customer needs to return to the web service before confirming the payment in the payment form; then the customer can go back to the form to continue working with it;
intermediate redirection from third-party services—when the customer needs to return to the web service after confirming the payment in the payment form and being redirected to a third-party service, without completing the required actions in that service;
final redirection—when the customer needs to return to the web service after performing all actions required for payment processing.

The merchant can provide customers with various capabilities for redirection (using only the necessary variants or none of them) and combine them with the payment form customised design (details) and with different options for opening web service pages when redirection to the web service is performed. This provides flexibility in adjusting to the nature of the business and various payment scenarios.

Redirection options

Preliminary redirection from the payment form

Overview

Customer preliminary redirection to the web service from the payment form pages is performed with the use of a link which is set up in the parameters of opening the form and is displayed as an additional element of the form.

If during Payment Page opening the capability of customer preliminary redirection from the payment form is set up, then the following options are applied for redirection by default:

If Payment Page opens in a separate browser tab, redirection is performed in the same tab.
If Payment Page opens in a modal window, this modal window closes.
If Payment Page opens in an iframe object, redirection is not performed, at the same time, interface events handling is available on the web service side (details).

In case if other redirection options are required, the corresponding parameters can be used on the web service side. These parameters are described in the section Managing redirection availability and options of this article.

When using the capability of redirecting customers from the payment form pages, also consider the following aspects:

The customer can return to the web service using the displayed link only before they confirm the payment in the payment form (by choosing a method and specifying the required information). After payment confirmation, the link is not displayed in the form, since the payment is then processed in the platform and the chosen payment system, and this payment processing can require customer's involvement.
If the time of working with the payment form is limited (details), the countdown begins from the initial opening of the form and does not stop in case of redirection to the web service.

Request format

The URL for customer preliminary redirection from the payment form pages to the web service is specified in the requests for opening Payment Page as the value of the merchant_return_url parameter

Figure: Example of data from a request for opening Payment Page

{
   "project_id": 42,
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": 131970,
   "customer_id": "customer_12",
    
   // URL for preliminary redirection
   "merchant_return_url": "https://example.com", 

   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."
}

Intermediate redirection from third-party services

Overview

Customer redirection to the web service from the pages of third-party services, such as banks or payment systems, is possible only when this redirection is supported by these services. Besides, such functionality can be implemented differently, depending on a service, and sometimes can include only one-way redirection (that is, not providing customer's return to the third-party service page). Considering these aspects and the potential negative impact they may have on payment acceptance, the implementation of customer redirection from the pages of third-party services should be discussed and coordinated with the ecommpay account manager.

Customer redirection to the web service from the pages of third-party services is possible only when this redirection is supported by these services. The implementation of customer redirection from the pages of third-party services should be discussed and coordinated with the ecommpay account manager.

The URLs for intermediate customer redirection can be specified in the requests for opening Payment Page after the capability has been coordinated and set up. Otherwise, the URLs are ignored.

Request format

The URL for redirecting customers to the web service from the pages of third-party services is specified in the requests for opening Payment Page as the value of the redirect_return_url parameter.

Figure: Example of data from a request for opening Payment Page

{
   "project_id": 42,
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": 131970,
   "customer_id": "customer_12",

   // URL for intermediate redirection
   "redirect_return_url": "https://your/bank/example.com",

   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."
}

Final redirection

Overview

During the work with Payment Page, final customer redirection to the web service—after payment processing—can be performed by the customer's decision, when the customer clicks the corresponding button on the final page of the payment form, and automatically, without the final page used and with the purchase result information displayed on the web service side. With automatic redirection, the capability of purchase retry attempts (details) cannot be provided to the customer. If you do not need to redirect the customer after payment processing, you can display the final page of the payment form without the button for redirection to the web service.

Figure: Final redirection performed by the customer's decision

Figure: Final redirection performed automatically

Figure: Payment confirmation process without final redirection available

The URLs and options for final customer redirection after payment processing can be specified for all payments within the project in general and individually for separate payments. General URLs and options should be specified via the Dashboard interface (and the tools in the Redirect URLs tab of the Projects section), individual URLs and options should be specified via the parameters of the requests for opening Payment Page (these parameters are described further, in the Request format paragraph of this section and in the Managing redirection availability and options section of this article).

The URLs and options for final customer redirection after payment processing can be specified for all payments within the project in general (via Dashboard) and individually for separate payments (via the parameters of requests for Payment Page opening that are described further).

With final redirection set up, the following redirection options are applied by default:

Redirection by the customer's decision is performed in the current browser tab, and if the payment form has been opened in a modal window, this window closes.
Automatic redirection is performed in the same interface element in which the payment form has been opened. That is, if the form has been opened in a separate browser tab, the redirection is performed in this tab, and if the form has been opened in a modal window or in an iframe object, the redirection is performed in this window or object.

Request format

For redirection by the customer's decision, the URLs can be specified as the values of the following parameters:

merchant_success_url—for customer redirection after the purchase has been completed,
merchant_fail_url—for customer redirection after the purchase has been declined.

Figure: Example of data from a request for opening Payment Page

{
   "project_id": 42,
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": 131970,
   "customer_id": "customer_12",

   // URLs for final customer redirection performed by customer's decision
   "merchant_success_url": "https://example.com/complete-redirect?id=success", 
   "merchant_fail_url": "https://example.com/complete-redirect?id=decline", 
   
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."

For automatic redirection, the URLs can be specified as the values of the following parameters:

redirect_success_url—for customer redirection after the purchase has been completed,
redirect_fail_url—for customer redirection after the purchase has been declined,
redirect_tokenize_url—for customer redirection after the payment data token has been generated in the card_tokenize mode (details).

Figure: Example of data from a request for opening Payment Page

{
   "project_id": 42,
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": "131970",
   "customer_id": "customer_12",

   // URLs for final customer redirection performed automatically
   "redirect_success_url": "https://example.com/complete-redirect?id=success", 
   "redirect_fail_url": "https://example.com/complete-redirect?id=decline", 
   
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."

Managing redirection availability and options

When preliminary and final customer redirections from the payment form to the web service are set up, you can manage the availability and options of these redirections for separate Payment Page openings. For this, the parameters of the enabled and mode groups are used.

Figure: Parameters of the enabled group for managing redirection availability

merchant_return_enabled—the availability of preliminary redirection from the payment form pages,
merchant_success_enabled—the availability of final redirection after the purchase has been completed,
merchant_fail_enabled—the availability of final redirection after the purchase has been declined.

For each of these parameters, the following values can be used:

0—redirection is unavailable.
1—redirection is partially available; that is, if Payment Page is opened in an iframe object or a modal window, the customer is not redirected to the web service, and if Payment Page is opened in a separate browser tab, the option of opening the web service page is identified via the parameter of the mode group.
2—redirection is available, used by default, and compatible with the option of opening the web service page specified in the parameter of the mode group.

Figure: Parameters of the mode group for managing redirection options

merchant_return_redirect_mode—the option for preliminary redirection from the payment form pages,
merchant_success_redirect_mode—the option for final redirection performed by the customer's decision after the purchase has been completed,
merchant_fail_redirect_mode—the option for final redirection performed by the customer's decision when the purchase has been declined,
redirect_success_mode—the option for final redirection performed automatically after the purchase has been completed,
redirect_fail_mode—the option for final redirection performed automatically after the purchase has been declined.

For each of these parameters, the following values can be used:

iframe—the page opens in an iframe object (this works if the payment form is opened in an iframe object or a modal window; if the payment form is opened in a separate browser tab, the page opens in the same tab).
parent_page—the page opens in the currently used tab.
blank_page—the page opens in a new tab.

The following examples contain the data from the requests for opening Payment Page according to which the customer redirection to the web service should be performed in different ways.

Figure: Opening the web service page in a new tab

{
   "project_id": 42,
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": 131970,
   "customer_id": "customer_12",

// URL of the web service page
   "merchant_success_url": "https://example.com/complete-redirect?id=success", 
   "merchant_success_redirect_mode": "blank_page",    // page opening option
   "merchant_success_enabled": 2,    // redirection availability
   
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."

Figure: Opening the web service page in the current tab

{
   "project_id": 42,
   "payment_id": "456789",
   "payment_currency": "USD",
   "payment_amount": 131970,
   "customer_id": "customer_12",

// URL of the web service page
   "merchant_success_url": "https://example.com/complete-redirect?id=success", 
   "merchant_success_redirect_mode": "parent_page",    //  page opening option
   "merchant_success_enabled": 1,    // redirection availability
   
   "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..."

The questions about working with these parameters as well as any other questions about the options for customer redirection to the web service can be directed to the ecommpay technical support specialists.