Delayed Capture

From Barion Documentation
Revision as of 11:28, 5 August 2019 by Stankovicsa (talk | contribs)
Jump to navigation Jump to search

Delayed Capture

(just in the sandbox, yet)

A delayed capture payment scenario means that upon completing the payment, the card of the payer is not immediately charged. Instead, it becomes reserved (or blocked) for a given period of time on the payer's card. During this times this time window, the amount in unavailbale for the the payer and the payee and the merchant has the right to decide whether to capture, or cancel the purchase. It is very similar to Reservation payment, the key difference is where the money is blocked. In a reservation scenario, the payer's card is immediately charged, and the amount is blocked in the Barion system. In a delayed capture scenario the payer's card is only charged upon the capture request, until then the amount is only blocked on the payer's card.


In order to implement delayed capture payments, you need to familiarize yourself with the simple Responsive Web Payment scenario. The preparation of payments, redirection to the Barion Smart Gateway and handling the Callback mechanism are identical to immediate payments. There are only additions to the immediate scenario.

It is VERY strongly advised to have a detailed knowledge about the payment process, the simple immediate payment scenario and the callback processing.

Key differences when using delayed capture

The finishing step

The most important thing to note when implementing a delayed capture payment process is that there is an extra step required to complete the payment: capturing the payment. This must be done by the merchant, before the delayed capture period runs out. This can be done by calling either the v2/Payment/Capture or the v2/Payment/CancelAuthorization API endpoint. The time window available (up to 21 days in case of a Hungarian shop, 7 otherwise) is also set by the merchant during the preparation of the payment - see the DelayedCapturePeriod parameter in the v2/Payment/Start API endpoint.

Differences between Reservation and Delayed Capture

Reservation and Delayed Capture scenarios share a lot of similarities, however there are some differences:

  • fees in reservation payments are deducted upfront from the original, prepared amount, in contrast in delayed capture payments it is deducted, when capturing the payment from the final, captured amount
  • all transactions are not required, when finishing a reservation payment, however this is not the case when capturing a delayed capture payment, all transactions must be present in the api call
  • a reservation payment can be finished in multiple steps (meaning that the finish endpoint can be called more than once for the same payment), however a delayed capture can be captured only a single time
  • the available time window in case of reservation is up to 365 days, but delayed capture is limited to a maximum of 21 days, in case of a Hungarian shop, 7 days otherwise

The lifecycle of a delayed capture payment

1. The merchant prepares the payment

Preparing the payment is identical to the Responsive Web Payment scenario, the two differences are that the payment type must be set to Delayed Capture, and the caller must provide a delayed capture period.

2. The customer completes the payment

When the payer's funding source gets charged successfully, the amount gets reserved on the payer's card.

At this moment the Delayed Capture period timer starts and the payment enters into Authorized status. A callback is sent to the merchant.

NOTE: the Barion Smart Gateway user interface is identical in all payment scenarios. The customer might not be (as they are not needed to be) aware that there is a delayed capture taking place in the background! Should this be an issue, the merchant should clarify this in their own respective environment.

3.a. The merchant captures the payment

Unless the delayed capture period timer passes, the merchant has to capture the payment in order to claim the amount. When capturing a payment, the merchant must provide the amount they want to capture the payment with. In layman's terms the merchant is stating that "of this reserved amount of X, I would like to receive Y in the end", where 0 <= Y <= X. This is done per payment transaction. The merchant must capture all transactions contained in a payment in one single API call, hence this endpoint can be called only once per payment.

The finishing amount must not exceed the prepared amount for a payment transaction. The merchant can also finish a payment with the total amount of zero, if they want to cancel or storno the payment. In this step the block of the amount on the payer's card is released, and charged with the final amount, which is available in the wallet of the merchant.

Alternatively instead of calling the /Payment/Capture with 0 amount, the more lightweight /Payment/CancelAuthorization can be used. The underlying process is the same for both endpoints.

IMPORTANT: if the bank card becomes unavailable (it is either expired or blocked by the owner) by the time of capturing the payment, then the capture will fail and the merchant will not receive the prepared amount.

If the merchant captures the reservation successfully, the payment enters into Succeeded status. A callback is sent to the merchant.

3.b. Delayed capture timer elapses

If there was no capturing before the delayed capture timer passes, all transactions in the payment are automatically finished with an amount of zero. The block on the payer's card is lifted. The payment enters into Expired status

In either case, a callback is sent to the merchant.