Latest revision as of 08:56, 15 November 2024

Delayed Capture

A delayed capture payment scenario means that upon completing the payment, 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 time window, the amount is unavailable for both the payer and the payee. 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 is immediately charged, and the amount is blocked in the Barion system. In a delayed capture scenario the payer is only charged upon the capture request, until then the amount is only blocked on the payer's card. Since the money stays on the payer's account until the capture is done, delayed capture payments are not visible in the history, excel export and account history, until the capture. If the payment is canceled, it does not appear at all.

NOTE

Delayed capture is currently available if the payer uses his bank card. Paying from Barion balance or wire transfer with bank button is not supported.

Prerequisites

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. Delayed capture scenarios involve elements added to the immediate payment scenario.

NOTE

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

Difference between Immediate Payment and 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 7 days, or up to 21 days for Hungarian shops) 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:


	Reservation	Delayed capture
Fees	Fees are deducted upfront from the original reserved amount.	Fees are deducted during capture, from the final, captured amount.
Separation of transactions	Individual transactions in a reservation payment may be completed independently of each other.	All transactions that make up a payment must be present in the (capturing or cancelling) API call.
Piecemeal payments	Reservation payments may be completed in multiple steps – the FinishReservation endpoint may be called multiple times for the same payment.	The same payment cannot be captured more than once.
Time window	Up to 365 days	7 days/21 days (for shops in Hungary)
Transaction visibility	Reservation payments show up in the payment history immediately.	Delayed capture payments aren't visible in the payment history (including Excel reports and statements) until the capture is complete.

The lifecycle of a delayed capture payment

1. The merchant prepares the payment

Preparing the payment is identical to the Responsive Web Payment scenario, except 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 card is auhorized successfully, the amount gets reserved on the payer's account.

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 won't be aware that a delayed capture is taking place unless the merchant wants to clarify this in their own respective environment.

3.a. The merchant captures or cancels the payment

The merchant has to capture the payment in order to claim the amount before the time set in DelayedCapturePeriod passes. When capturing a payment, the merchant must provide the amount he/she wants 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. If there are more than one transactions in a delayed capture payment, the merchant must capture all of these in a single call to the /Payment/Capture API endpoint.

The finishing amount must not exceed the original amount for a payment transaction. The merchant can also finish a payment with the total amount of zero, if they want to cancel the payment. In the capture step the payer is charged with the final amount and if the final amount is less than the original, the difference is released. The charged amount becomes 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 card issuer releases the hold on the payer's card for any reason, you won’t be able to capture the payment. The capture can also fail if the card is unavailable at the time—for example, if it has expired, been blocked by the cardholder, or the issuer has removed the hold on the funds. This means you should wait until the capture is successful before fulfilling the purchase to ensure you receive the payment.

IMPORTANT: The card issuer can arbitrarily lift the block of the amount on the payer's card, therefore you will be unable to capture it. If the bank card is unavailable (because it had expired, or been blocked by the owner, or because the bank had lifted the block on the amount) at the time of capture, the capture fails, and the merchant will not receive the money.

If the merchant captures the final amount or cancels the the capture successfully, the payment enters into Succeeded status. A callback is sent to the merchant.

3.b. Delayed capture period elapses

If the payment was not captured before the time set in DelayedCapturePeriod,

all transactions in the payment are automatically canceled,
the block on the payer's card is lifted,
the payment enters into Expired status,
and a callback is sent to the merchant.

@@ Line 2: / Line 2: @@
 {{PageTitle|title=Delayed Capture}}
