Guide · 06 / 10

Split & escrow

Divide a collection across recipients and hold shares in escrow.

Split rules describe how a collection's value is divided among recipients. Escrow lets a recipient's share be held back until a condition is met, instead of settling immediately.

Split rules

Create a reusable rule with POST /split-rules (a write operation; no idempotency key required).

Request (SplitRuleCreateRequest):

Field	Required	Notes
`name`	yes	Human label for the rule.
`rule_type`	yes	`percentage`, `flat`, or `tiered`.
`currency`	for `flat`	ISO-4217 the flat amounts are denominated in. Omit for percentage rules.
`recipients`	yes	1+ recipients (below).

Each recipient (SplitRuleRecipient):

Field	Required	Notes
`recipient_type`	yes	`platform`, `sub_merchant`, or `tax`.
`recipient_id`	for `sub_merchant`	UUID of the sub-merchant receiving the share.
`value`	yes	Percentage `0`–`100` when `rule_type = percentage`, otherwise a flat minor-unit amount.
`escrow`	no	`true` holds this recipient's share (default `false`).
`escrow_release_condition`	no	`manual`, `auto_timeout`, or `delivery_confirmation`.
`escrow_timeout_hours`	no	Used with `auto_timeout`.

Example — platform keeps 10%, the sub-merchant gets 90% held in escrow until delivery is confirmed:

curl -sS https://sandbox.api.wasaapay.com/v1/split-rules \
  -H "X-WasaaPay-Key: $KEY" -H "X-WasaaPay-Timestamp: $TS" -H "X-WasaaPay-Signature: $SIG" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "Standard marketplace split",
    "rule_type": "percentage",
    "recipients": [
      { "recipient_type": "platform", "value": 10, "escrow": false },
      { "recipient_type": "sub_merchant", "recipient_id": "5f0e1d2c-...", "value": 90,
        "escrow": true, "escrow_release_condition": "delivery_confirmation" }
    ]
  }'

The response is a SplitRule with an id and active: true. List rules with GET /split-rules (optionally ?active=true) and fetch one with GET /split-rules/{id}.

A percentage rule's values should describe a complete division of the collection (platform + recipients = 100%). Validation errors come back as 422 VALIDATION_ERROR with the offending fields in details.

Escrow

Escrow keeps a share in a wallet's pending bucket (it shows up as pending_balance, not available_balance) until it is released.

There are two ways a share enters escrow:

Per collection — set hold_in_escrow: true on POST /collections (Collections). The merchant leg lands in the pending bucket.
Per split recipient — set escrow: true on a recipient in a split rule, with an escrow_release_condition.

Release conditions

Condition	Releases when
`manual`	You explicitly release the hold (via the WasaaPay dashboard / operations).
`auto_timeout`	`escrow_timeout_hours` elapse.
`delivery_confirmation`	Delivery is confirmed for the order.

Escrow lifecycle & webhooks

Each hold moves through a lifecycle you observe via escrow.* webhooks:

escrow.held — funds moved into the pending bucket.
escrow.released — the condition was met; funds moved to available.
escrow.returned — the hold was returned to the payer/source (e.g. a dispute or a full refund on the collection).

Subscribe to these events to keep your own ledger in step with what is spendable.

Note on releasing escrow. This version of the public API does not expose a dedicated "release escrow" endpoint — release is driven by the configured condition (timeout / delivery confirmation) or performed operationally through the dashboard, and the outcome is reported to you as an escrow.released (or escrow.returned) webhook. If you need programmatic release, raise it with your WasaaPay contact.