Référence de l’API

Bénéficiaires

Les destinataires enregistrés de vos paiements, partagés avec le tableau de bord (Paiements › Bénéficiaires). Les bénéficiaires de test et de production sont séparés, selon le mode de la clé. Une destination (numéro ou compte) est enregistrée une seule fois par mode, et une entreprise garde jusqu’à 500 bénéficiaires par mode. Pour en payer un, créez un paiement avec beneficiary.

POST/v1/beneficiariesCréer un bénéficiaire GET/v1/beneficiaries/{id}Consulter un bénéficiaire POST/v1/beneficiaries/{id}Modifier un bénéficiaire GET/v1/beneficiariesLister les bénéficiaires DELETE/v1/beneficiaries/{id}Supprimer un bénéficiaire

L’objet bénéficiaire

Attributs

idstring

Identifiant unique (UUID).

livemodeboolean

true en production, false en mode test.

objectstring

Toujours beneficiary.

typestring

Portefeuille mobile money ou compte bancaire.

mobile_moneybank

namestring

Nom du bénéficiaire, repris comme nom du destinataire des paiements.

nicknamestring | null

Votre propre libellé, 40 caractères au plus.

countrystring

Code pays ISO 3166-1 alpha-2.

currencystring

Devise des paiements vers ce bénéficiaire (celle du pays).

operatorstring | null

Mobile money seulement : code opérateur.

phonestring | null

Mobile money seulement : numéro au format E.164.

bank_codestring | null

Banque seulement : code issu de Lister les banques.

bank_namestring | null

Banque seulement : nom de la banque.

accountstring | null

Banque seulement : numéro de compte masqué.

last_used_atstring | null

Date du dernier paiement créé avec ce bénéficiaire.

created_atstring

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

updated_atstring

Dernière modification, ISO 8601 (UTC).

L’objet bénéficiaire

{
  "id": "4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34",
  "object": "beneficiary",
  "livemode": false,
  "type": "mobile_money",
  "name": "Kossi Mensah",
  "nickname": "Akwa supplier",
  "country": "CM",
  "currency": "XAF",
  "operator": "MTN",
  "phone": "+237670000777",
  "bank_code": null,
  "bank_name": null,
  "account": null,
  "last_used_at": null,
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:06.394Z"
}

Créer un bénéficiaire

POST/v1/beneficiaries

Contrôle les coordonnées avec les mêmes règles que les paiements (pays ouvert aux paiements, opérateur du pays, numéro international, numéros de test en mode test, code banque exact) et les enregistre. Rien n’est envoyé au destinataire.

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

Corps

typestringRequis

mobile_moneybank

namestringRequis

Nom du bénéficiaire, 2 à 80 caractères.

countrystringRequis

Code ISO 3166-1 alpha-2 d’un pays ouvert aux paiements.

currencystringFacultatif

Code ISO 4217. Par défaut, la devise du pays.

nicknamestringFacultatif

Votre propre libellé, 40 caractères au plus.

phonestringFacultatif

Mobile money : numéro au format international (+237670000777).

operatorstringFacultatif

Mobile money : code opérateur issu de Lister les opérateurs.

bank_codestringFacultatif

Banque : un code issu de Lister les banques, exactement tel que renvoyé.

accountstringFacultatif

Banque : numéro de compte, 6 à 34 lettres ou chiffres.

Retour

Renvoie le nouvel objet beneficiary avec 201.

Erreurs à prévoir

