Démarrer

Démarrage rapide

Faites votre premier appel, encaissez un paiement de test et recevez son webhook.

Il vous faut un compte Monerails. Tout ce qui suit se passe en mode test : aucun argent réel ne bouge.

Créez une clé de test. Dans le tableau de bord, ouvrez Développeurs › Clés d’API, nommez la clé (2 à 60 caractères) et créez-la en mode test. Elle commence par mr_test_. Copiez-la et gardez-la sur votre serveur, jamais dans une page web ni une application mobile.
Consultez votre solde. Cela prouve que la clé fonctionne.

curl https://api.monerails.com/v1/balance \
  -H "Authorization: Bearer $MONERAIL_KEY"

const res = await fetch('https://api.monerails.com/v1/balance', {
  headers: { Authorization: `Bearer ${process.env.MONERAIL_KEY}` },
});
console.log(await res.json());

import os

import requests

res = requests.get(
    "https://api.monerails.com/v1/balance",
    headers={"Authorization": f"Bearer {os.environ['MONERAIL_KEY']}"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://api.monerails.com/v1/balance');
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('MONERAIL_KEY')],
  CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);

Chaque point d’accès de la référence de l’API donne le même appel en curl, Node.js, Python, PHP, Go, Java, Ruby et C#.

JSON

{
  "object": "balance",
  "livemode": false,
  "available": [{ "currency": "XAF", "amount": 0 }],
  "cards": { "currency": "USD", "amount": 0 }
}

Encaissez un paiement. Demandez à un client au Cameroun de payer 5 000 XAF avec MTN Mobile Money. Le numéro ci-dessous est un numéro de test camerounais qui réussit toujours. Envoyez une Idempotency-Key : une nouvelle tentative ne pourra jamais débiter deux fois.

curl https://api.monerails.com/v1/collections \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-42" \
  -d '{
    "amount": 5000,
    "currency": "XAF",
    "phone": "237660000001",
    "operator": "MTN",
    "customer": { "name": "Awa Ndiaye" },
    "client_reference": "order_42"
  }'

const res = await fetch('https://api.monerails.com/v1/collections', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MONERAIL_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-42',
  },
  body: JSON.stringify({
    amount: 5000,
    currency: 'XAF',
    phone: '237660000001',
    operator: 'MTN',
    customer: { name: 'Awa Ndiaye' },
    client_reference: 'order_42',
  }),
});
const collection = await res.json();

res = requests.post(
    "https://api.monerails.com/v1/collections",
    headers={
        "Authorization": f"Bearer {os.environ['MONERAIL_KEY']}",
        "Idempotency-Key": "order-42",
    },
    json={
        "amount": 5000,
        "currency": "XAF",
        "phone": "237660000001",
        "operator": "MTN",
        "customer": {"name": "Awa Ndiaye"},
        "client_reference": "order_42",
    },
    timeout=30,
)
collection = res.json()

<?php
$ch = curl_init('https://api.monerails.com/v1/collections');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('MONERAIL_KEY'),
    'Content-Type: application/json',
    'Idempotency-Key: order-42',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 5000,
    'currency' => 'XAF',
    'phone' => '237660000001',
    'operator' => 'MTN',
    'customer' => ['name' => 'Awa Ndiaye'],
    'client_reference' => 'order_42',
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$collection = json_decode(curl_exec($ch), true);

L’encaissement revient avec un status et, tant que le client a quelque chose à faire, un next_action. Affichez son message à votre client.

JSON

{
  "id": "3b8f6c1e-2a47-4d1b-9e35-7c0a9d2f4e61",
  "object": "collection",
  "status": "pending",
  "amount": 5000,
  "currency": "XAF",
  "next_action": {
    "type": "customer_approval",
    "message": "A payment request was sent. The customer enters their PIN.",
    "ussd_code": "*126#"
  }
}

En mode test, le dernier chiffre d’un numéro de test décide de l’issue : 237660000001 atteint succeeded en quelques secondes et envoie collection.succeeded, 237660000002 reste pending, 237660000003 finit failed. Tout autre numéro renvoie 400 test_phone_required.

Recevez le résultat. Créez un point de terminaison (tableau de bord › Développeurs › Webhooks, ou l’API) qui reçoit les événements d’encaissement. Quand l’encaissement atteint un statut définitif, Monerails envoie collection.succeeded, collection.failed ou collection.expired. Un encaissement réussi porte ses fee et net. Vérifiez la signature, puis marquez la commande payée.
Allez plus loin. Lisez Encaissements, Erreurs pour ce qui peut mal tourner, Sécurité, et Passer en production quand vous êtes prêt.