COF purchase with automatic debiting

Overview

COF purchase with automatic debiting is a payment type which uses a single initial request to make a series of regularly recurring funds transfers from the customer to the merchant by using stored payment credentials without verification of the payment instrument (such as a card verification code).

The payment platform performs COF purchases with automatic debiting according to the payment model (learn more).

Managing debiting retry attempts

If a scheduled automatic debiting is declined, for example, in case when the card account has insufficient balance, initiating this debiting can be attempted again in the payment platform after a certain time period. Refer to your ecommpay account manager to add this capability. It will be used if set up for the project in question and the following two requirements are met:

  • This is a card payment.
  • The debiting was declined by the issuer or the payment system.

In other cases, 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. Whether a debiting retry should occur or whether the series of debitings should be cancelled is decided by the merchant.

When retry attempts are used for COF purchases, their number and the time allocated for making them are limited: 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. The rest of the retry attempts are carried out every 24 hours. Along with that, it is checked that according to the debiting schedule the next debiting is to occur at least 12.5 or 24.5 hours after the retry attempt. If not, the retry attempts are cancelled. These restrictions are applicable to all payments within any project and cannot be modified in any way.

The steps of the debiting retry procedure are as follows:

  1. When a scheduled debiting is declined by the payment system or the issuer, the ecommpay payment platform checks if there is a possibility to attempt performing the debiting once again. If this possibility is confirmed, the web service is sent a callback that contains the information about the debiting decline with the operation status decline as well as the scheduled date and time of the retry attempt.
  2. At the scheduled time, the debiting retry attempt is performed automatically.
  3. Depending on the attempt result, the following steps are executed:
    • If the attempt results in debiting the funds from the customer to the merchant, a callback containing the debiting result information (with the operation status success) is sent to the web service. The COF purchase series continues according to the existing schedule.
    • If the attempt results in decline and the payment platform confirms the possibility to perform another attempt, a callback containing the information about the debiting decline (with the operation status decline and the scheduled date and time of the next retry attempt) is sent to the web service. Then step 2 is repeated.
    • If the attempt results in decline and the payment platform does not confirm the possibility to perform another attempt, a final callback containing the information about the debiting decline (with the operation status decline and without information about the next attempt) is sent to the web service. The COF purchase series continues according to the existing schedule. In this case, whether a debiting retry should occur or whether the series of debit operations should be cancelled must be decided by the merchant.

Along with that, retry Retry attempts can be cancelled even after they have been scheduled. You can send a request to Gate or use the tools of the Dashboard interface. In addition, you can stop the retry attempts by modifying the parameters of the COF purchase (including its expiration or cancellation, which changes the payment status in general and cancels subsequent debit operations in the series). If necessary, you can also contact the ecommpay technical support for assistance.

Workflow

COF purchase with initiation of the first debit operation during registration

If the scheduled_payment_id parameter has been passed during the COF purchase registration, these are the steps to perform a COF purchase with automatic debiting:

  1. Register a COF purchase. For more information, see Registering COF purchase.
  2. Accept a callback with the debiting result from the payment platform.
  3. Accept subsequent callbacks for each debit operation for this payment.

To update or cancel a COF purchase or to refund one or more debit operations, you need to submit the corresponding requests to the payment platform. (For more information, see Managing debiting series of a COF purchase.)

Figure 1. Processing a COF purchase with initiation of the first debit operation during registration
  1. According to the schedule, at the set time the payment platform sends the request for performing a recurrent debit operation to the payment system.
  2. The payment system processes the request and forwards it to the issuer.
  3. The issuer processes the debit operation and transfers the funds from the customer to the merchant.
  4. The issuer sends a notification with the debiting result information to the payment system.
  5. The payment system sends the notification with the debiting result information to the payment platform.
  6. The payment platform sends a callback with the debiting result to the web service.
  7. The customer receives the debiting result information from the web service.
  8. From this point forward, the payment platform initiates subsequent scheduled debit operations, with each following steps 1 through 7.

The sections that follow discuss formats for requests and callbacks; for general information about using the API, see Interaction concepts. Information about possible statuses of this payment type can be found in the corresponding article.

COF purchase with a separate initiation of the first debit operation

If the scheduled_payment_id parameter has not been passed during the COF purchase registration, these are the steps to perform a COF purchase with automatic debiting:

  1. Register a COF purchase. For more information, see Registering COF purchase.
  2. Submit a request for performing a COF payment with an identifier of the debit series record.
  3. Accept a callback with the debiting result from the payment platform.
  4. Accept subsequent callbacks for each debit operation for this payment.
Figure 2. Processing a COF purchase with a separate initiation of the first debit operation
  1. The web service sends a request for debiting to the ecommpay URL.
  2. The request enters the payment platform.
  3. The payment platform accepts and processes the request.
  4. The payment platform sends the request acknowledgement and request correctness information to the web service.
  5. The payment platform sends the request for performing a debit operation to the payment system.
  6. The payment system processes the request and forwards it to the issuer.
  7. The issuer processes the debit operation and transfers the funds from the customer to the merchant.
  8. The issuer sends a notification with the debiting result information to the payment system.
  9. The payment system sends the notification with the debiting result information to the payment platform.
  10. The payment platform sends a callback with the debiting result to the web service.
  11. The customer receives the debiting result information from the web service.
  12. From this point forward, the payment platform initiates subsequent scheduled debit operations, with each following steps 5 through 11.

