> For the complete documentation index, see [llms.txt](https://ivorypay.gitbook.io/ivorypay-api-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ivorypay.gitbook.io/ivorypay-api-documentation/transactions/settlements.md).

# Settlements

Use this endpoint to retrieve the history of settlements processed for your business. Both **fiat** (bank transfer) and **crypto** (on-chain withdrawal) settlements are returned in a single unified list, sorted by most recent first.

**Base path:** `/v1/business/settlements`\
**Authentication:** Secret key (`Authorization: sk_...`)

***

## Endpoints

| Method | Path                       | Auth    | Description                      |
| ------ | -------------------------- | ------- | -------------------------------- |
| `GET`  | `/v1/business/settlements` | API Key | List all settlements (paginated) |

***

## GET `/v1/business/settlements`

Returns a paginated, date-filtered list of all fiat and crypto settlements for the authenticated business and environment.

### Query Parameters

| Parameter | Type     | Required | Description                                                              |
| --------- | -------- | -------- | ------------------------------------------------------------------------ |
| `type`    | `string` | No       | Filter by settlement type — `FIAT` or `CRYPTO`. Returns both if omitted. |
| `from`    | `string` | No       | Start of date range (ISO 8601). e.g. `2026-01-01T00:00:00.000Z`          |
| `to`      | `string` | No       | End of date range (ISO 8601). e.g. `2026-01-31T23:59:59.999Z`            |
| `page`    | `number` | No       | Page number. Defaults to `1`.                                            |
| `limit`   | `number` | No       | Results per page. Defaults to `10`, max `100`.                           |

### Request

```http
GET /v1/business/settlements?type=FIAT&from=2026-01-01T00:00:00.000Z&to=2026-01-31T23:59:59.999Z&page=1&limit=20
Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

### Response

```json
{
  "success": true,
  "message": "Settlements retrieved successfully",
  "data": {
    "records": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "reference": "settlement-ref-001",
        "type": "FIAT",
        "status": "SUCCESS",
        "amount": 50000,
        "settledAmount": 49500,
        "fee": 500,
        "currency": "NGN",
        "chain": null,
        "withdrawalTxHash": null,
        "environment": "LIVE",
        "paymentMethod": {
          "type": "FIAT",
          "payoutMethod": "BANK_TRANSFER",
          "accountNumber": "0123456789",
          "accountName": "Acme Store Ltd",
          "bankName": "GTBank"
        },
        "createdAt": "2026-01-15T10:00:00.000Z",
        "updatedAt": "2026-01-15T10:05:00.000Z"
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "reference": "settlement-ref-002",
        "type": "CRYPTO",
        "status": "SUCCESS",
        "amount": 25.0,
        "settledAmount": 24.5,
        "fee": 0.5,
        "currency": "USDT",
        "chain": "BSC_MAINNET",
        "withdrawalTxHash": "0xabc123def456...",
        "environment": "LIVE",
        "paymentMethod": {
          "type": "CRYPTO",
          "payoutMethod": "CRYPTO_PAYMENT",
          "address": "0x5020D82d223ffC7Ae770af32eD91d7Af9Fd1adEd",
          "network": "BSC_MAINNET"
        },
        "createdAt": "2026-01-14T08:30:00.000Z",
        "updatedAt": "2026-01-14T08:35:00.000Z"
      }
    ],
    "count": 38
  }
}
```

### Response Fields

| Field                        | Type     | Description                                                                            |
| ---------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `records`                    | `array`  | Array of settlement records sorted by most recent first                                |
| `count`                      | `number` | Total number of records matching the query (across all pages)                          |
| `records[].id`               | `string` | Settlement UUID                                                                        |
| `records[].reference`        | `string` | Settlement reference                                                                   |
| `records[].type`             | `string` | `FIAT` or `CRYPTO`                                                                     |
| `records[].status`           | `string` | Settlement status. See [status values](#settlement-status-values)                      |
| `records[].amount`           | `number` | Original settlement amount before fees                                                 |
| `records[].settledAmount`    | `number` | Amount actually settled after fees, or `null` if not yet settled                       |
| `records[].fee`              | `number` | Fee deducted from the settlement amount                                                |
| `records[].currency`         | `string` | Fiat currency (e.g. `NGN`) for FIAT settlements, crypto token (e.g. `USDT`) for CRYPTO |
| `records[].chain`            | `string` | Blockchain network for CRYPTO settlements (e.g. `BSC_MAINNET`), `null` for FIAT        |
| `records[].withdrawalTxHash` | `string` | On-chain transaction hash for CRYPTO settlements, `null` for FIAT or if pending        |
| `records[].environment`      | `string` | `LIVE` or `TEST`                                                                       |
| `records[].paymentMethod`    | `object` | Destination account or wallet used for this settlement                                 |
| `records[].createdAt`        | `string` | ISO 8601 timestamp when the settlement was initiated                                   |
| `records[].updatedAt`        | `string` | ISO 8601 timestamp of the last status update                                           |

### Payment Method Fields

**FIAT settlement:**

| Field                         | Type     | Description                     |
| ----------------------------- | -------- | ------------------------------- |
| `paymentMethod.type`          | `string` | `"FIAT"`                        |
| `paymentMethod.payoutMethod`  | `string` | e.g. `BANK_TRANSFER`            |
| `paymentMethod.accountNumber` | `string` | Destination bank account number |
| `paymentMethod.accountName`   | `string` | Account holder name             |
| `paymentMethod.bankName`      | `string` | Name of the destination bank    |

**CRYPTO settlement:**

| Field                        | Type     | Description                             |
| ---------------------------- | -------- | --------------------------------------- |
| `paymentMethod.type`         | `string` | `"CRYPTO"`                              |
| `paymentMethod.payoutMethod` | `string` | e.g. `CRYPTO_PAYMENT`                   |
| `paymentMethod.address`      | `string` | Destination wallet address              |
| `paymentMethod.network`      | `string` | Blockchain network (e.g. `BSC_MAINNET`) |

***

## Settlement Status Values

| Status       | Description                               |
| ------------ | ----------------------------------------- |
| `PENDING`    | Settlement initiated, awaiting processing |
| `PROCESSING` | Settlement is being processed             |
| `SUCCESS`    | Settlement completed and funds dispatched |
| `FAILED`     | Settlement failed                         |

***

## Error Responses

| Status | Message        | Cause                      |
| ------ | -------------- | -------------------------- |
| `401`  | `Unauthorized` | Missing or invalid API key |

***

## Code Examples

### Node.js

```javascript
const axios = require('axios');

