One-time two-step purchase

Notice: This article provides a general description of processing one-time two-step 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 processing one-time two-step purchases:

Two-step purchase—an article that covers processing one-time two-step 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 one-time two-step purchases via Gate with the focus on the specific features of the payment method used and information about relevant requests and callbacks.

Overview

One-time two-step purchase is a payment type which uses two steps to make a one-time transfer of funds from customer to merchant. On the first step, merchant initiates an authorization hold—in other words, the purchase amount is deducted from the credit limit of customer's card account. On the second step, the purchase amount is 'captured', or, in other words, it is debited to the customer account based on the merchant request or after specific time lag.

This payment type allows merchant to “hold” the purchase amount and, thus, to ensure that specific amount will be charged, or captured, to customer account or, alternatively, to “release” the funds if the situation changes, for instance when the customer cancels hotel booking.

Payment model

You initiate the first step of a purchase by sending an auth request to the payment platform. Once the payment platform receives the request, it creates an auth operation which eventually results in holding funds on customer account.

The first step may require merchant to issue additional requests:

If the payment requires customer to be authenticated by using the 3‑D Secure technology, the payment platform sends to the web service a callback that contains the data required to generate a request to the issuer, suspends the purchase processing, and waits until the web service submits a 3ds_result request with the authentication results.
If the payment requires customer to be authenticated by the payment system on merchant's request, the payment platform receives a callback from the payment system and sends to the web service a callback with notification that authentication is required, and then suspends the payment processing and waits until the web service submits the following two merchant_auth requests: the start request—after customer confirms payment and finish—after customer enters validation code.
If any payment stakeholder requests additional information (For example, the payment system may request cardholder address which was missing from the initial request.), the payment platform sends to the web service a callback that lists the requested parameters, suspends the purchase processing, and waits until the web service submits a clarification request with the requested information.

You can change the amount you authorised on this step either before or during the second step. To increase the authorised amount, submit an incremental request; to decrease the authorised amount, submit a cancel request.

The second step may be initiated by request from merchant's web service or the payment platform may automatically perform the step after specific time elapses.

The merchant initiates the second step by sending one of the following requests to the payment platform:

capture—this request processing results in a capture operation and the customer account is debited for the held amount.
cancel—this request processing results in a cancel operation and release of the funds held on the customer account.

In your capture request, you can specify a to-be-debited amount which is different from the initially authorised amount.

For more information on how to initiate the second step, refer to your account manager.

If the payment method supports refunds, after completing a one-time two-step 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 one-time two-step purchase

The rest of this section describes any possible statuses of a one-time two-step purchase and operations related with the purchase. For more information about how to perform one-time two-step purchases with payment cards, see Two-step purchase. For more information about performing one-time one-step purchases depending on the payment method, see Methods.

Payment statuses

The following table describes the statuses of any one-time two-step 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 3ds result`	Payment processing is suspended until the web service submits a `3ds_result` request with the authentication result. If the payment platform does not receive this request within the required timeout time, then the payment status is set to `decline`. Normally, the timeout is 30 minutes, but it may differ depending on provider. For more information about specific timeouts, contact technical support at support@ecommpay.com.	Intermediate status
`awaiting merchant auth`	Payment processing is suspended until the web service submits a `merchant_auth` request—if the payment requires customer to be authenticated by the payment system on merchant's request—with the `type` parameter that is set to `finish`.	Intermediate status
`awaiting redirect result`	Payment processing is suspended until the payment system submits a callback with the result to the payment platform. Depending on the result that the payment system submitted the status is set to `success` or `decline`.	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
`awaiting customer`	Payment processing is suspended until one of additional attempts to perform this payment is successfully completed—the status is set to `success`—or the maximum amount of the additional attempts has been exceeded—the status is set to `decline`. For more information about the Try again payments, see Payment retries.	Intermediate status
`awaiting capture`	Payment processing is suspended until the web service submits a `capture` request or a `cancel` request.	Intermediate status
`canceled`	A hold placed on funds has cancelled.	Final status
`decline`	Payment could not be completed.	Final status
`success`	Payment has completed successfully.	Final status. Additionally the payment refund is supported.
`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.
`partially reversed`	The partial amount of payment has returned to a customer.	Final status
`reversed`	The total amount of payment was returned to a customer on the same business day the initial payment had been completed.	Final status

The auth operation statuses

The following table describes the statuses of the auth operation.


`processing`	Operation is being processed.	Intermediate status
`awaiting 3ds result`	Operation processing is suspended until the web service submits a `3ds_result` request with the authentication result. If the payment platform does not receive this request within the required timeout time, then the payment status is set to `decline`. Normally, the timeout is 30 minutes, but it may differ depending on provider. For more information about specific timeouts, contact technical support at support@ecommpay.com.	Intermediate status
`awaiting merchant auth`	Operation processing is suspended until the web service submits a `merchant_auth` request—if the payment requires customer to be authenticated by the payment system on merchant's request—with the `type` parameter that is set to `finish`.	Intermediate status
`awaiting redirect result`	Operation processing is suspended until the payment system submits a callback with the result to the payment platform. Depending on the result that the payment system submitted the status is set to `success` or `decline`.	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 incremental operation

The following table describes the statuses of the incremental operation.


`decline`	Operation is declined.	Final status
`success`	Operation is completed successfully.	Final status

Statuses of the capture and cancel operations

The following table describes the statuses of any capture or cancel 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 capture and cancel operation ones.