Skip to content

Settlements

A settlement is the money owed to your business from processed collections. This guide covers how to check how much of that money is still pending payout.

Pending Settlements Summary

Returns the total value and count of your pending settlements for a business and currency — that is, money from your collections that has not yet been paid out to you. This includes:

  • Collections that have not yet been grouped into a settlement batch, and
  • Collections already grouped into a settlement batch, but whose payout has not yet been completed.

Only settlements recorded in the last 30 days are included in the total; the window is fixed and cannot be changed via query parameters.

GET {BASE_URL}/api/v1/settlements/pending?businessId={business_id}&currency=NGN

Required Query Parameters

Parameter Type Description
businessId string (UUID) ID of the business to summarize pending settlements for
currency string Currency code (e.g. NGN, KES, USD)

Sample Response

{
  "status": 200,
  "message": "Success",
  "data": {
    "businessId": "xxx-xxx-xxx",
    "currency": "NGN",
    "totalPendingAmount": 452000.00,
    "totalPendingCount": 37
  }
}

Response Fields

Field Type Description
businessId string (UUID) The business ID the summary was requested for
currency string Currency of the amounts returned
totalPendingAmount number Total value of pending settlements recorded in the last 30 days
totalPendingCount number Number of individual settlement records included in the total

Example

curl -X GET \
  "https://core-sandbox.payonus.com/api/v1/settlements/pending?businessId=<business-uuid>&currency=NGN" \
  -H "Authorization: Bearer <access_token>"

Errors

  • 400 Bad Request — businessId or currency is missing or invalid
  • 401 Unauthorized — Missing or invalid token
  • 403 Forbidden — Insufficient authority