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

# 🇷🇼 RWF Payout

This endpoint allows you to process payouts in **Rwandan Franc (RWF)** to recipients in Rwanda using mobile money networks (e.g., MTN MoMo Rwanda, Airtel Money).

***

## Endpoint

| **Environment** | **Base URL** | **Method** |
| :- | :- | :- |
| **Production** | `https://api.me-cash.com/v2/payout` | `POST` |
| **Sandbox** | `https://sandboxapi.me-cash.com/v2/payout` | `POST` |

***

## Supported Payment Channels

RWF payouts support the following payment channel:

| **Channel** | **Description** | **Use Case** |
| :- | :- | :- |
| `MOBILE_MONEY` | Mobile Money transfers (e.g., MTN MoMo, Airtel Money) | Instant transfers directly to recipient mobile wallets |

***

## Request Details

### Headers

Include these headers in your request:

| **Header** | **Value** | **Required** |
| :- | :- | :- |
| `Content-Type` | `application/json` | ✅ Yes |
| `Accept` | `application/json` | ✅ Yes |
| `x-api-key` | `API_KEY_HERE` | ✅ Yes |

***

## Sample Requests

> [tab] MOBILE\_MONEY
>
> Use `MOBILE_MONEY` for instant disbursements to Rwandan mobile money subscribers (such as MTN MoMo).
>
> ```bash cURL theme={null}
> curl --location --request POST 'https://api.me-cash.com/v2/payout' \
> --header 'x-api-key: API_KEY_HERE' \
> --header 'Content-Type: application/json' \
> --header 'Accept: application/json' \
> --data '{
>     "remark": "Instant withdrawal",
>     "reason": "Other",
>     "quoteId": "c75ca56d-f5a7-48f0-85df-xxxxxxxxxxxx",
>     "recipient": {
>         "name": "Jean Paul Mugisha",
>         "account": {
>             "accountNumber": "+25079322XXXX",
>             "mobileProvider": "MTN_MOMO_RWA"
>         },
>         "paymentChannel": "MOBILE_MONEY",
>         "currency": "RWF",
>         "country": "RW"
>     }
> }'
> ```
>
> ```javascript JavaScript (Fetch) theme={null}
> const url = 'https://api.me-cash.com/v2/payout';
>
> const options = {
>   method: 'POST',
>   headers: {
>     'x-api-key': 'API_KEY_HERE',
>     'Content-Type': 'application/json',
>     'Accept': 'application/json'
>   },
>   body: JSON.stringify({
>     remark: "Instant withdrawal",
>     reason: "Other",
>     quoteId: "c75ca56d-f5a7-48f0-85df-xxxxxxxxxxxx",
>     recipient: {
>       name: "Jean Paul Mugisha",
>       account: {
>         accountNumber: "+25079322XXXX",
>         mobileProvider: "MTN_MOMO_RWA"
>       },
>       paymentChannel: "MOBILE_MONEY",
>       currency: "RWF",
>       country: "RW"
>     }
>   })
> };
>
> fetch(url, options)
>   .then(res => {
>     if (!res.ok) {
>       throw new Error(`HTTP error! status: ${res.status}`);
>     }
>     return res.json();
>   })
>   .then(data => console.log(data))
>   .catch(error => console.error('Error:', error));
> ```
>
> ```python Python (Requests) theme={null}
> import requests
> import json
>
> url = "https://api.me-cash.com/v2/payout"
>
> payload = {
>     "remark": "Instant withdrawal",
>     "reason": "Other",
>     "quoteId": "c75ca56d-f5a7-48f0-85df-xxxxxxxxxxxx",
>     "recipient": {
>         "name": "Jean Paul Mugisha",
>         "account": {
>             "accountNumber": "+25079322XXXX",
>             "mobileProvider": "MTN_MOMO_RWA"
>         },
>         "paymentChannel": "MOBILE_MONEY",
>         "currency": "RWF",
>         "country": "RW"
>     }
> }
>
> headers = {
>     "x-api-key": "API_KEY_HERE",
>     "Content-Type": "application/json",
>     "Accept": "application/json"
> }
>
> try:
>     response = requests.post(url, headers=headers, json=payload)
>     response.raise_for_status()
>     print(response.json())
> except requests.exceptions.HTTPError as err:
>     print(f"HTTP Error: {err}")
> ```
>
> ```javascript Node.js (Axios) theme={null}
> const axios = require('axios');
>
> const url = 'https://api.me-cash.com/v2/payout';
>
> const data = {
>   remark: 'Instant withdrawal',
>   reason: 'Other',
>   quoteId: 'c75ca56d-f5a7-48f0-85df-xxxxxxxxxxxx',
>   recipient: {
>     name: 'Jean Paul Mugisha',
>     account: {
>       accountNumber: '+25079322XXXX',
>       mobileProvider: 'MTN_MOMO_RWA'
>     },
>     paymentChannel: 'MOBILE_MONEY',
>     currency: 'RWF',
>     country: 'RW'
>   }
> };
>
> const config = {
>   headers: {
>     'x-api-key': 'API_KEY_HERE',
>     'Content-Type': 'application/json',
>     'Accept': 'application/json'
>   }
> };
>
> axios.post(url, data, config)
>   .then(response => {
>     console.log(response.data);
>   })
>   .catch(error => {
>     console.error('Error:', error.response ? error.response.data : error.message);
>   });
> ```

