API reference

Payouts

A payout sends money from your balance to a mobile money wallet or a bank account. The amount plus the fee is reserved when you create it, and returned if the payout fails.

POST/v1/payoutsCreate a payout GET/v1/payouts/{id}Retrieve a payout GET/v1/payoutsList payouts

The payout object

Attributes

idstring

Unique identifier (UUID).

livemodeboolean

true for live objects, false for test objects.

objectstring

Always payout.

statusstring

succeeded and failed are final. On failure, the amount and the fee return to your balance.

pendingprocessingsucceededfailed

amountinteger

Amount the recipient receives, in minor units.

currencystring

ISO 4217 currency code.

feeinteger

Monerail fee, debited from your balance on top of amount.

recipientobject

Who gets paid. Bank account numbers are masked.

Show child attributes

typestring

mobile_moneybank

namestring

Recipient name.

operatorstring

Mobile money only: operator code.

phonestring

Mobile money only: number, international format.

bank_codestring

Bank only: bank code from List banks.

accountstring

Bank only: masked account number.

countrystring

Country code.

descriptionstring | null

Your description.

client_referencestring | null

Your own reference, as sent at creation.

metadataobject

Key-value pairs you attached at creation.

failure_codestring | null

Why it failed, when status is failed or expired.

failure_messagestring | null

Detail from the payment partner, when available.

created_atstring

Creation time, ISO 8601 (UTC).

updated_atstring

Last change, ISO 8601 (UTC).

The payout object

{
  "id": "7b05e2b6-6638-4088-a984-7155dfd6a036",
  "object": "payout",
  "livemode": false,
  "status": "pending",
  "amount": 150000,
  "currency": "XAF",
  "fee": 2250,
  "recipient": {
    "type": "mobile_money",
    "name": "Kossi Mensah",
    "operator": "MTN",
    "phone": "237670000777",
    "country": "CM"
  },
  "description": "Invoice 2026-118",
  "client_reference": "inv_118",
  "metadata": {},
  "failure_code": null,
  "failure_message": null,
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:06.394Z"
}

Create a payout

POST/v1/payouts

Reserves amount + fee on your balance and sends the payout. Fails with 402 balance_insufficient if your balance does not cover both. Returns 201, or 202 with status: "processing" if the payment partner has not confirmed receipt yet: do not create the payout again, its outcome arrives by webhook.

Key roles: Owner, Finance or Approver

Body

amountintegerRequired

Amount in minor units of currency (whole francs for XAF, XOF and GNF; centimes for CDF, in multiples of 100). Integer only.

currencystringRequired

ISO 4217 code.

XAFXOFGNFCDFNGNKESGHSUGXTZSRWF

recipientobjectRequired

Who gets paid.

Show child attributes

typestringRequired

mobile_moneybank

namestringRequired

Recipient name, 2 to 80 characters.

phonestringOptional

Mobile money: recipient number.

operatorstringOptional

Mobile money: operator code.

bank_codestringOptional

Bank: a code from List banks, exactly as returned. Names and partial codes are refused with 400 bank_account_invalid.

accountstringOptional

Bank: account number.

countrystringOptional

ISO 3166-1 alpha-2. Defaults to the main country of the currency (CM for XAF, SN for XOF, GN for GNF, CD for CDF). Bank payouts are available in the countries listed with bank transfer in Coverage.

descriptionstringOptional

Up to 500 characters.

client_referencestringOptional

Your own reference, up to 64 characters: letters, digits and _ . : / -.

metadataobjectOptional

Up to 20 key-value pairs. Keys up to 40 characters (A-Z a-z 0-9 _ . -), values are stored as strings up to 500 characters.

Returns

Returns the new payout object with 201, or 202 when the outcome is not final yet.

Errors worth handling

