settlement.status_changed

Sent when a settlement run starts and when it finishes, scheduled or started with POST /v1/settlements. Check outcome on a completed run: failed_partial and failed_all can be retried with POST /v1/settlements/{id}/resettlements. Answer with any 2xx within 10 seconds. Anything else, a timeout or a redirect is retried up to 6 times over about a day. Events can arrive out of order, so compare statuses rather than trusting arrival order.

POSTsettlement.status_changedWebhook

Header parameters

Webhook-Idstringrequired

The event id. The same event can arrive more than once; use this to ignore repeats.

Webhook-Timestampstringrequired

Unix seconds when this attempt was signed. Reject a delivery older than 5 minutes.

Webhook-Signaturestringrequired

v1, then a comma, then the base64 HMAC-SHA256 of "{Webhook-Id}.{Webhook-Timestamp}.{raw body}" keyed with your endpoint's signing secret. Compare in constant time.

Request body

requiredapplication/json

idstringrequired

The event id, the same as the Webhook-Id header.

typestringrequired

createdAtstring<date-time>required

When the change happened.

dataSettlementRunEventDatarequired

A settlement run as carried by its event. The event has no run id; list runs with GET /v1/settlements and match on reference when you need it.

Show properties

referencestringrequired

statusstringrequired

running or completed. Others can appear, so do not treat this list as closed.

outcomestring

Set once completed: settled, failed_partial or failed_all. Others can appear.

itemCountintegerrequired

How many payments the run made.

totalstringrequired

The amount settled. A decimal string in major units.

currencystringrequired

startedAtstring<date-time>required

completedAtstring<date-time>

Responses

2XX

Received. Any 2xx stops retries.

Payload

{
  "id": "string",
  "type": "settlement.status_changed",
  "createdAt": "2019-08-24T14:15:22Z",
  "data": {
    "reference": "string",
    "status": "string",
    "outcome": "string",
    "itemCount": 0,
    "total": "1250.50",
    "currency": "GHS",
    "startedAt": "2019-08-24T14:15:22Z",
    "completedAt": "2019-08-24T14:15:22Z"
  }
}

Response

Received. Any 2xx stops retries.