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

# Fund Wallet

> Fund a wallet using supported payment methods

This endpoint is used to fund a wallet using supported payment methods.

***

## 🇳🇬 NGN Wallet Funding (Bank Transfer)

For NGN (Nigerian Naira) wallets, users do **NOT** need to call this endpoint to fund their wallet.

Instead, users should:

1. Call `/wallet/balance` to retrieve their wallet details.
2. Locate the `bankDetails` object for the `NGN` wallet.
3. Transfer funds directly to the provided bank account using their banking app.

The `bankDetails` object includes:

| Field           | Description                        |
| --------------- | ---------------------------------- |
| `accountName`   | Name on the bank account           |
| `accountNumber` | Bank account number to transfer to |
| `bankName`      | Name of the receiving bank         |

Once the transfer is completed, the wallet will be credited automatically. Applicable fees may apply.

<warning>
  Do **not** call this endpoint for NGN wallet funding.
</warning>

***

## 📱 Mobile Money Wallet Funding (GHS)

For wallets funded via `MOBILE_MONEY` (e.g. `GHS`), this endpoint must be called. The user provides their mobile money details and an authorization request will be initiated, after which the user will be prompted to authorize the transaction.

### Fetch Supported Providers

Call the utility endpoint below to fetch supported mobile money providers for the selected country and currency. Use the provider `code` as the `network` value.

```text theme={null}
GET /transaction/{method}/providers?currency={currency}&iso2={iso2}
```

**Example:**

```text theme={null}
GET /transaction/MOBILE_MONEY/providers?currency=GHS&iso2=GH
```

### Required Fields

| Field           | Type     | Description                                 |
| --------------- | -------- | ------------------------------------------- |
| `amount`        | `number` | Amount to fund                              |
| `currency`      | `string` | e.g. `GHS`                                  |
| `iso2`          | `string` | Country code, e.g. `GH`                     |
| `paymentMethod` | `string` | Must be `MOBILE_MONEY`                      |
| `phoneNumber`   | `string` | Mobile money phone number                   |
| `network`       | `string` | Provider code fetched from utility endpoint |

**Sample GHS `MOBILE_MONEY` Payload:**

```json theme={null}
{
  "amount": 100,
  "currency": "GHS",
  "iso2": "GH",
  "paymentMethod": "MOBILE_MONEY",
  "phoneNumber": "+233244607135",
  "network": "MTN"
}
```

***

## 🌍 Mobile Money Wallet Funding (XOF & XAF)

For XOF and XAF wallets, funding is done via `MOBILE_MONEY` and requires selecting a supported country and provider.

### Supported Countries

| Currency | Countries                                                             |
| -------- | --------------------------------------------------------------------- |
| `XOF`    | Benin (`BJ`), Ivory Coast (`CI`), Burkina Faso (`BF`), Senegal (`SN`) |
| `XAF`    | Cameroon (`CM`)                                                       |

### Step 1: Select Country

The user selects the country they want to fund from. This determines the `iso2` value.

### Step 2: Fetch Mobile Money Providers

Call the utility endpoint to fetch supported mobile money providers for the selected country and currency.

```text theme={null}
GET /transaction/{method}/providers?currency={currency}&iso2={iso2}
```

**Example:**

```text theme={null}
GET /transaction/MOBILE_MONEY/providers?currency=XOF&iso2=BJ
```

**Sample Response:**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "network": "MTN",
      "code": "MTN_MOMO_BEN",
      "name": "MTN",
      "logo": "https://monirate-product-design.s3.eu-west-2.amazonaws.com/momo/mtn.png",
      "hasGateway": true
    },
    {
      "network": "MOOV",
      "code": "MOOV",
      "name": "MOOV",
      "logo": "https://monirate-product-design.s3.eu-west-2.amazonaws.com/momo/moov.jpeg",
      "hasGateway": false
    }
  ],
  "message": "Banks fetched successfully"
}
```

<info>
  Use the provider `code` (e.g. `MTN_MOMO_BEN`) as the `network` value when funding the wallet.
</info>

### Step 3: Initiate XOF / XAF Wallet Funding

Call this endpoint with the selected provider details.

**Sample XOF `MOBILE_MONEY` Payload:**

```json theme={null}
{
  "amount": 100,
  "currency": "XOF",
  "iso2": "BJ",
  "paymentMethod": "MOBILE_MONEY",
  "phoneNumber": "+22990123456",
  "network": "MTN_MOMO_BEN"
}
```

***

## Notes

<info>
  * This endpoint should only be used for funding methods that require payment initiation.
  * For `NGN`, always fund wallets via direct bank transfer using `/wallet/balance`.
  * Always fetch mobile money providers using `/transaction/{method}/providers` before funding `XOF` or `XAF` wallets.
  * Unsupported currencies, countries (`iso2`), or providers will result in validation errors.
  * For mobile money payments, the user will receive a prompt on their phone to enter their mobile money PIN to authorize the transaction.
</info>