COF purchase with automatic debiting

Notice: This article provides a general description of processing COF purchases with automatic debiting in the ecommpay payment platform and covers information about operations utilised to execute a payment of this type and statuses that are assigned to the payment and the operations performed within it.

In addition, use the following materials to gain a fuller understanding of COF purchases with automatic debiting:

Credential-on-file (COF) purchases—an article that covers processing COF purchases via Gate and describes requests and callbacks that are used in case of card payments.
articles of the Payment methods section containing a description of processing COF purchases via Gate with the focus on the specific features of the payment method used and information about relevant requests and callbacks.

Overview

COF purchase with automatic debiting is a payment type which uses an initial request to initiate a series of fund transfers from customer to merchant by using previously stored payment credentials without validation of the payment instrument (such as card validation code, or CVC).

COF purchases with automatic debiting are used for purchases in which the same payment instrument for repeatable miscellaneous purchases with fixed amount and schedule, for instance to pay monthly fee for a subscription. COF purchases with automatic debiting are convenient for the customer and the merchant because they can be sure that payments will be performed automatically, with no additional actions on their part.

Payment model

COF purchase with automatic debiting becomes available only after you perform an initial purchase in which you specify the COF purchase type and instruct the payment platform to save customer's purchase credentials. To do so, you need to include in the initial request the recurring object that contains the register and type parameters.

You initiate COF purchase with automatic debiting by sending a recurring request to the payment platform. Once the payment platform receives the request, it creates a recurring operations which eventually results in debiting customer card or account on schedule without payment instrument validation.

In rare instances, a COF purchase with automatic debiting payment may require you to send another request to submit additional information requested by one of stakeholders, for example to provide cardholder address which is missing from the initial request. In this case, the payment platform sends to the web service a callback with the names of the missing parameters, suspends the purchase processing, and waits for the web service to submit a clarification request with the values for the missing parameters.

If required, you can change the payment schedule and/or amount or even cancel the payment altogether. To change the payment schedule and/or amount, you need to submit an update request to the payment platform. To cancel the payment, you submit a cancel request. To initiate the update and cancel requests, you use the recurring_update and recurring_cancel operations, respectively.

If the payment method supports refunds, after completing a COF purchase with automatic debiting you can return your customers their money, if needed. The total amount of refund cannot be larger than the total debited amount. You initiate a refund by sending a refund request to the payment platform. Refund is performed by using the refund operation.

Figure 1. State diagram for COF purchase with automatic debiting

The rest of this section describes any possible statuses of an COF purchase with automatic debiting and operations related with the purchase. For more information about how to perform COF purchase with automatic debiting with payment cards, see Credential-on-file (COF) purchases.

Payment statuses

The following table describes the statuses of any COF purchase with automatic debiting.


`error`	Error occurred when request processing. Payment is not performed.	Final status. The request can be resent with the same payment identifier.
`processing`	Payment is in progress. A current debiting is being processed on a prearranged schedule.	Intermediate status
`awaiting clarification`	Payment processing is suspended until the web service submits a `clarification` request—to continue the payment processing—with the required data. If the payment platform does not receive this request within 30 minutes, the status is set to `decline`.	Intermediate status
`scheduled recurring processing`	Payment is in progress. Automatic debiting is pending according to the prearranged schedule.	Intermediate status
`decline`	Payment is declined.	Final status
`success`	Payment has completed successfully—all automatic debiting happened.	Final status. Additionally the payment refund is supported.
`partially refunded`	The partial amount of payment has returned to a customer. The status is set to `partially refunded` when all debiting have happened.	Final status. Additionally a partial refund can be canceled.
`refunded`	The the total amount of payment was returned to a customer. The status is set to `partially refunded` when all automatic debiting operations have happened.	Final status. Additionally a refund can be canceled.

The recurring operation statuses

The following table describes the statuses of the recurring operation.


`processing`	Operation is being processed.	Intermediate status
`awaiting clarification`	Operation processing is suspended until the web service submits a `clarification` request—to continue the payment processing—with the required data. If the payment platform does not receive this request within 30 minutes, the status is set to `decline`.	Intermediate status
`decline`	Operation could not be completed.	Final status
`success`	Operation has completed successfully.	Final status

The recurring_update and recurring_cancel operations statuses

The following table describes the statuses of the recurring_update and recurring_cancel operations.


`processing`	Operation is being processed.	Intermediate status
`decline`	Operation denied.	Final status
`success`	Operation completed successfully.	Final status

The refund operation statuses

The refund operation statuses coincide with the recurring operation ones.