Skip to main content
Manage batch payouts programmatically.

​
Endpoints

MethodEndpointDescription
GET/disbursementsList disbursements
GET/disbursements/:idGet disbursement
GET/disbursements/:id/itemsGet disbursement items
GET/disbursements/:id/validation-summaryGet validation summary
POST/disbursements/:id/submitSubmit for approval

​
List Disbursements

GET /mfi/disbursements

​
Query Parameters

ParameterTypeDescription
pagenumberPage number (default: 1)
limitnumberItems per page (default: 20, max: 100)
statusstringFilter by status
searchstringSearch by name or description

​
Response

{
  "data": [
    {
      "id": "dsb_xxxxxxxx",
      "name": "January Payroll",
      "description": "Monthly payroll disbursement",
      "assetCode": "HTG",
      "assetIssuer": "GHTG...ISSUER",
      "status": "pending_submit",
      "createdAt": "2026-01-25T10:00:00Z",
      "currentUpload": {
        "id": "upl_xxxxxxxx",
        "totalRows": 50,
        "totalAmount": "250000.00",
        "fileName": "payroll.csv",
        "uploadedAt": "2026-01-25T10:05:00Z"
      },
      "actions": {
        "canSubmit": true,
        "canApprove": false,
        "canReject": false,
        "canCancel": true,
        "canRetry": false
      }
    }
  ],
  "pagination": {
    "total": 10,
    "page": 1,
    "limit": 20,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}

​
Get Disbursement

GET /mfi/disbursements/:id

​
Response

Same format as list item, plus additional details: 
{
  "id": "dsb_xxxxxxxx",
  "name": "January Payroll",
  "description": "Monthly payroll disbursement",
  "assetCode": "HTG",
  "assetIssuer": "GHTG...ISSUER",
  "status": "pending_submit",
  "creatorId": "usr_xxxxxxxx",
  "createdAt": "2026-01-25T10:00:00Z",
  "updatedAt": "2026-01-25T10:05:00Z",
  "currentUpload": {
    "id": "upl_xxxxxxxx",
    "totalRows": 50,
    "totalAmount": "250000.00",
    "fileName": "payroll.csv",
    "uploadedAt": "2026-01-25T10:05:00Z"
  },
  "actions": {
    "canSubmit": true,
    "canApprove": false,
    "canReject": false,
    "canCancel": true,
    "canRetry": false
  }
}

​
Get Disbursement Items

GET /mfi/disbursements/:id/items

​
Query Parameters

ParameterTypeDescription
statusstringFilter: pending, processing, valid, invalid

​
Response

{
  "data": [
    {
      "id": "itm_xxxxxxxx",
      "rowNumber": 1,
      "bousolUid": "EMP001",
      "recipientName": "Jean Pierre",
      "amount": "5000.00",
      "status": "valid",
      "validationError": null,
      "walletAddress": "GABC...XYZ",
      "payoutRoute": "payment",
      "updatedAt": "2026-01-25T10:05:00Z"
    },
    {
      "id": "itm_xxxxxxxx",
      "rowNumber": 2,
      "bousolUid": "EMP002",
      "recipientName": "",
      "amount": "4500.00",
      "status": "invalid",
      "validationError": "Client not found",
      "walletAddress": null,
      "payoutRoute": null,
      "updatedAt": "2026-01-25T10:05:00Z"
    }
  ],
  "total": 50,
  "assetCode": "HTG"
}

​
Item Status

StatusDescription
pendingNot yet validated
processingValidation in progress
validReady for payment
invalidValidation error

​
Get Validation Summary

GET /mfi/disbursements/:id/validation-summary

​
Response

{
  "disbursementId": "dsb_xxxxxxxx",
  "status": "pending_submit",
  "totalRows": 50,
  "validRows": 48,
  "invalidRows": 2,
  "directPayments": {
    "count": 48,
    "amount": 245000.00
  },
  "claimableBalances": {
    "count": 0,
    "amount": 0
  },
  "totalAmount": 245000.00
}

​
Submit for Approval

POST /mfi/disbursements/:id/submit
Submits the disbursement for approval. Only allowed when status is pending_submit.

​
Response

{
  "success": true,
  "message": "Disbursement submitted for approval",
  "status": "pending_approval"
}

​
Disbursement Status

StatusDescription
createdCSV uploaded, waiting for processing
processingCSV being parsed and wallets validated
pending_submitProcessing complete, ready for submission
pending_approvalSubmitted, awaiting approval
executingApproved, payments being sent
completedAll payments sent
failedProcessing or execution failed
rejectedApproval rejected

​
Status Flow

created → processing → pending_submit → pending_approval → executing → completed
              ↓                               ↓                ↓
           failed                          rejected         failed

​
Errors

StatusCodeDescription
400invalid_statusCannot perform action in current status
400no_uploadNo CSV uploaded
404not_foundDisbursement not found

​
Webhooks

Subscribe to disbursement events:
  • disbursement.created
  • disbursement.submitted
  • disbursement.approved
  • disbursement.rejected
  • disbursement.completed
  • disbursement.failed
See Webhooks for setup instructions.