Cascade payment processing

Overview

Payments could sometimes fail due to different reasons. For example, while a payment is being processed by a provider or a bank, technical issues may occur, or processing of the payment may take too long, or a customer's card limit may have been reached.

The ecommpay payment platform supports cascade payment processing that includes additional attempts to process a payment if your initial attempt to process the payment was unsuccessful. In any of the above cases, the cascading option enabled allows the payment that cannot be processed properly by a provider to be rerouted to an alternative provider with no change of the payment method. In card payments, you can use the cascading option for both one-step and two-step purchases with authentication by using 3‑D Secure as well as without authentication.

In card payments, a customer may be charged only once for the same payment, that's why it is the payment platform which is required to initiate new additional attempts to process the payment.

Using the cascading option doesn't require to update the merchant web service because workflows of cascade payment processing and regular payment processing are the same for the merchant web service. The following section discusses in more details the workflow of cascade payment processing.

Setup and configuration

To implement the cascading option in your web service you need to contact your ecommpay key account manager and discuss the possibility of implementing the option, and then test and deploy cascade payment processing with the ecommpay technical support.

Workflow

Payments with the enabled cascading option are initiated in the same way as regular payments. Your web service is required to send a request for purchase to initiate an attempt to process the payment by using Payment Page. When the payment platform accepts the request, Payment Page is displaying to a customer for entering card details. The payment platform processes the initial attempt to process the payment, and in addition the 3‑D Secure authentication may be required. If the customer is charged for this attempt, the payment platform sends a callback with the payment results and the success payment status. If the customer isn't charged for the initial attempt, the payment platform keeps processing the payment that may contain one or more additional attempts to process it.

Until the customer is charged for one of processed additional attempts before the limit on the number of allowed attempts has been reached, the payment platform initiates a new additional attempt. If the new additional attempt doesn't require 3‑D Secure authentication, there is no need any customer and web service involvement. If the 3‑D Secure authentication is required, Payment Page displays a page with customer card detailes, information about unsuccessfull attempt and Retry button. If the customer confirms one more additional attempt to process the payment, the payment platform keeps processing the new additional attempt with new 3‑D Secure authentication. The payment status is set to one of following ones: awaiting_3ds_result, awaiting_redirect_result or processing.

Payment processing with the enabled cascading option is completed in the same way as regular payment processing. The payment platform sends a callback with the success payment status, if the customer has been charged for one of processed additional attempts. The payment status is set to decline, if the customer hasn't been charged for one of processed additional attempts before the limit on the number of allowed attempts has been reached.

The following diagram provides the detailed picture of a one-step purchase processing with the cascade option enabled and 3‑D Secure authentication included.

* ecommpay may function as a provider.

Callback format

In card payments, payment processing with enabled cascading option uses the standard format for callbacks with payment results. For more information, see Callbacks.

Overview

In payments by using alternative payment methods, payment processing usually requires a customer to complete the payment on a provider service. But while processing payment on a provider service, two types of factors influence the payment results: subjective one (customer influence) and objective one (no customer influence). For example, factors that payment processing may be interrupted by include:

• Customer influence

  Basically, it happens after a customer has been redirected to a provider service in a separate window. The customer may close the window by accident or on purpose based on subjective evaluation or personal experience about payment processing on the provider service. For example, the customer doesn't trust the provider service and is afraid of entering account details, or the customer misunderstands the flow of payment completing on the provider service, or a form for entering data requires page refresh to load properly, or any other factors affect customer subjective evaluation.

• No customer influence

  Basically, it happens because of technical issues occurred on a merchant web service side (for example customer redirection has been failed) or on a provider side, for example if OTP limit count has been reached, or a customer can't use OTP, or a provider service is temporarily unavailable, or internet connection was interrupted, or any other factors result technical issues.

For these cases the ecommpay payment platform supports cascade payment processing that includes additional attempts to process a payment if your initial attempt to process the payment was unsuccessful. In any of the above cases, the cascading option enabled allows a payment that cannot be processed properly by a provider to be rerouted to an alternative provider with no change of payment method. In payments by using alternative payment methods, you can use the cascading option only for one-step purchases.

