Skip to main content

​
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