HTTP	Code	Description
`400`	`country_unsupported`	Ce pays n’est pas ouvert pour cette devise. Voir Couverture.
`400`	`operator_unsupported`	Opérateur inconnu, ou refusé par le partenaire de paiement pour cette devise.
`400`	`phone_invalid`	Le numéro ne peut pas être lu comme un numéro international.
`400`	`test_phone_required`	Mode test : utilisez un des numéros de test de ce pays. Voir Tests.
`400`	`bank_account_invalid`	`bank_code` ne correspond pas exactement à un code de Lister les banques, ou le numéro de compte est trop court.
`400`	`bank_transfer_unsupported`	Les virements bancaires ne sont pas disponibles dans ce pays : payez vers un portefeuille mobile money.
`400`	`limit_reached`	Une limite est atteinte : 10 points de terminaison par entreprise (test et production confondus), ou 500 bénéficiaires par mode.
`403`	`permission_denied`	Le créateur de la clé n’a pas le rôle requis pour cette opération.
`409`	`beneficiary_exists`	Un bénéficiaire avec ce numéro ou ce compte existe déjà dans ce mode.

curl https://api.monerail.com/v1/beneficiaries \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mobile_money",
    "name": "Kossi Mensah",
    "nickname": "Akwa supplier",
    "country": "CM",
    "phone": "+237670000777",
    "operator": "MTN"
  }'

const res = await fetch('https://api.monerail.com/v1/beneficiaries', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MONERAIL_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'mobile_money',
    name: 'Kossi Mensah',
    nickname: 'Akwa supplier',
    country: 'CM',
    phone: '+237670000777',
    operator: 'MTN',
  }),
});
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/beneficiaries",
    headers={"Authorization": f"Bearer {os.environ['MONERAIL_KEY']}"},
    json={
        "type": "mobile_money",
        "name": "Kossi Mensah",
        "nickname": "Akwa supplier",
        "country": "CM",
        "phone": "+237670000777",
        "operator": "MTN",
    },
    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/beneficiaries');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('MONERAIL_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'type' => 'mobile_money',
    'name' => 'Kossi Mensah',
    'nickname' => 'Akwa supplier',
    'country' => 'CM',
    'phone' => '+237670000777',
    'operator' => 'MTN',
  ]),
  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{
		"type":     "mobile_money",
		"name":     "Kossi Mensah",
		"nickname": "Akwa supplier",
		"country":  "CM",
		"phone":    "+237670000777",
		"operator": "MTN",
	})
	if err != nil {
		panic(err)
	}
	req, err := http.NewRequest(http.MethodPost, "https://api.monerail.com/v1/beneficiaries", bytes.NewReader(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("MONERAIL_KEY"))
	req.Header.Set("Content-Type", "application/json")

	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 = """
            {
              "type": "mobile_money",
              "name": "Kossi Mensah",
              "nickname": "Akwa supplier",
              "country": "CM",
              "phone": "+237670000777",
              "operator": "MTN"
            }
            """;
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.monerail.com/v1/beneficiaries"))
            .header("Authorization", "Bearer " + System.getenv("MONERAIL_KEY"))
            .header("Content-Type", "application/json")
            .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/beneficiaries")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch("MONERAIL_KEY")}"
req["Content-Type"] = "application/json"
req.body = JSON.generate({
  type: "mobile_money",
  name: "Kossi Mensah",
  nickname: "Akwa supplier",
  country: "CM",
  phone: "+237670000777",
  operator: "MTN",
})

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/beneficiaries");
request.Content = JsonContent.Create(new
{
    type = "mobile_money",
    name = "Kossi Mensah",
    nickname = "Akwa supplier",
    country = "CM",
    phone = "+237670000777",
    @operator = "MTN",
});

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": "4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34",
  "object": "beneficiary",
  "livemode": false,
  "type": "mobile_money",
  "name": "Kossi Mensah",
  "nickname": "Akwa supplier",
  "country": "CM",
  "currency": "XAF",
  "operator": "MTN",
  "phone": "+237670000777",
  "bank_code": null,
  "bank_name": null,
  "account": null,
  "last_used_at": null,
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:06.394Z"
}

Consulter un bénéficiaire

GET/v1/beneficiaries/{id}

Rôles de la clé : Propriétaire, Finance, Valideur ou Développeur

Paramètres de chemin

idstringRequis

Identifiant du bénéficiaire.

