|
|
| (24 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| {{PageTitle|title=Marketplace and facilitated payments}} | | {{PageTitle|title=Marketplace, sharing economy, and facilitated payments}} |
|
| |
|
| {| style="margin-left:2em;" align="right" | | {| style="margin-left:2em;" align="right" |
| Line 5: |
Line 5: |
| |} | | |} |
|
| |
|
| In this scenario the shop works as a facilitator, handling the payment transactions but the user do not pay for the shop but for another user. Both facilitator and agents ( if any included) receive a fee.
| | Payment facilitation is a special kind of payment scenario, where the payment itself is supervised by a third party. This means that a supervising shop (called the '''facilitator''') defines all parameters for a payment, but it does not take part in the process as a payee. This is useful in marketplace and sharing economy scenarios, where the customer buys products and services from various sellers, under the management of a service provider. The service provider may also charge fees for the service that is paid by the seller. |
| | |
| | '''''Example:''' consider calling an Uber - the car driver is the seller, the passenger is the customer, and the company Uber is the facilitator. The money travels between the passenger and the driver, while the company deducts a fee from the driver.'' |
|
| |
|
| == Prerequisites == | | == Prerequisites == |
| The prerequisites is similar to [[Responsive_web_payment|Responsive web payment]].
| | To successfully implement facilitated payments, you need to familiarize yourself with the simple [[Responsive_web_payment|Responsive Web Payment]] scenario, and, in case you wish to combine it with the reservation feature, also [[Reservation_payment|Reservation payments]]. The preparation of payments, redirection to the Barion Smart Gateway and handling the [[Callback mechanism]] are identical to all other scenarios. |
|
| |
|
| == The Payment Process == | | {{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}} |
| The payment process is similar to [[Responsive_web_payment|Responsive web payment]]. However in this case the facilitator is responsible to manage the payment.
| |
|
| |
|
| | == The marketplace scenario == |
| | The payment process is similar to all other scenarios. The only difference is that the API calls are placed by the facilitator. Neither the customer nor the payee takes any action. |
|
| |
|
| This example shows the process of a marketplace payment.
| | The basic structure of a facilitated payment consists of the facilitator, the customer, and one or more sellers. See the figure below. |
|
| |
|
| | |
|
| |
|
| [[file:sharing-economy-marketplace-nocontributor.png|700px]] | | [[file:sharing-economy-marketplace-nocontributor.png|700px]] |
|
| |
|
| == Preparing the payment == | | == Seller accounts == |
| 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 for the facilitator. 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 facilitator 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.
| |
| | |
| '''Payment scenario'''
| |
|
| |
|
| Every attached transaction has a <code>Payee</code> property. That property indicates the user wallet that will receive the amount of the transaction. In this scenario there should be at least one payee who is not the same as the one with the provided <code>POSKey</code>.
| | When taking part in a facilitated payment, the seller (payee) must have a registered, activated Barion wallet. They do not need to have a shop though. |
|
| |
|
| '''Currency''' | | '''Good to know:''' if the seller does not have an account with the payment's currency, it will automatically be created for them upon successful payment. |
| | |
| You can define the currency of the payment by specifying the Currency 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 Total. For example for HUF payments no decimal digits allowed while for EUR payments two decimal digits can be used. 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 yet).
| |
| | |
| | |
| This is an example POST Start.
| |
| {{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": "Immediate",
| |
| "PaymentRequestId": "TEST-01",
| |
| "GuestCheckOut" : true,
| |
| "FundingSources": ["All"],
| |
| "Currency":"EUR",
| |
| | |
| "Transactions": [
| |
| {
| |
| "POSTransactionId": "EXMPLSHOP-PM-001/TR001",
| |
| | |
| "Total": 37.2,
| |
| "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"
| |
| },
| |
| ],
| |
| "PayeeTransactions": [
| |
| {
| |
| | |
| "POSTransactionId": "TEST-01-AGENTFEE-02",
| |
| "Total": 30,
| |
| "Comment": "Agent Fee"
| |
| },
| |
| {
| |
| | |
| "POSTransactionId": "TEST-01-FACILITATORFEE-02",
| |
| "Total": 10,
| |
| "Comment": "Facilitator Fee"
| |
| }
| |
| ]
| |
| }
| |
| ]
| |
| }
| |
| </syntaxhighlight>
| |
| | |
| === Processing the successful response ===
| |
| | |
| After a successfully preparing the payment a JSON response is sent back as response. This JSON should be processed and some properties should be saved in the database of the webshop. The single most important property of this JSON is the <tt>PaymentId</tt>. This should be saved into the database of the webshop along the the ids of the transactions (<code>TransactionId</code>) attached.
| |
| | |
| The successful response will also contain the appropriate URL where the customer should be redirected so the integration doesn't have to hard-code any URL. This information is displayed in the <code>GatewayUrl</code>.
| |
| | |
| At this point the ''Status'' of the payment should be <code>Prepared</code>. This means that all the necessary information is prepared for the payment but no financial transfer happened yet.
| |
| | |
| In the <code>Transactions</code> array are all the transaction that were processed. This array also contains the various fee transactions as well. So if there are transaction here that are not familiar it's because they were not sent by the webshop.
| |
| | |
| ==== Example success response ====
| |
| In this response there are no errors because the <code>Errors</code> array is empty. The transactions for agent and facilitator fees is prepared aswell.
| |
| | |
| <source lang="json">
| |
| {
| |
| "PaymentId": "105d618968e5489c8d18e2439b99e5c2",
| |
| "PaymentRequestId": "TEST-01",
| |
| "Status": "Prepared",
| |
| "QRUrl": "https://api.demo.barion.com/qr/generate?paymentId=105d6189-68e5-489c-8d18-e2439b99e5c2&size=Large",
| |
| "Transactions": [
| |
| {
| |
| "POSTransactionId": "TEST-01-01",
| |
| "TransactionId": "a0715a9cd1df4318a8ea9c2fd8a8c334",
| |
| "Status": "Prepared",
| |
| "Currency": "EUR",
| |
| "TransactionTime": "2017-12-13T12:03:02.275",
| |
| "RelatedId": null
| |
| },
| |
| {
| |
| "POSTransactionId": "TEST-01-AGENTFEE-02",
| |
| "TransactionId": "bff280b111104a929ce17886cd76a2a5",
| |
| "Status": "Prepared",
| |
| "Currency": "EUR",
| |
| "TransactionTime": "2017-12-13T12:03:02.275",
| |
| "RelatedId": "a0715a9cd1df4318a8ea9c2fd8a8c334"
| |
| },
| |
| {
| |
| "POSTransactionId": "TEST-01-FACILITATORTFEE-02",
| |
| "TransactionId": "385af623920a4a2c8a153ebf0965f9a2",
| |
| "Status": "Prepared",
| |
| "Currency": "EUR",
| |
| "TransactionTime": "2017-12-13T12:03:02.29",
| |
| "RelatedId": "a0715a9cd1df4318a8ea9c2fd8a8c334"
| |
| }
| |
| ],
| |
| "RecurrenceResult": "None",
| |
| "GatewayUrl": "https://secure.demo.barion.com:443/Pay?Id=105d618968e5489c8d18e2439b99e5c2",
| |
| "RedirectUrl": "https://testshop.demo.barion.com/Redirect?paymentId=105d618968e5489c8d18e2439b99e5c2",
| |
| "CallbackUrl": "https://testshop.demo.barion.com/callback?paymentId=105d618968e5489c8d18e2439b99e5c2",
| |
| "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 ====
| |
| For example this is the error response when the authentication data (the <code>POSKey</code>) is not correct.
| |
|
| |
|
| <source lang="json">
| | == The lifecycle of a facilitated payment == |
| {
| | ==== 1. The facilitator prepares the payment ==== |
| "Errors": [
| | Preparing the payment is identical to the [[Responsive_web_payment|Responsive Web Payment]] scenario. The facilitator specifies the payee[s], and the optional payment parameters. |
| {
| |
| "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 == | | ==== 2. The customer completes the payment ==== |
| 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. | | After the customer completes the payment via the Barion Smart Gateway, the money is transferred to the facilitator. |
| | A callback is sent to the facilitator. |
|
| |
|
| 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.
| | On the Barion Smart Gateway user interface the customer will see that the payee is the facilitator, while the sellers and items are listed in the payment details |
|
| |
|
| {{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}}
| | [[file:barion_marketplace_example_screenshot.png|700px]] |
|
| |
|
| == Processing the callback == | | ==== 3. The sellers receive the money ==== |
| 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]].
| | The Barion system distributes the paid amount among the sellers, according to the payment transactions specified by the facilitator when preparing the payment, and also processes all payee transactions (if applicable). |
| | * At this point the location and availability of the money depends on wether the facilitator uses [[Responsive_web_payment|Immediate]] or [[Reservation_payment|Reservation]] payments. See the corresponding article for details. |
|
| |
|
| {{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}}
| | == Refunding facilitated payments == |
| | When using facilitated payments, refund is a special case. As long as a reservation payment is not finished, the facilitator has complete control of the process and is able to refund the amount by finishing the payment transactions with zero amount. However, in case of a completed immediate or a finished reservation payment, the facilitator no longer has control over the process. This means that incurring refunds must be done by the seller. The facilitator and the seller must ensure the legal compliance of this in their respective environment. |
|
| |
|
| == Requesting information about the payment == | | == Example == |
| 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.
| |
|
| |
|
| == Processing the returning customer ==
| | Please check out the [[Marketplace_Example|detailed example of a marketplace payment]] page for more informations. |
| 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 == | | == Reference == |
| * [[Payment-GetPaymentState-v2|/Payment/GetPaymentState]]
| |
| * [[Payment-Start-v2|/Payment/Start]] | | * [[Payment-Start-v2|/Payment/Start]] |
| | * [[Payment-PaymentState-v4|/v4/Payment/<PaymentId>/PaymentState]] |
| | * [[Payment-FinishReservation-v2|/Payment/FinishReservation]] |
Marketplace, sharing economy, and facilitated payments
Payment facilitation is a special kind of payment scenario, where the payment itself is supervised by a third party. This means that a supervising shop (called the facilitator) defines all parameters for a payment, but it does not take part in the process as a payee. This is useful in marketplace and sharing economy scenarios, where the customer buys products and services from various sellers, under the management of a service provider. The service provider may also charge fees for the service that is paid by the seller.
Example: consider calling an Uber - the car driver is the seller, the passenger is the customer, and the company Uber is the facilitator. The money travels between the passenger and the driver, while the company deducts a fee from the driver.
Prerequisites
To successfully implement facilitated payments, you need to familiarize yourself with the simple Responsive Web Payment scenario, and, in case you wish to combine it with the reservation feature, also Reservation payments. The preparation of payments, redirection to the Barion Smart Gateway and handling the Callback mechanism are identical to all other scenarios.
NOTE
It is VERY strongly advised to have a detailed knowledge about the payment process, the simple immediate payment scenario and the callback processing.
The marketplace scenario
The payment process is similar to all other scenarios. The only difference is that the API calls are placed by the facilitator. Neither the customer nor the payee takes any action.
The basic structure of a facilitated payment consists of the facilitator, the customer, and one or more sellers. See the figure below.
Seller accounts
When taking part in a facilitated payment, the seller (payee) must have a registered, activated Barion wallet. They do not need to have a shop though.
Good to know: if the seller does not have an account with the payment's currency, it will automatically be created for them upon successful payment.
The lifecycle of a facilitated payment
1. The facilitator prepares the payment
Preparing the payment is identical to the Responsive Web Payment scenario. The facilitator specifies the payee[s], and the optional payment parameters.
2. The customer completes the payment
After the customer completes the payment via the Barion Smart Gateway, the money is transferred to the facilitator.
A callback is sent to the facilitator.
On the Barion Smart Gateway user interface the customer will see that the payee is the facilitator, while the sellers and items are listed in the payment details
3. The sellers receive the money
The Barion system distributes the paid amount among the sellers, according to the payment transactions specified by the facilitator when preparing the payment, and also processes all payee transactions (if applicable).
- At this point the location and availability of the money depends on wether the facilitator uses Immediate or Reservation payments. See the corresponding article for details.
Refunding facilitated payments
When using facilitated payments, refund is a special case. As long as a reservation payment is not finished, the facilitator has complete control of the process and is able to refund the amount by finishing the payment transactions with zero amount. However, in case of a completed immediate or a finished reservation payment, the facilitator no longer has control over the process. This means that incurring refunds must be done by the seller. The facilitator and the seller must ensure the legal compliance of this in their respective environment.
Example
Please check out the detailed example of a marketplace payment page for more informations.
Reference
