Working with debiting retry attempts

Introduction

If a scheduled automatic debiting is declined, for example, in case when the customer's account has insufficient balance, initiating this debiting can be attempted again in the ecommpay payment platform after a certain time period. You can add this capability for specific projects and for a specific group of payment methods upon agreement with your ecommpay account manager. Note that the merchant is responsible for notifying the customers that this functionality is being used, specifically when a scheduled debiting was declined and retry attempts have been set up.

If retry attempts are not used for COF purchases, when a scheduled debiting in the series is declined, the next scheduled debiting is expected to be processed in the payment platform according to the schedule (details). Whether an additional debiting should occur or whether the series of debitings should be cancelled is decided by the merchant.

Special aspects

When working with the debiting retries, consider the following:

• For each project you can implement a specific retry schedule: either a default one by ecommpay or a custom one.
• Debiting retries can be used for a limited number of the globally accepted payment methods: Apple Pay, Google Pay, and standard card payments.
• Debiting retries can be used only for regular COF purchases when the debiting schedule is stored on the side of the payment platform (type R).
• Debiting can be retried only if the previous debiting attempts were declined by the issuer or the payment system.
• Using the functionality of debiting retries does not guarantee that the funds will be withdrawn eventually. If the allowed number of retries does not result in debiting, then this debit operation is deemed declined (it is assigned the decline status), and the COF purchase in question is subsequently processed in the platform according to its debiting schedule.

Use

The specifics of using debiting retries can be illustrated with the following examples.

Suppose within a specific COF purchase automatic debitings are initiated on Monday at 12:00 and, according to the schedule, are to be performed on November 02, 09, 16, and 23, but on November 09 and 16 scheduled debitings do not occur, then the options to respond to this situation can be as follows:

1. If the functionality of debiting retries is not available for this purchase, then regardless whether the scheduled debiting was completed or declined after the declined scheduled debiting, the next scheduled debiting will be performed.
2. If a default retry schedule from ecommpay is used, then after the initial scheduled debiting is declined, the platform will retry it as many times as determined by the schedule follows: the first two attempts will occur with a delay of 12 hours between them, the following attempts will occur every 24 hours, and the attempts will be stopped at least 24.5 hours before the next scheduled debiting on Monday.
3. If a default retry schedule from ecommpay is used, and the web service requests to stop subsequent debiting retries after three attempts are declined one after another, then if the initial debiting is declined, the platform will retry it up to three times in a row.
4. If a custom retry schedule is used, then after the initial scheduled debiting is declined, the platform will retry it as many times as configured with a delay of 24 hours between consecutive attempts, and the attempts will be stopped at least 24.5 hours before the next scheduled debiting on Monday.

Since schedules of both regular COF purchases and debiting retry attempts can be flexibly configured, these scenarios can be used in a wide range of situations. However, it is also important to monitor statuses of all operations and maintain appropriate communication with customers depending on the operation statuses and retry schedule.

Overview

The payment platform allows you to implement one schedule of debiting retries for a specific project. The schedule applies to all regular COF purchases within this project. To set up, you can send requests via Gate (more on this below) or use the tools of the Dashboard interface (details). It can be a default schedule from ecommpay or a custom schedule that you can set up on your own depending on the specific project: it can be either a default schedule from ecommpay, or a custom schedule configured by the merchant.

The main characteristics of these schedule types can be compared as follows.

• In case of a default schedule, for each scheduled debiting there can be no more than 7 retry attempts carried out within 6 days.

  The time interval between an initial debiting and the first retry attempt as well as between the first and the second retry attempts equals 12 hours. If, according to the debiting schedule, the next debiting is to occur less than 12.5 hours after the retry attempt, the retry attempt is not performed. The remaining five retry attempts are carried out every 24 hours, with the restriction that the next scheduled debiting is to occur at least 24.5 hours after the retry attempt.

• In case of a custom schedule, for each scheduled debiting there can be 1 to 10 retry attempts carried out within 10 days.

  The time interval between the retry attempts can vary, but it must be a multiple of 24 hours, and there is a restriction that the next scheduled debiting is to occur at least 24.5 hours after the retry attempt. For example, if the debiting is scheduled once a month, the four retry attempts can be set with the increasing time interval of 24, 48, 72, and 96 hours (occurring on the first, third, sixth, and tenth day, in compliance with an overall 10 day time limit for retries and the restriction that the next scheduled debiting is to occur at least 24.5 hours after the retry attempt).

The schedule implemented for any project can be customised by modifying its specific parameters or by resetting them to default. Keep in mind that a retry attempt that was scheduled before the retry schedule was customised is performed according to the initially set date and time (according to the previous schedule). However, if any of these attempts is declined after the schedule was modified and it is possible to perform the next attempt of this debiting retry in the payment platform, then the new attempt is scheduled and performed according to the updated schedule. In either case, the information about each subsequent retry attempt is sent to the web service in the callback notifying that a debiting attempt was declined (details).

