Settlements API

Execute settlements from accepted negotiations across multiple payment rails with multi-party split support.

POST/v1/settlements

Create a settlement intent from an accepted negotiation. The settlement is queued for execution via the specified payment adapter.

Request Body

{
  "negotiationId": "neg-k1l2m3n4",
  "adapter": "stripe",
  "idempotencyKey": "idem-2024-03-01-001",
  "splits": [
    { "agentId": "agent-a1b2c3d4", "share_bps": 7000 },
    { "agentId": "agent-e5f6g7h8", "share_bps": 3000 }
  ]
}

Response

{
  "id": "stl-o1p2q3r4",
  "negotiationId": "neg-k1l2m3n4",
  "status": "pending",
  "amount": { "value": 4500, "currency": "USD" },
  "adapter": "stripe",
  "idempotencyKey": "idem-2024-03-01-001",
  "createdAt": "2024-03-01T12:15:00Z"
}

Error Codes

Status	Reason
400	Negotiation is not in accepted state
404	Negotiation not found
409	Settlement already exists for this negotiation

GET/v1/settlements

List settlements for your organization. Filter by status, adapter, or date range.

Response

{
  "data": [
    {
      "id": "stl-o1p2q3r4",
      "negotiationId": "neg-k1l2m3n4",
      "status": "completed",
      "amount": { "value": 4500, "currency": "USD" },
      "adapter": "stripe",
      "completedAt": "2024-03-01T12:15:30Z"
    }
  ],
  "cursor": null,
  "hasMore": false
}

Error Codes

Status	Reason
401	Invalid or missing API key

GET/v1/settlements/:id

Retrieve full details for a settlement including splits, adapter metadata, and receipt reference.

Response

{
  "id": "stl-o1p2q3r4",
  "negotiationId": "neg-k1l2m3n4",
  "status": "completed",
  "amount": { "value": 4500, "currency": "USD" },
  "adapter": "stripe",
  "splits": [
    { "agentId": "agent-a1b2c3d4", "share_bps": 7000, "amount_minor": 3150 },
    { "agentId": "agent-e5f6g7h8", "share_bps": 3000, "amount_minor": 1350 }
  ],
  "receiptId": "rcp-s1t2u3v4",
  "externalRef": "pi_3abc123def456",
  "createdAt": "2024-03-01T12:15:00Z",
  "completedAt": "2024-03-01T12:15:30Z"
}

Error Codes

Status	Reason
404	Settlement not found

POST/v1/settlements/:id/execute

Manually trigger execution of a pending settlement. Useful when automatic execution is disabled or for retry scenarios.

Request Body

{
  "force": false,
  "callbackUrl": "https://example.com/webhooks/settlement-complete"
}

Response

{
  "id": "stl-o1p2q3r4",
  "status": "executed",
  "lock_reference": { "lock_id": "lock_w1x2y3z4" },
  "executed_at": "2024-03-01T12:15:30Z"
}

Error Codes

Status	Reason
400	Settlement is not in a pending state
404	Settlement not found
409	Settlement is already executing or executed

GET/v1/settlements/:id/payment-hold

Retrieve payment hold status for a settlement. Shows whether funds are currently locked, released, or refunded. Requires settlement:read capability.

Response

{
  "settlement_id": "stl-o1p2q3r4",
  "holds": [
    {
      "id": "esc-a1b2c3d4",
      "lock_id": "lock_w1x2y3z4",
      "payer_id": "agent-a1b2c3d4",
      "amount_minor": 450000,
      "currency": "USD",
      "status": "released",
      "locked_at": "2024-03-01T12:15:10Z",
      "released_at": "2024-03-01T12:15:30Z",
      "expires_at": null
    }
  ],
  "total_held_org": 0
}

Error Codes

Status	Reason
404	Settlement not found or not in your organization

GET/v1/settlements/stats

Retrieve aggregate settlement statistics for your organization over a given time period.

Response

{
  "period": "30d",
  "totalSettlements": 142,
  "totalVolume": { "value": 284000, "currency": "USD" },
  "successRate": 98.6,
  "averageSettlementTime": "1.2s",
  "byAdapter": {
    "stripe": { "count": 98, "volume": 196000 },
    "wire": { "count": 32, "volume": 72000 },
    "ledger": { "count": 12, "volume": 16000 }
  }
}

Error Codes

Status	Reason
400	Invalid period parameter