In payments by using alternative payment methods, a customer may be charged more than once for the same payment, and that's why it is the customer who is required to initiate new additional attempts to process the payment. Until the customer confirms initiating a new additional attempt, the payment platform does nothing for a new attempt. Multiple charges for one purchase usually result from a combination of factors (the section Example of cascade payment processing shows an example of a combination of these factors). For example, common factors include:

• A poor internet connection that any participant of payment processing may experience.
• Incorrect customer opinions about issues caused while processing payment.
• A lack of information about payment results. For example, a customer hasn’t received payment notifications from a bank, or a provider hasn't sent any payment results to the payment platform because technical issues occurred, or payment notifications may be turned off, or any other reasons. And other factors that result the multiple charges for one purchase.

To support the cascading option it is recommended to update the merchant web service because the workflow of cascade payment processing includes additional steps that are not included in the workflow of regular payment processing. The following section discusses in more details the workflow of cascade payment processing and how to integrate the option in your web service.

Setup and configuration

To integrate and enable cascading option in your web service you need to do the following:

1. Address the organisational interaction issue with ecommpay.
   • Contact your ecommpay key account manager and discuss the possibility of implementing the option, as well as discuss what you should do if a customer is charged more than once for the same payment.
   • Select payment methods that supports payment processing with the cascading option.

     For more information, see payment methods that are described in Methods or contact your ecommpay key account manager.

   • If needed, contact your ecommpay key account manager and discuss updates on the default text of notification that is displayed to ask a customer to confirm a new additional attempt. The default is "Should you experience any problems to finish payment, you may try to pay again. Note that banking delays are possible. To avoid double charging, first check your bank account history to make sure funds haven't been debited already." It's recommended to inform a customer that the customer may be charged more than once. In the example that is supplied with illustrations you can see the notification.
2. Update your web service to support the cascading option.
   • Update your web service to support payment processing with the cascading option.

     The payment platform may send a callback with payment results within the same payment more than once because the payment platform sends these callbacks for each attempt to process the payment when a customer is charged. That's why the time period for accepting callbacks shouldn’t expiry when the merchant web service accepts the first callback and may takes several days to get the final callback.

   • Note, the enabled cascading option affects the payment status model.

     The payment platform keeps the payment in the processing status, an intermediate one, until the payment platform gets payment results of all attempts from all providers involved in processing. If the payment platform gets payment results of all attempts, the payment status is set to decline or success, a final status. In the example below you can see this case.

   • Support payouts for payment methods that support ones. You may send request for payout in case of a customer is charged more than once for the same payment.
3. Test and deploy cascade payment processing with the ecommpay technical support.

Workflow

Payments with the enabled cascading option are initiated in the same way as regular payments. Your web service is required to send a request for opening Payment Page. The payment platform accepts the request, and then Payment Page is displaying for a customer to choose a payment method and to confirm the payment, and the customer is redirecting to the provider service where the customer has to complete the payment. If payment processing doesn't take longer time than usual and the customer is charged for the initial attempt, payment processing with the enabled cascading option is completed in the same way as regular payment processing: the payment platform sends a callback with payment results and the success payment status. If the customer isn't charged for the initial attempt, the payment platform keeps processing the payment that may contain one or more additional attempts to process it.

Until the customer is charged for one of processed additional attempts before the limit on the number of allowed attempts has been reached, the customer may initiate a new additional attempt to process the payment.

Note that unlike regular payment processing, payment processing with the enabled payment option is completed in another way: the payment platform may send a callback with payment results more than once for the same payment. It is because the payment platform sends a final callback for each attempt to process the payment that has been processed successfully. Some providers may take a long time to process the request and to send results to the payment platform that's why the time period for accepting callbacks shouldn’t expiry when the merchant web service accepts the first callback, it may takes several days to get the final callback. If the customer is charged more than once, it's recommended to make a refund.

The following diagram provides the detailed picture of payment processing with the enabled cascading option in one the Banks of South-East Asia method, and in this diagram technical issues on a provider side are the reason why the payment can be declined.

Callback format

In the ecommpay payment platform, each attempt to process a payment within the payment is a separate operation, and the payment platform provides specific operation_id for each operation, meanwhile payment_id is the same for all of operations defined in the payment. Thus, callbacks may include information about both the payment and a separate operation.