COF purchase with debiting retry attempts

If the capability of debiting retries is set up for the project, these are the steps to perform a COF purchase with automatic debiting:

  1. Register a COF purchase. For more information, see Registering COF purchase.
  2. If the scheduled_payment_id parameter has not been passed during the COF purchase registration, submit a request for performing a COF payment with an identifier of the debit series record (recurring.id).
  3. Accept a callback with the debiting result from the payment platform (one or several depending on the number of executed retries).
  4. Accept subsequent callbacks for each scheduled debit operation and the retry attempts (if there are any) for this payment. If necessary, you can cancel retrying a specific debiting via Gate or Dashboard.

    Keep in mind that if debiting retries are cancelled, no callbacks are sent to communicate the cancellation.

Figure 3. Processing a COF purchase with debiting retry attempts
  1. If a scheduled debiting has not resulted in transferring of funds, the payment platform checks if there is a possibility to attempt performing the debiting once again.
  2. The payment platform sends a callback to the web service containing the information about the debiting decline (with the operation status decline) and the scheduled date and time of the retry attempt.
  3. The payment platform sends a request to perform a debit operation to the payment system on the scheduled date and time.
  4. The payment system processes the request and forwards it to the issuer.
  5. The issuer processes the debit operation.
  6. The issuer sends a notification about the debiting decline to the payment system.
  7. The payment system sends the notification about the debiting decline to the payment platform.
  8. The payment platform checks if the possibility to retry the operation is available. If necessary, the payment platform initiates subsequent retry attempts, and for each attempt, step 2 through 7 are repeated.
  9. The payment platform sends a callback to the web service: with the operation status decline if none of the retries resulted in debiting or success if one of the retries resulted in debiting.
  10. The customer receives the debiting result information from the web service.
  11. From this point forward, the payment platform can initiate subsequent debit operations, with each following steps 1 through 10.

To cancel retrying a specific debiting, send a request to cancel debiting retries, accept the response, and notify the customer if necessary.

Figure 4. Processing a COF purchase with cancellation of debiting retries
  1. The web service sends a request to cancel the retry attempts scheduled in the payment platform for the declined debiting to the ecommpay URL.
  2. The request enters the payment platform.
  3. The payment platform processes the request.
  4. The payment platform sends the request acknowledgement and request correctness information to the web service. The payment platform ceases to retry this debiting.
  5. The customer receives the debiting result information from the web service.
  6. From this point forward, the payment platform initiates subsequent debit operations according to the existing schedule.

Request format

Request to initiate a COF purchase

There are several things you need to consider when sending a request for a COF purchase with automatic debiting using a payment card:

  1. To initiate each purchase, send a separate POST request to the /v2/payment/card/recurring endpoint.
  2. Each request must include the following objects and parameters:
    • general—object with general request identification information:
      • project_id—project identifier obtained from ecommpay during integration.
      • payment_id—payment identifier, unique within the project.
      • signature—request signature generated after all required parameters are specified (details—in Signature generation and verification). (details)
    • customer—object with customer information:
      • id—customer identifier, unique within the project, the same identifier as the one used to register this COF purchase.
        Warning: Using different customer identifiers for operations performed as part of the COF purchase is not allowed.
      • ip_address—customer IP address relevant for the initiated payment.
    • payment—object with payment information:
      • amount—payment amount in the smallest currency unit.
      • currency—payment currency code in the ISO-4217 alpha-3 format.
    • recurring—object with the COF payment information:
      • id—identifier of the debit series received in the callback with the COF purchase registration data or assigned when the COF purchase information was migrated from another acquirer.
  3. The set of parameters required for executing a payment can vary depending on the regional characteristics and other aspects of the payment services providers. Refer to your ecommpay account manager to learn more about the providers' specifics and requirements.
  4. Additionally, any other parameters included in the specification can be used.

Thus, a correct request must contain the project identifier, basic payment information (identifier, amount, and currency code), customer IP address, signature, and the identifier of the debiting series record.

Figure 5. Example of data passed in the request to initiate a COF payment
{  
  "general":{  
    "project_id":42,
    "payment_id":"456789",
    "signature":"K5D/aZAMdeR+YyilUwS=="
  },
  "customer":{  
    "ip_address":"202.144.196.0",
    "id":"customer_12"
  },
  "payment":{
    "amount":400,
    "currency":"USD"
  },
  "recurring":{
    "id":1079
  }
}

Request to cancel debiting retries

