Overview
End-to-end Disbursement flow for validating recipients, requesting disbursements, and verifying final transaction status.
Use JGME Pay disbursements to send Disbursements to validated recipients across supported providers and markets.
Flow Summary
1. Validate Recipient
Confirm recipient account details before Disbursement.
2. Request Disbursement
Initiate Disbursement with amount, recipient ID, and authorization mode.
3. Verify Final Status
Confirm outcome using verification endpoint and/or webhook.
Disbursement Flow Overview
sequenceDiagram
participant Merchant as Merchant Backend
participant JGME Pay
participant Provider as MNO/Bank Provider
participant Recipient
Merchant->>JGME Pay: Validate recipient details
JGME Pay->>Provider: Validate account/wallet
Provider-->>JGME Pay: Validation result
JGME Pay-->>Merchant: transferRecipientId
Merchant->>JGME Pay: Request disbursement
JGME Pay->>Provider: Initiate Disbursement
Provider-->>Recipient: Credit recipient account/wallet
Provider-->>JGME Pay: Status update
JGME Pay-->>Merchant: Webhook notification
Merchant->>JGME Pay: Verify by reference
JGME Pay-->>Merchant: Final status (success/failed)Endpoints
| Method | Endpoint | Purpose |
|---|---|---|
GET | /billing/v1/transfer-recipients/{provider}/properties | Fetch provider-specific properties (optional) |
POST | /billing/v1/transfer-recipients/validate | Validate recipient details |
POST | /billing/v1/disbursements | Request disbursement |
GET | /billing/v1/disbursements/verify/{reference} | Verify disbursement status |
Prerequisites
- Valid
client-idandclient-secret - Sufficient Disbursement wallet balance
- Disbursement authorization setup (
pinor authorization URL flow) - Valid provider slug from Supported Providers
Step 1: Validate Transfer Recipient
1.1 Fetch provider properties (optional)
Some providers require extra details (for example bank list/network options) before validation.
curl --location 'https://api.jgmepay.com/billing/v1/transfer-recipients/{provider}/properties' \
--header 'client-id: <client-id>' \
--header 'client-secret: <client-secret>'1.2 Validate recipient
Bank transfer example:
{
"currency": "NGN",
"country": "NG",
"provider": "bank-transfer-nigeria",
"account": {
"accountNumber": "0123456789",
"bankCode": "044"
}
}Mobile money example:
{
"currency": "XOF",
"country": "CI",
"provider": "wave-ivory-coast",
"account": {
"phoneNumber": "2250538102474"
}
}Sample response:
{
"data": {
"id": "recipient-id",
"currency": "NGN",
"country": "NG",
"provider": "bank-transfer-nigeria",
"accountLabel": "Bank Transfer | Zenith Bank | Dummy User | 0123456789",
"account": {
"accountNumber": "0123456789",
"bankCode": "044"
}
}
}Save data.id as your transferRecipientId.
Step 2: Request Disbursement
curl --location 'https://api.jgmepay.com/billing/v1/disbursements' \
--header 'client-id: <client-id>' \
--header 'client-secret: <client-secret>' \
--header 'Content-Type: application/json' \
--data '{
"transferRecipientId": "6659692f019f6a143f7f90db",
"amount": 100000,
"reference": "Disbursement-1001",
"narration": "Vendor settlement",
"pin": "1234",
"webhookURL": "https://yourapp.com/webhooks/jgmepay"
}'Sample response:
{
"data": {
"reference": "Disbursement-1001",
"amount": 100000,
"amountPayable": 100000,
"provider": "bank-transfer-nigeria",
"currency": "NGN",
"country": "NG",
"status": "processing"
}
}Request fields
| Field | Type | Required | Description |
|---|---|---|---|
transferRecipientId | string | Yes | ID from recipient validation step |
amount | integer | Yes | Amount in minor units (no decimals) |
reference | string | Recommended | Unique Disbursement reference |
narration | string | No | Disbursement description |
pin | string | Conditional | Required when PIN authorization mode is enabled |
webhookURL | string | No | Override webhook URL for this Disbursement |
Status values
Disbursement status values from API responses:
processingsuccessfailed
Step 3: Verify Disbursement
curl --location 'https://api.jgmepay.com/billing/v1/disbursements/verify/Disbursement-1001' \
--header 'client-id: <client-id>' \
--header 'client-secret: <client-secret>'Sample response:
{
"data": {
"status": "success",
"reference": "Disbursement-1001",
"externalReference": "Disbursement-1001",
"amount": 100000,
"currency": "NGN"
}
}Amount Rule (Important)
JGME Pay does not support decimal API amounts. Send integer minor-unit values only.
1000.00 NGN->100000250.75 NGN->25075
See Amount Specification.
Best Practices
Validation reduces failed Disbursements caused by invalid account details.
Reuse validated recipients to avoid repeated validation requests.
Unique references prevent duplicate Disbursement issues and simplify reconciliation.
Process webhook events and verify final status for critical business actions.
Keep disbursement PIN and authorization URLs strictly server-side.