HTTP	Code	Description
`402`	`balance_insufficient`	Your balance (or cards balance) does not cover the amount and the fee.
`400`	`bank_account_invalid`	`bank_code` does not exactly match a code from List banks, or the account number is too short.
`400`	`bank_transfer_unsupported`	Bank payouts are not available in this country: pay to a mobile money wallet.
`400`	`country_unsupported`	This country is not open for this currency. See Coverage.
`400`	`test_phone_required`	Test mode: use one of the test phone numbers of this country. See Testing.
`402`	`recipient_invalid`	The payment partner rejected the recipient.
`403`	`permission_denied`	The key’s creator does not have the role required for this operation.
`429`	`rate_limited`	A rate limit was reached. Wait for `Retry-After` seconds. See Rate limits.
`503`	`provider_insufficient_funds`	The payment partner cannot process this payout right now. Retry later.

curl https://api.monerail.com/v1/payouts \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1f3c9e2-5b7d-4c21-9f80-3e6b2d1c7a45" \
  -d '{
    "amount": 150000,
    "currency": "XAF",
    "recipient": {
      "type": "mobile_money",
      "name": "Kossi Mensah",
      "phone": "237670000777",
      "operator": "MTN"
    },
    "description": "Invoice 2026-118",
    "client_reference": "inv_118"
  }'

