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.

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");

from modempay import ModemPay

modem_pay = ModemPay(api_key="sk_test_...")

response = modem_pay.transfers.initiate(
    params={
        "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="Idempotency-Key"
)

use ModemPay\ModemPay;

$modemPay = new ModemPay('sk_test_...');

$transfer = $modemPay->transfers()->initiate([
    'amount' => 100,
    'currency' => 'GMD',
    'account_number' => '7834567',
    'network' => 'afrimoney',
    'beneficiary_name' => 'John Doe',
    'narration' => 'Vendor payment for April supplies',
    'metadata' => [
      'vendor_id' => 'vendor_001',
      'invoice_id' => 'inv_204',
    ],
], 'Idempotency-Key');

curl -X POST https://api.modempay.com/v1/transfers \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: Idempotency-Key" \
  -d '{
    "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"
    }
  }'

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.

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

transfer = modem_pay.transfers.retrieve("45eb796c...")
print(transfer["status"]); # e.g., 'completed'

$transfer = $modemPay->transfers()->retrieve("45eb796c...");
echo $transfer->status; # e.g., 'completed'

curl -X GET https://api.modempay.com/v1/transfers/45eb796c... \
  -H "Authorization: Bearer sk_test_..."

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.

Start Here

Collections

DeFi

Payouts

Drop-ins

Core API Resources

Split Payments

Terminals

Supported Networks

Required Fields

Initiate Payout

Payout Response

Retrieve a Payout

Fraud Monitoring & Security

​Supported Networks

​Required Fields

​Initiate Payout

​Payout Response

​Retrieve a Payout

​Fraud Monitoring & Security

Supported Networks

Required Fields

Initiate Payout

Payout Response

Retrieve a Payout

Fraud Monitoring & Security