Payment Splitting

Payment splitting allows a merchant or platform to divide the payment amount along multiple recipients programmatically allowing many business models to conduct business while being compliant with SAMA and ZATCA regulations.

Payment splitting allows you to:

Split the payment along multiple recipients: Entity, Platform and Beneficiary.
Ensure money flows directly from the licensed gateway to the validated recipient thus complying with SAMA regulations regarding payments aggregation.
Only money that is intended for you (as a Platform) will reach your account avoiding complexities that can introduce for your accounting team.

Note that splitting is only available for aggregation clients only. Client with the facilitation (bank merchants) model cannot benefit from this feature.

Splitting on a payment source that is not aggregated by will be ignored.

Prerequisites

Splitting is not enabled by default for all platforms and only for a select partners, please contact your account manager to enable this feature.

You also need to know your recipient IDs before attempting splitting:

Entity recipient ID is the entity_id returned in the platform API which also can be found in the dashboard settings.
Platform recipient ID is the platform ID itself.

How Splitting Works

Splitting works by creating payments while adding splits field as in the following example:

{
  "amount": 10000,
  "description": "Cheesecake delivery for 100.00 SAR",
  "currency": "SAR",
  "callback_url": "https://example.com",
  "source": {
    "type": "creditcard",
    "number": "4111111111111111",
    "year": "2030",
    "month": "09",
    "cvc": "123"
  },
  "splits": [
    {
      "recipient_id": "36df2179-02bc-44b3-93bb-2e9285c03033",
      "amount": 8000
    },
    {
      "recipient_id": "ecf64e76-09f3-4ef2-ab56-d0e2e48e499e",
      "amount": 2000,
      "reference": "optional-reference-for-split-1fcfcbe9-ba75-4eed",
      "description": "Platform processing fee",
      "fee_source": true
    }
  ]
}

This example assumes that:

Entity ID is 36df2179-02bc-44b3-93bb-2e9285c03033
Platform ID is ecf64e76-09f3-4ef2-ab56-d0e2e48e499e

The previous example defines 2 splits where 80.00 SAR is sent to the merchant and 20.00 SAR as processing fee is sent to the platform (e.g. the delivery app).

Splits have two required fields recipient_id and amount while also supports additional fields that allows the API user to add extra information and references to help them track splits during settlements.

The option fee_source allows the API user to select which split to deduct the payment gateway processing fee from. If no split is denoted as a fee source, the merchant highest split will be chosen automatically.

Validation rules:

Split totals must equal to the payment amount.
Zero or exactly one fee source can be selected from the splits
Recipients must be valid recipients within the system
If a recipient is a platform, the platform must be the parent platform of the current merchant.
Splits can be negative, however, the absolute value sum for the negative splits must not exceed the payment.
Entity splits cannot be negative.

The following sections will into more practical examples for splitting to guide you through the whole process.

Example 1: Entity with a Non-reseller Platform

A non-reseller platform manages entities but does not profit from the payment gateway processing fees, the fee structure for such situation can be imagined as follows:

Entity fee: 2.5% + 1 SAR

In this case, Moyasar sells to the merchant directly but the merchant is managed by the platform.

If we have a payment with 100.00 SAR and the platform takes a 5.00% cut including the payment gateway processing fee. Our payment request will look as follows:

{
  "amount": 10000,
  "description": "Cheesecake delivery for 100.00 SAR",
  "currency": "SAR",
  "callback_url": "https://example.com",
  "source": {
    "type": "creditcard",
    "name": "John Doe",
    "number": "4111111111111111",
    "year": "2030",
    "month": "09",
    "cvc": "123"
  },
  "splits": [
    {
      "recipient_id": "36df2179-02bc-44b3-93bb-2e9285c03033",
      "amount": 9500
    },
    {
      "recipient_id": "ecf64e76-09f3-4ef2-ab56-d0e2e48e499e",
      "amount": 500,
      "reference": "optional-reference-for-split-1fcfcbe9-ba75-4eed",
      "description": "Platform processing fee",
      "fee_source": true
    }
  ]
}

Note that we have set fee_source: true to inform Moyasar that thus split should be used for processing fees.

Once the payment is paid Moyasar will calculate the payment gateway processing fee using the following formula:

Fee = round(Payment Amount * (Fee Rate / 100)) + Fee Fixed
VAT = round(Fee * (15 / 100))
Total Fee = Fee + VAT

Note: rounding must be used with each calculation using Banker Rounding to ensure all amounts are valid SAR.

