> ## Documentation Index
> Fetch the complete documentation index at: https://dvaultdocs.dukka.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Disbursement API

> Manage fund disbursements and payouts

# 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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**

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}
```

**404 Not Found**

```json theme={null}
{
  "statusCode": 404,
  "message": "User not found",
  "data": null
}
```

**409 Conflict**

```json theme={null}
{
  "statusCode": 409,
  "message": "Disbursement already exists",
  "data": null
}
```

**403 Forbidden**

```json theme={null}
{
  "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