Référence de l’API

Reversements

Un reversement transfère de l’argent de votre solde Monerail vers votre propre compte bancaire ou mobile money, tel qu’enregistré pour cette devise par un Propriétaire dans le tableau de bord (Paramètres › Reversements).

POST/v1/settlementsCréer un reversement GET/v1/settlements/{id}Consulter un reversement GET/v1/settlementsLister les reversements

L’objet reversement

Attributs

idstring

Identifiant unique (UUID).

livemodeboolean

true en production, false en mode test.

objectstring

Toujours settlement.

statusstring

succeeded et failed sont définitifs.

pendingprocessingsucceededfailed

amountinteger

Montant envoyé sur votre compte de reversement, en unités mineures.

currencystring

Code devise ISO 4217.

feeinteger

Frais Monerail.

recipientobject

Votre compte de reversement pour cette devise, tel qu’enregistré dans le tableau de bord (même forme que pour les paiements : mobile_money ou bank).

descriptionstring | null

Toujours null pour les reversements.

client_referencestring | null

Votre propre référence, telle qu’envoyée à la création.

metadataobject

Paires clé-valeur jointes à la création.

failure_codestring | null

Raison de l’échec, si status vaut failed ou expired.

failure_messagestring | null

Détail transmis par le partenaire de paiement, s’il existe.

created_atstring

Date de création, ISO 8601 (UTC).

updated_atstring

Dernière modification, ISO 8601 (UTC).

L’objet reversement

{
  "id": "575f3a4b-ccd5-4949-9c4d-158127ccccd1",
  "object": "settlement",
  "livemode": false,
  "status": "pending",
  "amount": 2500000,
  "currency": "XAF",
  "fee": 0,
  "recipient": {
    "type": "bank",
    "name": "Acme SARL",
    "bank_code": "10005",
    "account": "••••0193",
    "country": "CM"
  },
  "description": null,
  "client_reference": null,
  "metadata": {},
  "failure_code": null,
  "failure_message": null,
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:06.394Z"
}

Créer un reversement

POST/v1/settlements

La destination est toujours votre compte de reversement enregistré : elle ne peut pas être changée par l’API.

Rôles de la clé : Propriétaire ou Finance

Corps

amountintegerRequis

Montant en unités mineures de currency (francs entiers pour XAF, XOF et GNF ; centimes pour CDF, par multiples de 100). Entier seulement.

currencystringRequis

Code ISO 4217.

XAFXOFGNFCDFNGNKESGHSUGXTZSRWF

Retour

Renvoie le nouvel objet reversement avec 201, ou 202 quand le résultat n’est pas encore définitif.

Erreurs à prévoir

HTTP	Code	Description
`400`	`settlement_destination_missing`	Aucun compte de reversement enregistré pour cette devise.
`400`	`settlement_destination_invalid`	Le compte de reversement enregistré n’est pas valide pour le partenaire de paiement.
`402`	`balance_insufficient`	Votre solde (ou solde cartes) ne couvre pas le montant et les frais.
`403`	`permission_denied`	Le créateur de la clé n’a pas le rôle requis pour cette opération.
`429`	`rate_limited`	Une limite de débit est atteinte. Attendez `Retry-After` secondes. Voir Limites de débit.

curl https://api.monerail.com/v1/settlements \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1f3c9e2-5b7d-4c21-9f80-3e6b2d1c7a45" \
  -d '{
    "amount": 2500000,
    "currency": "XAF"
  }'

