Payment retries

Overview

When making payments using Payment Page, customers usually need one attempt to complete the payment, but sometimes they have to repeat the procedure—for example, when there are insufficient funds on the payment card the customer is using to make the purchase. In such cases, the ecommpay payment platform provides the capability of retry attempts to make one payment (a payment with the same identifier) during a single session on Payment Page.

During the work with Payment Page, the procedure of retrying a payment within a single session is supported. Under this procedure, if the payment fails, the customer can attempt this payment again. The number of attempts as well as the time allocated for executing these attempts are coordinated with the technical support specialists during the capability setup.

Generally, if the payment has been declined, the final page of the payment form with an error message is displayed to the customer. In this case, without the functionality of payment retries, the Payment Page session is completed, and, to repeat the attempt, the customer has to go back to the web service to initiate a new payment. With the capability of retry attempts set up, if the payment fails, it can be attempted again within a single session; in this case, the error message and the button for retrying the payment are displayed on the final page of the payment form.

For retrying a payment, an additional button is displayed on the final page of the payment form. Upon clicking this button, the customer is redirected to the initial page of the current payment form session. Keep in mind that the parameters specified in the request for opening Payment Page remain unchanged for all subsequent attempts. For example, if a payment method has been preselected, all attempts are performed with the use of this payment method. Similarly, if you provide a payment card token in a payment request, all attempts for this payment are possible only with the use of this token. Without such parameters passed in the request, the customer can choose any of the available methods to make additional payment attempts.

Note: Cookies are required for the emulator to function properly. The emulator will not load without cookies.

Since all retry attempts are made within a single Payment Page session, the parameters specified in the request for opening Payment Page remain unchanged for all subsequent attempts. This also applies to cases when payment methods or method groups are preselected.

Overall, when the payment retries functionality is used, the options of payment method selection are determined as follows.

Preselected payment method or method group First attempt Each retry attempt
–

(none)

 any payment method available depending on the action performed during the first attempt:
  • processing a purchase—any of the payment methods available for making a purchase
  • placing an authorisation hold—any of the payment methods available for performing an auth operation
card payments card payments card payments or (if agreed upon and set up) Apple Pay or Google Pay
alternative payment method

(group of methods)

 specified method

(group of methods)

 specified method

(group of methods)
Note: Keep in mind the following considerations for payment method selection when using the functionality:
  • If the payment method has not been preselected, should the customer decide to retry the payment, they can choose one of the payment methods that support the type of the operation performed during the first attempt. For example, if the first attempt involved placing an authorisation hold as part of performing a two-step purchase (auth), then for every subsequent attempt the customer can select the method for which two-step purchases are supported, so that the authorisation hold is performed instead of the withdrawal of funds (sale).
  • If card payments are preselected and such option has been set up for the project, the customer can choose to retry the payment not only with the card but also with Apple Pay or Google Pay. This option is set up separately, upon agreement with your ecommpay account manager.
  • If you specify one of the alternative payment methods in a payment request, all subsequent retry attempts are performed with the use of this method. Another payment method cannot be selected.
  • If you provide a payment card token in a payment request, all subsequent retry attempts are performed with the use of this token. Another payment method or payment instrument cannot be selected.

The number of attempts and the time allocated for executing these attempts are limited. These restrictions can be configured upon coordination with your account manager and apply to all payments within a project for which the functionality of payment retries is set up.

Usage scenario

The following steps present the customer procedure of making a purchase with the capability of retry attempts:

  1. The customer confirms the purchase in the merchant web service.
  2. The customer is redirected to Payment Page which is generated according to the parameters specified in the request for opening Payment Page. The customer, performs the required actions and waits for the purchase result.
  3. After the purchase has failed, the final page of the payment form with the button for retrying the payment is displayed to the customer. Upon clicking the button, the customer is redirected to step 2.
  4. After the payment has been completed, the information is displayed on the standard final page of the payment form (without the button for retrying the payment).

