Marketplace Example: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
Line 255: Line 255:
}
}
</syntaxhighlight>
</syntaxhighlight>
{{NotificationBox|title=WARNING|text=Do '''NOT''' copy this JSON to your project without modifications, this is for demo purposes only.|color=#FF7A3D}}


If the refund was successful the response would look like this:
If the refund was successful the response would look like this:

Revision as of 10:26, 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. 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",
    "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"
                }
            ]
        }
    ]
}
WARNING
Do NOT copy this JSON to your project without modifications, this is for demo purposes only.

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:

File:Marketplace payment example.png

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 payment finish.png

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.

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": []
}

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

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": []
}

Reference