const res = await fetch('https://api.monerail.com/v1/payouts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MONERAIL_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'a1f3c9e2-5b7d-4c21-9f80-3e6b2d1c7a45',
  },
  body: JSON.stringify({
    amount: 150000,
    currency: 'XAF',
    recipient: {
      type: 'mobile_money',
      name: 'Kossi Mensah',
      phone: '237670000777',
      operator: 'MTN',
    },
    description: 'Invoice 2026-118',
    client_reference: 'inv_118',
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

import os

import requests

res = requests.post(
    "https://api.monerail.com/v1/payouts",
    headers={"Authorization": f"Bearer {os.environ['MONERAIL_KEY']}", "Idempotency-Key": "a1f3c9e2-5b7d-4c21-9f80-3e6b2d1c7a45"},
    json={
        "amount": 150000,
        "currency": "XAF",
        "recipient": {
            "type": "mobile_money",
            "name": "Kossi Mensah",
            "phone": "237670000777",
            "operator": "MTN",
        },
        "description": "Invoice 2026-118",
        "client_reference": "inv_118",
    },
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)

<?php
$ch = curl_init('https://api.monerail.com/v1/payouts');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('MONERAIL_KEY'),
    'Content-Type: application/json',
    'Idempotency-Key: a1f3c9e2-5b7d-4c21-9f80-3e6b2d1c7a45',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 150000,
    'currency' => 'XAF',
    'recipient' => [
      'type' => 'mobile_money',
      'name' => 'Kossi Mensah',
      'phone' => '237670000777',
      'operator' => 'MTN',
    ],
    'description' => 'Invoice 2026-118',
    'client_reference' => 'inv_118',
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status >= 400) {
  throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
}
print_r($data);

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	payload, err := json.Marshal(map[string]any{
		"amount":   150000,
		"currency": "XAF",
		"recipient": map[string]any{
			"type":     "mobile_money",
			"name":     "Kossi Mensah",
			"phone":    "237670000777",
			"operator": "MTN",
		},
		"description":      "Invoice 2026-118",
		"client_reference": "inv_118",
	})
	if err != nil {
		panic(err)
	}
	req, err := http.NewRequest(http.MethodPost, "https://api.monerail.com/v1/payouts", bytes.NewReader(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("MONERAIL_KEY"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", "a1f3c9e2-5b7d-4c21-9f80-3e6b2d1c7a45")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
		panic(err)
	}
	if res.StatusCode >= 400 {
		panic(fmt.Sprint(data["error"]))
	}
	fmt.Println(data)
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "amount": 150000,
              "currency": "XAF",
              "recipient": {
                "type": "mobile_money",
                "name": "Kossi Mensah",
                "phone": "237670000777",
                "operator": "MTN"
              },
              "description": "Invoice 2026-118",
              "client_reference": "inv_118"
            }
            """;
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.monerail.com/v1/payouts"))
            .header("Authorization", "Bearer " + System.getenv("MONERAIL_KEY"))
            .header("Content-Type", "application/json")
            .header("Idempotency-Key", "a1f3c9e2-5b7d-4c21-9f80-3e6b2d1c7a45")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            throw new RuntimeException(response.body());
        }
        System.out.println(response.body()); // parse with your JSON library (Jackson, Gson…)
    }
}

require "json"
require "net/http"

uri = URI("https://api.monerail.com/v1/payouts")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch("MONERAIL_KEY")}"
req["Content-Type"] = "application/json"
req["Idempotency-Key"] = "a1f3c9e2-5b7d-4c21-9f80-3e6b2d1c7a45"
req.body = JSON.generate({
  amount: 150000,
  currency: "XAF",
  recipient: {
    type: "mobile_money",
    name: "Kossi Mensah",
    phone: "237670000777",
    operator: "MTN",
  },
  description: "Invoice 2026-118",
  client_reference: "inv_118",
})

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
raise "#{data["error"]["code"]}: #{data["error"]["message"]}" unless res.is_a?(Net::HTTPSuccess)
puts data

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MONERAIL_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.monerail.com/v1/payouts");
request.Headers.Add("Idempotency-Key", "a1f3c9e2-5b7d-4c21-9f80-3e6b2d1c7a45");
request.Content = JsonContent.Create(new
{
    amount = 150000,
    currency = "XAF",
    recipient = new
    {
        type = "mobile_money",
        name = "Kossi Mensah",
        phone = "237670000777",
        @operator = "MTN",
    },
    description = "Invoice 2026-118",
    client_reference = "inv_118",
});

using var response = await http.SendAsync(request);
var data = await response.Content.ReadFromJsonAsync<JsonElement>();
if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(data.GetProperty("error").GetProperty("message").GetString());
}
Console.WriteLine(data);

Response201

{
  "id": "7b05e2b6-6638-4088-a984-7155dfd6a036",
  "object": "payout",
  "livemode": false,
  "status": "pending",
  "amount": 150000,
  "currency": "XAF",
  "fee": 2250,
  "recipient": {
    "type": "mobile_money",
    "name": "Kossi Mensah",
    "operator": "MTN",
    "phone": "237670000777",
    "country": "CM"
  },
  "description": "Invoice 2026-118",
  "client_reference": "inv_118",
  "metadata": {},
  "failure_code": null,
  "failure_message": null,
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:06.394Z"
}

Retrieve a payout

GET/v1/payouts/{id}

If the payout is still on its way, Monerail first asks the payment partner for news.

Key roles: Every role

Path parameters

idstringRequired

ID of the payout.

Returns

Returns the payout object.

curl https://api.monerail.com/v1/payouts/7b05e2b6-6638-4088-a984-7155dfd6a036 \
  -H "Authorization: Bearer $MONERAIL_KEY"

const res = await fetch('https://api.monerail.com/v1/payouts/7b05e2b6-6638-4088-a984-7155dfd6a036', {
  headers: {
    Authorization: `Bearer ${process.env.MONERAIL_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

import os

import requests

res = requests.get(
    "https://api.monerail.com/v1/payouts/7b05e2b6-6638-4088-a984-7155dfd6a036",
    headers={"Authorization": f"Bearer {os.environ['MONERAIL_KEY']}"},
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)

<?php
$ch = curl_init('https://api.monerail.com/v1/payouts/7b05e2b6-6638-4088-a984-7155dfd6a036');
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('MONERAIL_KEY'),
  ],
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status >= 400) {
  throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
}
print_r($data);

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://api.monerail.com/v1/payouts/7b05e2b6-6638-4088-a984-7155dfd6a036", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("MONERAIL_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
		panic(err)
	}
	if res.StatusCode >= 400 {
		panic(fmt.Sprint(data["error"]))
	}
	fmt.Println(data)
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.monerail.com/v1/payouts/7b05e2b6-6638-4088-a984-7155dfd6a036"))
            .header("Authorization", "Bearer " + System.getenv("MONERAIL_KEY"))
            .GET()
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            throw new RuntimeException(response.body());
        }
        System.out.println(response.body()); // parse with your JSON library (Jackson, Gson…)
    }
}

require "json"
require "net/http"

uri = URI("https://api.monerail.com/v1/payouts/7b05e2b6-6638-4088-a984-7155dfd6a036")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch("MONERAIL_KEY")}"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
raise "#{data["error"]["code"]}: #{data["error"]["message"]}" unless res.is_a?(Net::HTTPSuccess)
puts data

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MONERAIL_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.monerail.com/v1/payouts/7b05e2b6-6638-4088-a984-7155dfd6a036");

using var response = await http.SendAsync(request);
var data = await response.Content.ReadFromJsonAsync<JsonElement>();
if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(data.GetProperty("error").GetProperty("message").GetString());
}
Console.WriteLine(data);

Response200

{
  "id": "7b05e2b6-6638-4088-a984-7155dfd6a036",
  "object": "payout",
  "livemode": false,
  "status": "succeeded",
  "amount": 150000,
  "currency": "XAF",
  "fee": 2250,
  "recipient": {
    "type": "mobile_money",
    "name": "Kossi Mensah",
    "operator": "MTN",
    "phone": "237670000777",
    "country": "CM"
  },
  "description": "Invoice 2026-118",
  "client_reference": "inv_118",
  "metadata": {},
  "failure_code": null,
  "failure_message": null,
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:09.807Z"
}

List payouts

GET/v1/payouts

Newest first.

Key roles: Every role

Query parameters

limitintegerOptionalDefault 20

Number of objects to return, 1 to 100.

starting_afterstringOptional

Cursor: the ID of the last object of the previous page.

Returns

Returns a list object: data holds up to limit payout objects, and has_more tells whether more follow.

curl "https://api.monerail.com/v1/payouts?limit=10" \
  -H "Authorization: Bearer $MONERAIL_KEY"

const res = await fetch('https://api.monerail.com/v1/payouts?limit=10', {
  headers: {
    Authorization: `Bearer ${process.env.MONERAIL_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

import os

import requests

res = requests.get(
    "https://api.monerail.com/v1/payouts",
    headers={"Authorization": f"Bearer {os.environ['MONERAIL_KEY']}"},
    params={"limit": 10},
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)

<?php
$ch = curl_init('https://api.monerail.com/v1/payouts?limit=10');
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('MONERAIL_KEY'),
  ],
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status >= 400) {
  throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
}
print_r($data);

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://api.monerail.com/v1/payouts?limit=10", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("MONERAIL_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
		panic(err)
	}
	if res.StatusCode >= 400 {
		panic(fmt.Sprint(data["error"]))
	}
	fmt.Println(data)
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.monerail.com/v1/payouts?limit=10"))
            .header("Authorization", "Bearer " + System.getenv("MONERAIL_KEY"))
            .GET()
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            throw new RuntimeException(response.body());
        }
        System.out.println(response.body()); // parse with your JSON library (Jackson, Gson…)
    }
}

require "json"
require "net/http"

uri = URI("https://api.monerail.com/v1/payouts?limit=10")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch("MONERAIL_KEY")}"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
raise "#{data["error"]["code"]}: #{data["error"]["message"]}" unless res.is_a?(Net::HTTPSuccess)
puts data

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MONERAIL_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.monerail.com/v1/payouts?limit=10");

using var response = await http.SendAsync(request);
var data = await response.Content.ReadFromJsonAsync<JsonElement>();
if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(data.GetProperty("error").GetProperty("message").GetString());
}
Console.WriteLine(data);

Response200

{
  "object": "list",
  "url": "/v1/payouts",
  "data": [
    {
      "id": "7b05e2b6-6638-4088-a984-7155dfd6a036",
      "object": "payout",
      "livemode": false,
      "status": "pending",
      "amount": 150000,
      "currency": "XAF",
      "fee": 2250,
      "recipient": {
        "type": "bank",
        "name": "Kossi Mensah",
        "bank_code": "10005",
        "account": "••••4821",
        "country": "CM"
      },
      "description": "Invoice 2026-118",
      "client_reference": "inv_118",
      "metadata": {},
      "failure_code": null,
      "failure_message": null,
      "created_at": "2026-10-30T13:47:06.394Z",
      "updated_at": "2026-10-30T13:47:06.394Z"
    }
  ],
  "has_more": false
}

Payouts

The payout object#

Attributes

Create a payout#

Body

Returns

Errors worth handling

Retrieve a payout#

Path parameters

Returns

List payouts#

Query parameters

Returns

The payout object

Create a payout

Retrieve a payout

List payouts