Disbursement Authorization Mode
Configure secure authorization for disbursement requests using PIN mode or Authorization URL mode.
JGME Pay 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 | JGME Pay 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, JGME Pay 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 JGME Pay 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
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.