POST /transaction/web/fetch_settlements

Retrieve cleared settlement records for your accounts via the Dashboard API. Use settlements to reconcile confirmed credit transactions.

Settlement transactions represent inbound payments that have been fully cleared and credited to one of your accounts. Unlike the general transaction list, the settlements endpoint filters to confirmed credit events only, making it the right tool for end-of-day reconciliation and balance verification. Use the date range filters to scope results to a specific period and match settlements against your own records.

Endpoint

POST https://baasapi.payrepmfb.com/api/v1/transaction/web/fetch_settlement_transactions

Sandbox

POST https://shogun-dev.xchangeboxng.com/api/v1/transaction/web/fetch_settlement_transactions

Authentication

Include your Bearer token in the Authorization header:

Authorization: Bearer <access_token>

Obtain a token by logging in via User Login.

Request body

All filter criteria are nested inside a filters object.

filters · object

Optional object containing filter criteria for the settlement query.

Show filters

account_number · string

Limit results to settlements for a specific 10-digit account number.

start_date · string (date)

Return only settlements on or after this date. Format: YYYY-MM-DD.

end_date · string (date)

Return only settlements on or before this date. Format: YYYY-MM-DD.

date · string (date)

Filter to a single calendar day. Format: YYYY-MM-DD. When provided, takes precedence over start_date and end_date.

reference_number · string

Fetch a specific settlement by its unique reference number.

status · string

Filter by settlement status. Typically success for cleared records.

page · integer · default: "1"

Page number for paginated results. Starts at 1.

page_size · integer · default: "20"

Number of records to return per page. Minimum 1.

limit · integer · default: "20"

Maximum number of results to return. Minimum 1.

cursor_created_at · string (date-time)

Cursor for cursor-based pagination. Pass the created_at timestamp of the last item from the previous page.

cursor_id · string (uuid)

Cursor ID paired with cursor_created_at for stable cursor-based pagination.

Example request

curl --request POST \
  --url https://baasapi.payrepmfb.com/api/v1/transaction/web/fetch_settlement_transactions \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": {
      "account_number": "7801234567",
      "start_date": "2026-04-01",
      "end_date": "2026-04-28"
    },
    "page": 1,
    "page_size": 20
  }'

Response

A successful response returns the standard envelope with an array of settlement records in data.

status · boolean

true when the request succeeded.

response_code · string

"00" on success.

message · string

Human-readable status message.

data · array

Array of cleared settlement objects matching your filters.

Show Settlement object

reference · string

Unique reference for the settlement record. Use this to match against your own payment records.

account_number · string

The 10-digit account number that received the settlement credit.

amount · string (decimal)

The settled amount in NGN (e.g., "25000.00").

settlement_date · string (date-time)

ISO 8601 timestamp of when the settlement was cleared and credited to the account.

status · string

Settlement status. A value of success confirms the credit has been applied to the account balance.

{
  "status": true,
  "response_code": "00",
  "message": "Settlement transactions fetched successfully",
  "data": [
    {
      "reference": "STL-20260415-00056",
      "account_number": "7801234567",
      "amount": "25000.00",
      "settlement_date": "2026-04-15T14:00:00Z",
      "status": "success"
    }
  ]
}

Error codes

Code	Meaning
00	Success
41	Customer not found — your session token is invalid or expired