In payments by using alternative payment methods, payment processing with the enabled cascading option uses the standard formats for both intermediate and final callbacks that is described in Callbacks, and the information about each payment method that is described in Methods includes examples of these callbacks. Parameters the payment platform sends in callbacks depends on a payment method and an involved provider.

The following section covers examples of a final callback.

Example of cascade payment processing

Overview

The following example should help you figure out how cascade payment processing works: what goes on the payment platform side, and what a customer may do while payment processing.

The example is structured in such a way that it represents a timeline which begins at the top and descends gradually to mark the sequence of interactions. Each interaction between a customer and a Payment Page has an illustration, and callbacks with payment results the payment platform sends to a merchant's web service are represented by code examples. Since final callbacks have different format, unlike in regular payment processing, comments used in the code examples indicate differences.

In this example, a customer has chosen the Banks of Malaysia payment method and initiated three attempts to process the purchase. Two of these attempts has been processed successfully and the customer has been charged twice.

The initial attempt to process the purchase

While processing the initial attempt, on Payment Page the customer chooses the Hong Leong Bank, a malaysian bank, is redirected to a provider service in a separate browser window, closes the window (for example, the customer doesn't trust this provider service), and confirms initiating a new additional attempt to process the purchase. Within the initial attempt, cascade payment processing includes:

1. Initiating the purchase

   The customer confirms the purchase, and then the web service sends the request to open Payment Page. On Payment Page the customer selects the payment method and chooses the bank and confirms the payment.

   
   
   

   
   
   

   
   
   

2. Customer redirecting

   The Payment Page redirects the customer to the provider service in a separate browser window. In this example, the customer doesn't confirm the purchase, closes the window, and is back to the Payment Page.

   
   
   

3. Getting confirmation to initiate a new additional attempt to process the purchase

   In this example, since the payment platform doesn't receive a callback with payment results, Payment Page displays notification that asks the customer to initiate a new additional attempt. Then the customer clicks the Retry button to confirm a new attempt.

   
   
   

The second attempt to process the purchase

Unlike in the initial attempt, the alternative provider is involved in processing this attempt. This provider requires to gather additional information about the customer and update the list of banks that includes Standard Chartered Bank the customer selects on Payment Page. Since the provider takes longer to process the attempt, the customer doesn't wait for a long time and closes the window. Then the customer is back to Payment Page and confirms the third attempt to process the purchase. While processing the next third attempt, the payment platform still doesn't get payment results of this second attempt from the provider. Within this second attempt, on the customer side cascade purchase processing includes:

1. Choosing a bank

   The customer chooses the bank from the updated list of banks on Payment Page.

   
   
   

2. Gathering additional payment information

   On Payment Page the customer submits required information and confirms the payment. For more information about the procedure, see Submission of additional payment information.

   
   
   

   
   
   

3. Customer redirecting

   Payment Page redirects the customer to the current provider service in a separate browser window. In this example, the customer confirm the purchase, doesn't wait for until the current provider process the attempt, closes the window, and is back to Payment Page.

   
   
   

   
   
   

4. Getting confirmation to initiate a new additional attempt to process the purchase

   In this example, since the payment platform doesn't receive a callback with payment results, Payment Page displays notification that asks the customer to initiate a new additional attempt. Then the customer clicks the Retry button to confirm a new attempt.

   
   
   

The third attempt to process the purchase

Unlike in the previous attempts, another alternative provider is involved in processing this attempt. This provider also requires to update the list of banks that includes Hong Leong Bank the customer selects again on Payment Page. The customer gets payment results on the provider service and then is back to Payment Page. Within this third attempt, on the customer side cascade purchase processing includes:

1. Choosing a bank

   The customer chooses the bank from the updated list of banks on Payment Page.

   
   
   

2. Customer redirecting

   Payment Page redirects the customer to the provider service in a separate browser window. In this example, the customer confirms the purchase, gets the payment results, closes the window, and is back to Payment Page.

   
   
   

   
   
   

   Processing the payment results

   The payment platform sends a callback with final payment status for each attempt that has been processed successfully.

   In this example, since the third attempt to process the purchase doesn't take more time than usual and a customer is charged for this attempt, the payment platform sends the callback with the payment results on time, and then the results is displayed to a customer on Payment Page. Then, for example, several hours later, when the provider that involved into the second attempt completed payment processing successfully and sends the payment results to the payment platform, the payment platform sends the callback with the payment results again. But unlike in the last callback, the payment amount includes total amount of both attempts that the customer has been charged for. In this case it's recommended to make a refund, if needed.

   On the merchant web service side processing the payment results includes:

1. Receiving the callback with payment results for the third attempt

   The payment platform sends the callback with the successful payment results. Since the payment platform still doesn't get the results of the second attempt from the provider involved in processing this attempt, the payment platform keeps the payment in the processing status, an intermediate one, but the attempt (operation) status is success, the final one. The payment results is also displayed to the customer on Payment Page.

   
   
   

   {
           "customer": {
               "id": "653"
           },
           "project_id": 200,
           "payment": { // payment(purchase) information
               "payment_id": "cosmo_set_4589", // payment identifier, the same for all attempts
               "type": "purchase",
               "status": "processing", // payment status
               "date": "2020-07-20T04:37:57+0000",
               "method": "Malaysian banks",
               "sum": {
                   "amount": 131970, // payment amount includes amount of only one charge
                   "currency": "MYR"
               },
               "description": "Astronaut set" 
           },
           "operation": { // operation information (attempt to process the purchase) 
               "id": 003, // operation identifier defined in the payment platform            
               "type": "sale",
               "status": "success",
               "date": "2020-07-20T04:37:57+0000",
               "created_date": "2020-07-20T04:36:45+0000",
               "request_id": "cosmo_set_4589_request3", // the request identifier the payment platform sends in response 
                                                        // for the request for purchase (for the third attempt)
               "sum_initial": {
                   "amount": 131970, // amount for the third attempt
                   "currency": "MYR"
               },
               "sum_converted": {
                   "amount": 131970,
                   "currency": "MYR"
               },
               "code": "0",
               "message": "Success",
               "provider": { // information about provider involved in processing the thirst attempt
                   "id": 1256,
                   "payment_id": "064604207", // payment identifier defined on a provider side
                   "auth_code": "",
                   "date": "2020-07-20T04:36:51+0000"
               }
           },
           "signature": "n3zmkj5yG..."
       }

2. Receiving the callback with payment results for the second attempt

   Several hours later the payment platform sends the callback with the payment results again. Since the payment platform gets the payment results of all attempts to process the payment from all providers involved in the processing and the customer has been charged for at least one of the attempts, the payment status is set to success, the final one, while the payment amount includes total amount of both attempts that the customer has been charged for.

   {
           "customer": {
               "id": "653"
           },
           "project_id": 200,
           "payment": { // payment(purchase) information
               "payment_id": "cosmo_set_4589", // payment identifier, the same for all attempts
               "type": "purchase",
               "status": "success",// payment status
               "date": "2020-07-20T07:12:04+0000",
               "method": "Malaysian banks",
               "sum": {
                   "amount": 263940, // payment amount includes total amount of double charges
                   "currency": "MYR"
               },
               "description": "Astronaut set"
           },
           "operation":{ // operation information (attempt to process the purchase) 
               "id": 002, // operation identifier defined in the payment platform                  
               "type": "sale",
               "status": "success",
               "date": "2020-07-20T07:12:04+0000",
               "created_date": "2020-07-20T04:33:37+0000",
               "request_id": "cosmo_set_4589_request2", // the request identifier the payment platform sends in response 
                                                        // for the request for purchase (for the second attempt)
               "sum_initial": {
                   "amount": 131970, // amount for the second attempt
                   "currency": "MYR"
               },
               "sum_converted": {
                   "amount": 131970,
                   "currency": "MYR"
               },
               "code": "0",
               "message": "Success",
               "provider": { // information about provider involved in processing the thirs attempt
                   "id": 1589,
                   "payment_id": "0757821", // identifier of payment defined on a provider side
                   "auth_code": "",
                   "date": "2020-07-20T07:11:48+0000"
               }
           },
           "signature": "bYNjg..."
       }