Split Settlements

Split Settlements enables merchants to allocate portions of a transaction amount to different partner accounts or entities. This is particularly useful for platforms with multiple service providers, affiliate programs or shared revenue agreements. Each partner receives a predefined share of the transaction amount directly. Additionally, some partner accounts are dynamic and must be included in every request.

Charge Requests with Split Settlements

All charge requests, whether through Checkout Redirect or Direct Charge API, include an extra_data property containing metadata about the specific transaction. For transactions involving split settlements, the following should be added to extra_data

{
    "extra_data": {
        "split_settlements": [
            {
                "account": "100008898",
                "amount": "100",
                "reason": "LPG cylinder delivery costs"
            }
        ]
    }
}

Example Request

{
    "external_reference": "testref12345567",
    "origin_channel_code": "API",
    "originator_msisdn": "25410000000",
    "payer_msisdn": "25410000000",
    "payer_email": "[email protected]",
    "payer_name": "John",
    "client_code": "Doe",
    "service_code": "TESTCHECKOUT",
    "account_number": "01000000000",
    "invoice_number": "test",
    "currency_code": "KES",
    "country_code": "KEN",
    "amount": 1000,
    "add_transaction_charge": false,
    "transaction_charge": 0,
    "payment_method_code": "MPESA",
    "paybill": "111111",
    "extra_data": {
        "split_settlements": [
            {
                "account": "10000191",
                "amount": 500,
                "reason": "LPG cylinder delivery costs"
            }
        ]
    },
    "description": "Payment by 254700123456",
    "notify_client": true,
    "notify_originator": true
}

Payment Service Processing Confirmation

Endpoints:

1. POST https://api.lipad.io/transactions/acknowledge (production)
2. POST https://dev.lipad.io/transactions/acknowledge (sandbox)

Split settlements follow the service processing confirmation step. Once the merchant confirms the transaction service, the system validates and allocates the split settlements. This ensures all partner accounts receive their respective amounts as per the transaction details.

Confirmation Workflow

1. Transaction Processing: The payment is processed through the designated payment method.
2. Service Confirmation: The system receives a confirmation from the payment service, indicating the success or failure of the transaction.
3. Settlement Allocation: Upon successful confirmation, the split settlements are processed, and funds are distributed to the specified partner accounts.

Transaction Confirmation Payload

{
    "payment_id":"1234",
    "status":"SUCCESSFUL",
    "narration":"Service processed successfully"
}

Transaction processing status:

1. FAILED
2. SUCCESSFUL

Confirmation Response

{
    "payment_id": "1234",
    "message": "Success"
}