On-demand COF purchase

Notice: This article provides a general description of processing on-demand COF purchases 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 on-demand COF purchases:

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

On-demand COF purchase is a payment type which uses a single initial request to make one transfer of funds from customer to merchant by using previously stored payment credentials but without validation of the payment instrument (such as card validation code, or CVC).

The on-demand COF purchases are used for purchases that use the same payment instrument for repeatable miscellaneous purchases with variable amount and no specific schedule, for instance to pay for taxi services. On-demand COF purchases are convenient because they do not require customer to enter payment credentials and to validate payment instrument for each purchase.

Payment model

A COF purchase 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 by sending a recurring request to the payment platform. Once the payment platform receives the request, it creates a recurring operation which eventually results in debiting customer card or account without payment instrument validation.

In rare instances, a COF purchase may require you to send another request to submit additional information requested by one of the 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 until the web service submits a clarification request with the values for the missing parameters.

If the payment method supports refunds, after completing an on-demand COF purchase you can return your customers their money, if needed. You initiate a refund by sending a refund request to the payment platform. Refund is performed by using one of the following operations:

reversal—this operation is used when refund is performed on the same business day as the initial purchase.
refund—this operation is used when refund is performed after the business day of the initial purchase is closed.

Figure 1. State diagram for on-demand COF purchase

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

Payment statuses

The following table describes the statuses of any on-demand COF purchase.


`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 being processed.	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
`decline`	Payment could not be completed.	Final status
`success`	Payment has completed successfully.	Final status. Additionally the payment refund is supported.
`reversed`	The total amount of payment was returned to a customer on the same business day the initial payment had been completed.	Final status. Additionally a refund can be cancelled.
`partially refunded`	The partial amount of payment has returned to a customer.	Final status. Additionally a partial refund can be cancelled.
`refunded`	The the total amount of payment was returned to a customer after the business day the initial purchase had been completed. This status is used if the total amount of payment is returned in one refund or if the total amount of the partial refunds is equal to the total amount of payment.	Final status. Additionally a refund can be cancelled.

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

Statuses of the reversal and refund operations

The reversal and refund operation statuses coincide with the recurring operation ones.