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.

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.

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. For example, 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. Similarly, if you specify a certain payment method in the request, all attempts are performed with the use of this payment method. Without such parameters passed in the request, the customer can choose any of the available methods to make additional payment attempts.

The number of attempts and the time allocated for executing these attempts are limited. These restrictions can be configured upon coordination with your key 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.
  2. The customer is redirected to the payment form 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 fails, 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 processed successfully, 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 the customer is redirected to the web service upon completing the purchase without the final page displayed, they cannot retry the same payment procedure. For more information, see Options for returning customers to project after payment.
  • Support for Payment Page customisation. With a customised payment form, merchants should contact their key account managers for setting up a new element of that form—the button for redirecting the customer to a payment attempt. After that, merchants should provide the technical support specialists with the preferred design of the template layout. For more information about the Payment Page customisation, see Customisation.
  • 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, 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. For more information, see Limiting time for using Payment Page. 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 key 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 3 attempts that must be performed within 6 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 key 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: 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. With the capability of retry attempts, after the purchase fails, 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 six minutes (attempts_timeout = 360).

Figure: 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": 360,    // remaining time
      "sum": {
         "amount": 131970,
         "currency": "USD"
      },
      "description": ""
   },
   "account": {
      "number": "424242******4242",
      "type": "visa",
      "card_holder": "JOHN DOE",
      "expiry_month": "01",
      "expiry_year": "2023"
   },
   "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: Example of callback data indicating that the purchase was 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": "424242******4242",
      "type": "visa",
      "card_holder": "JOHN DOE",
      "expiry_month": "01",
      "expiry_year": "2023"
   },
   "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..."
}