Skip to main content

​
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.

​
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.
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.

​
Related Docs

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.