Skip to main content

​
Disbursement Example Payloads

This page provides practical payloads for each major disbursement step:
  1. Validate recipient
  2. Request disbursement
  3. Verify disbursement

​
1) Validate Recipient (Mobile Money)

Endpoint: POST /billing/v1/transfer-recipients/validate 
{
  "provider": "mtn-momo-ivory-coast",
  "currency": "XOF",
  "country": "CI",
  "account": {
    "phoneNumber": "225XXXXXXXXXX"
  }
}
Sample response: 
{
  "statusCode": 200,
  "data": {
    "provider": "mtn-momo-ivory-coast",
    "providerLabel": "MTN MoMo",
    "source": "disbursement",
    "channel": "mobile-money",
    "currency": "XOF",
    "country": "CI",
    "accountLabel": "MTN MoMo | 225XXXXXXXXXX",
    "account": {
      "network": "MTN",
      "phoneNumber": "225XXXXXXXXXX",
      "accountName": "John Doe"
    },
    "status": "active",
    "id": "675a4528d14b406a3d31e4a8"
  }
}

​
2) Validate Recipient (Bank Transfer)

Endpoint: POST /billing/v1/transfer-recipients/validate 
{
  "provider": "bank-transfer-nigeria",
  "currency": "NGN",
  "country": "NG",
  "account": {
    "accountNumber": "0123456789",
    "bankCode": "948"
  }
}
Sample response: 
{
  "statusCode": 200,
  "data": {
    "provider": "bank-transfer-nigeria",
    "providerLabel": "Bank Transfer",
    "source": "disbursement",
    "channel": "bank-transfer",
    "currency": "NGN",
    "country": "NG",
    "accountLabel": "Momo Payment Service Bank | AAA BBB XXX | 2215381176",
    "account": {
      "name": "AAA BBB XXX",
      "accountName": "AAA BBB XXX",
      "accountNumber": "2215381176",
      "bankCode": "948",
      "bankName": "Momo Payment Service Bank"
    },
    "status": "pending",
    "id": "6834655cdc1370231451f2a5"
  }
}

​
3) Request Disbursement

Endpoint: POST /billing/v1/disbursements 
{
  "transferRecipientId": "675a4528d14b406a3d31e4a8",
  "amount": 3000,
  "reference": "disbursement-1001",
  "narration": "Vendor disbursement",
  "pin": "1111"
}
Sample response: 
{
  "statusCode": 201,
  "data": {
    "reference": "D20241216141720XXXXX",
    "amount": 3000,
    "amountPayable": 3000,
    "charge": 15,
    "provider": "mtn-momo-ivory-coast",
    "currency": "XOF",
    "country": "CI",
    "status": "processing"
  }
}

​
4) Verify Disbursement

Endpoint: GET /billing/v1/disbursements/verify/{reference} Sample response: 
{
  "data": {
    "clientId": "payfusion",
    "status": "success",
    "statusDescription": "success",
    "reference": "D20241223060657MOHAA",
    "providersReference": "pt-D20241223060657MOHAA",
    "externalReference": "D20241223060657MOHAA",
    "currency": "XOF",
    "country": "CI",
    "transferRecipientId": "6768fdf84764676cde0b630e",
    "transferRecipientLabel": "Wave | +2257038102474",
    "charge": 0,
    "amount": 3000,
    "finalAmount": 3000,
    "provider": "wave-ivory-coast",
    "channel": "mobile-money",
    "integrationId": "6762bcccdd35fc1c7cae5bd6",
    "id": "6768fe014764676cde0b6313"
  },
  "statusCode": 200
}

​
Validation Checklist

Amount format

Send integer minor-unit values only. Decimals are not supported.
Use a unique disbursement reference to avoid duplicate transaction errors.
Always validate recipient before requesting disbursement.
Ensure request matches your configured authorization mode (PIN or Authorization URL).

Disbursements Overview

Full disbursement flow walkthrough.

Authorization Mode

Configure and secure disbursement authorization.

Disbursement Webhooks

Process status callbacks safely.