When working via the Gate API, keep in mind that requests for modifying retry schedules are processed according to the synchronous model of interaction between the web service and the payment platform. This implies that each request is fully processed within one HTTP session and uses only the resources of the payment platform. The response to the correct request contains an HTTP response status code (200) and the required data without detailed request processing information. If the request is incorrect, or there have been issues with its acceptance and processing, then the response contains an HTTP response status code, request processing status error, and the detailed description of the error that occurred. The description of the response format can be found here.

Keep in mind that requests for modifying retry schedules are processed according to the synchronous model of interaction between the web service and the payment platform. This implies that each request is fully processed within one HTTP session and results in relevant response (details).

Configuring a custom schedule

To customise a retry schedule via the Gate API for a specific project:

1. Send an HTTP-POST request to the /v2/recurring/retry-custom-schedule/save endpoint.
2. Receive a synchronous response communicating that the schedule was updated in the platform.

The request must contain the following objects and parameters:

• general—object with the general identification information
  • project_id—project identifier obtained from ecommpay during integration
  • signature—request signature generated after all required parameters are specified (details can be found in the article Signature generation and verification) (details)
• interval_days—array with the ordinal numerals indicating the days on which retry attempts are to be performed, counted from the day when the initial debiting was declined and specified as an ascending sequence of numbers from 1 to 10, with comma used as a delimiter (for example, [1,5,9])

Thus, a correct request must contain the project identifier, signature, and the interval_days array. In the following example, the retry attempts are scheduled on the first, fifth, and ninth day after the initial debiting was declined.

{
"general":{
    "project_id": 42,
    "signature": "K5D/aZAsdsg ... R+YyilEtbS="
    }, 
"interval_days": [1,5,9]
}

{
"general":{
    "project_id": 42,
    "signature": "K5D/aZAsdsg ... R+YyilEtbS="
    }, 
"interval_days": [1,5,9]
}

When the request to configure a retry schedule is processed, the payment platform sends a response with the code 200 OK to the web service. If the request is declined, the response contains a request processing status error and the description of the error that occurred, for example, Recurring retry not enabled.

Checking the schedule

To check the schedule of debiting retry attempts for a specific project via the Gate API:

1. Send an HTTP-POST request to the /v2/recurring/retry-custom-schedule/info endpoint.
2. Receive a synchronous response with information about the schedule.

The request must contain the following objects and parameters:

• general—object with the general identification information
  • project_id—project identifier obtained from ecommpay during integration
  • signature—request signature generated after all required parameters are specified (details can be found in the article Signature generation and verification) (details)

Thus, a correct request must contain the project identifier and signature.

{
  "general":{
    "project_id": 42,
    "signature": "K5D/kyky...il8l="
  }
}

{
  "general":{
    "project_id": 42,
    "signature": "K5D/kyky...il8l="
  }
}

When the request to check a retry schedule is processed, the payment platform sends a response with the code 200 OK and required information to the web service. If the request is declined, the response contains a request processing status error and the description of the error that occurred. The response body contains the projects identifier and the schedule object.

If the retry schedule was customised for a specific project in the platform, the schedule object includes the following parameters:

• interval_days—array with the ordinal numerals indicating the days on which retry attempts are to be performed, counted from the day when the initial debiting was declined and specified as an ascending sequence of numbers from 1 to 10, with comma used as a delimiter (for example, [1,5,9])
• status—indicator specifying whether the custom schedule is activated (contains the value active if the custom schedule has been configured and not deactivated for the project)

If a default retry schedule from ecommpay is used for a specific project, the schedule object will be empty.

In the following example, the response communicates that for project 42 a custom schedule was configured, with the retry attempts set on the first, fifth, and ninth day after the initial debiting was declined.

{
  "project_id": 42,
  "schedule": {
    "interval_days": [1,5,9],
    "status": "active"
  }
}

{
  "project_id": 42,
  "schedule": {
    "interval_days": [1,5,9],
    "status": "active"
  }
}

In the following example, the response does not contain any data in the schedule object, which means that for project 42 a default schedule is used.

{
  "project_id": 42,
  "schedule": {}
}

{
  "project_id": 42,
  "schedule": {}
}

Resetting the schedule to default values

To reset the retry schedule to default values for a specific project via the Gate API:

1. Send an HTTP-POST request to the /v2/recurring/retry-custom-schedule/disable endpoint.
2. Receive a synchronous response communicating that the request has been processed.

The request must contain the following objects and parameters:

• general—object with the general identification information
  • project_id—project identifier obtained from ecommpay during integration
  • signature—request signature generated after all required parameters are specified (details can be found in the article Signature generation and verification) (details)

Thus, a correct request must contain the project identifier and signature.

{
 "general":{    
    "project_id": 42,
    "signature": "K5D/aZAMdeR+YyilUwS="
 }
}

{
 "general":{    
    "project_id": 42,
    "signature": "K5D/aZAMdeR+YyilUwS="
 }
}

When the request to reset the schedule to default values is processed, the payment platform sends a response with the code 200 OK to the web service. If the request is declined, the response contains a request processing status error and the description of the error that occurred.