Latest revision as of 10:59, 8 April 2024

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.

@@ Line 1: / Line 1: @@
-{{PageTitle|title=Payment with reservation}}
+{{PageTitle|title=Payments with reservation / escrow}}
-If at the moment of payment the amount of the transaction is not eventual, it is possible to reserve the money, and finalize it later in one or more steps. In case of reservation there is only one condition, the final amount cannot be higher then the reserved one. If the reservation ends with 0 currency, the reserved amount will be refunded to the user. Reservations both work with e-money or bank cards.  If bank card was used the amount will be immediatly sent to the payee, in case of e-money the amount will be reserved at the payer. The  reserved money can not be used until the reservation finished
+{| style="margin-left:2em;" align="right"
+| __TOC__
-== The payment process ==
+|}
-# In this scenario the payment starts with the '''preparation''' of the payment. This means that the webshop creates a JSON representation of the payment data. This data contains all the necessary information about the items to be purchased, the customer and the desired payment scenario.  This JSON should be sent as the body of a POST request to the <code>/v2/Payment/Start</code> API endpoint. After the system recives the data it will be validated. If all the properties are correct a payment will be prepared in the database and a HTTP response is returned to the webshop.
-# The '''response''' should be processed by the webshop system and the Id of the payment (<tt>PaymentId</tt>) should be extracted from the response. This Id should be stored in the webshop database with the initial information about the payment. This is necessary because every following request is based on this Id.
-# The next step is to '''redirect''' the customer to the Barion website to a specific URL with the <tt>PaymentId</tt> as a query parameter.
-# After the customer paid the requested amount and the payment is completed a server to server request is initiated by Barion towards the webshop. This is called the '''callback mechanism'''.
-# At this point the customer is advised on the screen to return to the webshop to complete the process. If the customer clicks through the customer is '''redirected''' back to the webshop.
-# At any point of the process the webshop can request information about the payment through the <code>v2/Payment/GetPaymentState</code> API endpoint.
-# The reservation should be finished at a later time ( within the <tt>ReservationPeriod</tt> ) trought the <code>v2/Payment/FinishReservation</code> API endpoint.
-== Preparing the payment ==
-To prepare a new payment an HTTP POST request should be made to the [[Payment-Start-v2|<tt>/v2/Payment/Start</tt>]] API endpoint. The body of this request should contain a well-formed JSON representation of the desired payment process. To see the full specification of this endpoint head over to the [[Payment-Start-v2|API reference]].
-''' Structure '''
-The structure of a Barion Gateway payment is hierarchical. The payment is the meta information that describes the process. This payment contains at least one transaction. The transaction represents a financial transfer from a customer to a seller. The payment can contain multiple transactions, this is up to the webshop to decide how the structure of the whole process should be represented. The purchased products should be represented in the <tt>Items </tt> array of the transactions. The total payment amount will be calculated from the attached transactions. The amount specified for the items is not validated against the transaction Total it is up to the integrator to make sure it is calculated appropriately.
-''' Identification '''
-To make sure that the payment can be properly identified always generate an Id for the payment, that is is unique in the webshop. This should be sent in the <code>PaymentRequestId</code> property. This is true for all the transactions attached to the payment. For this user the <code>POSTransactionId</code> of the [[PaymentTransaction]] entity. If the webshop only handles one transaction per payment it is possible to use the same Id for both the <code>PaymentRequestId</code> and the <code>POSTransactionId</code> although it is not recommended. In addition to this you can also provide an <code>OrderNumber</code> for the payment.
+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.
-'''Payment scenario'''
+== Prerequisites ==
+In order to implement reservation 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 this scenario the <code>PaymenType</code> should be set to <code>Reservation</code> indicating that the financial transaction should be finished at a later time. This means that the amount charged will be placed to reservation until the transaction is not completed. The property <code>ReservationPeriod</code> should  be set as well, indicating how long will the reservation stay active.
+{{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}}
-Every attached transaction has a <code>Payee</code> property. That property indicates the user wallet that will receive the amount of the transaction. It is very important to make sure that this wallet ''is the same wallet'' that opened the webshop. In technical terms the <code>POSKey</code> provided should belong to one of the Payee's shop. This is valid for all the transactions attached to the particular payment. If one of the payees is different the scenario autmatically will be upgraded to sharing economy scenario.
+== Key differences when using reservation ==
-'''Currency'''
+=== 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 [[Payment-FinishReservation-v2|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 [[Payment-Start-v2|v2/Payment/Start]] API endpoint.
-You can define the currency of the payment by specifying the <tt>Currency</tt> payment property. It is important to mention that multi-currency transactions are not supported. This means that the currency you define for the payment will be automatically the currency of all the attached transactions. The currency also defines the available precision of the transaction <tt>Total</tt>. For example for HUF payments no decimal digits allowed while for EUR payments two decimal digits can be used. To be able to receive payments in the selected currency the shop has to have an account created in that currency in the wallet. This means that if the shop only has HUF and USD accounts in its wallet, EUR payments will not be allowed to prepare. However in case of market place or sharing economy scenario, the agents and facilitator's accounts will be created for the given currency ( if not existed already).
+=== 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.
-''' Example preparation'''
+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.
-This is an example POST Start with minimum provided information.
+If the merchant does not have enough money to cover the fees, the [[Payment-Start-v2|/Payment/Start]] endpoint will return a <code>DoNotHaveEnoughMoneyToPreparePayment</code> error code.
-{{NotificationBox|title=IMPORTANT|text=Always double check your POSKey and Payee properties. The POSKey is different in the sandbox and live Barion systems.|color=#FF7A3D}}
-<syntaxhighlight lang="json">
-{
-    "POSKey": "630ee026-3e19-469f-8325-afc9bd1ae6a6",
-    "PaymentType": "Reservation",
-    "ReservationPeriod": "1.00:00:00",
-    "PaymentRequestId": "TEST-01",
-    "GuestCheckOut" : true,
-    "FundingSources": ["All"],
-    "Transactions": [
-        {
-            "POSTransactionId": "TEST-01-01",
-            "Payee": "{{shoplogin}}",
-            "Total": "1000",
-            "Comment": "A brief description of the transaction",
-            "Items": [
-                {
-                    "Name": "iPhone 7 smart case",
-                    "Description": "Durable elegant phone case / matte black",
-                    "Quantity": 1,
-                    "Unit": "piece",
-                    "UnitPrice": 25.2,
-                    "ItemTotal": 25.2,
-                    "SKU": "EXMPLSHOP/SKU/PHC-01"
-                }
-            ]
-        }
-    ]
-}
-</syntaxhighlight>
+== The lifecycle of a reservation 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 Reservation, and the caller must provide a reservation period.
-==== Example success response ====
+==== 2. The customer completes the payment ====
-In this response there are no errors because the <code>Errors</code> array is empty. There is no fee charged for the payment because there is only one transaction in the <code>Transactions</code> array and it's the one the webshop sent in.
+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 <u>of the payer</u>
-<source lang="json">
+* when paying with bank card, the amount is transferred to the merchant, and stays reserved in the wallet <u>of the merchant</u>
-{
+At this moment the Reservation period timer starts and the payment enters into <code>Reserved</code> status. A callback is sent to the merchant.
-    "PaymentId": "00e75116f5ea4cd2b09cc95dcd1eff30",
-    "PaymentRequestId": "TEST-01",
-    "Status": "Prepared",
-    "QRUrl": "https://api.demo.barion.com/qr/generate?paymentId=00e75116-f5ea-4cd2-b09c-c95dcd1eff30&size=Large",
-    "Transactions": [
-        {
-            "POSTransactionId": "TEST-01-01",
-            "TransactionId": "8056a2755d4543f294a7d861fc9b41ca",
-            "Status": "Prepared",
-            "Currency": "HUF",
-            "TransactionTime": "2017-12-13T09:45:57.118",
-            "RelatedId": null
-        }
-    ],
-    "RecurrenceResult": "None",
-    "GatewayUrl": "https://secure.demo.barion.com:443/Pay?Id=00e75116f5ea4cd2b09cc95dcd1eff30",
-    "RedirectUrl": "https://testshop.demo.barion.com/Redirect?paymentId=00e75116f5ea4cd2b09cc95dcd1eff30",
-    "CallbackUrl": "https://testshop.demo.barion.com/callback?paymentId=00e75116f5ea4cd2b09cc95dcd1eff30",
-    "Errors": []
-</source>
-=== Processing the error response ===
-If there is something wrong during the preparation an error response will be provided. If this happens the <code>Errors</code> array will be filled out with information about the problem.
-==== Possible error responses ====
-{| class="wikitable api-table"
-! Error code || Description
-|-
-| ModelValidationError || This happens when some of the input properties fail the basic validation. For example when transaction set to reservation but no ReservationPeriod was given
-|-
-| AuthenticationFailed || The provided <code>POSKey</code> is invalid. Check that the key used is appropriate for the environment. The test and production environment are separate so the keys are only valid for one environment. Another problem could be that the provided key is the public key and not the private key. For API requests the secret API key should be used.
-|-
-| ShopIsClosed || The shop is closed in the Barion system, no payments are allowed.
-|-
-| InvalidUser|| There is a problem with one of the participants taking part in the payment. All of them should be registered Barion users.
-|-
-| UserCantReceiveEMoney|| There is a problem with the recipient of the payment. Every <code>Payee</code> specified in the attached transactions should be a fully registered user of Barion.
-|-
-| NotExistingCurrency || The currency specified for the payment is not supported by the Barion system.
-|-
-| InvalidFundingSource || The specified funding source is not valid. Check the <code>FundingSources</code> input parameter.
-|-
-| InvalidCulture || The specified culture is not supported by the Barion system.
-|-
-| DoNotHaveEnoughMoneyToPreparePayment || In certain corner cases when the webshops Barion balance and the incoming money is not enough to cover the Barion fee this error message is sent.
-|-
-| PaymentStatusNotValid || The status of the payment is InProgress already.
-|-
-|}
-==== Example error response ====
+'''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.
-For example this is the error response when the authentication data (the <code>POSKey</code>) is not correct.
-<source lang="json">
+==== 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 <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>. 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.
-  "Errors": [
-    {
-      "ErrorCode": "AuthenticationFailed",
-      "Title": "User authentication failed.",
-      "Description": "The login information provided is incorrect. There is no such user in the system or the password is incorrect.",
-      "EndPoint": "https://api.barion.com/v2/payment/start",
-      "AuthData": null,
-      "HappenedAt": "2017-02-03T13:18:07.8878292Z"
-    }
-  ]
-}
-</source>
-== Redirecting the customer ==
+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.
-After a successful payment preparation the next step is to redirect the customer to the secure Barion site. The URL is provided in the response of the <code>Payment/Start</code> request. '''Make sure that the user is redirected properly no iframe hacks are allowed.''' At this point the webshop gives the flow control to the Barion system. There is no need for constant <code>GetPaymentState</code> requests, at least for a reasonable time period. The callback mechanism will take care of the notification. However mistakes could happen so after a reasonable time the webshop can make a <code>GetPaymentState</code> request just to rule out any callback errors. Again, this should not be frequent, let the user fill out its credit card information. If you want to shorten the period the user is allowed to pay you can specify this time period in the <code>PaymentWindow</code> property.
+* 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.
-Once the customer arrives to the secure Barion server the payment GUI is displayed. At this point the customer either pays with e-money or with its credit card. If the payment fails for any reason (invalid card for example) the customer can try the payment again '''without leaving the Barion payment GUI'''. This means that the customer won't return automatically to webshop when the payment fails. This is worth mentioning because this could lengthen the time the customer takes at the Barion server.
+'''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
-{{NotificationBox|title=IMPORTANT|text=Do not try to pay with the account that owns the shop! It is not permitted to purchase in your own shop!|color=#FF7A3D}}
+'''NOTE:''' bank card refunds can take up to 30 days depending on the bank system!
-== Processing the callback ==
+'''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!
-Once the payment completed a callback request is sent to webshop's server to the specified URL. In fact any change happens in the state of the payment a callback is sent out to notify the webshop. This can be interpreted as a signal to start a <code>GetPaymentState</code> request towards the Barion system. '''The callback signal is only a signal does not indicate the success of the payment!''' Therefore a <code>GetPaymentState</code> request is mandatory to make sure that the appropriate payment state is registered in the webshop as well. Read more about the whole [[Callback_mechanism|callback mechanism]].
-{{NotificationBox|title=WARNING|text=Flooding the Barion servers with unnecessary API calls, instead of relying on the callback mechanism, may lead to suspension of the shop.|color=#ff0000}}
+If the merchant finishes the reservation successfully, the payment enters into <code>Succeeded</code> status. A callback is sent to the merchant.
-== Requesting information about the payment ==
+==== 3.b. Reservation timer elapses ====
-Once the webshop server received the callback the webshop needs to request information about the outcome of the payment process. For this a [[Payment-GetPaymentState-v2|<tt>Payment/GetPaymentState</tt>]] request should be sent to the Barion API.
+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 <code>PartiallySucceeded</code> status
+* if there was no finished transactions at all, the payment enters into <code>Expired</code> status
+In either case, a callback is sent to the merchant.
-== Processing the returning customer ==
+[[file:reservation_demo.png|1100px]]
-At the end of the payment process the customer decides whether to return to the webshop or just close the browser. Therefore '''no financial decision should be made based on the returning customer'''. The only valid way to decide what to do with the order to request information about the payment through the GetPaymentState API endpoint.
 == Reference ==
-* [[Payment-GetPaymentState-v2|/Payment/GetPaymentState]]
+* [[Payment-PaymentState-v4|/v4/Payment/<PaymentId>/PaymentState]]
 * [[Payment-Start-v2|/Payment/Start]]
-* [[Payment-FinishReservation|/Payment/FinishReservation]]
+* [[Payment-FinishReservation-v2|/Payment/FinishReservation]]

Reservation payment: Difference between revisions