Disbursement Example Payloads

This page provides practical payloads for each major disbursement step:

Validate recipient
Request disbursement
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.

Unique reference

Use a unique disbursement reference to avoid duplicate transaction errors.

Recipient validation first

Always validate recipient before requesting disbursement.

Authorization mode alignment

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.

​Disbursement Example Payloads

​1) Validate Recipient

​Mobile Money

​Bank Transfer

​Bank Transfer (Angola)

​2) Request Disbursement

​3) Verify Disbursement

​Validation Checklist

​Related Docs

Disbursements Overview

Authorization Mode

Disbursement Webhooks

Disbursement Example Payloads

1) Validate Recipient

Mobile Money

Bank Transfer

Bank Transfer (Angola)

2) Request Disbursement

3) Verify Disbursement

Validation Checklist

Related Docs