Skip to content
YusrDocs

API reference

Settlements

A settlement is a batch payout of your net collections to your verified settlement bank account, on your T+0 or T+1 schedule.

Settlements endpoints
get/v1/settlementsList settlements
get/v1/settlements/{id}Retrieve a settlement with its transactions

Read the Settlements and fees for the concepts behind these endpoints.

List settlements

get/v1/settlements

Query parameters

Query parameters
limitinteger

1–100, default 20

starting_afterstring

Cursor: the next_cursor from the previous page.

curl "https://api.yusr.ng/v1/settlements?limit=10" \
  -H "Authorization: Bearer sk_test_..."

Responses

200A page of settlements
Show response attributes
Response attributes
objectstringrequired

always "list"

dataarray of objectrequired
Show child attributes
idstringrequired
objectstringrequired

always "settlement"

modestringrequired

One of test, live

statusstringrequired

One of pending, processing, completed, failed, on_hold

currencystringrequired

always "NGN"

period_startstringrequired
period_endstringrequired
grossintegerrequired
feesintegerrequired
netintegerrequired
transaction_countintegerrequired
bank_accountobject | nullrequired
created_atstringrequired
completed_atstring | nullrequired
transactionsarray of object
Show child attributes
idstringrequired
referencestringrequired
amount_receivedintegerrequired
feeintegerrequired
net_amountintegerrequired
has_morebooleanrequired
next_cursorstring | nullrequired
Response 200
{
  "object": "list",
  "data": [
    {
      "id": "stl_01JA9R7T2C4E6G8J0K2M4P6R8T",
      "object": "settlement",
      "mode": "live",
      "status": "completed",
      "currency": "NGN",
      "period_start": "2026-10-05T00:00:00.000Z",
      "period_end": "2026-10-06T00:00:00.000Z",
      "gross": 7500000,
      "fees": 112500,
      "net": 7387500,
      "transaction_count": 3,
      "bank_account": {
        "bank_name": "Partner Bank",
        "account_number": "******7890",
        "account_name": "ACME STORES LIMITED"
      },
      "created_at": "2026-10-06T08:00:00.000Z",
      "completed_at": "2026-10-06T08:00:41.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
Error responses
StatusMeaningError codes
401Authentication failedauthentication_failed
Try it in the sandbox

Retrieve a settlement with its transactions

get/v1/settlements/{id}

Path parameters

Path parameters
idstringrequired
curl "https://api.yusr.ng/v1/settlements/stl_01JA9R7T2C4E6G8J0K2M4P6R8T" \
  -H "Authorization: Bearer sk_test_..."

Responses

200The settlement
Show response attributes
Response attributes
idstringrequired
objectstringrequired

always "settlement"

modestringrequired

One of test, live

statusstringrequired

One of pending, processing, completed, failed, on_hold

currencystringrequired

always "NGN"

period_startstringrequired
period_endstringrequired
grossintegerrequired
feesintegerrequired
netintegerrequired
transaction_countintegerrequired
bank_accountobject | nullrequired
created_atstringrequired
completed_atstring | nullrequired
transactionsarray of object
Show child attributes
idstringrequired
referencestringrequired
amount_receivedintegerrequired
feeintegerrequired
net_amountintegerrequired
Response 200
{
  "id": "stl_01JA9R7T2C4E6G8J0K2M4P6R8T",
  "object": "settlement",
  "mode": "live",
  "status": "completed",
  "currency": "NGN",
  "period_start": "2026-10-05T00:00:00.000Z",
  "period_end": "2026-10-06T00:00:00.000Z",
  "gross": 7500000,
  "fees": 112500,
  "net": 7387500,
  "transaction_count": 3,
  "bank_account": {
    "bank_name": "Partner Bank",
    "account_number": "******7890",
    "account_name": "ACME STORES LIMITED"
  },
  "created_at": "2026-10-06T08:00:00.000Z",
  "completed_at": "2026-10-06T08:00:41.000Z",
  "transactions": [
    {
      "id": "txn_01JA9Q3K7M2VXR8D5N0B4C6E2F",
      "reference": "order-1042",
      "amount_received": 2500000,
      "fee": 37500,
      "net_amount": 2462500
    }
  ]
}
Error responses
StatusMeaningError codes
401Authentication failedauthentication_failed
404Not foundnot_found
Try it in the sandbox