Fee = 100.00 * (2.50 / 100.00) + 1.00 = 3.50
VAT = 3.50 * (15 / 100) = 0.53
Total Fee = 4.03 SAR

Once the payment is made, you can see the splits definition returned in the payment response:

{
  "id": "7c8c9ecd-5d38-4033-93f6-8b65ed28f1cd",
  "status": "paid",
  "amount": 10000,
  "fee": 403,
  "currency": "SAR",
  "refunded": 0,
  "refunded_at": null,
  "captured": 0,
  "captured_at": null,
  "voided_at": null,
  "description": "Cheesecake delivery for 100.00 SAR",
  "amount_format": "100.00 SAR",
  "fee_format": "4.03 SAR",
  "refunded_format": "0.00 SAR",
  "captured_format": "0.00 SAR",
  "invoice_id": null,
  "ip": "5.163.174.31",
  "callback_url": "https://example.com",
  "created_at": "2025-10-13T10:26:49.895Z",
  "updated_at": "2025-10-13T10:26:49.933Z",
  "metadata": null,
  "source": {
    "type": "creditcard",
    "company": "visa",
    "name": "John Doe",
    "number": "4111-11XX-XXXX-1111",
    "gateway_id": "moyasar_cc_4MRjxCYVGzXcUNrmkU2WyhR",
    "reference_number": "992528682471",
    "token": null,
    "message": "APPROVED",
    "transaction_url": null,
    "response_code": "00",
    "authorization_code": "007594",
    "issuer_name": "MOYASAR PAY SANDBOX",
    "issuer_country": "SA",
    "issuer_card_type": "credit",
    "issuer_card_category": "PREPAID"
  },
  "splits": [
    {
      "recipient_type": "Entity",
      "recipient_id": "d09ec959-8a3a-45d8-9db3-08cb7c589130",
      "amount": 9500,
      "description": null,
      "reference": null,
      "fee_source": false,
      "refundable": true
    },
    {
      "recipient_type": "Platform",
      "recipient_id": "a6c3afed-aa8d-46ef-a316-e2dd78ea54fd",
      "amount": 500,
      "description": "Platform processing fee",
      "reference": "optional-reference-for-split-1fcfcbe9-ba75-4eed",
      "fee_source": true,
      "refundable": true
    }
  ]
}

Once Moyasar settle to the platform and merchant, the splits will look something like this:

Platform will recieve 0.97 SAR which is 5.00 - 4.03 = 0.97 SAR where 4.03 is the gateway processing fee.
Merchant (Entity) will recieve 95.00 SAR.

Example settlement CSV for Platform

payment_id	description	scheme	source	type	currency	amount	net_amount	fee	vat	total_fee	transaction_date	source_country	is_custom_split	split_reference	split_description
7c8c9ecd-5d38-4033-93f6-8b65ed28f1cd	Cheesecake delivery for 100.00 SAR	visa	Card	pay	SAR	100.00	0.97	0.00	0.00	0.00	2025-10-13 01:26 PM	SA	true	optional-reference-for-split-1fcfcbe9-ba75-4eed	Platform processing fee

Example settlement CSV for Entity

payment_id	description	scheme	source	type	currency	amount	net_amount	fee	vat	total_fee	transaction_date	source_country	is_custom_split	split_reference	split_description
7c8c9ecd-5d38-4033-93f6-8b65ed28f1cd	Cheesecake delivery for 100.00 SAR	visa	Card	pay	SAR	100.00	95.00	3.50	0.53	4.03	2025-10-13 01:26 PM	SA	true

This example explores a powerful feature that allows platform to make complex settlement senarios by allowing it to move money from one recipient to another.

Let's take the following as an example:

A customer buys a 100.00 SAR gourmet pizza.
They use the platform coupon feature to get a 20.00 SAR discount.
The platform make a payment for 80.00 SAR while still settlling 95.00 SAR to the merchant.

To achieve this, we can utilize a negative split where we deduct 20.00 SAR from the platform current balance with Moyasar and still add a split to the merchant for 95.00 SAR. Note that if the platform balance is not enough the payment will still go through and platform balance will be negative.

