API Reference

Splits API

Trigger split executions and batch operations via the Orchestrator API.

POST /api/v1/split

Initiates a single split execution. The Orchestrator matches the incoming transaction to an active routing rule and processes disbursements accordingly.

Request Body

{
  "routingRuleId": "rule_id",
  "amountInPesewas": 10000,
  "metadata": {
    "orderId": "ord_67890",
    "customerId": "cust_111"
  }
}

Request Fields

Field	Type	Description
routingRuleId	string	The specific routing rule to apply
amountInPesewas	integer	Amount in pesewas (e.g. 10000 = GHS 100.00). Must be a positive integer.
externalId	string (optional)	External reference for this transaction, passed through to webhooks and logs
metadata	object (optional)	Arbitrary key-value pairs passed through to webhooks and logs
idempotencyKey	string (optional)	Unique key for idempotent request processing (max 256 chars)

POST /api/v1/split/batch

Executes multiple splits in a single request. Each item is processed independently — partial failures are reported per item.

Request Body

{
  "items": [
    {
      "routingRuleId": "rule_a",
      "amountInPesewas": 5000,
      "metadata": { "orderId": "ord_111" }
    },
    {
      "routingRuleId": "rule_b",
      "amountInPesewas": 15000,
      "metadata": { "orderId": "ord_222" }
    }
  ]
}

Response

Split Response

{
  "success": true,
  "transactionId": "txn_id"
}

How Routing Rules Are Triggered

The incoming transaction is matched to the merchant's active routing rules.
If a routingRuleId is provided in the request, that specific rule is used.
Otherwise, the first active rule matching the transaction criteria is applied.
The split engine calculates disbursements based on the rule's preset configuration.
Disbursements are queued and processed asynchronously — the initial response confirms the transaction was enqueued (success: true).
Track final status via the Transactions API or webhook callbacks.
If the routing rule has escrow enabled, the transaction enters a LOCKED state instead of proceeding to disbursement. Release it via POST /api/v1/escrow/release or wait for the configured lock duration to expire.