Split payments

A split payment lets one application collect a payment and have Pesepay settle part of it to a different Pesepay merchant, automatically, with no transfer between you afterwards. The application that collects is the master merchant; the merchant that receives a share is the beneficiary.

Typical uses: a marketplace paying a vendor out of each sale, a booking platform paying a venue, a fees portal collecting on behalf of a school.

Turning splits on changes the contract for every transaction

From the moment your first beneficiary accepts, every transaction on that application must carry the beneficiary’s email in paymentMetadata — including ordinary sales that have nothing to do with the arrangement. Transactions without it are refused at initiation:

Transaction cannot be initiated without Beneficiary merchant email in paymentMetadata because this application has settlement split beneficiaries.

A merchant who adds their first beneficiary will break their existing checkout on the next payment unless the code is deployed first. Plan the two together, or set the arrangement up on a separate application.

Not the same thing as an EcoCash split

EcoCash payments above the per-transaction ceiling are collected in several parts — see Payments above the limit. That is one customer paying one merchant in several charges, and it is what the splits array on the result callback refers to. It has nothing to do with the settlement arrangement on this page.

How the money moves

Customer

Your server

Pesepay

Beneficiary

1 Create the transaction beneficiary email in paymentMetadata

2 Pays once one reference number

3 Divides the amount on success

4 Result callback no split detail on it

5 Credits the master merchant share

6 Credits the remainder their application, their payout account

1. Your server → Pesepay Create the transaction beneficiary email in paymentMetadata
2. Customer → Pesepay Pays once one reference number
3. Pesepay Divides the amount on success
4. Pesepay → Your server Result callback no split detail on it
5. Pesepay → Your server Credits the master merchant share
6. Pesepay → Beneficiary Credits the remainder their application, their payout account

One payment, two settlement credits

1. The customer pays once. One transaction, one reference number, one result callback — the customer never sees the arrangement.

2. On success, Pesepay creates two settlement records against the parent transaction: a credit to the master merchant for their share, and a credit to the beneficiary for the rest. Both are booked in the currency of the parent payment.

3. Each side is paid out on its own. The beneficiary’s credit lands against their Pesepay application and is settled to their payout account under the normal settlement schedule. You never hold or forward their money.

The split arithmetic runs on the transaction amount. Pesepay’s own transaction service fee is applied as usual for your application’s fee charge type — it is not part of the calculation below.

Note

Every standard Pesepay term still applies to both sides separately, including the minimum settlement threshold from your Merchant Agreement. A beneficiary taking a small percentage of small payments can sit below that threshold for a long time — their share accumulates, but it isn’t paid out until it clears the minimum.

Before you start

Both sides need to be approved Pesepay merchants before an arrangement can exist:

Requirement	Applies to	Why
An approved Pesepay merchant account	Beneficiary	The invitation is matched to an existing business by email. An unapproved account is rejected with Beneficiary merchant account has not yet been approved.
An approved payout account in the currency you charge in	Beneficiary	Credits inherit the parent transaction’s currency and are never converted. A ZWG payment to a beneficiary who only holds a USD payout account produces a balance they cannot withdraw
The email address the beneficiary’s business is registered under	Master merchant	It is both the invitation address and the value you send on every transaction

Caution

The currency point is an onboarding prerequisite, not a runtime check. Nothing fails at payment time — the money simply sits in a currency the beneficiary has no approved account for. Confirm their payout accounts cover every currency you will charge in before you send the invitation.

Setting up an arrangement

Arrangements are configured per application, in the Merchant Control Panel under Applications → View Details → Manage Splits.

1. The master merchant configures the split. Configure Split opens a form asking for the beneficiary merchant email, effective date, split amount mode, allocation model, and the fixed amount or percentage — the settings below. Submitting it sends the invitation.

2. The beneficiary gets an emailed invitation headed “<your application> split settlement invitation”, showing the agreement details and a link to review and accept it.

