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

# Disbursement Example Payloads

> Copy-ready payload examples for recipient validation, disbursement requests, and disbursement verification.

# 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`

```json theme={null}
{
  "provider": "mtn-momo-ivory-coast",
  "currency": "XOF",
  "country": "CI",
  "account": {
    "phoneNumber": "225XXXXXXXXXX"
  }
}
```

Sample response:

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

```bash theme={null}
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:

```json theme={null}
{
  "statusCode": 200,
  "data": {
    "banks": [
      {
        "bankName": "Access Bank",
        "bankCode": "044"
      }
    ]
  }
}
```

Use the selected `bankCode` when validating the recipient.

Endpoint: `POST /billing/v1/transfer-recipients/validate`

```json theme={null}
{
  "provider": "bank-transfer-nigeria",
  "currency": "NGN",
  "country": "NG",
  "account": {
    "accountNumber": "0123456789",
    "bankCode": "044"
  }
}
```

Sample response:

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

```json theme={null}
{
  "provider": "bank-transfer-angola",
  "currency": "AOA",
  "country": "AO",
  "account": {
    "accountName": "John Doe",
    "accountNumber": "0123456789"
  }
}
```

Sample response:

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

```json theme={null}
{
  "transferRecipientId": "675a4528d14b406a3d31e4a8",
  "amount": 3000,
  "reference": "disbursement-1001",
  "narration": "Vendor disbursement",
  "pin": "1111",
  "webhookURL": "https://yourdomain.com/webhook",
}
```

Sample response:

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

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

<AccordionGroup>
  <Accordion title="Amount format" icon="hashtag" defaultOpen>
    Send integer minor-unit values only. Decimals are not supported.
  </Accordion>

  <Accordion title="Unique reference" icon="fingerprint">
    Use a unique disbursement reference to avoid duplicate transaction errors.
  </Accordion>

  <Accordion title="Recipient validation first" icon="user">
    Always validate recipient before requesting disbursement.
  </Accordion>

  <Accordion title="Authorization mode alignment" icon="key">
    Ensure request matches your configured authorization mode (PIN or Authorization URL).
  </Accordion>
</AccordionGroup>

## Related Docs

<CardGroup cols={3}>
  <Card title="Disbursements Overview" icon="money-bill-transfer" href="/en/guides/disbursements/overview">
    Full disbursement flow walkthrough.
  </Card>

  <Card title="Authorization Mode" icon="key" href="/en/guides/disbursements/authorization-mode">
    Configure and secure disbursement authorization.
  </Card>

  <Card title="Disbursement Webhooks" icon="bell" href="/en/guides/disbursements/webhook">
    Process status callbacks safely.
  </Card>
</CardGroup>