Split payments between merchants

When one payment pays for the work of more than one business, you must tell Datman how to share the funds. For example, when a shopper orders a pizza for delivery, part of the payment can go to the delivery partner and the rest to the takeaway.

You define these split instructions in each API request. Each instruction books one part of the payment to another Datman merchant, under a split commission type: a label that says what that part of the payment is for, such as a delivery fee or a tip.

If you do not provide any split instructions, the whole payment is booked to the merchant that took the payment.

Before sending an API request with split instructions, make sure you understand:

• When to provide split instructions
• How to send split instructions
• Which split commission types you can use

RequirementsCopy Anchor Link

Before you begin, take into account the following requirements, limitations, and preparations.

To collect your own share of a payment, send the MID of your liable account in partner_merchant_id.

When to provide split instructionsCopy Anchor Link

You can provide split instructions for payments when you make the following requests:

• Open the hosted payment page, in the split_fee array of the encrypted payload.
• Adjust the amount of a pre-authorised payment, in the split_fee array. The new split instructions replace the existing ones. If you don't send split_fee, the existing split instructions are kept.

Note that when you capture a pre-authorised payment, the split instructions from the payment or the last adjustment are used. You can't send new split instructions in the capture request.

You can provide instructions to split refunds when you make the following request:

• Refund a payment, in the refund_split_fee array. For each merchant that received part of the payment, specify the partner_merchant_id and the refund_amount to take back.

Send split instructionsCopy Anchor Link

To split a payment at the time of payment:

1. Add a split_fee array to your hosted payment page payload.

   For each item in the array, specify the following fields:

   Parameter	Required	Description
   partner_merchant_id	Required	The MID of the merchant that receives this part of the payment.
   type_id	Required	The split commission type of this part of the payment.
   value_type	Required	amount to send a fixed amount, or percentage to send a percentage of the payment amount.
   value	Required	The amount, or the percentage when value_type is percentage. Must be greater than 0. A percentage must be less than 100.

   For example, a shopper pays Example Pizza Ltd GBP 24.50 for a delivered order:

   • With type_id 3 (Delivery Fee), value_type amount and value 3.50, we book GBP 3.50 to the delivery partner, Example Couriers Ltd (partner_merchant_id 1000002).
   • The remaining GBP 21.00, before fees, is booked to Example Pizza Ltd.

   Send your split instructions in the split_fee array of the hosted payment page payload. The API Explorer has every field of the payload.

2. When the payment is captured, Datman sends a payment status webhook with a split_fee_status object. It contains the outcome and a message for the split.

TroubleshootingCopy Anchor Link

If the split instructions are not valid, the request fails. For example, an adjustment whose split amounts add up to the payment amount or more fails with the message Total split cannot be greater than or equal to order value.

To correct the balances after a payment is booked, you can transfer the funds between the merchants.

Track fund movementsCopy Anchor Link

To check how a payment was split:

1. Listen to the payment status webhook. On capture events for payments with split instructions, it contains split_fee_status.

2. Get the revenue split breakdown for the transaction, with the order reference in the path. The response contains one item for each share of the payment, with:

   • merchant_id: the merchant that receives the share.
   • commission_type: the name of the split commission type.
   • amount and amount_refunded: the amount of the share, and how much of it has been refunded.

   Note that amount and amount_refunded can be returned as strings, such as "3.5000". Parse them as numbers.

Split commission typesCopy Anchor Link

In each split instruction, you must use the type_id field to define the purpose of that part of the payment.

Datman provides the following global types, which every partner can use:

You can also create custom types for your own business. Custom types have an ID above 100. Types with an ID of 100 or below are built in, and you can't change or delete them.

Note that names must be unique among your types, ignoring case, and that this includes deleted types. A deleted type's name can't be reused.

Next stepsCopy Anchor Link

See alsoCopy Anchor Link

• Split commission types API
• Transactions
• Webhooks