3. The beneficiary accepts. Pesepay creates a dedicated application on their account — named <your application> - <their business> Beneficiary — and their share of each payment is credited to it. They add a payout account to that application if they have not already.

4. The arrangement becomes active. Deploy the paymentMetadata change described below at this point, not after.

An application can hold several arrangements — one per beneficiary you collect for. Each transaction names exactly one of them.

Agreement status

Manage Splits lists every arrangement on the application with its beneficiary, allocation model, split amount mode, share, effective date and status; expanding a row also shows the agreement reference and the beneficiary’s settlement account.

Status	Meaning	Payments
INVITED	Sent, not yet answered	Not yet required, and not yet accepted
ENABLED / ACCEPTED	Live	Accepted for this beneficiary
DECLINED	The beneficiary refused the invitation	Never active
DISABLED	Suspended because the beneficiary’s application was deactivated	Refused, and the metadata requirement stays in force
REVOKED	Ended by the master merchant	Refused

Configuration reference

Setting	Values	Notes
allocationModel	PERCENTAGE, FIXED_AMOUNT	Required
percentage	Greater than 0, less than 100	Required for PERCENTAGE. This is the master merchant’s share, not the beneficiary’s
fixedAmount	Greater than 0	Required for FIXED_AMOUNT. Also the master merchant’s share
splitAmountMode	PRINCIPAL (default), ADD_ON	Set on the arrangement, not per transaction — see below
effectiveDate	A date; defaults to the day the invitation is created	Shown on the invitation

percentage is the master merchant's share

The field sits on a record called split beneficiary, which reads as though it describes what the beneficiary gets. It does not. percentage: 30 on a 100.00 payment means the master merchant keeps 30.00 and the beneficiary receives 70.00. Getting this backwards is the easiest misconfiguration to make — the invitation email calls it Master Merchant Share for exactly this reason.

Note

A third model, HYBRID, exists in the platform but isn’t offered in the panel, and currently allocates the fixed amount only — the percentage is never applied on top. Ignore it until that changes.

PRINCIPAL vs ADD_ON

PRINCIPAL takes the master merchant’s share out of the amount you submit. ADD_ON adds it on top, so the customer is charged more than the amount you sent.

Submitting amount: 100.00 against a 30% arrangement:

	PRINCIPAL	ADD_ON
Amount you submit	100.00	100.00
Amount the customer is charged	100.00	130.00
Master merchant receives	30.00	30.00
Beneficiary receives	70.00	100.00

The same payment with a fixed share of 5.00:

	PRINCIPAL	ADD_ON
Amount you submit	100.00	100.00
Amount the customer is charged	100.00	105.00
Master merchant receives	5.00	5.00
Beneficiary receives	95.00	100.00

ADD_ON rewrites the amount before the payment is created

Under ADD_ON, the amount on the transaction — and so on the hosted checkout, the callback and every report — is the amount you submitted plus the master merchant’s share. If your order totals, receipts or reconciliation are built against your own figure, they will disagree with Pesepay. Read the amount back from the transaction rather than assuming it is the one you sent.

Note

splitAmountMode is read from the accepted arrangement and written into the transaction’s metadata by Pesepay. Sending it yourself in paymentMetadata has no effect — from a request’s point of view it is read-only. Earlier Pesepay documentation said it had to be sent on every request (with aliases such as ADDON and ON_TOP). It no longer is: the mode set on the arrangement wins, whatever the request contains. Leaving it in an existing integration does no harm, but don’t rely on it to change anything.

What changes in your requests

Add the beneficiary’s email to paymentMetadata on every Initiate Transaction or Make Payment request for the application:

Plaintext request body (before encryption)

{
  "amountDetails": {
    "amount": 100.00,
    "currencyCode": "USD"
  },
  "reasonForPayment": "Order #1042 — running shoes",
  "paymentMetadata": {
    "beneficiaryMerchantEmail": "vendor@example.com"
  },
  "resultUrl": "https://example.com/payments/result",
  "returnUrl": "https://example.com/payments/return"
}

