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

Use the matching account object for the provider channel you are validating.

​
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"
  }
}

​
Bank Transfer

Fetch the bank list before validating a bank transfer recipient so you can send a valid bankCode. Endpoint: GET /billing/v1/transfer-recipients/{provider}/properties 
curl --location 'https://sandbox-api.payfonte.com/billing/v1/transfer-recipients/bank-transfer-nigeria/properties' \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>'
Sample response: 
{
  "statusCode": 200,
  "data": {
    "banks": [
      {
        "bankName": "Access Bank",
        "bankCode": "044"
      }
    ]
  }
}
Use the selected bankCode when validating the recipient. Endpoint: POST /billing/v1/transfer-recipients/validate 
{
  "provider": "bank-transfer-nigeria",
  "currency": "NGN",
  "country": "NG",
  "account": {
    "accountNumber": "0123456789",
    "bankCode": "044"
  }
}
Sample response: 
{
  "statusCode": 200,
  "data": {
    "provider": "bank-transfer-nigeria",
    "providerLabel": "Bank Transfer",
    "source": "disbursement",
    "channel": "bank-transfer",
    "currency": "NGN",
    "country": "NG",
    "accountLabel": "Access Bank | AAA BBB XXX | 0123456789",
    "account": {
      "name": "AAA BBB XXX",
      "accountName": "AAA BBB XXX",
      "accountNumber": "0123456789",
      "bankCode": "044",
      "bankName": "Access Bank"
    },
    "status": "pending",
    "id": "6834655cdc1370231451f2a5"
  }
}

​
Bank Transfer (Angola)

Endpoint: POST /billing/v1/transfer-recipients/validate 
{
  "provider": "bank-transfer-angola",
  "currency": "AOA",
  "country": "AO",
  "account": {
    "accountName": "John Doe",
    "accountNumber": "0123456789"
  }
}
Sample response: 
{
  "statusCode": 200,
  "data": {
    "clientId": "6thbridge",
    "parentClientId": "payfusion",
    "ownerType": "client",
    "ownerId": "6thbridge",
    "provider": "bank-transfer-angola",
    "providerLabel": "Bank Transfer",
    "providerLogo": "https://app-tst.appypay.co.ao/images/payment-methods/ref.png",
    "source": "disbursement",
    "channel": "bank-transfer",
    "currency": "AOA",
    "country": "AO",
    "tags": [],
    "accountLabel": "Bank Transfer  | Miss Billie Friesen | 2215381176",
    "account": {
      "accountNumber": "2215381176",
      "accountName": "Miss Billie Friesen"
    },
    "status": "pending",
    "createdAt": "2026-04-20T12:40:56.084Z",
    "updatedAt": "2026-04-20T12:40:56.084Z",
    "id": "69e61ed8c5938efd8ef63e1b"
  }
}

​
2) Request Disbursement

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

​
3) 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.