API reference

Reference data

The operators and banks you can use, from the payment partner, for the mode of your key. Answers are cached for up to 10 minutes.

GET/v1/operatorsList operators GET/v1/banksList banks

List operators

GET/v1/operators

Mobile money operators open for a currency, in every country of that currency, or in one country with country. authorization tells how customers approve: NONE, PIN (on the phone), OTP (code to send with authorize) or REDIRECT (payment page). Use code with the matching country when you create a collection or a payout.

Key roles: Every role

Query parameters

currencystringRequired

XAFXOFGNFCDFNGNKESGHSUGXTZSRWF

countrystringOptional

Optional ISO 3166-1 alpha-2 code, for example TD with XAF. Unknown pair: 400 country_unsupported.

Returns

Returns a list object whose data holds every operator, with has_more: false.

curl "https://api.monerails.com/v1/operators?currency=XAF" \
  -H "Authorization: Bearer $MONERAIL_KEY"

const res = await fetch('https://api.monerails.com/v1/operators?currency=XAF', {
  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.monerails.com/v1/operators",
    headers={"Authorization": f"Bearer {os.environ['MONERAIL_KEY']}"},
    params={"currency": "XAF"},
    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.monerails.com/v1/operators?currency=XAF');
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.monerails.com/v1/operators?currency=XAF", 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.monerails.com/v1/operators?currency=XAF"))
            .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.monerails.com/v1/operators?currency=XAF")
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.monerails.com/v1/operators?currency=XAF");

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/operators",
  "data": [
    {
      "object": "operator",
      "code": "MTN",
      "name": "MTN MoMo",
      "country": "CM",
      "currency": "XAF",
      "authorization": [
        "NONE"
      ],
      "ussd_code": "*126#"
    },
    {
      "object": "operator",
      "code": "ORANGE",
      "name": "Orange Money",
      "country": "CM",
      "currency": "XAF",
      "authorization": [
        "NONE"
      ],
      "ussd_code": "#150*50#"
    }
  ],
  "has_more": false
}

List banks

GET/v1/banks

Banks you can pay out to in a country. Use code, unchanged, as recipient.bank_code. Bank payouts are offered in Ghana, Nigeria, Kenya, Uganda, Tanzania and Rwanda, currently being activated (400 country_unsupported until they open); elsewhere this call returns 400 bank_transfer_unsupported: pay out to a mobile money wallet.

Key roles: Every role

Query parameters

countrystringRequired

ISO 3166-1 alpha-2.

Returns

Returns a list object whose data holds every bank, with has_more: false.

Errors worth handling

HTTP	Code	Description
`400`	`country_unsupported`	This country is not open for this currency. See Coverage.
`400`	`bank_transfer_unsupported`	Bank payouts are not available in this country: pay to a mobile money wallet.
`503`	`provider_unavailable`	This service is not open in this mode yet.

curl "https://api.monerails.com/v1/banks?country=CM" \
  -H "Authorization: Bearer $MONERAIL_KEY"

const res = await fetch('https://api.monerails.com/v1/banks?country=CM', {
  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.monerails.com/v1/banks",
    headers={"Authorization": f"Bearer {os.environ['MONERAIL_KEY']}"},
    params={"country": "CM"},
    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.monerails.com/v1/banks?country=CM');
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.monerails.com/v1/banks?country=CM", 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.monerails.com/v1/banks?country=CM"))
            .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.monerails.com/v1/banks?country=CM")
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.monerails.com/v1/banks?country=CM");

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/banks",
  "data": [
    {
      "object": "bank",
      "code": "044",
      "name": "Access Bank",
      "country": "NG"
    }
  ],
  "has_more": false
}

Reference data

List operators#

Query parameters

Returns

List banks#

Query parameters

Returns

Errors worth handling

List operators

List banks