Démarrer

Démarrage rapide

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

Il vous faut un compte Monerail. 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 tout de suite : elle ne s’affiche qu’une fois. 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.monerail.com/v1/balance \
  -H "Authorization: Bearer $MONERAIL_KEY"

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

import os

import requests

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

<?php
$ch = curl_init('https://api.monerail.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. Envoyez une Idempotency-Key : une nouvelle tentative ne pourra jamais débiter deux fois.

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

const res = await fetch('https://api.monerail.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: '237670000999',
    operator: 'MTN',
    customer: { name: 'Awa Ndiaye' },
    client_reference: 'order_42',
  }),
});
const collection = await res.json();

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

<?php
$ch = curl_init('https://api.monerail.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' => '237670000999',
    '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 bac à sable du partenaire de paiement décide du déroulé de l’encaissement et de son issue. Voir Tests.

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, Monerail 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.