const res = await fetch('https://api.monerail.com/v1/settlements', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MONERAIL_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'a1f3c9e2-5b7d-4c21-9f80-3e6b2d1c7a45',
  },
  body: JSON.stringify({
    amount: 2500000,
    currency: 'XAF',
  }),
});
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/settlements",
    headers={"Authorization": f"Bearer {os.environ['MONERAIL_KEY']}", "Idempotency-Key": "a1f3c9e2-5b7d-4c21-9f80-3e6b2d1c7a45"},
    json={
        "amount": 2500000,
        "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.monerail.com/v1/settlements');
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' => 2500000,
    'currency' => 'XAF',
  ]),
  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":   2500000,
		"currency": "XAF",
	})
	if err != nil {
		panic(err)
	}
	req, err := http.NewRequest(http.MethodPost, "https://api.monerail.com/v1/settlements", 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": 2500000,
              "currency": "XAF"
            }
            """;
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.monerail.com/v1/settlements"))
            .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/settlements")
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: 2500000,
  currency: "XAF",
})

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/settlements");
request.Headers.Add("Idempotency-Key", "a1f3c9e2-5b7d-4c21-9f80-3e6b2d1c7a45");
request.Content = JsonContent.Create(new
{
    amount = 2500000,
    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);

Réponse201

{
  "id": "575f3a4b-ccd5-4949-9c4d-158127ccccd1",
  "object": "settlement",
  "livemode": false,
  "status": "pending",
  "amount": 2500000,
  "currency": "XAF",
  "fee": 0,
  "recipient": {
    "type": "bank",
    "name": "Acme SARL",
    "bank_code": "10005",
    "account": "••••0193",
    "country": "CM"
  },
  "description": null,
  "client_reference": null,
  "metadata": {},
  "failure_code": null,
  "failure_message": null,
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:06.394Z"
}

Consulter un reversement

GET/v1/settlements/{id}

Rôles de la clé : Tous les rôles

Paramètres de chemin

idstringRequis

Identifiant du reversement.

Retour

Renvoie l’objet reversement.

curl https://api.monerail.com/v1/settlements/575f3a4b-ccd5-4949-9c4d-158127ccccd1 \
  -H "Authorization: Bearer $MONERAIL_KEY"

const res = await fetch('https://api.monerail.com/v1/settlements/575f3a4b-ccd5-4949-9c4d-158127ccccd1', {
  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/settlements/575f3a4b-ccd5-4949-9c4d-158127ccccd1",
    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/settlements/575f3a4b-ccd5-4949-9c4d-158127ccccd1');
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/settlements/575f3a4b-ccd5-4949-9c4d-158127ccccd1", 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/settlements/575f3a4b-ccd5-4949-9c4d-158127ccccd1"))
            .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/settlements/575f3a4b-ccd5-4949-9c4d-158127ccccd1")
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/settlements/575f3a4b-ccd5-4949-9c4d-158127ccccd1");

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

Réponse200

{
  "id": "575f3a4b-ccd5-4949-9c4d-158127ccccd1",
  "object": "settlement",
  "livemode": false,
  "status": "succeeded",
  "amount": 2500000,
  "currency": "XAF",
  "fee": 0,
  "recipient": {
    "type": "bank",
    "name": "Acme SARL",
    "bank_code": "10005",
    "account": "••••0193",
    "country": "CM"
  },
  "description": null,
  "client_reference": null,
  "metadata": {},
  "failure_code": null,
  "failure_message": null,
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:06.394Z"
}

Lister les reversements

GET/v1/settlements

Du plus récent au plus ancien.

Rôles de la clé : Tous les rôles

Paramètres de requête

limitintegerFacultatifPar défaut 20

Nombre d’objets à renvoyer, de 1 à 100.

starting_afterstringFacultatif

Curseur : l’identifiant du dernier objet de la page précédente.

Retour

Renvoie un objet liste : data contient jusqu’à limit objets settlement, et has_more indique s’il en reste.

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

const res = await fetch('https://api.monerail.com/v1/settlements?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/settlements",
    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/settlements?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/settlements?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/settlements?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/settlements?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/settlements?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);

Réponse200

{
  "object": "list",
  "url": "/v1/settlements",
  "data": [
    {
      "id": "575f3a4b-ccd5-4949-9c4d-158127ccccd1",
      "object": "settlement",
      "livemode": false,
      "status": "pending",
      "amount": 2500000,
      "currency": "XAF",
      "fee": 0,
      "recipient": {
        "type": "bank",
        "name": "Acme SARL",
        "bank_code": "10005",
        "account": "••••0193",
        "country": "CM"
      },
      "description": null,
      "client_reference": null,
      "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
}

Reversements

L’objet reversement#

Attributs

Créer un reversement#

Corps

Retour

Erreurs à prévoir

Consulter un reversement#

Paramètres de chemin

Retour

Lister les reversements#

Paramètres de requête

Retour

L’objet reversement

Créer un reversement

Consulter un reversement

Lister les reversements