Marketplace Example: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
VisualWikitext
No edit summary
m (replaced reference to v2 GetPaymentState with v4 PaymentState)
 
(49 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{PageTitle|title=Example of a marketplace pamyent}}
{{PageTitle|title=Detailed example of a marketplace payment}}


This guide's purpose to show an immediate payment process including a facilitator, from end to end.
{{TableOfContents}}


In this example a demo marketplace will be used as the facilitator. This facilitator will manage the payment  process, but it does not take part in the process as a payee. Neither the customer nor the payee(s) take any actions.
=== Introduction ===


The process starts with the shopping part. The user select  products on an arbitrary  site. These products  belongs to manufacturers ( other "users" of the system), therefore the prices of their product will be transferred to them. Both manufacturers have a registered Barion wallet but they do not own a shop in the system.
This example is to show the full life cycle of a purchase made at a marketplace scenario. Through this you will be familiar with how the Barion payment system works in a complex payment situation - how the payments are processed, how the money travels between participants and how the systems communicate with each other. '''Please read this carefully.'''
The demo products will be the followings ( including the manufacturers):
 
{{NotificationBox|title=WARNING|text=Do '''NOT''' copy any JSON content to your project - these are for demonstration purposes only!|color=#FF7A3D}}
 
Imagine Chef Chris would like to buy some groceries and products at the Marketplace. In this case, we are talking about a facilitated payment scenario, where the Marketplace is the facilitator. The facilitator manages and organizes the whole payment process, but they do not take part in it as a final payee. Instead, they distribute the money between the different sellers of the chosen products.
 
=== Starting the payment ===
 
The process starts with the shopping. Chris has put some products / services (referred to as ''items'') in his shopping cart on the Marketplace website. These items belong to different manufacturers / providers / distributors - other users of the Barion system, henceforth referred to as ''sellers''. They all have registered, active Barion wallets but they do not own a shop in the system.
 
Chris has selected four items from two sellers and went to checkout. The Marketplace informs him that there is a one-day period of confirmation from the sellers upon placing an order.


[[File:marketplace_products_example.png]]
[[File:marketplace_products_example.png]]


At this point, the Marketplace prepares the payment trough the Barion API, using the [[Payment-Start-v2|/v2/Payment/Start]] endpoint. Chris is purchasing items from two separate sellers, the payment will contain two payment transactions, with the respective items and payees set accordingly. Since there is a time window where the sellers should confirm the order, the Marketplace prepares a [[Reservation_payment|reservation payment]] with a reservation period of one day.


The next step is start the payment for the selected products via Barion. The facilitator prepares the payment trough the Barion API.
For this API call the request JSON looks like this :
For this concrete payment the JSON file required for [[Payment-Start-v2|Payment Start]] would look like this :


<syntaxhighlight lang="json">  
<syntaxhighlight lang="json">  
{
{
     "POSKey": "60I98E979-Z592-4AA2-BC9F-DF14ABA4P8F17",
     "POSKey": "60I98E979-Z592-4AA2-BC9F-DF14ABA4P8F17",
     "PaymentType": "Immediate",
     "PaymentType": "Reservation",
     "PaymentRequestId": "TEST-01",
    "ReservationPeriod": "1.00:00:00",
     "PaymentRequestId": "MARKETPAY-123456",
     "GuestCheckOut" : true,
     "GuestCheckOut" : true,
     "FundingSources": ["All"],
     "FundingSources": ["All"],
     "Locale":"en-US",
     "Locale":"en-US",
    "OrderNumber": "1234-5678",
     "Currency":"EUR",
     "Currency":"EUR",
     "Transactions": [
     "Transactions": [
         {
         {
             "POSTransactionId": "TEST-01-01",
             "POSTransactionId": "MP-TR-01",
             "Payee": "[email protected]",
             "Payee": "[email protected]",
             "Total": "49",
             "Total": "49",
Line 60: Line 71:
         },
         },
         {
         {
             "POSTransactionId": "TEST-01-02",
             "POSTransactionId": "MP-TR-02",
             "Payee": "[email protected]",
             "Payee": "[email protected]",
             "Total": "35",
             "Total": "35",
Line 80: Line 91:
</syntaxhighlight>
</syntaxhighlight>


Please '''DO NOT''' copy this JSON to your project without modifications, it will '''NOT''' work.
The Barion API accepts the request and prepares the payment. The response JSON content is sent to the Marketplace:


If the prepare is done, the user will be redirected to the following page:
<syntaxhighlight lang="json">
{
    "PaymentId": "c2283b509e424b729cabca6437079d6e",
    "PaymentRequestId": "MARKETPAY-123456",
    "Status": "Prepared",
    "QRUrl": "https://api.barion.com/qr/generate?paymentId=48257700-d044-344a-85df-fc75d5fu62cd&size=Large",
    "Transactions": [
        {
            "POSTransactionId": "MP-TR-01",
            "TransactionId": "07ecff0bb7404b40aeae1bb285ed38c8",
            "Status": "Prepared",
            "Currency": "EUR",
            "TransactionTime": "2017-12-20T12:37:39.696",
            "RelatedId": null
        },
        {
            "POSTransactionId": "MP-TR-02",
            "TransactionId": "b673b95ee96746ca8e182a8596d67a9e",
            "Status": "Prepared",
            "Currency": "EUR",
            "TransactionTime": "2017-12-20T12:37:39.696",
            "RelatedId": null
        }
    ],
    "RecurrenceResult": "None",
    "GatewayUrl": "https://secure.barion.com:443/Pay?Id=c2283b509e424b729cabca6437079d6e",
    "RedirectUrl": "https://testshop.barion.com/Redirect?paymentId=c2283b509e424b729cabca6437079d6e",
    "CallbackUrl": "https://testshop.barion.com/callback?paymentId=c2283b509e424b729cabca6437079d6e",
    "Errors": []
}
</syntaxhighlight>
 
The Marketplace system logs the result and stores the appropriate parameters of the order (eg. the identifiers for the payment and its transactions) for later use.
 
=== Paying on the Barion Smart Gateway ===
 
At this point, the Marketplace has all necessary data. It successfully processed the response from the Barion API, so they redirect Chris's browser to the Barion Smart Gateway:
 
[[File:marketplace_example_payment_gateway.png|800px]]
 
Chris logs in to the Barion system and chooses one of his saved bank cards to pay for the order.
 
The payment is successfully finished in a few seconds. The Barion Smart Gateway confirms the successful payment in a summary window.
 
[[File:marketplace_example_payment_completed.png|800px]]
 
Chris's browser is redirected back to the Marketplace's website, where he may get another confirmation of the order being processed.
At this point, the reservation timer is started. The Marketplace has one day to finish the reservation.
 
The paid amount is transferred to the Barion wallets of Terry Wellington (€49) and Robert Craig (€84), but the amount is blocked and is not available to use until the reservation is finished.


[[File:marketplace_payment_example.png|750px]]
The Barion system also sends a [[Callback_mechanism|callback]] to the Marketplace so they can process data accordingly even if Chris never returns to the Marketplace website.


At this point they can choose from paying using either with their Barion wallet or with bank card.
=== Finishing the reservation ===
If they choose the Barion wallet option, and log in successfully, they can finish the payment with any of their saved cards ( or add a new one), or with the funds in their wallet.
In case of bank card payment, they need to fill the required card datas and their email address.


After the payment is successfully finished, they will be redirected to the following page:
The next day the facilitator is informed that one of the items (€9 worth of fresh potatoes) ran out of stock at Terry Wellington. The Marketplace removes this item from Chris's order and modifies the transaction accordingly. All other items are available.


[[File:marketplace_payment_finish.png | 700px]]
Because the total amount due to the payment is changed, the Marketplace has to finish the reservation with an amount lower than the initial value. The Marketplace sends a request to the Barion API to finish the reservation, via the [[Payment-FinishReservation-v2|/v2/Payment/FinishReservation]] API endpoint, using the payment and transaction identifiers received earlier when preparing the payment.
The JSON content of the request looks like this:


<syntaxhighlight lang="json">
{
    "POSKey": "60F99E979-S5U2-4AA2-BC9F-DF14ABA4P8F17",
    "PaymentId": "c2283b509e424b729cabca6437079d6e",
    "Transactions": [
        {
            "TransactionId": "07ecff0bb7404b40aeae1bb285ed38c8",
            "Payee": "[email protected]",
            "Total": "40",
            "Comment": "Order 1",
            "Items": [
                {
                    "Name": "Ginger, sliced",
                    "Description": "Ginger, sliced",
                    "Quantity": 2,
                    "Unit": "packs",
                    "UnitPrice": 10,
                    "ItemTotal": 20,
                    "SKU": "SM-02"
                },
                {
                    "Name": "Truffle box",
                    "Description": "Truffle box",
                    "Quantity": 1,
                    "Unit": "pc",
                    "UnitPrice": 20,
                    "ItemTotal": 20,
                    "SKU": "SM-03"
                }
            ]
        },
        {
            "TransactionId": "b673b95ee96746ca8e182a8596d67a9e",
            "Payee": "[email protected]",
            "Total": "35",
            "Comment": "Order  2",
            "Items": [
                {
                    "Name": "8 piece kitchen knives set",
                    "Description": "8 piece kitchen knives set",
                    "Quantity": 1,
                    "Unit": "pc",
                    "UnitPrice": 35,
                    "ItemTotal": 35,
                    "SKU": "SM-04"
                }
            ]
        }
    ]
}
</syntaxhighlight>
{{NotificationBox|title=NOTE|text=See the items and the total amount for the first payment transaction has changed!|color=#1993c7}}
The Barion API accepts and processes the request. Both transactions are finished successfully. The payment is set to <code>Succeeded</code> state.
<syntaxhighlight lang="json">
{
    "IsSuccessful": true,
    "PaymentId": "c2283b509e424b729cabca6437079d6e",
    "PaymentRequestId": "MARKETPAY-123456",
    "Status": "Succeeded",
    "Transactions": [
        {
            "POSTransactionId": "MP-TR-01",
            "TransactionId": "07ecff0bb7404b40aeae1bb285ed38c8",
            "Status": "Succeeded",
            "Currency": "EUR",
            "TransactionTime": "2017-12-20T13:47:11.251Z",
            "RelatedId": null
        },
        {
            "POSTransactionId": "MP-TR-02",
            "TransactionId": "b673b95ee96746ca8e182a8596d67a9e",
            "Status": "Succeeded",
            "Currency": "EUR",
            "TransactionTime": "2017-12-20T13:47:11.251Z",
            "RelatedId": null
        }
    ],
    "Errors": []
}
</syntaxhighlight>
Even though the Marketplace just received a response and probably processed it, the Barion system also sends a [[Callback_mechanism|callback]] to the respective callback URL of the payment - should there be any extra processing required in the Marketplace system.
From the reserved amount of €49 in Terry Wellington's wallet, €40 is released and is now available for him to use. The €9 difference from the initially reserved amount is automatically refunded to Chris's bank card. Robert Craig receives the whole amount of €35.
The Marketplace informs Chris about the confirmed order and that the items are being shipped.
=== Refunding the payment ===
Chris receives the items he ordered and discovers that the knife set he ordered from Robert Craig has broken during shipment. He informs the Marketplace about this.
The Marketplace forwards his feedback to Robert, who arranges a full refund with Chris in compensation.
Robert can do the refund via the Barion web user interface under the details of the corresponding payment after logging into his Barion wallet.
If Robert is not available for some reason, the Marketplace may also refund the payment via the Barion API, using the [[Payment-Refund-v2|/vs/Payment/Refund]] endpoint.
In this case, the following JSON content is sent in the request:
<syntaxhighlight lang="json">
{
    "POSKey": "60I98E979-Z592-4AA2-BC9F-DF14ABA4P8F17",
    "PaymentId": "c2283b509e424b729cabca6437079d6e",
    "TransactionsToRefund": [{
        "TransactionId": "b673b95ee96746ca8e182a8596d67a9e",
        "AmountToRefund": 35,
        "POSTransactionId": "MP-TR-02",
        "Comment": "Refund due to broken product sold at Marketplace"
    }],
}
</syntaxhighlight>
The Barion API receives the refund request and processes it. The refund successfully takes place, although Chris might have to wait up to 30 days to receive the refund on his bank card, depending on the bank system.
<syntaxhighlight lang="json">
{
    "POSKey": "60I98E979-Z592-4AA2-BC9F-DF14ABA4P8F17",
    "PaymentId": "c2283b509e424b729cabca6437079d6e",
    "RefundedTransactions": [{
        "TransactionId": "b673b95ee96746ca8e182a8596d67a9e",
        "Total": 35,
        "POSTransactionId": "MP-TR-02",
        "Comment": "Refund due to broken product sold at Marketplace",
        "Status": "Succeeded"
    }],
    "Errors": []
}
</syntaxhighlight>


After a short period of time, they will be redirected back to the shop's site (the RerdirectUrl can be specified at the  [[Payment-Start-v2|Payment Start]].
Whoever initiated the refund, the Barion system sends a [[Callback_mechanism|callback]] to the Marketplace so they can do additional processing if they need to.


Since this is a marketplace scenario, the payees will be the manufacturers( Terry and Robert). They will pay a fee to the facilitator (they may pay for other third parties, however in this example no other payments will happen for simplicity) for its services. These fees are calculated by the Barion System.
== Reference ==
And
* [[Payment-Start-v2|/Payment/Start]]
* [[Payment-PaymentState-v4|/v4/Payment/<PaymentId>/PaymentState]]
* [[Payment-FinishReservation-v2|/Payment/FinishReservation]]
* [[Payment-Refund-v2|/Payment/Refund]]

Latest revision as of 10:14, 25 March 2024

Detailed example of a marketplace payment

Introduction

This example is to show the full life cycle of a purchase made at a marketplace scenario. Through this you will be familiar with how the Barion payment system works in a complex payment situation - how the payments are processed, how the money travels between participants and how the systems communicate with each other. Please read this carefully.

WARNING
Do NOT copy any JSON content to your project - these are for demonstration purposes only!

Imagine Chef Chris would like to buy some groceries and products at the Marketplace. In this case, we are talking about a facilitated payment scenario, where the Marketplace is the facilitator. The facilitator manages and organizes the whole payment process, but they do not take part in it as a final payee. Instead, they distribute the money between the different sellers of the chosen products.

Starting the payment

The process starts with the shopping. Chris has put some products / services (referred to as items) in his shopping cart on the Marketplace website. These items belong to different manufacturers / providers / distributors - other users of the Barion system, henceforth referred to as sellers. They all have registered, active Barion wallets but they do not own a shop in the system.

Chris has selected four items from two sellers and went to checkout. The Marketplace informs him that there is a one-day period of confirmation from the sellers upon placing an order.

At this point, the Marketplace prepares the payment trough the Barion API, using the /v2/Payment/Start endpoint. Chris is purchasing items from two separate sellers, the payment will contain two payment transactions, with the respective items and payees set accordingly. Since there is a time window where the sellers should confirm the order, the Marketplace prepares a reservation payment with a reservation period of one day.

For this API call the request JSON looks like this : 

 
{
    "POSKey": "60I98E979-Z592-4AA2-BC9F-DF14ABA4P8F17",
    "PaymentType": "Reservation",
    "ReservationPeriod": "1.00:00:00",
    "PaymentRequestId": "MARKETPAY-123456",
    "GuestCheckOut" : true,
    "FundingSources": ["All"],
    "Locale":"en-US",
    "OrderNumber": "1234-5678",
    "Currency":"EUR",
    "Transactions": [
        {
            "POSTransactionId": "MP-TR-01",
            "Payee": "[email protected]",
            "Total": "49",
            "Comment": "Order 1",
            "Items": [
                {
                    "Name": "Fresh potatoes",
                    "Description": "Fresh potatoes",
                    "Quantity": 3,
                    "Unit": "kg",
                    "UnitPrice": 3,
                    "ItemTotal": 9,
                    "SKU": "SM-01"
                },
                {
                    "Name": "Ginger, sliced",
                    "Description": "Ginger, sliced",
                    "Quantity": 2,
                    "Unit": "packs",
                    "UnitPrice": 10,
                    "ItemTotal": 20,
                    "SKU": "SM-02"
                },
                {
                    "Name": "Truffle box",
                    "Description": "Truffle box",
                    "Quantity": 1,
                    "Unit": "pc",
                    "UnitPrice": 20,
                    "ItemTotal": 20,
                    "SKU": "SM-03"
                }
            ]
        },
        {
            "POSTransactionId": "MP-TR-02",
            "Payee": "[email protected]",
            "Total": "35",
            "Comment": "Order  2",
            "Items": [
                {
                    "Name": "8 piece kitchen knives set",
                    "Description": "8 piece kitchen knives set",
                    "Quantity": 1,
                    "Unit": "pc",
                    "UnitPrice": 35,
                    "ItemTotal": 35,
                    "SKU": "SM-04"
                }
            ]
        }
    ]
}

The Barion API accepts the request and prepares the payment. The response JSON content is sent to the Marketplace: 

 
{
    "PaymentId": "c2283b509e424b729cabca6437079d6e",
    "PaymentRequestId": "MARKETPAY-123456",
    "Status": "Prepared",
    "QRUrl": "https://api.barion.com/qr/generate?paymentId=48257700-d044-344a-85df-fc75d5fu62cd&size=Large",
    "Transactions": [
        {
            "POSTransactionId": "MP-TR-01",
            "TransactionId": "07ecff0bb7404b40aeae1bb285ed38c8",
            "Status": "Prepared",
            "Currency": "EUR",
            "TransactionTime": "2017-12-20T12:37:39.696",
            "RelatedId": null
        },
        {
            "POSTransactionId": "MP-TR-02",
            "TransactionId": "b673b95ee96746ca8e182a8596d67a9e",
            "Status": "Prepared",
            "Currency": "EUR",
            "TransactionTime": "2017-12-20T12:37:39.696",
            "RelatedId": null
        }
    ],
    "RecurrenceResult": "None",
    "GatewayUrl": "https://secure.barion.com:443/Pay?Id=c2283b509e424b729cabca6437079d6e",
    "RedirectUrl": "https://testshop.barion.com/Redirect?paymentId=c2283b509e424b729cabca6437079d6e",
    "CallbackUrl": "https://testshop.barion.com/callback?paymentId=c2283b509e424b729cabca6437079d6e",
    "Errors": []
}

The Marketplace system logs the result and stores the appropriate parameters of the order (eg. the identifiers for the payment and its transactions) for later use.

Paying on the Barion Smart Gateway

At this point, the Marketplace has all necessary data. It successfully processed the response from the Barion API, so they redirect Chris's browser to the Barion Smart Gateway:

Chris logs in to the Barion system and chooses one of his saved bank cards to pay for the order.

The payment is successfully finished in a few seconds. The Barion Smart Gateway confirms the successful payment in a summary window.

Chris's browser is redirected back to the Marketplace's website, where he may get another confirmation of the order being processed. At this point, the reservation timer is started. The Marketplace has one day to finish the reservation.

The paid amount is transferred to the Barion wallets of Terry Wellington (€49) and Robert Craig (€84), but the amount is blocked and is not available to use until the reservation is finished.

The Barion system also sends a callback to the Marketplace so they can process data accordingly even if Chris never returns to the Marketplace website.

Finishing the reservation

The next day the facilitator is informed that one of the items (€9 worth of fresh potatoes) ran out of stock at Terry Wellington. The Marketplace removes this item from Chris's order and modifies the transaction accordingly. All other items are available.

Because the total amount due to the payment is changed, the Marketplace has to finish the reservation with an amount lower than the initial value. The Marketplace sends a request to the Barion API to finish the reservation, via the /v2/Payment/FinishReservation API endpoint, using the payment and transaction identifiers received earlier when preparing the payment. The JSON content of the request looks like this: 

 
{
    "POSKey": "60F99E979-S5U2-4AA2-BC9F-DF14ABA4P8F17",
    "PaymentId": "c2283b509e424b729cabca6437079d6e",
     "Transactions": [
        {
            "TransactionId": "07ecff0bb7404b40aeae1bb285ed38c8",
            "Payee": "[email protected]",
            "Total": "40",
            "Comment": "Order 1",
            "Items": [
                {
                    "Name": "Ginger, sliced",
                    "Description": "Ginger, sliced",
                    "Quantity": 2,
                    "Unit": "packs",
                    "UnitPrice": 10,
                    "ItemTotal": 20,
                    "SKU": "SM-02"
                },
                {
                    "Name": "Truffle box",
                    "Description": "Truffle box",
                    "Quantity": 1,
                    "Unit": "pc",
                    "UnitPrice": 20,
                    "ItemTotal": 20,
                    "SKU": "SM-03"
                }
            ]
        },
        {
            "TransactionId": "b673b95ee96746ca8e182a8596d67a9e",
            "Payee": "[email protected]",
            "Total": "35",
            "Comment": "Order  2",
            "Items": [
                {
                    "Name": "8 piece kitchen knives set",
                    "Description": "8 piece kitchen knives set",
                    "Quantity": 1,
                    "Unit": "pc",
                    "UnitPrice": 35,
                    "ItemTotal": 35,
                    "SKU": "SM-04"
                }
            ]
        }
    ]
}
NOTE
See the items and the total amount for the first payment transaction has changed!

The Barion API accepts and processes the request. Both transactions are finished successfully. The payment is set to Succeeded state. 

{
    "IsSuccessful": true,
    "PaymentId": "c2283b509e424b729cabca6437079d6e",
    "PaymentRequestId": "MARKETPAY-123456",
    "Status": "Succeeded",
    "Transactions": [
        {
            "POSTransactionId": "MP-TR-01",
            "TransactionId": "07ecff0bb7404b40aeae1bb285ed38c8",
            "Status": "Succeeded",
            "Currency": "EUR",
            "TransactionTime": "2017-12-20T13:47:11.251Z",
            "RelatedId": null
        },
        {
            "POSTransactionId": "MP-TR-02",
            "TransactionId": "b673b95ee96746ca8e182a8596d67a9e",
            "Status": "Succeeded",
            "Currency": "EUR",
            "TransactionTime": "2017-12-20T13:47:11.251Z",
            "RelatedId": null
        }
    ],
    "Errors": []
}

Even though the Marketplace just received a response and probably processed it, the Barion system also sends a callback to the respective callback URL of the payment - should there be any extra processing required in the Marketplace system.

From the reserved amount of €49 in Terry Wellington's wallet, €40 is released and is now available for him to use. The €9 difference from the initially reserved amount is automatically refunded to Chris's bank card. Robert Craig receives the whole amount of €35.

The Marketplace informs Chris about the confirmed order and that the items are being shipped.

Refunding the payment

Chris receives the items he ordered and discovers that the knife set he ordered from Robert Craig has broken during shipment. He informs the Marketplace about this.

The Marketplace forwards his feedback to Robert, who arranges a full refund with Chris in compensation. Robert can do the refund via the Barion web user interface under the details of the corresponding payment after logging into his Barion wallet.

If Robert is not available for some reason, the Marketplace may also refund the payment via the Barion API, using the /vs/Payment/Refund endpoint. In this case, the following JSON content is sent in the request: 

{
    "POSKey": "60I98E979-Z592-4AA2-BC9F-DF14ABA4P8F17",
    "PaymentId": "c2283b509e424b729cabca6437079d6e",
    "TransactionsToRefund": [{
        "TransactionId": "b673b95ee96746ca8e182a8596d67a9e",
        "AmountToRefund": 35,
        "POSTransactionId": "MP-TR-02",
        "Comment": "Refund due to broken product sold at Marketplace"
    }],
}

The Barion API receives the refund request and processes it. The refund successfully takes place, although Chris might have to wait up to 30 days to receive the refund on his bank card, depending on the bank system. 

{
    "POSKey": "60I98E979-Z592-4AA2-BC9F-DF14ABA4P8F17",
    "PaymentId": "c2283b509e424b729cabca6437079d6e",
    "RefundedTransactions": [{
        "TransactionId": "b673b95ee96746ca8e182a8596d67a9e",
        "Total": 35,
        "POSTransactionId": "MP-TR-02",
        "Comment": "Refund due to broken product sold at Marketplace",
        "Status": "Succeeded"
    }],
    "Errors": []
}

Whoever initiated the refund, the Barion system sends a callback to the Marketplace so they can do additional processing if they need to.

Reference

Retrieved from "https://docs.barion.com/index.php?title=Marketplace_Example&oldid=4289"