What to send
| Field | Required | What it is |
|---|---|---|
amount | Yes | How much to send, in GMD. At least 10. |
currency | Yes | GMD. |
network | Yes | wave or afrimoney. |
account_number | Yes | The wallet’s phone number, 7 or 9 digits. |
beneficiary_name | Yes | The wallet holder’s name, at least 3 characters. |
narration | No | A note for your records. |
metadata | No | Your own data, like an invoice ID. |
callback_url | No | An HTTPS URL to receive this payout’s result. |
Idempotency-Key header: a unique value, like a UUID, for each payout. If you send the same request again with the same key, for example after a timeout, we return the first payout instead of paying twice.
Not sure what it will cost? Check the fee first. The fee is taken from your balance on top of the amount.
Send a payout
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"
}
}'
What you get back
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
}
Look up a payout
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_..."
Fraud checks
Every payout goes through automatic fraud checks. If one looks unusual:- its status becomes
pending_review; - you get an email and a
transfer.flaggedwebhook; - no more payouts can go to that number until you review it in the dashboard.
Common errors
| Message | Fix |
|---|---|
Invalid transfer amount: … Must be at least 10. | Send 10 GMD or more. |
Invalid account number format. Must be 7 or 9 digits | Send only digits, no country code or spaces. |
Invalid network. Must be one of: afrimoney or wave | Check the network value. |
429 with a code such as RATE_LIMIT | Slow down and retry later. See Errors. |