-{{TestEnvironmentOnly}}
+A delayed capture payment scenario means that upon completing the payment, 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 time window, the amount is unavailable for both the payer and the payee. The merchant has the right to decide whether to capture or cancel the purchase. It is very similar to [[Reservation_payment|Reservation payment]], the key difference is where the money is blocked. In a reservation scenario, the payer is immediately charged, and the amount is blocked in the Barion system. In a delayed capture scenario the payer is only charged upon the capture request, until then the amount is only blocked on the payer's card. Since the money stays on the payer's account until the capture is done, delayed capture payments are not visible in the history, excel export and account history, until the capture. If the payment is canceled, it does not appear at all.
-A delayed capture payment scenario means that upon completing the payment, 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 time window, the amount is unavailbale for both the payer and the payee. The merchant has the right to decide whether to capture, or cancel the purchase. It is very similar to [[Reservation_payment|Reservation payment]], the key difference is where the money is blocked. In a reservation scenario, the payer is immediately charged, and the amount is blocked in the Barion system. In a delayed capture scenario the payer is only charged upon the capture request, until then the amount is only blocked on the payer's card. Since the money stays on the payer's account until the capture is done, delayed capture payments are not visible in the history, excel export and account history, until the capture. If the payment is canceled, it does not appear at all.
 {{NotificationBox|title=NOTE|text=Delayed capture is currently available if the payer uses his bank card. Paying from Barion balance or wire transfer with bank button is not supported.|color=#1993C7}}
@@ Line 10: / Line 8: @@
 == Prerequisites ==
-In order to implement delayed capture payments, you need to familiarize yourself with the simple [[Responsive_web_payment|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.
+In order to implement delayed capture payments, you need to familiarize yourself with the simple [[Responsive_web_payment|Responsive Web Payment]] scenario. The preparation of payments, redirection to the Barion Smart Gateway and handling the [[Callback mechanism]] are identical to immediate payments. Delayed capture scenarios involve elements added to the immediate payment scenario.
 {{NotificationBox|title=NOTE|text=It is VERY strongly advised to have a detailed knowledge about the payment process, the simple immediate payment scenario and the callback processing.|color=#1993C7}}
@@ Line 18: / Line 16: @@
 === 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 [[Payment-Capture-v2|v2/Payment/Capture]] or the [[Payment-CancelAuthorization-v2|v2/Payment/CancelAuthorization]] API endpoint.
-The time window available (up to 7 days, but for Hungarian shop 21 days) is also set by the merchant during the preparation of the payment - see the ''DelayedCapturePeriod'' parameter in the [[Payment-Start-v2|v2/Payment/Start]] API endpoint.
+The time window available (up to 7 days, or up to 21 days for Hungarian shops) is also set by the merchant during the preparation of the payment – see the ''DelayedCapturePeriod'' parameter in the [[Payment-Start-v2|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 reserved amount, in contrast in delayed capture payments it is deducted when capturing the payment from the final, captured amount.
+{| class="wikitable"
-* You can finish individual transactions separately of a reservation payment, however this is not the case when capturing a delayed capture payment. All transactions of the payment must be present in the api call (either capture or cancel).
+|+
-* 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, on the other hand delayed capture is limited to a maximum of 7 days (21 days in case of a Hungarian shop).
+!Reservation
-* In case of delayed capture, the payment is not visible (nor in the history, neither in the excel export, neither in the staements) until the capture is done, in contrast to reservation, where the payment is visible from the start.
+!Delayed capture
+|-
+|Fees
+|Fees are deducted upfront from the original reserved amount.
+|Fees are deducted during capture, from the final, captured amount.
+|-
+|Separation of transactions
+|Individual transactions in a reservation payment may be completed independently of each other.
+|All transactions that make up a payment must be present in the (capturing or cancelling) API call.
+|-
+|Piecemeal payments
+|Reservation payments may be completed in multiple steps – [[Payment-FinishReservation-v2|the FinishReservation endpoint]] may be called multiple times for the same payment.
+|The same payment cannot be captured more than once.
+|-
+|Time window
+|Up to 365 days
+|7 days/21 days (for shops in Hungary)
+|-
+|Transaction visibility
+|Reservation payments show up in the payment history immediately.
+|Delayed capture payments aren't visible in the payment history (including Excel reports and statements) until the capture is complete.
+|}
 == The lifecycle of a delayed capture payment ==
 ==== 1. The merchant prepares the payment ====
-Preparing the payment is identical to the [[Responsive_web_payment|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.
+Preparing the payment is identical to the [[Responsive_web_payment|Responsive Web Payment]] scenario, except 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 ====
@@ Line 37: / Line 59: @@
 At this moment the Delayed Capture period timer starts and the payment enters into <code>Authorized</code> 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.
+'''NOTE:''' the Barion Smart Gateway user interface is identical in all payment scenarios. The customer won't be aware that a delayed capture is taking place unless the merchant wants to clarify this in their own respective environment.
 ==== 3.a. The merchant captures or cancels the payment ====
-The merchant has to capture the payment in order to claim the amount before the time set in DelayedCapturePeriod passes. When capturing a payment, the merchant must provide the amount he/she wants to capture the payment with. In layman's terms the merchant is stating that ''"of this reserved amount of <b>X</b>, I would like to receive <b>Y</b> in the end"'', where <code>0 <= Y <= X</code>. This is done <u>per payment transaction</u>. If there are more than on transaction in a payment, the merchant must capture all transactions in one single API call, hence this endpoint can be called only once per payment.
+The merchant has to capture the payment in order to claim the amount before the time set in ''DelayedCapturePeriod'' passes. When capturing a payment, the merchant must provide the amount he/she wants to capture the payment with. In layman's terms the merchant is stating that ''"of this reserved amount of <b>X</b>, I would like to receive <b>Y</b> in the end"'', where <code>0 <= Y <= X</code>. This is done <u>per payment transaction</u>. If there are more than one transactions in a delayed capture payment, the merchant must capture all of these in a single call to the [[Payment-Capture-v2|/Payment/Capture]] API endpoint.
 The finishing amount must not exceed the original amount for a payment transaction. The merchant can also finish a payment with the total amount of zero, if they want to cancel the payment.
 In the capture step the payer is charged with the final amount and if the final amount is less than the original, the difference is released. The charged amount becomes available in the wallet of the merchant.
-Alternatively instead of calling the [[Payment-Capture-v2|/Payment/Capture]] with 0 amount, the more lightweight [[Payment-CancelAuthorization-v2|/Payment/CancelAuthorization]] can be used. The underlying process is the same for both endpoints.
+Alternatively, instead of calling the [[Payment-Capture-v2|/Payment/Capture]] with 0 amount, the more lightweight [[Payment-CancelAuthorization-v2|/Payment/CancelAuthorization]] can be used. The underlying process is the same for both endpoints.{{NotificationBox|title=IMPORTANT|text=If the card issuer releases the hold on the payer's card for any reason, you won’t be able to capture the payment. The capture can also fail if the card is unavailable at the time—for example, if it has expired, been blocked by the cardholder, or the issuer has removed the hold on the funds.
-'''IMPORTANT:''' The card issuer can arbitrarily lift the block of the amount on tha payer's card, therefore you will be unable to capture it. If the bank card becomes unavailable (it is either expired or blocked by the owner or the bank previously lifted the block) by the time of capturing the payment, the capture will fail and the merchant will not receive the money.
+This means you should wait until the capture is successful before fulfilling the purchase to ensure you receive the payment.|color=#FF7A3D}}'''IMPORTANT:''' The card issuer can arbitrarily lift the block of the amount on the payer's card, therefore you will be unable to capture it. If the bank card is unavailable (because it had expired, or been blocked by the owner, or because the bank had lifted the block on the amount) at the time of capture, the capture fails, and the merchant will not receive the money.
 If the merchant captures the final amount or cancels the the capture successfully, the payment enters into <code>Succeeded</code> status. A callback is sent to the merchant.
 ==== 3.b. Delayed capture period elapses ====
-If the payment was not captured before the time set in DelayedCapturePeriod, all transactions in the payment are automatically canceled. The block on the payer's card is lifted. The payment enters into <code>Expired</code> status and a callback is sent to the merchant.
+If the payment was not captured before the time set in ''DelayedCapturePeriod'',
+* all transactions in the payment are automatically canceled,
+* the block on the payer's card is lifted,
+* the payment enters into <code>Expired</code> status,
+* and a callback is sent to the merchant.
 == Reference ==
-* [[Payment-GetPaymentState-v2|/Payment/GetPaymentState]]
+* [[Payment-PaymentState-v4|/v4/Payment/<PaymentId>/PaymentState]]
 * [[Payment-Start-v2|/Payment/Start]]
 * [[Payment-Capture-v2|/Payment/Capture]]
 * [[Payment-CancelAuthorization-v2|/Payment/CancelAuthorization]]

Delayed Capture: Difference between revisions