Retour

Renvoie l’objet beneficiary.

Erreurs à prévoir

HTTP	Code	Description
`403`	`permission_denied`	Le créateur de la clé n’a pas le rôle requis pour cette opération.
`404`	`resource_missing`	Aucun objet avec cet identifiant dans ce mode.

curl https://api.monerail.com/v1/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34 \
  -H "Authorization: Bearer $MONERAIL_KEY"

const res = await fetch('https://api.monerail.com/v1/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34', {
  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/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34",
    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/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34');
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/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34", 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/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34"))
            .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/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34")
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/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34");

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": "4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34",
  "object": "beneficiary",
  "livemode": false,
  "type": "mobile_money",
  "name": "Kossi Mensah",
  "nickname": "Akwa supplier",
  "country": "CM",
  "currency": "XAF",
  "operator": "MTN",
  "phone": "+237670000777",
  "bank_code": null,
  "bank_name": null,
  "account": null,
  "last_used_at": null,
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:06.394Z"
}

Modifier un bénéficiaire

POST/v1/beneficiaries/{id}

Modifie les paramètres envoyés ; les autres gardent leur valeur. type ne peut pas changer. Envoyez nickname: null pour retirer le surnom. Les contrôles de la création s’appliquent.

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

Paramètres de chemin

idstringRequis

Identifiant du bénéficiaire.

Corps

namestringFacultatif

2 à 80 caractères.

nicknamestringFacultatif

40 caractères au plus, ou null.

countrystringFacultatif

phonestringFacultatif

operatorstringFacultatif

bank_codestringFacultatif

accountstringFacultatif

Retour

Renvoie l’objet beneficiary.

Erreurs à prévoir

HTTP	Code	Description
`400`	`parameter_invalid`	Un paramètre a un type ou une valeur incorrects. Voir `param`.
`403`	`permission_denied`	Le créateur de la clé n’a pas le rôle requis pour cette opération.
`404`	`resource_missing`	Aucun objet avec cet identifiant dans ce mode.
`409`	`beneficiary_exists`	Un bénéficiaire avec ce numéro ou ce compte existe déjà dans ce mode.

curl https://api.monerail.com/v1/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34 \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nickname": "Douala courier"
  }'

const res = await fetch('https://api.monerail.com/v1/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MONERAIL_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    nickname: 'Douala courier',
  }),
});
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/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34",
    headers={"Authorization": f"Bearer {os.environ['MONERAIL_KEY']}"},
    json={
        "nickname": "Douala courier",
    },
    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/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('MONERAIL_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'nickname' => 'Douala courier',
  ]),
  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{
		"nickname": "Douala courier",
	})
	if err != nil {
		panic(err)
	}
	req, err := http.NewRequest(http.MethodPost, "https://api.monerail.com/v1/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34", bytes.NewReader(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("MONERAIL_KEY"))
	req.Header.Set("Content-Type", "application/json")

	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 = """
            {
              "nickname": "Douala courier"
            }
            """;
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.monerail.com/v1/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34"))
            .header("Authorization", "Bearer " + System.getenv("MONERAIL_KEY"))
            .header("Content-Type", "application/json")
            .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/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch("MONERAIL_KEY")}"
req["Content-Type"] = "application/json"
req.body = JSON.generate({
  nickname: "Douala courier",
})

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/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34");
request.Content = JsonContent.Create(new
{
    nickname = "Douala courier",
});

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": "4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34",
  "object": "beneficiary",
  "livemode": false,
  "type": "mobile_money",
  "name": "Kossi Mensah",
  "nickname": "Douala courier",
  "country": "CM",
  "currency": "XAF",
  "operator": "MTN",
  "phone": "+237670000777",
  "bank_code": null,
  "bank_name": null,
  "account": null,
  "last_used_at": null,
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:09.807Z"
}

Lister les bénéficiaires

GET/v1/beneficiaries