Special aspects

If you want to set up the functionality of payment retries, consider the following aspects:

  • The requirement to display the final page of the payment form. With the functionality of payment retries, the final page with the payment result must be displayed to the customer. If automatic customer redirection to the web service is set up, the customer cannot retry the payment. For more information, see Options for redirecting customers to the web service. The retry attempts are initiated by the customer on the final page of the payment form. This is why for working with this capability, it is important not to use automatic customer redirection to the web service.
  • Support for Payment Page customisation. If the payment form design is implemented on the basis of another interface model (not the basic one), coordinate with the ecommpay account manager the implementation of an additional element on the payment form—the button for redirecting the customer to a payment attempt—and, if necessary, provide the corresponding template layout to the technical support specialists.
  • The time limit for repeating payment attempts. The countdown for all retry attempts begins at the moment when the payment failure is registered in the payment platform for the first time. In this case, the timer is not displayed on Payment Page. However, if there is a time limit for making this payment via Payment Page (details), the customer can see the timer counting down the amount of time allowed for this payment. At this point, the time restriction on the payment attempts is ignored. In any of the above cases, if there have been no successful retry attempts over the time allocated for using Payment Page, the payment is declined, and the final page with the corresponding notification is displayed on the payment form.

Setup

To have the capability of retry attempts set up, merchants should complete the following steps:

  1. Coordinate the process with your ecommpay account manager: discuss the setup procedure and whether it is necessary to test the functionality. Also consider the restrictions on the number of attempts and the time allocated for making the attempts. These limits apply to all payments within the project and can be configured by the ecommpay specialists according to the needs of merchants. Usually, such restrictions are set to 5 attempts that must be performed within 10 minutes.
  2. If it was agreed that testing is required, wait to be notified by the ecommpay specialists when the functionality is ready, then test the payment form workflow with the new capability. After that inform the account manager that you are ready to launch the functionality in your production environment.
  3. Receive the notification from the ecommpay specialists about the completion of the capability setup.

Workflow

The following diagram illustrates the payment retries workflow:

Figure 1. The steps of the purchase retry procedure
  1. If the purchase has not been completed with the debiting of funds or authorisation hold, it is checked if retry attempts are available for making the purchase within the project.
  2. An intermediate callback with the information about the capability is sent from the payment platform to the web service.
  3. The information about the availability of payment retries is transmitted from the payment platform to Payment Page.
  4. The final page of the payment form is shown to the customer. It displays the message stating that the purchase has been declined. The page also contains the button for redirecting the customer to an additional payment attempt.
  5. The customer agrees to retry the payment and performs the required actions.
  6. After the customer payment data is transmitted to the payment platform, a retry is initiated with the use of this data.

When payment retries are processed, the payment status can vary:

  • processing—checking for the availability of retry attempts in case the purchase fails (when step 1 on the diagram is performed) or upon receiving payment data from the customer within the scope of the current retry attempt (after step 6 is performed).
  • awaiting customer—waiting for the customer actions. The status remains from the moment when the availability of retry attempts is identified within the payment platform (at step 1) and until the customer payment data is received (after step 6 is performed) or until the attempt time limit expires (in this case, the payment gets the decline status).
  • success—the required action has been completed (one of the retries has resulted in the debiting of funds or authorisation hold).
  • decline—all the possible retries have failed (none has led to the debiting of funds or hold on funds) or the time allowed for the attempts has expired. The same status is assigned when the customer declines to repeat the attempt.

All possible payment statuses used within the platform are described in Payment models and statuses.

Callbacks

During the process of payment retries, intermediate and final callbacks are sent from the payment platform to the web service.

Intermediate callbacks. If the purchase has failed and the availability of retry attempts has been identified, an intermediate callback is sent from the payment platform to the web service. This callback contains information about the availability of retry attempts (specified in the is_new_attempts_available parameter) and the remaining time allowed for these attempts (specified in the timeout_attempts parameter in seconds—ss).

