Get started

Quickstart

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

You need a Monerails 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 and 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.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);

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. The number below is a Cameroon test number that always succeeds. Send an Idempotency-Key so a retry can never charge twice.

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

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 last digit of a test number decides the outcome: 237660000001 reaches succeeded within a few seconds and sends collection.succeeded, 237660000002 stays pending, 237660000003 ends failed. Any other number returns 400 test_phone_required.

Receive the result. Create a webhook endpoint (dashboard › Developers › Webhooks, or the API) that receives collection events. When the collection reaches a final status, Monerails 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.