Split payouts on Payment Provider Protocol

Split payouts are a common requirement for payment providers used by marketplaces. They allow a marketplace to process the payment for an order, collect its commission, and pay sellers for their products in a single transaction, which improves operational efficiency when managing payouts at scale.

The VTEX platform allows merchants to register sellers, configure commission percentages for the total order and shipping rates, and set specific commissions by seller category. For more information, see Adding a seller.

This guide describes how the VTEX Gateway calculates the split and what changes in each Payment Provider Protocol request when split payouts are active.

Check the following requirements:

• Your connector must be integrated through the Payment Provider Protocol.
• The manifest returned by the Get manifest endpoint must declare the allowsSplit property for every payment method, using disabled for methods that don't support split payouts.
• To support partial refunds in split transactions, the acceptSplitPartialRefund parameter must be enabled for your connector. Request this during the payment provider homologation process.
• The merchant must have sellers and commission percentages configured in the marketplace, as described in Adding a seller.

When an order is placed, the cart falls into one of three scenarios:

When a split payout is required, the VTEX Gateway is responsible for:

• Calculating the commission per seller of each order.
• Sending the split payload data to the payment provider.
• Processing the complete or partial refund in split operations, when required.

The VTEX Gateway sends the split payload only if the payment provider supports this scenario.

Consider an order of 199.62 USD with the following registered commissions: 16% for the marketplace when the product comes from seller X, and 20% for the marketplace when the product comes from seller Y. The cart contains products from seller X, seller Y, and the marketplace itself.

The VTEX Gateway calculates the following breakdown:

The marketplace receives the value of its own products plus the commission collected from both sellers, and each seller receives the value of its products minus the marketplace commission.

You can configure the following characteristics of the split process:

• Automatic settlement time: The payment provider controls whether automatic settlement occurs before or after the anti-fraud analysis via the delayToAutoSettle and delayToAutoSettleAfterAntifraud fields in the authorization response.
• Split payload sending time: Set per payment method through the allowsSplit property of each item in the paymentMethods array of the manifest.

The allowsSplit property accepts the following values:

The allowsSplit property is required for every payment method in the manifest. Don't omit it: use disabled for payment methods that don't support split payouts. The split payload is sent at the stage specified by the declared value.

The split payout solution adds an array of objects called recipients to the Payment Provider Protocol. Each item of this array carries the data your connector needs to split the transaction between the recipients involved, meaning the marketplace and the sellers.

The recipient object contains the following fields:

The commission field is spelled comissionAmount, with a single m, in the Create payment and Refund payment schemas, and commissionAmount, with a double m, in the Settle payment schema. Handle both spellings in your connector to avoid losing commission data.

The following sections describe the changes applied to each stage of the Payment Provider Protocol when split payouts are active.

When allowsSplit is onAuthorize for the payment method, the VTEX Gateway sends the recipients array in the authorization payload, containing the values to be passed on to each seller and to the marketplace involved in the order.

The following example shows the authorization request for the order described in Commission calculation example:

When allowsSplit is onCapture or disabled for the payment method, there are no changes in the authorization payload.

When allowsSplit is onCapture for the payment method, the VTEX Gateway sends the list of recipients involved in the transaction in the settlement request.

Consider a cart consisting of products from seller A, with an order value of 45.00 and a marketplace commission rate of 16%. The VTEX Gateway sends 7.2 to the marketplace and 37.8 to seller A:

When allowsSplit is onAuthorize or disabled for the payment method, there are no changes in the settlement payload.

The complete refund payload has no changes when split payouts are active, because the refund covers the whole transaction:

To use the split partial refund feature, request the Partner Support team to enable the acceptSplitPartialRefund parameter as true during the payment provider homologation process.

The recipients array contains the recipients affected by the refund: each seller whose items are refunded and the marketplace, with the commission share it returns. When the refund applies only to marketplace items, the array contains only the marketplace data.

Partial refund of a seller item

Consider a cart composed of items from seller A, with a marketplace commission of 16%, for which 20.00 must be refunded. The VTEX Gateway sends 3.2 for the marketplace and 16.8 for seller A:

Partial refund of a marketplace item

When 20.00 USD must be refunded for a marketplace item, the VTEX Gateway sends a single recipient object with the marketplace data:

The cancellation payload has no changes in this version of the split payouts feature:

Split payouts don't change the response bodies your connector must return. Answer each request with the standard Payment Provider Protocol response for that operation.

A successful settlement returns the status code 200 OK:

A successful refund also returns the status code 200 OK:

Report failures through the status code and the code and message fields of the response, so that the VTEX Gateway can record the result of the operation:

The following example shows a settlement that failed:

When validating a split request, consider the following:

• The sum of the amount values of all recipients matches the value field of the request.
• The recipients array is absent when the payment method sets allowsSplit as disabled, or when the order contains marketplace products only. Treat the absence of this array as a transaction without split.
• Partial refund requests only include the recipients involved in that refund, so don't assume that the array repeats every recipient of the authorization.

• Payment Provider Protocol
• Payment provider homologation
• Split payment
• Adding a seller