Skip to main content
Use Payfonte disbursements to send Disbursements to validated recipients across supported providers and markets.

​
Flow Summary

1. Validate Recipient

Confirm recipient account details before Disbursement.

2. Request Disbursement

Initiate Disbursement with amount, recipient ID, and authorization mode.

3. Verify Final Status

Confirm outcome using verification endpoint and/or webhook.

​
Disbursement Flow Overview

​
Endpoints

MethodEndpointPurpose
GET/billing/v1/transfer-recipients/{provider}/propertiesFetch provider-specific properties (optional)
POST/billing/v1/transfer-recipients/validateValidate recipient details
POST/billing/v1/disbursementsRequest disbursement
GET/billing/v1/disbursements/verify/{reference}Verify disbursement status

​
Prerequisites

  • Valid client-id and client-secret
  • Sufficient Disbursement wallet balance
  • Disbursement authorization setup (pin or authorization URL flow)
  • Valid provider slug from Supported Providers

​
Step 1: Validate Transfer Recipient

​
1.1 Fetch provider properties (optional)

Some providers require extra details (for example bank list/network options) before validation. 
curl --location 'https://sandbox-api.payfonte.com/billing/v1/transfer-recipients/{provider}/properties' \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>'

​
1.2 Validate recipient

Bank transfer example: 
{
  "currency": "NGN",
  "country": "NG",
  "provider": "bank-transfer-nigeria",
  "account": {
    "accountNumber": "0123456789",
    "bankCode": "044"
  }
}
Mobile money example: 
{
  "currency": "XOF",
  "country": "CI",
  "provider": "wave-ivory-coast",
  "account": {
    "phoneNumber": "2250538102474"
  }
}
Sample response: 
{
  "data": {
    "id": "recipient-id",
    "currency": "NGN",
    "country": "NG",
    "provider": "bank-transfer-nigeria",
    "accountLabel": "Bank Transfer | Zenith Bank | Dummy User | 0123456789",
    "account": {
      "accountNumber": "0123456789",
      "bankCode": "044"
    }
  }
}
Save data.id as your transferRecipientId.

​
Step 2: Request Disbursement

curl --location 'https://sandbox-api.payfonte.com/billing/v1/disbursements' \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "transferRecipientId": "6659692f019f6a143f7f90db",
    "amount": 100000,
    "reference": "Disbursement-1001",
    "narration": "Vendor settlement",
    "pin": "1234",
    "webhookURL": "https://yourapp.com/webhooks/payfonte"
  }'
Sample response: 
{
  "data": {
    "reference": "Disbursement-1001",
    "amount": 100000,
    "amountPayable": 100000,
    "provider": "bank-transfer-nigeria",
    "currency": "NGN",
    "country": "NG",
    "status": "processing"
  }
}

​
Request fields

FieldTypeRequiredDescription
transferRecipientIdstringYesID from recipient validation step
amountintegerYesAmount in minor units (no decimals)
referencestringRecommendedUnique Disbursement reference
narrationstringNoDisbursement description
pinstringConditionalRequired when PIN authorization mode is enabled
webhookURLstringNoOverride webhook URL for this Disbursement

​
Status values

Disbursement status values from API responses:
  • processing
  • success
  • failed

​
Step 3: Verify Disbursement

curl --location 'https://sandbox-api.payfonte.com/billing/v1/disbursements/verify/Disbursement-1001' \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>'
Sample response: 
{
  "data": {
    "status": "success",
    "reference": "Disbursement-1001",
    "externalReference": "Disbursement-1001",
    "amount": 100000,
    "currency": "NGN"
  }
}

​
Amount Rule (Important)

Payfonte does not support decimal API amounts. Send integer minor-unit values only.
  • 1000.00 NGN -> 100000
  • 250.75 NGN -> 25075
See Amount Specification.

​
Best Practices

Always validate recipient first

Validation reduces failed Disbursements caused by invalid account details.
Reuse validated recipients to avoid repeated validation requests.
Unique references prevent duplicate Disbursement issues and simplify reconciliation.
Process webhook events and verify final status for critical business actions.
Keep disbursement PIN and authorization URLs strictly server-side.

Authorization Mode

Configure PIN or authorization URL mode.

Disbursement Examples

Request and response payload examples.

Disbursement Webhooks

Handle Disbursement status updates asynchronously.