There are several things you need to consider when sending a request to cancel debiting retry attempts:

  1. To cancel a debiting retry, send a separate POST request to the /v2/recurring/retry_stop endpoint.
  2. Each request must include the following objects and parameters:
    • general—object with general request identification information:
      • project_id—project identifier obtained from ecommpay during integration.
      • signature—request signature generated after all required parameters are specified (details—in the Signature generation and verification). (details)
    • recurring—object with the COF payment information:
      • id—identifier of the debit series received in the callback with the COF purchase registration data or assigned when the COF purchase information was migrated from another acquirer.
    • trigger_operation_id—identifier of the recurring debit operation for which you need to cancel retries.

Thus, a correct request must contain the project identifier, signature, and the identifiers of the debiting series record and the target debit operation.

Figure 6. Example of data passed in the request to cancel debiting retries
{ 
  "general":{ 
    "project_id":42,
    "signature":"K5D/anjn7fv+YyilUwS=="
  },
  "recurring":{
    "id":1079
   },
  "trigger_operation_id":092384
}

Callback format

The payment platform communicates results of processing each debit operation in callbacks sent to your web service. These callbacks are arranged in a standard format the detailed description of which can be found in Handling callbacks.

If the capability of debiting retries is set up, callbacks will contain the recurring_retry object that can include some or all of the following parameters:

  • trigger_operation_id—identifier of the debit operation that was retried.
  • retry_count—the number of the retry attempt (an integer from 1 to 7) if such attempt has been performed.
  • next_retry_exists—an indicator that shows whether the next scheduled attempt is available.

    This parameter is set to true if the debiting resulted in decline and there is an available retry attempt (the number of attempts and the time allocated for making them are not used up). In all other cases this parameter is set to false.

  • next_retry_date—the scheduled date and time of the next retry attempt.

The following callback contains information about processing 4.00 USD debit operation for card 431422******0056 of the customer with identifier customer_12 within project 42. The capability of debiting retries is not available.

Figure 7. Example of data passed in a callback with debiting results (retries capability is not set up)
{  
  "customer":{  
    "id":"customer_12"
  },
  "account":{  
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JOHN SMITH",
    "id":45678,
    "expiry_month":"08",
    "expiry_year":"2026"
  },
  "payment":{  
    "sum":{  
      "amount":400,
      "currency":"USD"
    },
    "method":"card",
    "date":"2023-06-07T06:18:02+0000",
    "status":"scheduled recurring processing",    // Payment status
    "type":"recurring",    // Payment type
    "id":"456789",
    "description":""
  },
  "project_id":42,
  "recurring":{  
    "valid_thru":"2023-07-31T00:00:00+0000",
    "currency":"USD",
    "id":1079    // Identifier of the debit series
  },
  "operation":{  
    "id":39690002636,
    "type":"recurring",    // Operation type
    "status":"success",    // Operation status
    "date":"2023-06-07T06:18:02+0000",
    "created_date":"2023-06-07T06:18:02+0000",
    "request_id":"5cfa0199c33071",
    "sum_initial":{  
      "amount":400,
      "currency":"USD"
    },
    "sum_converted":{  
      "amount":400,
      "currency":"USD"
    },
    "provider":{  
      "id":6,
      "payment_id":"1192",
      "date":"2023-02-07T08:34:24+0000",
      "auth_code":"5253",
      "endpoint_id":6
    },
    "code":"0",
    "message":"Success"
  },
  "signature":"v7KNMpfZZ5D/aZMdeR+YyilUwSm...=="
}

The following callback contains information that the declined debiting can be retried and the first retry attempt has been scheduled ("next_retry_exists : true"). In this case, the identifiers of the target debit operation and the retry attempt are not specified because no retry attempts have been performed yet.

Figure 8. Example of data passed in a callback with information about the debiting decline and the scheduled first retry
"recurring_retry": {   
            "next_retry_exists": true,
            "next_retry_date": "2023-05-24T16:58:02+0000"  
            }

The following callback contains information that the first attempt ("retry_count": 1) to retry debit operation 344589675 was declined and, as a result, the second attempt ("next_retry_exists" : true) has been scheduled for this debit operation at 2023-05-24T16:58:02+0000.

Figure 9. Example of data passed in a callback with information about the retry decline and the scheduled second attempt
"recurring_retry": {   
            "trigger_operation_id": 344589675,
            "retry_count": 1,
            "next_retry_exists": true,
            "next_retry_date": "2023-05-24T16:58:02+0000"  
            }

The following callback contains information that the second attempt ("retry_count": 2) to retry debit operation 344589675 was performed successfully (the funds were transferred from the customer to the merchant) and, as a result, there is no need to retry this debiting any more ("next_retry_exists" : false).

Figure 10. Example of data passed in a callback with information about the debiting completed at the second attempt
"recurring_retry": {     
            "trigger_operation_id": 344589675,
            "next_retry_exists": false,
            "retry_count": 2
            }

The following callback contains information that no retry attempts were performed or scheduled for one of the debit operations in the series. Such callbacks are sent if the debiting resulted in funds transfer when it was first initiated or retry attempts cannot be performed.

Figure 11. Example of data passed in a callback with information that no scheduled retry attempts are available
"recurring_retry": {   
            "next_retry_exists": false 
            }