Reservation payment

Payments with reservation / escrow

A reservation (escrow) payment scenario means that upon charging the funding source of the payer, the money is not immediately handed over to the merchant. Instead, it becomes reserved (or blocked) for a given period of time. During this time window, the amount is unavailable for both the payer and the payee - consider it similar to a pending card transaction in a bank system. During the reservation period, the merchant has the right to decide whether to finalize, partially finalize or cancel the purchase. This comes in handy in situations where goods or services are not immediately available at the time of purchase, or might become unavailable by the time of shipping/fulfillment.

Prerequisites

In order to implement reservation 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.

NOTE

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 reservation

The finishing step

The most important thing to note when implementing a reservation payment process is that there is an extra step required to complete the payment: finishing the reservation. This must be done by the merchant, before the reservation time runs out. This can be done by calling the v2/Payment/FinishReservation API endpoint. The time window available is also set by the merchant during the preparation of the payment - see the ReservationPeriod parameter in the v2/Payment/Start API endpoint.

Pre-deducted fees

The Barion system deducts fees from the merchant after each payment. In case of immediate payments, this mechanism is quite straightforward: when the payment is completed, the money is transferred to the merchant and the fee is deducted and transferred to the Barion system. When using reservation, this process becomes a bit more complicated.

In order to prepare a reservation payment, the merchant must ensure that they have enough money to cover all the necessary fees for the payment - even if in the end the payment is finished with a smaller amount than prepared! To make sure the merchant does not spend the fees in the meantime, the Barion system reserves the fee amount in the merchant's wallet, and only deducts or releases it when the payment was successfully completed and finished.

If the merchant does not have enough money to cover the fees, the /Payment/Start endpoint will return a DoNotHaveEnoughMoneyToPreparePayment error code.

The lifecycle of a reservation 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 Reservation, and the caller must provide a reservation period.

2. The customer completes the payment

When the payer's funding source gets charged successfully, the amount gets reserved. The location of the money depends on the funding source:

• when paying with Barion wallet, the amount stays reserved in the wallet of the payer
• when paying with bank card, the amount is transferred to the merchant, and stays reserved in the wallet of the merchant

At this moment the Reservation period timer starts and the payment enters into Reserved 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 reservation taking place in the background! Should this be an issue, the merchant should clarify this in their own respective environment.

3.a. The merchant finishes the reservation

Unless the reservation period timer passes, the merchant has to finish the reservation in order to claim the amount. When finishing a reservation, the merchant must provide the amount they want to finish 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 can finish all transactions contained in a payment in one single API call, or in separate calls. However, each payment transaction can only be finished once.

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. The reservation outcome is different depending on the finishing amount.

• if the finishing amount equals to the prepared amount (everything was okay with the payment, all goods have been delivered or services were fulfilled), then the reserved amount is released and becomes available in the wallet of the merchant
• if the finishing amount is less than the prepared amount, but is greater than zero (some goods could not be delivered, the customer did not want all products in the end or a service was only partially fulfilled), the finishing amount is released and becomes available in the wallet of the merchant, and the remaining amount is refunded to the customer
• if the finishing amount is zero (the customer declined the order or the goods/services are not available), the whole amount is refunded to the customer

NOTE: The Barion system does not send a mail message at this point to the customer, it is the responsibility of the merchant to notify their customer about the the final amount.

Refunds during finish

• if the customer paid with their Barion balance, the amount is given back to them and becomes available in their Barion wallet
• if the customer paid with a bank card, the amount is refunded to that bank card

NOTE: bank card refunds can take up to 30 days depending on the bank system!

IMPORTANT: if the bank card becomes unavailable (it is either expired or blocked by the owner) by the time of finishing the reservation, then the refund will fail and the merchant receives the full prepared amount - in this case, it is the merchant's full responsibility to arrange the return of the remaining amount to the customer!

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

3.b. Reservation timer elapses

If there was no finishing before the reservation timer passes, all unfinished transactions in the payment are automatically finished with an amount of zero. In this case, the unfinished amount is refunded to the customer (in the same way as the merchant would have finished the payment).

• if there were any finished transactions in the payment, then the payment enters into PartiallySucceeded status
• if there was no finished transactions at all, the payment enters into Expired status

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

Reference

• /v4/Payment/<PaymentId>/PaymentState
• /Payment/Start
• /Payment/FinishReservation