***

### Request Body Breakdown

| **Field** | **Type** | **Description** | **Required** |
| :- | :- | :- | :- |
| `quoteId` | String | The unique ID of the quote for this payout generated via the [Quote API](https://developer.me-cash.com/quote-docs/create-quote). | ✅ Yes |
| `reason` | String | The purpose of the transfer (e.g., `Other`, `Salary`, `Services`). | ✅ Yes |
| `remark` | String | An optional, additional note or description for the transaction. | ❔ No |
| `recipient` | Object | An object containing all details about the beneficiary. | ✅ Yes |
| `recipient.name` | String | The full name of the recipient registered on the mobile money line. | ✅ Yes |
| `recipient.account` | Object | An object containing the recipient's mobile money account details. | ✅ Yes |
| `recipient.account.accountNumber` | String | The recipient's mobile money phone number in international format (e.g., `+25079322XXXX`). | ✅ Yes |
| `recipient.account.mobileProvider` | String | The mobile money provider code (e.g., `MTN_MOMO_RWA`). See [Get Mobile Networks](https://developer.me-cash.com/collection/get-mobile-money-operators.md) for supported codes. | ✅ Yes |
| `recipient.paymentChannel` | String | The payment method. Must be `MOBILE_MONEY`. | ✅ Yes |
| `recipient.currency` | String | The destination ISO currency code. Must be `RWF`. | ✅ Yes |
| `recipient.country` | String | The recipient's two-letter ISO country code. Must be `RW`. | ✅ Yes |

> [!TIP]
>
> To retrieve the list of supported `mobileProvider` codes for different countries and networks, query the [Get Mobile Networks](https://developer.me-cash.com/collection/get-mobile-money-operators.md) endpoint.

***

## Success Response (200 OK)

When the payout request is successfully validated and queued, the API returns a `200 OK` response with a `payout.pending` event:

```json copy theme={null}
{
  "event": "payout.pending",
  "data": {
    "id": "96f5eabc-8ddb-462f-b7b7-xxxxxxxxxxxx",
    "reason": "Other",
    "remark": "Instant withdrawal",
    "referenceNumber": "QHVIJJXXXXXXX",
    "type": "SEND",
    "state": "PENDING",
    "quote": {
      "id": "1edb7bcb-fc04-490a-980b-xxxxxxxxxxxx",
      "paymentChannel": "MOBILE_MONEY",
      "source": {
        "currency": "RWF",
        "country": "RW",
        "amount": "5747.31"
      },
      "target": {
        "currency": "RWF",
        "country": "RW",
        "amount": "5747.31"
      },
      "rate": "1.000000000000",
      "fee": {
        "amount": "68.967720",
        "stampDuty": "0.00"
      },
      "summary": {
        "total": "5816.28"
      }
    },
    "recipient": {
      "name": "Jean Paul Mugisha",
      "account": {
        "accountNumber": "+25079322XXXX",
        "mobileProvider": "MTN_MOMO_RWA"
      },
      "paymentChannel": "MOBILE_MONEY",
      "currency": "RWF",
      "country": "RW"
    },
    "created": "2026-10-22T10:13:37.762Z",
    "processed": "2026-10-22T10:13:37.762Z"
  }
}
```

***

### Response Body Breakdown

| **Field** | **Type** | **Description** |
| :- | :- | :- |
| `event` | String | Event notification type (`payout.pending`). |
| `data.id` | String | Unique identifier for the created payout transaction. |
| `data.reason` | String | Purpose or category specified for the transfer. |
| `data.remark` | String | Additional note or remark submitted with the payout. |
| `data.referenceNumber` | String | Unique reference identifier generated for tracking and reconciliation. |
| `data.type` | String | Transaction type (`SEND`). |
| `data.state` | String | Current transaction state (`PENDING`, `COMPLETED`, `FAILED`, `REFUNDED`). |
| `data.quote` | Object | Complete breakdown of the applied quote. |
| `data.quote.id` | String | Unique identifier of the locked exchange quote. |
| `data.quote.paymentChannel` | String | Payment channel utilized (`MOBILE_MONEY`). |
| `data.quote.source` | Object | Source amount, currency (`RWF`), and origin country (`RW`). |
| `data.quote.target` | Object | Payout amount, currency (`RWF`), and destination country (`RW`). |
| `data.quote.rate` | String | Applied conversion exchange rate (`1.000000000000` for local corridor). |
| `data.quote.fee` | Object | Transaction processing fee and stamp duty. |
| `data.quote.summary.total` | String | Total cost deducted from your balance (principal + fees). |
| `data.recipient` | Object | Beneficiary account details and selected mobile provider. |
| `data.created` | String | ISO 8601 timestamp when the payout was initiated. |
| `data.processed` | String | ISO 8601 timestamp when processing commenced. |

***

## Payout Transaction States

A payout transaction progresses through the following lifecycles:

| **State** | **Description** |
| :- | :- |
| `PENDING` | Payout request has been initiated and is being processed by the mobile network operator. |
| `COMPLETED` | Funds have been successfully delivered to the recipient's mobile money wallet. |
| `FAILED` | Payout could not be fulfilled (e.g. invalid subscriber number, operator timeout, or wallet limits). |
| `REFUNDED` | The debited amount plus fees were returned to your account balance after a failure. |

> [!NOTE]
>
> **Webhook Updates:** You can listen for real-time status transitions using webhooks (`payout.pending`, `payout.completed`, and `payout.failed`). See the [Payout Webhooks Guide](https://developer.me-cash.com/webhook/payout-webhook.md) for payload examples and verification steps.

***

## Error Handling

Common HTTP response status codes returned by the API:

| **Status Code** | **Meaning** | **Description** |
| :- | :- | :- |
| `400 Bad Request` | Bad Request | Missing required parameters, invalid mobile provider code, or insufficient wallet balance. |
| `401 Unauthorized` | Unauthorized | Missing or invalid `x-api-key` header. |
| `403 Forbidden` | Forbidden | Request IP is not whitelisted. |
| `404 Not Found` | Not Found | Endpoint or specified resource does not exist. |
| `422 Unprocessable Entity` | Validation Error | The provided `quoteId` is invalid or expired. |
| `500 Internal Server Error` | Server Error | Internal processing error. Retry with an idempotent request. |

***

## Best Practices

✅ **Verify Phone Numbers:** Always ensure the recipient's mobile money number is active and formatted with the international calling code (e.g., `+250...`).\
✅ **Use Valid Quotes:** Retrieve a fresh quote via [`POST /v2/quote`](https://developer.me-cash.com/quote-docs/create-quote) before submitting the payout.\
✅ **Listen for Webhooks:** Mobile money network confirmations are asynchronous. Rely on webhook notifications rather than polling to determine final payout delivery.\
✅ **Idempotency & Reconciliations:** Store and index the returned `data.referenceNumber` and `data.id` for accounting and customer support reconciliation.

> [!TIP]
>
> **Sandbox Testing:** In the sandbox environment, you can test failure flows and webhook handling by passing `"remark": "fail"` in your request payload. This will trigger a `payout.failed` webhook event.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.