Skip to main content

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 Authorization Mode

Payfonte supports two authorization modes for disbursement requests:
  • PIN Authorization
  • Authorization URL

​
Mode Comparison

ModeHow it worksRecommended for
PIN AuthorizationYou send pin in each disbursement requestTeams with strict backend-controlled disbursement flows
Authorization URLPayfonte calls your approval endpoint per request; disbursement continues only on HTTP 200Platforms that require policy/risk checks before each disbursement

​
1) PIN Authorization

PIN mode requires a disbursement PIN on disbursement requests.

​
Setup

1

Set PIN in dashboard

Open any Disbursements page in dashboard and complete PIN setup when prompted.
2

Store PIN securely

Keep PIN in backend secret storage only. Never expose in frontend/mobile clients.
3

Send PIN per disbursement request

Include pin field in POST /billing/v1/disbursements.
PIN request example: 
{
  "transferRecipientId": "6659692f019f6a143f7f90db",
  "amount": 100000,
  "reference": "disbursement-1001",
  "narration": "Vendor settlement",
  "pin": "1234"
}

​
2) Authorization URL

Authorization URL mode lets your system approve or reject each disbursement attempt dynamically.

​
Setup

1

Configure authorization URL

Set your endpoint under Disbursements -> Settings in dashboard.
2

Implement request validation

Validate incoming request authenticity (hash/signature verification) before responding.
3

Return strict decision

Return HTTP 200 to approve; non-200 to block the disbursement.
Authorization URL mode is strict: if your endpoint is unavailable or returns non-200, the disbursement is not processed.

​
Authorization Request Payload

When Authorization URL mode is enabled, Payfonte sends a JSON payload like this to your configured authorization URL: 
{
  "clientId": "client_123456789",
  "type": "disbursement",
  "externalReference": "EXT-DISB-000001",
  "reference": "DISB-000001",
  "provider": "paystack",
  "channel": "bank-transfer",
  "finalAmount": 500000,
  "amount": 500000,
  "transferRecipientLabel": "Paystack | Zenith Bank | Ada Lovelace | 0123456789",
  "transferRecipient": {
    "accountNumber": "0123456789",
    "bankCode": "057",
    "bankName": "Zenith Bank",
    "accountName": "Ada Lovelace"
  },
  "recipient": {
    "accountNumber": "0123456789",
    "bankCode": "057",
    "bankName": "Zenith Bank",
    "accountName": "Ada Lovelace"
  },
  "transferRecipientId": "trf_recipient_123456789",
  "charge": 15000,
  "chargesApplied": [],
  "fees": {},
  "status": "queued",
  "country": "NG",
  "currency": "NGN",
  "narration": "Vendor payout for invoice INV-2026-0001",
  "webhookURL": "https://example.com/webhooks/disbursements"
}
When Payfonte calls your authorization URL, validate:
  • Request authenticity (signature/hash verification)
  • Amount and currency match expected business rules
  • Recipient is eligible for disbursement
  • Sender/account has enough balance (if you enforce internal wallet rules)
  • Daily limits, AML/risk policies, and velocity thresholds

​
Security Checklist

Keep secrets server-side

Never expose disbursement PIN or authorization secrets in browser/mobile code.
Authorization URL must be publicly reachable over HTTPS.
If signature/hash checks fail, reject the authorization request.
Log both approved and rejected decisions with reasons for compliance and troubleshooting.

Disbursements Overview

End-to-end disbursement flow and endpoint usage.

Disbursement Webhooks

Handle asynchronous disbursement status updates.

Disbursement Examples

Copy-ready request and response payloads.