Disbursement Authorization Mode

Payfonte supports two authorization modes for disbursement requests:

PIN Authorization
Authorization URL

Mode Comparison

Mode	How it works	Recommended for
PIN Authorization	You send `pin` in each disbursement request	Teams with strict backend-controlled disbursement flows
Authorization URL	Payfonte calls your approval endpoint per request; disbursement continues only on HTTP `200`	Platforms that require policy/risk checks before each disbursement

1) PIN Authorization

PIN mode requires a disbursement PIN on disbursement requests.

Setup

Set PIN in dashboard

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

Store PIN securely

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

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

Configure authorization URL

Set your endpoint under Disbursements -> Settings in dashboard.

Implement request validation

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

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"
}

Recommended Validation Checks (Authorization URL)

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.

Use HTTPS endpoints

Authorization URL must be publicly reachable over HTTPS.

Fail closed on verification errors

If signature/hash checks fail, reject the authorization request.

Audit every disbursement decision

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.

Getting Started

Core Concepts

Providers & Coverage

Development

Collect Payment

Disbursements

Disbursement Authorization Mode

Disbursement Authorization Mode

Mode Comparison

1) PIN Authorization

Setup

2) Authorization URL

Setup

Authorization Request Payload

Recommended Validation Checks (Authorization URL)

Security Checklist

Disbursements Overview

Disbursement Webhooks

Disbursement Examples

​Disbursement Authorization Mode

​Mode Comparison

​1) PIN Authorization

​Setup

​2) Authorization URL

​Setup

​Authorization Request Payload

​Recommended Validation Checks (Authorization URL)

​Security Checklist

​Related Docs

Disbursements Overview

Disbursement Webhooks

Disbursement Examples

Disbursement Authorization Mode

Mode Comparison

1) PIN Authorization

Setup

2) Authorization URL

Setup

Authorization Request Payload

Recommended Validation Checks (Authorization URL)

Security Checklist

Related Docs