JGME Pay
Disbursements

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

ModeHow it worksRecommended for
PIN AuthorizationYou send pin in each disbursement requestTeams with strict backend-controlled disbursement flows
Authorization URLJGME Pay 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

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

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

On this page