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 in 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 and remote.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.

📘

This JSON format can also be use in order.json and remote.json format.

Example:

"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 deducted.

Example:

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

📘

This JSON format can also be use in order.json and remote.json format.

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. Possible values are:
  1. flat: A fixed amount is deducted from the total transaction value.
  2. percentage: A percentage-based deduction from the total transaction value.
• 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 the remote_mpi.xml file, split fields should only be included in the first remote_mpi request and must be excluded from the third remote_mpi request and any subsequent remote.xml requests.

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 5AED 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 more than 100 which are not multiple of 1000 or more than 100000, then the request will be declined with an exception.

📘

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