Split in Payment API

The Split Payment feature allows merchants to distribute the payout of a single transaction across a primary account and multiple sub-accounts via the API. This offers enhanced flexibility, enabling merchants to allocate funds to different recipients based on pre-configured or dynamic splitting rules.

Split payment parameters are supported in the following API endpoints: order.json, mobile.xml, remote.xml, remote_mpi.xml, remote.json and api_quicklink.json.

JSON Request Format

Merchants must include the 'splits' array of objects in the request body to define how the transaction is divided. Each entry in the array uses the 'id' parameter to identify the subaccount where the funds will be allocated.

Example 1:

"splits": [
  {
    "id": 1
  },
  {
    "id": 6
  },
  {
    "id": 8
  }
]

Custom Split Format with Values

Merchants can further customize how the transaction is split by using the 'type' and 'value' fields. This allows specifying whether the split should be a flat amount or a percentage of the total transaction after the MDR deduction.

Example 2:

"splits": [
  {
    "id": 1,
    "type": "flat",
    "value": "300"
  },
  {
    "id": 6,
    "type": "percentage",
    "value": "10"
  },
  {
    "id": 8
  },
  {
    "id": 9,
    "type": "flat",
    "value": "100"
  }
]

Explicit Merchant Share (id = 0)

Merchants can explicitly define how much they receive by specifying a split entry with id: 0.

Example 3:

"splits": [
  {
    "id": 0,
    "type": "flat",
    "value": "1"
  },
  {
    "id": 1001,
    "type": "remaining"
  }
]

• Merchant (id 0) receives a fixed 1 AED.
• Sub-merchant (id 1001) receives the remaining amount.

Example 4:

"splits": [
  {
    "id": 0,
    "type": "flat",
    "value": "1"
  },
  {
    "id": 1001,
    "type": "flat",
    "value": "30"
  },
  {
    "id": 1002,
    "type": "percentage",
    "value": "20"
  },
  {
    "id": 1003,
    "type": "remaining"
  }
]

• Merchant (id 0): 1 AED
• Sub-merchant 1001: 30 AED.
• Sub-merchant 1002: 20% of net payout.
• Sub-merchant 1003: remaining balance.

📘

This JSON format is supported in order.json , remote.json and api_quicklink.json.

XML Request Format:

<splits>
<split>
<id>10</id>
</split>
</splits>

<splits>
<split>
<id>10</id>
<type>flat</type>
<value>2</value>
</split>
<split>
<id>11</id>
<type>percentage</type>
<value>20</value>
</split>
</splits>

📘

This XML format can be used in mobile.xml, remote.xml, and remote_mpi.xml.

Parameter Details:

• id (Required): A unique identifier for the subaccount receiving the split.
• type (Optional): Specifies how the split should be calculated. Supported values:
  1. flat: A fixed amount is deducted from the total transaction value.
  2. percentage: A percentage-based deduction from the total transaction value.
  3. remaining: Allocates all remaining funds after other splits. Requires another split with id = 0. Must not include a value field.
• value (Optional if type is provided): The value associated with the split, either a fixed amount (for flat) or a percentage (for percentage).

Note:

• Multi-split payments are not supported for form-based requests.
• Split fields are not supported in authorization (auth) transactions.
• Split fields can be used during capture transactions processed via the remote API.
• In remote_mpi.xml, split fields must only be included in the first request and excluded from the third and any subsequent requests.
• The 'remaining' split type is only supported via API, not via dashboard.
• When using 'id: 0', exactly one 'remaining' split must be included.
• Only one remaining split and one id: 0 split are allowed per transaction.
• You may combine flat and percentage splits in any order—just be sure to include exactly one remaining split.

Test Split ID values for API:

Using the Test Split ID in a transaction request will process the transaction under the split payment flow. The following values can be used in the order.json API to simulate split payment transactions in test mode with "test" parameter as "1":

1. If Split ID value is passed anything from 1 to 100, it will act as flat settlement functionality for sub merchant. (E.g.: split_id = 5, then the settlement amount will be flat 5 AED on that transaction)
2. If Split ID value is passed anything from 1000 – 100000, it will act as percentage settlement functionality for sub merchant. Value will be multiples of 1000 and will be treated as percentage values (E.g.: 1000 = 1%, 2000 = 2%, 30000 = 30% and it goes on).
3. If the split ID value is greater than 100 but not a multiple of 1000, or if it's greater than 100000, the request will be rejected with an exception.
4. Note on Testing: The Test Split ID rules for flat and percentage remain unchanged; the new remaining type uses the same sandbox validation without a separate Test Split ID.

📘

Settlement will not be done in Split payment test mode. The test split ID’s will not be visible on the merchant dashboard.