beneficiaryMerchantEmail is the canonical key. These aliases are also accepted, case-insensitively, for integrations that already use them: beneficiaryEmail, beneficiary_email, schoolEmail, school_email. Prefer the canonical key in new code.

Metadata Pesepay writes back

Pesepay adds two keys to the transaction’s metadata, and you get them back as transactionMetadata on the callback and from check payment status:

Key	Value
splitAmountMode	PRINCIPAL or ADD_ON, taken from the arrangement
splitPrincipalAmount	The amount before the master merchant’s share was added. Under PRINCIPAL this equals the amount charged; under ADD_ON it is the amount you submitted

Under ADD_ON, splitPrincipalAmount is the figure to reconcile your own order total against — amountDetails.amount is the larger, charged amount.

Errors

Split payments add three failures, all raised when you create the transaction and all 400 responses in the standard error shape. The message text is reproduced exactly.

No beneficiary email on the request

Transaction cannot be initiated without Beneficiary merchant email in paymentMetadata because this application has settlement split beneficiaries.

The application has at least one beneficiary in ENABLED, ACCEPTED or DISABLED, and this request carried no beneficiary email. Fix: send beneficiaryMerchantEmail on every transaction for this application, not only the ones you think of as split.

The email isn’t an accepted beneficiary

Transaction cannot be initiated because the supplied split beneficiary merchant email is not accepted.

There is no accepted arrangement on this application for that address — it was never invited, is still INVITED, was DECLINED, or has been REVOKED. Fix: check the spelling, and check the arrangement’s status in Manage Splits. This is also what you get in the gap while an arrangement is being replaced.

The beneficiary is disabled

PAYMENTS TO THE MERCHANT ARE CURRENTLY DISABLED, PLEASE CONTACT ADMINISTRATOR, OR TRY AGAIN LATER

The arrangement is DISABLED because the beneficiary’s own application was deactivated. Fix: nothing in your code — the beneficiary’s account needs attention. Note this message is customer-facing in tone but arrives as an API error; don’t show it verbatim at checkout.

One failure happens after the customer has paid

Allocation runs when the payment succeeds. If it cannot produce a valid division — most often because a fixed master-merchant share is equal to or larger than the payment amount — the payment still succeeds and the customer is still charged, but the split is not allocated and the transaction is flagged internally as a failed settlement split. Keep fixed shares comfortably below your smallest expected payment, and treat a beneficiary reporting a missing credit on an otherwise successful payment as a support case, with the referenceNumber.

Current limits

• One beneficiary per transaction. A payment divides between the master merchant and exactly one beneficiary. There is no n-way split, and no way to name more than one beneficiary on a request.
• One current arrangement per beneficiary, per application. Inviting a business that already has one is rejected — revoke the existing arrangement first.
• No currency conversion. Both credits inherit the parent transaction’s currency.
• Nothing about the split appears on the callback. The result callback describes the customer’s payment. The two credits are settlement records, visible in each merchant’s own dashboard.

Changing or ending an arrangement

Terms are fixed once accepted. To change a share, mode or model, revoke the arrangement and send a fresh invitation, which the beneficiary must accept again. Revoking is the ⋮ action on the arrangement’s row in Manage Splits; there is no edit, and no un-revoke.

Schedule this — do not do it mid-trade

Between the revocation and the new acceptance there is a gap in which transactions carrying that beneficiary’s email are refused with the supplied split beneficiary merchant email is not accepted. Revoking is also not reversible: a revoked arrangement cannot be switched back on, only replaced by a new invitation. Do it in a maintenance window, or outside trading hours.

Revoking your only beneficiary also lifts the metadata requirement, so transactions that omit the email start succeeding again while any request still sending the revoked address keeps failing. During a change-over, old and new code therefore fail in different ways — deploy the request change and the new acceptance close together.