🇷🇼 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

MOBILE_MONEY

Use MOBILE_MONEY for instant disbursements to Rwandan mobile money subscribers (such as MTN MoMo).

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"
    }
}'

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

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

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.	✅ 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 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

To retrieve the list of supported mobileProvider codes for different countries and networks, query the Get Mobile Networks 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:

copy

{
  "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.

Webhook Updates: You can listen for real-time status transitions using webhooks (payout.pending, payout.completed, and payout.failed). See the Payout Webhooks Guide 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 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.

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.

Overview

Wallets

Quotes

Payouts

Virtual Accounts

Ramp

Transactions

Webhooks

Endpoint

Supported Payment Channels

Request Details

Headers

Sample Requests

Request Body Breakdown

Success Response (200 OK)

Response Body Breakdown

Payout Transaction States

Error Handling

Best Practices

​Endpoint

​Supported Payment Channels

​Request Details

​Headers

​Sample Requests

​Request Body Breakdown

​Success Response (200 OK)

​Response Body Breakdown

​Payout Transaction States

​Error Handling

​Best Practices

Endpoint

Supported Payment Channels

Request Details

Headers

Sample Requests

Request Body Breakdown

Success Response (200 OK)

Response Body Breakdown

Payout Transaction States

Error Handling

Best Practices