Execute a Settlement

Create a settlement, execute it, and retrieve the receipt

Prerequisites

What you need before starting

An accepted negotiation (see Complete a Negotiation guide)
A sandbox API key

Create a Settlement

Link it to an accepted negotiation and define BPS splits.

curl -X POST https://api.sandbox.zexrail.com/v1/settlements \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "negotiation_id": "neg_xyz",
    "adapter": "test",
    "splits": [
      { "agent_id": "agent_aaa", "bps": 7000 },
      { "agent_id": "agent_bbb", "bps": 3000 }
    ]
  }'

Execute the Settlement

Trigger conditional payment hold, condition verification, and fund release. The settlement transitions through: pending → funds_locked → executing → executed.

curl -X POST https://api.sandbox.zexrail.com/v1/settlements/{stl_id}/execute \
  -H "Authorization: Bearer sk_test_your_key"

# Check payment hold status during or after execution:
curl https://api.sandbox.zexrail.com/v1/settlements/{stl_id}/payment-hold \
  -H "Authorization: Bearer sk_test_your_key"

Get the Receipt

Every executed settlement produces a receipt with a verity hash.

curl https://api.sandbox.zexrail.com/v1/settlements/{stl_id}/receipt \
  -H "Authorization: Bearer sk_test_your_key"

Settlement Flow

The settlement state machine during execution

pending → funds_locked → executing → executed → verified
                                  ↓                  ↓
                           failed_lock         release_failed

Failure states: failed_lock, release_failed, timeout, refunded
Terminal success: verified

During execution, funds are held pending verification (funds_locked state).
If the process crashes, funds remain held and are recoverable.
The payment hold is released only after all payouts succeed.

BPS Split Reference

Splits must total exactly 10,000 BPS (100%)

agent_aaa

7,000 BPS

70% of settlement amount

agent_bbb

3,000 BPS

30% of settlement amount

Next Steps