Disbursement API Documentation

Overview

The Disbursement API provides endpoints for managing bulk disbursements to multiple recipients, supporting both bank transfers and wallet-to-wallet transfers.

Base URL

/api/v1/disbursement

Authentication

All endpoints require authentication using an API key in the request headers:

X-API-KEY: Your API key

Endpoints

Create Disbursement

Creates a new disbursement to multiple recipients. Endpoint: POST /register Headers:

X-API-KEY (optional): API key for authentication

Request Body:

{
  "disbursementReference": "string",
  "accountId": "string",
  "tenantId": "string",
  "narration": "string",
  "currency": {
    "code": "string",
    "name": "string"
  },
  "channel": "BANK|WALLET",
  "disbursementRecipients": [
    {
      "recipientName": "string",
      "recipientAccountNumber": "string",
      "bankCode": "string",
      "amount": "number",
      "reason": "string"
    }
  ]
}

Response:

{
  "statusCode": 201,
  "message": "string",
  "data": {
    "id": "number",
    "disbursementReference": "string",
    "tenantId": "string",
    "accountId": "string",
    "currency": "string",
    "channel": "BANK|WALLET",
    "narration": "string",
    "disbursementRecipients": [
      {
        "id": "number",
        "recipientName": "string",
        "recipientAccountNumber": "string",
        "bankCode": "string",
        "amount": "number",
        "reason": "string",
        "narration": "string",
        "status": "PENDING|APPROVED|FAILED"
      }
    ],
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Get Disbursements

Retrieves a list of disbursements with optional filtering and pagination. Endpoint: GET / Headers:

X-API-KEY (optional): API key for authentication

Query Parameters:

tenantId: Tenant ID
disbursementReference: Disbursement reference
status: Transaction status (PENDING|APPROVED|FAILED)
accountId: Account ID
currency: Currency code
channel: Disbursement channel (BANK|WALLET)
recipientName: Recipient name
recipientAccountNumber: Recipient account number
page: Page number (default: 0)
size: Page size (default: 20)
sort: Sort field and direction (e.g., “createdAt,desc”)

Response:

{
  "statusCode": 200,
  "message": "string",
  "data": {
    "content": [
      {
        "id": "number",
        "disbursementReference": "string",
        "tenantId": "string",
        "accountId": "string",
        "currency": "string",
        "channel": "BANK|WALLET",
        "narration": "string",
        "disbursementRecipients": [
          {
            "id": "number",
            "recipientName": "string",
            "recipientAccountNumber": "string",
            "bankCode": "string",
            "amount": "number",
            "reason": "string",
            "narration": "string",
            "status": "PENDING|APPROVED|FAILED"
          }
        ],
        "createdAt": "string",
        "updatedAt": "string"
      }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 20,
      "sort": {
        "sorted": true,
        "unsorted": false,
        "empty": false
      },
      "offset": 0,
      "paged": true,
      "unpaged": false
    },
    "totalElements": 0,
    "totalPages": 0,
    "last": true,
    "size": 20,
    "number": 0,
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    },
    "numberOfElements": 0,
    "first": true,
    "empty": false
  }
}

Error Responses

All endpoints may return the following error responses: 401 Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}

404 Not Found

{
  "statusCode": 404,
  "message": "User not found",
  "data": null
}

409 Conflict

{
  "statusCode": 409,
  "message": "Disbursement already exists",
  "data": null
}

403 Forbidden

{
  "statusCode": 403,
  "message": "Insufficient funds for disbursement",
  "data": null
}

Notes

All timestamps are in ISO-8601 format
Disbursement channels can be either BANK or WALLET
For BANK channel, the recipient account number and bank code are required
For WALLET channel, the recipient account number should be a valid wallet account ID
The system will validate account balance before processing disbursements
Failed disbursements can be retried through a separate process
Only tenant admins and platform admins can view disbursements
Each disbursement must have a unique reference per tenant

Getting Started

Core Features

Additional Features

Disbursement API

Disbursement API Documentation

Overview

Base URL

Authentication

Endpoints

Create Disbursement

Get Disbursements

Error Responses

Notes

​Disbursement API Documentation

​Overview

​Base URL

​Authentication

​Endpoints

​Create Disbursement

​Get Disbursements

​Error Responses

​Notes

Disbursement API Documentation

Overview

Base URL

Authentication

Endpoints

Create Disbursement

Get Disbursements

Error Responses

Notes