In the intermediate callbacks, the is_new_attempts_available parameter is set to true, which implies that all of the following conditions have been met:

  • None of the attempts has led to the completion of the payment.
  • There are available attempts.
  • The time for executing the attempts has not expired.

In the following example of the callback body, you can see that for the purchase with the identifier 100028024 repeating payment attempts is allowed (is_new_attempts_available = true) and the time limit for the attempts is set to ten minutes (attempts_timeout = 600).

Figure 2. Example of callback data indicating the availability of retry attempts
{
   "project_id": 212,
   "payment": {
      "id": "100028024",
      "type": "purchase",
      "status": "awaiting customer",    // payment status
      "date": "2020-07-21T17:51:04+0000",
      "method": "card",
      "is_new_attempts_available": true,    // availability of retry attempts
      "attempts_timeout": 600,    // remaining time
      "sum": {
         "amount": 131970,
         "currency": "USD"
      },
      "description": ""
   },
   "account": {
      "number": "431422******0056 ",
      "type": "visa",
      "card_holder": "JOHN DOE",
      "expiry_month": "01",
      "expiry_year": "2025"
   },
   "operation": {
      "id": 20759000013841,
      "type": "auth",
      "status": "decline",
      "date": "2020-07-21T17:51:04+0000",
      "created_date": "2020-07-21T17:20:55+0000",
      "request_id": "7ba0fb24436a717d3091f7b71007891696db6e-00020760",
      "sum_initial": {
         "amount": 131970,
         "currency": "USD"
      },
      "sum_converted": {
         "amount": 131970,
         "currency": "USD"
      },
      "code": "108",
      "provider": {
         "id": 414,
         "payment_id": "",
         "endpoint_id": 414
      }
   },
   "signature": "oXlx8QWh3OC/YOqb2ib3C5jq/lHvisceI9Lqg/tRTuwcrNmj1zQ..."
}

Final callbacks. If the payment has been completed or cannot be completed within the session, a final callback is sent from the payment platform to the web service. In this case, the is_new_attempts_available parameter is set to false due to one of the following conditions:

  • The final attempt has led to the completion of the payment.
  • The customer has declined to repeat the attempt.
  • All the available payment attempts have been used up.
  • The time for making the attempts has expired.

In the following example of the callback body, you can see that the time for performing retries has expired and the purchase has been declined.

Figure 3. Example of callback data indicating that the purchase has been declined
{
   "project_id": 212,
   "payment": {
      "id": "100028024",
      "type": "purchase",
      "status": "decline",    // payment status
      "date": "2020-07-21T17:51:04+0000",
      "method": "card",
      "is_new_attempts_available": false,    // availability of retry attempts
      "attempts_timeout": 0,    // remaining time
      "sum": {
         "amount": 131970,
         "currency": "USD"
      },
      "description": ""
   },
   "account": {
      "number": "431422******0056 ",
      "type": "visa",
      "card_holder": "JOHN DOE",
      "expiry_month": "01",
      "expiry_year": "2025"
   },
   "operation": {
      "id": 20759000013841,
      "type": "auth",
      "status": "decline",
      "date": "2020-07-21T17:51:04+0000",
      "created_date": "2020-07-21T17:20:55+0000",
      "request_id": "7ba0fb24436a717d3091a2bdf7891696db6e-00020760",
      "sum_initial": {
         "amount": 131970,
         "currency": "USD"
      },
      "sum_converted": {
         "amount": 131970,
         "currency": "USD"
      },
      "code": "603",
      "message": "Auto decline",
      "provider": {
         "id": 414,
         "payment_id": "",
         "endpoint_id": 414
      }
   },
   "signature": "oXlx8QWh3OC/YOqb2ib3C5VLPksceI9Lqg/tRTuwcrNmj1zQ..."
}