Split payouts are a common requirement for payment providers used by marketplaces, since it allows marketplaces to not only process the payment for an order, but also collect their commission and pay sellers for their products. This leads to improved operational efficiency when managing payouts for a large marketplace.

The VTEX platform allows the merchant to register sellers, configure commission percentages (total order and freight values), and specific commissions by seller category. Check on Adding a Seller.

When an order is placed, one of three scenarios are present in the cart:

1. Products only from the Marketplace.
2. Products from the Marketplace, and one or more sellers.
3. Products only from seller(s).

As the order contains products only from the Marketplace, there is no split of payment, calculation of commissioning, or split payload to be sent. The Marketplace will receive the full order payment value.

When an order contains products from the Marketplace and sellers (or only from sellers), a split payout is required. In this scenario, the VTEX gateway is responsible for:

• Calculate commissioning per seller of each order.
• Send split payload data to the payment processor.
• Process the complete or partial refund in split operations, if required.

The split payload is sent only if the payment provider supports this scenario.

An illustrative example is shown below to explain how a calculation breakdown for split is performed:

1. The registered commission is: a. 16% for the marketplace when buying the product from seller X. b. 20% for the marketplace when buying products from seller Y.
2. The cart is made up of products from sellerX, sellerY, and the Marketplace itself.
3. An Order with the value of 199.62 is registered. See below:

4. The following containers will be sent with these values: a. 92.36 for the marketplace. b. 73.18 for seller X. c. 34.08 for seller Y.

Calculation Breakdown

ID	Item Value	Marketplace Comission	Recipient
SellerX	87.12	13.94	73.18
SellerY	42.60	8.52	34.08
Marketplace	69.90	-	(69.90+13.94+8.52) = 92.36

It is also possible to configure the following characteristics of the split process:

• Automatic Capture Time: The payment processor has the permission to control if the automatic capture will occur before or after approval of anti-fraud (setting the fields as delayToAutoSettle or delayToAutoSettleAfterAntifraud).

• Split Payload Sending Time: This moment can be set according to each method of payment associated with the transaction. For processors within the PPP (Payment Provider Protocol), it can be done through setting the field on the manifest as onAuthorize, onCapture or disabled.

  If not specified by the processor, the default behavior is:

  • Credit card transaction: The sending of the split is in the capture call.
  • Transaction with boleto: The sending of the split is in the authorization call.

Our Split Payout solution consists of adding an array of objects in the Payment Provider Protocol that we call recipients.

Each item of this array informs the necessary data so that the provider can perform the split between the recipients involved in that transaction (marketplace/sellers). The following fields are part of the recipient’s object:

Field	Type	Description
id	string	Recipient identifier
name	string	Recipient name
documentType	string	Recipient document type
document	string	Recipient document number
role	string	Indicates if the recipient is the seller or the marketplace
chargeProcessingFee	boolean	Indicates whether or not this recipient is charged for processing fees
chargebackLiable	boolean	Indicates whether or not this recipient is liable to chargebacks
amount	float	Amount due to this recipient
comissionAmount	float	Amount received by the Marketplace

In this section, we will describe modifications applied to our payment protocol at each stage (e.g., authorization, capture, etc.) when the split payout is active.

For transactions where the split in authorization is enabled, we send the recipients in the authorization payload. The “recipient’s” object array contains data on the values to be passed on to each seller and the marketplace involved in the order.

See below an example of the authorization request:

For transactions where the split in authorization is disabled, there are no changes in the normal authorization payload.

The list of recipients involved in the transaction will be sent in this stage when the split is configured for the capture step (according to the payment method).

Split example:

1. The registered commission is 16% for the Marketplace when buying the product from sellerA.
2. The cart is made up of products from sellerA.
3. An order with the value of 45.00 is registered.
4. The following containers will be sent with these values: a. 7.2 for the marketplace. b. 37.8 for seller A.

For transactions where the split in authorization is disabled, there are no changes in the normal catch payload.

See below the capture request for this split example:

There is no change in the normal complete refund payload.

See below an example of the complete refund request:

To allow the use of the split partial refund functionality, you must request the Partner Support team to enable the acceptSplitPartialRefund parameter as true during the payment provider homologation process.

The “recipient’s” object array will contain the sellers involved in the chargeback. If the chargeback is only applicable for Marketplace items, the “recipient’s” object array will be sent containing only the Marketplace data.

Split example of a partial refund of a seller item:

1. Sending the array of recipient objects with the Marketplace value to be refunded and the seller value to be refunded.
2. The registered commission is 16% for the Marketplace when buying the product from sellerA.
3. The cart was made up of items from sellerA.
4. The value to be refunded from sellerA item is 20.00.
5. The following containers will be sent with these values: a. 3.2 for the marketplace. b. 16.8 for seller A.

See below the partial refund request for this split example:

Split example of a partial refund of a Marketplace item:

1. Sending the array of recipient objects with the Marketplace value to be refunded.
2. The value to be refunded from the Marketplace item is 20.00.
3. A recipient object with a value of 20.00 will be sent to the Marketplace.

See below the partial refund request for this split example:

In this version of the Split Payouts, there are no changes in the normal cancellation payload.

See below an example of the cancellation request:

For more information about payment splits on VTEX, see Split Payment.