Overview

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

Method	Endpoint	Purpose
`GET`	`/billing/v1/transfer-recipients/{provider}/properties`	Fetch provider-specific properties (optional)
`POST`	`/billing/v1/transfer-recipients/validate`	Validate recipient details
`POST`	`/billing/v1/disbursements`	Request 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

Field	Type	Required	Description
`transferRecipientId`	string	Yes	ID from recipient validation step
`amount`	integer	Yes	Amount in minor units (no decimals)
`reference`	string	Recommended	Unique Disbursement reference
`narration`	string	No	Disbursement description
`pin`	string	Conditional	Required when PIN authorization mode is enabled
`webhookURL`	string	No	Override 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.

Store recipient IDs for reuse

Reuse validated recipients to avoid repeated validation requests.

Use unique references

Unique references prevent duplicate Disbursement issues and simplify reconciliation.

Use webhook + verification

Process webhook events and verify final status for critical business actions.

Protect authorization controls

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.

Getting Started

Core Concepts

Providers & Coverage

Development

Collect Payment

Disbursements

Flow Summary

1. Validate Recipient

2. Request Disbursement

3. Verify Final Status

Disbursement Flow Overview

Endpoints

Prerequisites

Step 1: Validate Transfer Recipient

1.1 Fetch provider properties (optional)

1.2 Validate recipient

Step 2: Request Disbursement

Request fields

Status values

Step 3: Verify Disbursement

Amount Rule (Important)

Best Practices

Authorization Mode

Disbursement Examples

Disbursement Webhooks

​Flow Summary

1. Validate Recipient

2. Request Disbursement

3. Verify Final Status

​Disbursement Flow Overview

​Endpoints

​Prerequisites

​Step 1: Validate Transfer Recipient

​1.1 Fetch provider properties (optional)

​1.2 Validate recipient

​Step 2: Request Disbursement

​Request fields

​Status values

​Step 3: Verify Disbursement

​Amount Rule (Important)

​Best Practices

​Related Docs

Authorization Mode

Disbursement Examples

Disbursement Webhooks

Flow Summary

Disbursement Flow Overview

Endpoints

Prerequisites

Step 1: Validate Transfer Recipient

1.1 Fetch provider properties (optional)

1.2 Validate recipient

Step 2: Request Disbursement

Request fields

Status values

Step 3: Verify Disbursement

Amount Rule (Important)

Best Practices

Related Docs