JGME Pay
Disbursements

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

MethodEndpointPurpose
GET/billing/v1/transfer-recipients/{provider}/propertiesFetch provider-specific properties (optional)
POST/billing/v1/transfer-recipients/validateValidate recipient details
POST/billing/v1/disbursementsRequest disbursement
GET/billing/v1/disbursements/verify/{reference}Verify disbursement status

Prerequisites

  • Valid client-id and client-secret
  • Sufficient Disbursement wallet balance
  • Disbursement authorization setup (pin or 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

FieldTypeRequiredDescription
transferRecipientIdstringYesID from recipient validation step
amountintegerYesAmount in minor units (no decimals)
referencestringRecommendedUnique Disbursement reference
narrationstringNoDisbursement description
pinstringConditionalRequired when PIN authorization mode is enabled
webhookURLstringNoOverride webhook URL for this Disbursement

Status values

Disbursement status values from API responses:

  • processing
  • success
  • failed

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 -> 100000
  • 250.75 NGN -> 25075

See Amount Specification.

Best Practices

On this page