Marketplace Example: Difference between revisions
No edit summary |
No edit summary |
||
| Line 7: | Line 7: | ||
This detailed guide is to show the full life cycle of a purchase made at a marketplace scenario. Through this you will be familiar how the Barion payment system works in a complex payment situation - how the payments are processed, how the money travels between the parties and how the systems communicate with each other. | This detailed guide is to show the full life cycle of a purchase made at a marketplace scenario. Through this you will be familiar how the Barion payment system works in a complex payment situation - how the payments are processed, how the money travels between the parties and how the systems communicate with each other. | ||
Imagine | 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 === | === Starting the payment === | ||
The process starts with the shopping. | 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. Since 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_payments]] with a reservation period of one day. | |||
For this | |||
For this API call the request JSON looks like this : | |||
<syntaxhighlight lang="json"> | <syntaxhighlight lang="json"> | ||
| Line 25: | Line 26: | ||
"PaymentType": "Reservation", | "PaymentType": "Reservation", | ||
"ReservationPeriod": "1.00:00:00", | "ReservationPeriod": "1.00:00:00", | ||
"PaymentRequestId": " | "PaymentRequestId": "MARKETPAY-123456", | ||
"GuestCheckOut" : true, | "GuestCheckOut" : true, | ||
"FundingSources": ["All"], | "FundingSources": ["All"], | ||
| Line 32: | Line 33: | ||
"Transactions": [ | "Transactions": [ | ||
{ | { | ||
"POSTransactionId": " | "POSTransactionId": "MP-TR-01", | ||
"Payee": "[email protected]", | "Payee": "[email protected]", | ||
"Total": "49", | "Total": "49", | ||
| Line 67: | Line 68: | ||
}, | }, | ||
{ | { | ||
"POSTransactionId": " | "POSTransactionId": "MP-TR-02", | ||
"Payee": "[email protected]", | "Payee": "[email protected]", | ||
"Total": "35", | "Total": "35", | ||
Revision as of 09:47, 21 December 2017
Detailed example of a marketplace payment
Introduction
This detailed guide is to show the full life cycle of a purchase made at a marketplace scenario. Through this you will be familiar how the Barion payment system works in a complex payment situation - how the payments are processed, how the money travels between the parties and how the systems communicate with each other.
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. Since 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_payments 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",
"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 response JSON for this request would be the following:
{
"PaymentId": "48257505a0541244bo7dffb85d5fb62ca",
"PaymentRequestId": "TEST-01",
"Status": "Prepared",
"QRUrl": "https://api.barion.com/qr/generate?paymentId=48257700-d044-344a-85df-fc75d5fu62cd&size=Large",
"Transactions": [
{
"POSTransactionId": "TEST-01-01",
"TransactionId": "3db7ffbacuea463c93p5145e172fc3d6",
"Status": "Prepared",
"Currency": "EUR",
"TransactionTime": "2017-12-20T12:37:39.696",
"RelatedId": null
},
{
"POSTransactionId": "TEST-01-02",
"TransactionId": "a2b7tfbncwpa663c96i2946g122fq3de",
"Status": "Prepared",
"Currency": "EUR",
"TransactionTime": "2017-12-20T12:37:39.696",
"RelatedId": null
}
],
"RecurrenceResult": "None",
"GatewayUrl": "https://secure.barion.com:443/Pay?Id=48257700d044344a85dffc75d5fu62cd",
"RedirectUrl": "https://testshop.barion.com/Redirect?paymentId=48257700d044344a85dffc75d5fu62cd",
"CallbackUrl": "https://testshop.barion.com/callback?paymentId=48257700d044344a85dffc75d5fu62cd",
"Errors": []
}
If the prepare is done, the user will be redirected to the following page:
File:Marketplace payment example.png
The customer will see the payee is the facilitator, while the sellers are the manufacturers.
At this point they can choose from paying using either with their Barion wallet or with bank card. 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 this case the reserved amount will stay in the payer's wallet.
In case of bank card payment, they need to fill the required card datas and their email address. This way the amount is transferred the manufacturers, but stays in reserved status.
When the user selected from the give payment options and completed the process, the system sends a callback to the facilitator about the reservation. The status of the payment becomes Reserved.
If the payment is successfully finished, they will be redirected to the following page:
File:Marketplace payment finish.png
After a short period of time, the user be redirected back to the shop's site (the RerdirectUrl can be specified at the Payment Start). The reservation is started, but it has to be finished by the facilitator before the reservation period passes (in this example this time period is 24 hours).
The "next day" the facilitator completes the reservation. However potatoes have tainted over the night, so it will be removed from the payment. This can be achieved by removing the said product from the finishing JSON:
{
"POSKey": "60F99E979-S5U2-4AA2-BC9F-DF14ABA4P8F17",
"PaymentId": "48257505a0541244bo7dffb85d5fb62ca",
"Transactions": [
{
"TransactionId": "3db7ffbacuea463c93p5145e172fc3d6",
"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": "a2b7tfbncwpa663c96i2946g122fq3de",
"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"
}
]
}
]
}They PaymentId and TransactionIds are the same as the ones got in the response from /Payment/Start!
In case of a successful finish the following response should arrive:
{
"IsSuccessful": true,
"PaymentId": "6ca30e4b-1d3d-467b-8b47-87e6a555523e",
"PaymentRequestId": "TEST-01",
"Status": "Succeeded",
"Transactions": [
{
"POSTransactionId": "TEST-01-01",
"TransactionId": "56f399b094d14a75afc7644a3c0ed84f",
"Status": "Succeeded",
"Currency": "HUF",
"TransactionTime": "2017-12-20T13:47:11.251Z",
"RelatedId": null
},
{
"POSTransactionId": "TEST-01-02",
"TransactionId": "6f44d84031a6424d83208abcc5824fab",
"Status": "Succeeded",
"Currency": "HUF",
"TransactionTime": "2017-12-20T13:47:11.251Z",
"RelatedId": null
}
],
"Errors": []
}The difference between the finished and reserved amount (9 euros in this example) will be refunded to the payer. A callback sent to the facilitator. Since this is a marketplace scenario, the payees will be the manufacturers(in this case 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. The distribution of the payed amount, and the applicable fee(s) is automatically managed by the Barion system (based on the specified payment transactions by the facilitator).
So the reservation is finished at this point, but when the products arrive it turns out that the 8 piece knives set, is actually contains only seven knives. Therefore the payer demands a full refund. The manufacturer initiates the refund. To start a refund the user must log in to their Barion wallet. The transaction details are under the activity tab. With the "Refund the transaction amount" button the user will be redirected to the refund page. A refund can not exceed the paid amount, but it can be lesser than that. In this example a full refund will happen so the refunded amount will be the same as the paid one (35 euros). When the user (Robert for this case) clicks on "Refund" button the following JSON will be sent to /Payment-Refund-v2:
{
"POSKey": "60I98E979-Z592-4AA2-BC9F-DF14ABA4P8F17",
"PaymentId": "48257700-d044-344a-85df-fc75d5fu62cd",
"TransactionsToRefund": [{
"TransactionId": "6f44d84031a6424d83208abcc5824fab",
"AmountToRefund": 35,
"POSTransactionId": "TEST-01-02",
"Comment": "Faulty product"
}],
}If the refund was successful the response would look like this:
{
"POSKey": "60I98E979-Z592-4AA2-BC9F-DF14ABA4P8F17",
"PaymentId": "48257700-d044-344a-85df-fc75d5fu62cd",
"RefundedTransactions": [{
"TransactionId": "6f44d84031a6424d83208abcc5824fab",
"Total": 35,
"POSTransactionId": "TEST-01-02",
"Comment": "Faulty product",
"Status": "Succeded"
}],
"Errors": []
}