> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modempay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 |

<Note>
  You must specify the correct `network` value in your transfer request.
</Note>

### 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

<Note>
  When initiating a transfer, you must provide an <b>Idempotency-Key</b> 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 <b>Idempotency-Key</b> should be a unique value (such as a UUID) for each transfer request.
</Note>

<CodeGroup>
  ```typescript nodejs theme={null}
  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");
  ```

  ```python python theme={null}
  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"
  )
  ```

  ```php php theme={null}
  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');
  ```

  ```bash cURL theme={null}
  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"
      }
    }'

  ```
</CodeGroup>

### Payout Response

```typescript json theme={null}
{
  "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`.

<CodeGroup>
  ```typescript nodejs theme={null}
  const transfer = await modemPay.transfers.retrieve("45eb796c...");
  console.log(transfer.status); // e.g., 'completed'
  ```

  ```python python theme={null}
  transfer = modem_pay.transfers.retrieve("45eb796c...")
  print(transfer["status"]); # e.g., 'completed'
  ```

  ```php php theme={null}
  $transfer = $modemPay->transfers()->retrieve("45eb796c...");
  echo $transfer->status; # e.g., 'completed'
  ```

  ```bash cURL theme={null}
  curl -X GET https://api.modempay.com/v1/transfers/45eb796c... \
    -H "Authorization: Bearer sk_test_..."
  ```
</CodeGroup>

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.