Multi-seller Payments

Handling Payments for Items Sold by Multiple Sellers

Remember that as the owner of a marketplace platform, you will accept a payment for the total amount of all items purchased. When handling payments involving multiple sellers, you may thus need to keep track of all items in the transaction including their sellers. This will allow the amount to be split between all sellers when you’re paid out at a later stage.

Keeping track of sold items per seller is easy. When invoking the Create Payment request, simply pass each sold item as a separate item in the order.line_items array. To specify from which seller an item was purchased, include a marketplace object and specify the seller’s ID. If desired, you can include a handling fee in the marketplace object as well. Here’s a sample Create Payment request body (truncated for brevity):

{
   "amount":1000, // The total amount of the transaction
    ...
   "order":{
      "id":233503,
      "sub_total":1000,
       ...
      "line_items":[ // List all items purchased and their sellers
         {
            "name":"Garden chair",
            "id":"kjk428vvkcle931686k1900mkg9",
            "unit_price": 540,
            "tax_percentage": 0.1,
            ...
            "marketplace": 
               {
                  "seller_id":"seller_123",
                  "fee":100
               }
         },
         {
            "name":"Garden barbecue",
            "id":"zeg428vvkcle931686k1900old3",
            "unit_price": 360,
            "tax_percentage": 0.1,
            ...
            "marketplace": 
               {
                  "seller_id":"seller_789",
                  "fee":100
               }
         }
      ]
   }
   ...
}

Capturing or Refunding the Amount of a Sold Item

If you want to capture or refund the payment amount of an item sold by a specific seller, then you can pass a marketplace array with an object for each of the items purchased. In each object, include the line_item_id of the item you passed in the Create Payment request; PaymentsOS will then capture or refund the total amount (order.line_items.unit_price + order.line_items.tax_percentage) for which that item was sold. And of course, having the line_item_id at hand will also allow you to backtrack the item to its seller.

Here’s an example marketplace object (notice that you do not need to pass an amount):

{
  "marketplace": [
    {
      "line_item_id": "kjk428vvkcle931686k1900mkg9", // This is the line item ID you passed in the Create Payment request
    }
  ]
}

Capturing or Refunding a Part of the Sold Item’s Amount

If desired, you can also capture or refund a part of the amount of the item that was sold. In this case, add the partial amount to the marketplace object as well:

{
  "marketplace": [
    {
      "line_item_id": "kjk428vvkcle931686k1900mkg9", // This is the line item ID you passed in the Create Payment request
      "amount": 50, // Add an amount to capture or refund a part of the item's payment amount  
      "fee": 5
    }
  ]
}