Get started

Quickstart

Make your first API call, collect a test payment and receive its webhook.

You need a Monerail account. Everything below happens in test mode: no real money moves.

Create a test key. In the dashboard, open Developers › API keys, give the key a name (2 to 60 characters) and create it in test mode. It starts with mr_test_. Copy it now: it is shown only once. Keep it on your server, never in a web page or a mobile app.
Check your balance. This proves the key works.

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

Every endpoint of the API reference has the same call in curl, Node.js, Python, PHP, Go, Java, Ruby and C#.

JSON

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

Collect a payment. Ask a customer in Cameroon to pay 5,000 XAF with MTN Mobile Money. Send an Idempotency-Key so a retry can never charge twice.

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

The collection comes back with a status and, while the customer has something to do, a next_action. Show its message to your customer.

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#"
  }
}

In test mode, the payment partner’s sandbox decides how the collection proceeds and how it ends. See Testing.

Receive the result. Create a webhook endpoint (dashboard › Developers › Webhooks, or the API) that receives collection events. When the collection reaches a final status, Monerail sends collection.succeeded, collection.failed or collection.expired. A succeeded collection carries its fee and net. Verify the signature, then mark the order paid.
Go further. Read Collections, Errors for what can go wrong, Security, and Going live when you are ready.