const { data } = await axios.get(
  'https://api.ivorypay.io/api/v1/business/settlements',
  {
    params: {
      from: '2026-01-01T00:00:00.000Z',
      to: '2026-01-31T23:59:59.999Z',
      page: 1,
      limit: 20,
    },
    headers: { Authorization: process.env.IVORYPAY_SECRET_KEY },
  },
);

const { records, count } = data.data;
console.log(`Showing ${records.length} of ${count} settlements`);

records.forEach((s) => {
  if (s.type === 'FIAT') {
    console.log(`FIAT — ${s.amount} ${s.currency} → ${s.paymentMethod?.bankName} ${s.paymentMethod?.accountNumber} [${s.status}]`);
  } else {
    console.log(`CRYPTO — ${s.amount} ${s.currency} → ${s.paymentMethod?.address} [${s.status}]`);
  }
});
```

### cURL

```bash
curl "https://api.ivorypay.io/api/v1/business/settlements?from=2026-01-01T00:00:00.000Z&to=2026-01-31T23:59:59.999Z&page=1&limit=20" \
  -H "Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
```

***

## Notes

* Results are scoped to the authenticated business and environment — use your **live key** for live settlements and your **test key** for test data.
* `count` reflects the **total** matching records, not just the current page.
* Both FIAT and CRYPTO settlements appear in the same list, ordered by `createdAt` descending.
* `settledAmount` may differ from `amount` due to the processing fee (`fee`).