{
  "amount": 8000,
  "description": "Cheesecake delivery for 100.00 SAR",
  "currency": "SAR",
  "callback_url": "https://example.com",
  "source": {
    "type": "creditcard",
    "name": "John Doe",
    "number": "4111111111111111",
    "year": "2030",
    "month": "09",
    "cvc": "123"
  },
  "splits": [
    {
      "recipient_id": "d09ec959-8a3a-45d8-9db3-08cb7c589130",
      "amount": 9500
    },
    {
      "recipient_id": "a6c3afed-aa8d-46ef-a316-e2dd78ea54fd",
      "amount": 500,
      "reference": "optional-reference-for-split-1fcfcbe9-ba75-4eed",
      "description": "Platform processing fee",
      "fee_source": true
    },
    {
      "recipient_id": "a6c3afed-aa8d-46ef-a316-e2dd78ea54fd",
      "amount": -2000,
      "reference": "368243a7-2aa7-4ec8-99b2-cf0b374418cd",
      "description": "Loyality programa discount"
    }
  ]
}

Once the payment is processed, the following splits will be created:

Platform: 1.55 SAR (from the result of 5.00 - 3.45 SAR)
Platform: -20.00 SAR
Entity: 95.00 SAR

Example 3: Entity with a Reseller Platform

Before we begin with this, what is a reseller platform?

A reseller platform partners with Moyasar under the reselling model where Moyasar provides payment services to the platform at a given rate, and the platform can then offer these services to merchants at a higher price to ear profit.

The platform remains compliant here since all merchants KYC and settlements will be handled by Moyasar. The platform will recieve only their profit after a given time.

Let's begin our example:

Moyasar charge the platform 2.0% for a transaction
The platform charges the merchant 2.5% for a transaction

Now for any transaction, the platform should receive 0.5% as profit margin. Let's begin our example:

{
  "amount": 10000,
  "description": "Cheesecake delivery for 100.00 SAR",
  "currency": "SAR",
  "callback_url": "https://example.com",
  "source": {
    "type": "creditcard",
    "name": "John Doe",
    "number": "4111111111111111",
    "year": "2030",
    "month": "09",
    "cvc": "123"
  },
  "splits": [
    {
      "recipient_id": "8f354708-0858-480d-8d59-99e2bedd8a93",
      "amount": 9000
    },
    {
      "recipient_id": "7747134f-cbf1-4ced-ab0c-c818b8b00b30",
      "amount": 1000,
      "description": "Platform food material cost"
    }
  ]
}

The payment processing for the previous example will be

Entity Fee: 2.88 SAR
Platform Fee: 2.30 SAR

The system will generate the following splits for the payment:

Entity: 87.12 SAR (90.00 - 2.88)
Platform: 10.00 SAR
Platform processing profit: 2.88 SAR - 2.30 = 0.58 SAR

You can see that the system added an extra split which is the profit from processing fees for the platform.

Here is the settlement file for the Entity:

payment_id	description	scheme	source	type	currency	amount	net_amount	fee	vat	total_fee	transaction_date	source_country	is_custom_split	split_reference	split_description
84b6fec8-b6e5-4d50-8220-a4939910d399	Cheesecake delivery for 100.00 SAR	visa	Card	pay	SAR	100.00	87.12	2.50	0.38	2.88	2025-10-14 06:36 PM	SA	true

Here is the settlement for Platform:

payment_id	description	scheme	source	type	currency	amount	net_amount	fee	vat	total_fee	transaction_date	source_country	is_custom_split	split_reference	split_description
84b6fec8-b6e5-4d50-8220-a4939910d399	Cheesecake delivery for 100.00 SAR	visa	Card	pay	SAR	100.00	10.00	2.00	0.30	2.30	2025-10-14 06:36 PM	SA	true		Platform food material cost
84b6fec8-b6e5-4d50-8220-a4939910d399	Cheesecake delivery for 100.00 SAR	visa	Card	pay	SAR	100.00	0.58	2.00	0.30	2.30	2025-10-14 06:36 PM	SA	false

Notes on Refunds

By default, all splits will be reversed in the following cases:

The payment is voided (reversed) through dashboard or API.
The payment is refunded through dashboard or API.

To prevent splits from being refunded, you can add the following parameter in the split object:

"refundable": false

With this option, when the payment is refunded, the remaining amount will be deducted from the merchant account.

Please note that a void will always reverse the split.

Prerequisites​

How Splitting Works​

Example 1: Entity with a Non-reseller Platform​

Example 2 (Promo Code)​

Example 3: Entity with a Reseller Platform​

Notes on Refunds​

Prerequisites

How Splitting Works

Example 1: Entity with a Non-reseller Platform

Example 2 (Promo Code)

Example 3: Entity with a Reseller Platform

Notes on Refunds