Marketplace Example: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
VisualWikitext
No edit summary
No edit summary
Line 1: Line 1:
{{PageTitle|title=Detailed example of a marketplace payment}}
{{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.  
This guide's purpose to show a reservation payment process including a facilitator. After the payment, a refund will be showcased aswell.


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.
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.
Line 18: Line 18:
{
{
     "POSKey": "60I98E979-Z592-4AA2-BC9F-DF14ABA4P8F17",
     "POSKey": "60I98E979-Z592-4AA2-BC9F-DF14ABA4P8F17",
     "PaymentType": "Immediate",
     "PaymentType": "Reservation",
    "ReservationPeriod": "1.00:00:00",
     "PaymentRequestId": "TEST-01",
     "PaymentRequestId": "TEST-01",
     "GuestCheckOut" : true,
     "GuestCheckOut" : true,
Line 83: Line 84:
{{NotificationBox|title=WARNING|text=Do '''NOT''' copy this JSON to your project without modifications, this is for demo purposes only.|color=#FF7A3D}}
{{NotificationBox|title=WARNING|text=Do '''NOT''' copy this JSON to your project without modifications, this is for demo purposes only.|color=#FF7A3D}}


The response JSON for this request would be the following:
<syntaxhighlight lang="json">
{
    "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": []
}
</syntaxhighlight>
{{NotificationBox|title=WARNING|text=Its important to save the PaymentId and the TransactionIds. These will be the key parameters for further requests.|color=#FF7A3D}}




Line 89: Line 126:
[[File:marketplace_payment_example.png|750px]]
[[File:marketplace_payment_example.png|750px]]


The customer will see the payee is the facilitators, while the sellers are the manufacturers.
The customer will see the payee is the facilitator, while the sellers are the manufacturers.




Line 98: Line 135:
[[File:marketplace_payment_payment_type_example.png | 700px]]
[[File:marketplace_payment_payment_type_example.png | 700px]]


In case of bank card payment, they need to fill the required card datas and their email address.
In this case the reserved amount will stay in the payer's wallet.


When the user selected from the give payment options and completed the process, the facilitator will finish the payment trough the Barion API. The money will be transfared to the facilitator.
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:
If the payment is successfully finished, they will be redirected to the following page:
Line 109: Line 148:


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-v2|Payment Start]]).
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-v2|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).
{{NotificationBox|title=NOTE|text=''If the payment should be refunded at this point, the facilitator had to finish the reservation with a total amount of zero.''|color=#1993c7}}
The "next day" the facilitator will finish 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:
<syntaxhighlight lang="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"
                }
            ]
        }
    ]
}
</syntaxhighlight>
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:
<syntaxhighlight lang="json">
{
    "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": []
}
</syntaxhighlight>
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).
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|/Payment-Refund-v2]]:
<syntaxhighlight lang="json">
{
    "POSKey": "60I98E979-Z592-4AA2-BC9F-DF14ABA4P8F17",
    "PaymentId": "48257700-d044-344a-85df-fc75d5fu62cd",
    "TransactionsToRefund": [{
        "TransactionId": "6f44d84031a6424d83208abcc5824fab",
        "AmountToRefund": 40,
        "POSTransactionId": "TEST-01-02",
        "Comment": "Faulty product"
    }],
}
</syntaxhighlight>
If the refund was successful the response would look like this:
<syntaxhighlight lang="json">
{
    "POSKey": "60I98E979-Z592-4AA2-BC9F-DF14ABA4P8F17",
    "PaymentId": "48257700-d044-344a-85df-fc75d5fu62cd",
    "RefundedTransactions": [{
        "TransactionId": "6f44d84031a6424d83208abcc5824fab",
        "Total": 40,
        "POSTransactionId": "TEST-01-02",
        "Comment": "Faulty product",
        "Status": "Succeded"
    }],
    "Errors": []
}
</syntaxhighlight>


== Reference ==
== Reference ==
* [[Payment-Start-v2|/Payment/Start]]
* [[Payment-Start-v2|/Payment/Start]]
* [[Marketplace|/Marketplace]]
* [[Marketplace|/Marketplace]]
* [[Reservation|/Reservation_payment]]
* [[Finish reservation|/Payment-FinishReservation-v2]]
* [[Refund|/Payment-Refund-v2]]

Revision as of 15:02, 20 December 2017

Detailed example of a marketplace payment

This guide's purpose to show a reservation payment process including a facilitator. After the payment, a refund will be showcased aswell.

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.

The process starts with the shopping part. The user select products on a given site. These products belongs to manufacturers ( other "users" of the system), therefore the prices of their products will be transferred to them. Both manufacturers have a registered Barion wallet but they do not own a shop in the system. The demo products will be the followings (including the manufacturers):


The next step is to start the payment for the selected products via Barion. The facilitator prepares the payment trough the Barion API (/Payment/Start). Two transactions will be specified, with the manufacturers set as payees. For this specific payment the required JSON content would look like this : 

 
{
    "POSKey": "60I98E979-Z592-4AA2-BC9F-DF14ABA4P8F17",
    "PaymentType": "Reservation",
    "ReservationPeriod": "1.00:00:00",
    "PaymentRequestId": "TEST-01",
    "GuestCheckOut" : true,
    "FundingSources": ["All"],
    "Locale":"en-US",
    "Currency":"EUR",
    "Transactions": [
        {
            "POSTransactionId": "TEST-01-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": "TEST-01-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"
                }
            ]
        }
    ]
}
WARNING
Do NOT copy this JSON to your project without modifications, this is for demo purposes only.


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": []
}
WARNING
Its important to save the PaymentId and the TransactionIds. These will be the key parameters for further requests.


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).

NOTE
If the payment should be refunded at this point, the facilitator had to finish the reservation with a total amount of zero.


The "next day" the facilitator will finish 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": 40,
        "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": 40,
        "POSTransactionId": "TEST-01-02",
        "Comment": "Faulty product",
        "Status": "Succeded"
    }],
    "Errors": []
}

Reference

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