Du plus récent au plus ancien.

Rôles de la clé : Propriétaire, Finance, Valideur ou Développeur

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.

typestringFacultatif

Seulement ce type.

mobile_moneybank

countrystringFacultatif

Seulement ce pays (ISO 3166-1 alpha-2).

Retour

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

Erreurs à prévoir

HTTP	Code	Description
`403`	`permission_denied`	Le créateur de la clé n’a pas le rôle requis pour cette opération.

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

const res = await fetch('https://api.monerail.com/v1/beneficiaries?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/beneficiaries",
    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/beneficiaries?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/beneficiaries?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/beneficiaries?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/beneficiaries?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/beneficiaries?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/beneficiaries",
  "data": [
    {
      "id": "4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34",
      "object": "beneficiary",
      "livemode": false,
      "type": "mobile_money",
      "name": "Kossi Mensah",
      "nickname": "Akwa supplier",
      "country": "CM",
      "currency": "XAF",
      "operator": "MTN",
      "phone": "+237670000777",
      "bank_code": null,
      "bank_name": null,
      "account": null,
      "last_used_at": null,
      "created_at": "2026-10-30T13:47:06.394Z",
      "updated_at": "2026-10-30T13:47:06.394Z"
    },
    {
      "id": "4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34",
      "object": "beneficiary",
      "livemode": false,
      "type": "bank",
      "name": "Kossi Mensah",
      "nickname": null,
      "country": "CM",
      "currency": "XAF",
      "operator": null,
      "phone": null,
      "bank_code": "10005",
      "bank_name": "Example Bank",
      "account": "••••4821",
      "last_used_at": "2026-10-30T13:47:09.807Z",
      "created_at": "2026-10-30T13:47:06.394Z",
      "updated_at": "2026-10-30T13:47:06.394Z"
    }
  ],
  "has_more": false
}

Supprimer un bénéficiaire

DELETE/v1/beneficiaries/{id}

Retire le bénéficiaire de la liste. Les paiements déjà créés ne sont pas modifiés.

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

Paramètres de chemin

idstringRequis

Identifiant du bénéficiaire.

Retour

Renvoie { id, object, deleted: true }.

Erreurs à prévoir

HTTP	Code	Description
`403`	`permission_denied`	Le créateur de la clé n’a pas le rôle requis pour cette opération.
`404`	`resource_missing`	Aucun objet avec cet identifiant dans ce mode.

curl -X DELETE https://api.monerail.com/v1/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34 \
  -H "Authorization: Bearer $MONERAIL_KEY"

const res = await fetch('https://api.monerail.com/v1/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34', {
  method: 'DELETE',
  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.delete(
    "https://api.monerail.com/v1/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34",
    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/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  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.MethodDelete, "https://api.monerail.com/v1/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34", 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/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34"))
            .header("Authorization", "Bearer " + System.getenv("MONERAIL_KEY"))
            .DELETE()
            .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/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34")
req = Net::HTTP::Delete.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.Delete, "https://api.monerail.com/v1/beneficiaries/4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34");

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": "4c2e9a17-6b3d-4f58-a0e1-8d7c5b2f9e34",
  "object": "beneficiary",
  "deleted": true
}

Bénéficiaires

L’objet bénéficiaire#

Attributs

Créer un bénéficiaire#

Corps

Retour

Erreurs à prévoir

Consulter un bénéficiaire#

Paramètres de chemin

Retour

Erreurs à prévoir

Modifier un bénéficiaire#

Paramètres de chemin

Corps

Retour

Erreurs à prévoir

Lister les bénéficiaires#

Paramètres de requête

Retour

Erreurs à prévoir

Supprimer un bénéficiaire#

Paramètres de chemin

Retour

Erreurs à prévoir

L’objet bénéficiaire

Créer un bénéficiaire

Consulter un bénéficiaire

Modifier un bénéficiaire

Lister les bénéficiaires

Supprimer un bénéficiaire