Mobile Money Payouts

Mobile money is one of the most popular and accessible methods of transferring funds in The Gambia and across West Africa. Modem Pay supports seamless transfers to major mobile money providers.

Supported Networks

Here are the currently supported mobile money networks on Modem Pay:

Network	Key (network)	Notes
Africell	afrimoney	Instant transfers supported
Wave	wave	Instant transfers supported

You must specify the correct network value in your transfer request.

Required Fields

For mobile money transfers, you must provide the following in your request:

Field	Required	Description
amount	✅	Amount to send
currency	✅	Currency code (e.g., GMD)
network	✅	One of: afrimoney, wave
account_number	✅	Recipient’s mobile wallet number
beneficiary_name	✅	Name of the wallet holder
narration	⛔	Optional transfer note
metadata	⛔	Optional structured data (JSON)

Initiate Payout

When initiating a transfer, you must provide an Idempotency-Key in the request header. This ensures that if the same request is sent multiple times (for example, due to network issues), only one transfer will be processed. The Idempotency-Key should be a unique value (such as a UUID) for each transfer request.

nodejs

import ModemPay from "modem-pay";

const modemPay = new ModemPay("sk_test_...");

const response = await modemPay.transfers.initiate({
  amount: 100,
  currency: "GMD",
  network: "afrimoney",
  account_number: "7834567",
  beneficiary_name: "John Doe",
  narration: "Vendor payment for April supplies",
  metadata: {
    vendor_id: "vendor_001",
    invoice_id: "inv_204"
  }
}, "Idempotency-Key");

Payout Response

json

{
  "id": "45eb796c-e66a-442f-bba2-d282053f8883",
  "events": {},
  "business_id": "120c298f-b736-49c1-8220-8a8c84a5d8f3",
  "account_id": "199bf17b-0b5a-45c0-a5b0-1d29f5f173c9",
  "amount": 100,
  "currency": "GMD",
  "type": "mobile-money",
  "balance_before": 995,
  "balance_after": 894,
  "transfer_reference": "5Np7iVHrN",
  "test_mode": true,
  "status": "completed",
  "account_name": "John Doe",
  "network": "afrimoney",
  "mobile_number": "7834567",
  "account_number": "7834567",
  "note": "Vendor payment for April supplies",
  "fee": 1,
  "metadata": {
    "vendor_id": "vendor_001",
    "invoice_id": "inv_204"
  },
  "updatedAt": "2025-05-05T21:12:52.839Z",
  "createdAt": "2025-05-05T21:12:52.839Z",
  "merchant_id": null,
  "recipient_business_id": null,
  "bank": null,
  "amount_received": null,
  "otp": null
}

Retrieve a Payout

You can fetch the details of a specific transfer using its unique id.

nodejs

const transfer = await modemPay.transfers.retrieve("45eb796c...");
console.log(transfer.status); // e.g., 'completed'

This returns the full transfer object with all metadata, status, and transaction history.

Fraud Monitoring & Security

Modem Pay automatically monitors all payout transfers for suspicious or anomalous activity. If a transfer triggers our fraud detection systems, it is immediately flagged for review. When this happens:

• You will receive an email notification alerting you to the flagged transfer.
• A transfer.flagged webhook event will be sent to your configured webhook endpoint.

Important: No further transfers can be made to the affected account number until you review and resolve the flagged issue. This helps protect your business and recipients from potential fraud or misuse. Always investigate flagged transfers promptly to restore normal payout operations.