Step-by-step guides
Quickstart: sandbox to live
Seven stages from a sandbox wallet to your first collection, first payout, webhooks and the go-live switch, with what to send and what you get back at every step.
What you will build
This guide takes you from nothing to a live integration in seven stages: a sandbox wallet, your first collection, your first payout, webhooks, your first mistakes (on purpose), the go-live switch, and the first live day. Every stage says what to send, what you should get back, and what to do next.
You need a Moolre account, a server that can make HTTPS requests, and a public HTTPS URL for webhooks (a tunnel is fine while you develop). Keep credentials on your server: never put API keys in a web page or mobile app.
- A Moolre account
- A server-side language (Node.js, Python, PHP or plain curl)
- A public HTTPS URL you control, for webhooks
- A place to store secrets (environment variables or a secret manager)
Stage 1: create a sandbox wallet
A wallet holds your balance. Everything you do in the API names a wallet by its account number.
- Call Create Account in the sandbox with your username in X-API-USER. Send type 1, a currency (GHS or NGN), an accountname and api: true.
- Read data in the reply: it gives the account number and the wallet secret (data.secret). Store them as MOOLRE_ACCOUNT and MOOLRE_WALLET_SECRET: the secret signs your webhooks. In the sandbox it starts with GHS 1,000.00.
- Set the wallet callback with Update Account (callback), pointing at your webhook URL. You can leave it empty until stage 4.
curl https://sandbox.moolre.com/open/account/create \ -H "Content-Type: application/json" \ -H "X-API-USER: $MOOLRE_USER" \ -d '{ "type": 1, "currency": "GHS", "accountname": "My Test Wallet", "api": true, "callback": "https://example.com/moolre/webhook" }'Live wallets are created in the app
Create Account works only in the sandbox. In production you create wallets in the Moolre app. See Account wallets.
Stage 2: your first collection
A collection asks a customer to approve a payment on their phone. Use the test number 0240000111, which always succeeds.
- Send Mobile Money Collection with type 1, channel MTN, currency GHS, payer 0240000111, an amount, a unique externalref and your accountnumber.
- You get TP14 (verify the phone first). For a test number no SMS is sent and the code is 123456. Send the same request with "otpcode": "123456" and you get TP17.
- Send the original request a third time. You get the prompt reply (TR099) and the sandbox starts the scenario. The customer would now approve on their phone.
- Check the outcome with Payment Status (idtype 1, your externalref). txstatus 1 means paid, 0 pending, 2 failed. Or wait for the payment.succeeded webhook.
curl https://sandbox.moolre.com/open/transact/payment \ -H "Content-Type: application/json" \ -H "X-API-USER: $MOOLRE_USER" \ -d '{ "type": 1, "channel": "MTN", "currency": "GHS", "payer": "0240000111", "amount": "10.00", "externalref": "ORDER-1001", "accountnumber": "1000000000001" }'externalref is your idempotency anchor
It must be unique per wallet. Create it before you send the request and store it with your order. If anything times out, ask for the status of the same externalref instead of sending a new request.
Stage 3: your first payout
A payout sends money from your wallet to a phone number or bank account. Always check the name first.
- Call Validate Name with the receiver, channel and currency. For the test number 0240000111 it returns the holder name SANDBOX TEST SUCCESS. Show the name to your user and let them confirm.
- Call Initiate Transfer with type 1, channel, currency, amount, receiver, a unique externalref, an optional sendername and your accountnumber. Add an Idempotency-Key header so a retry cannot pay twice.
- Read the reply. OBGH01 means the payout was accepted and paid; APY16 means in progress. Neither is final proof for an uncertain case: check Transfer Status with the externalref.
- Never resend a payout whose outcome you do not know. See Send payouts, step by step for the unknown-outcome rules (TP18, PY02).
curl https://sandbox.moolre.com/open/transact/validate \ -H "Content-Type: application/json" \ -H "X-API-USER: $MOOLRE_USER" \ -d '{ "type": 1, "receiver": "0240000111", "channel": "MTN", "currency": "GHS", "accountnumber": "1000000000001" }'Stage 4: receive webhooks
Polling works, but a webhook tells you the moment a payment settles. Treat the webhook as a notification and your database as the truth.
- Expose an HTTPS endpoint that reads the raw request body.
- Verify the X-Moolre-Signature header with your wallet secret. Reject a bad signature and a timestamp more than 5 minutes old.
- Store the event_id. If you already have it, answer 200 and do nothing else.
- Update your order from data.externalref, then answer 2xx quickly.
- Call Send test webhook to confirm delivery, then fire real events with the sandbox trigger endpoint.
Stage 5: break it on purpose
Before live, rehearse the failures. The sandbox makes them deterministic with test numbers.
| Try this | Number or amount | You should see |
|---|---|---|
| A payment that fails | 0240000999 (wrong PIN) or amount 10.91 | txstatus 2 with a reason; payment.failed webhook; your order stays unpaid |
| A payment that takes a minute | 0240000222 | txstatus 0, then 1 after about 60 seconds |
| A payment that never settles | 0240000555 | txstatus 0 for ever; your reconciliation job finds it |
| A payout that fails | 0240000333 | OM14 insufficient balance, txstatus 2 |
| Duplicate webhook | Resend webhook | The same event_id again; you ignore it |
| A repeated request | Same Idempotency-Key and body | The stored reply with meta.replayed true |
Stage 6: go live
Going live changes credentials and the base URL, nothing else. Do it in this order.
- In the Moolre app create the live wallet (complete any verification the app asks for) and an API Service linked to it. Generate the keys you need: a private key for payouts, accounts, sales, bulk payouts, invoices and webhook tools, a public key for collections and payment links, and VAS keys for SMS and WhatsApp.
- Store the live keys in your secret manager. Never reuse sandbox values and never commit keys.
- Whitelist your server IP addresses for disbursements. A payout from an address that is not on the list is refused (TK01).
- Set the live wallet callback (Update Account) to your production webhook URL, and make sure it serves a valid public TLS certificate (the grace period for webhooks ends 2026-12-31).
- Switch the base URL from https://sandbox.moolre.com to https://api.moolre.com and the credentials to the live ones. Use channel names, send credentials in headers only and add an Idempotency-Key to money requests.
- Run one small real collection and one small real payout, and check each with its status endpoint and its webhook.
- Follow the full Going live checklist before you announce.
curl https://api.moolre.com/open/transact/payment \ -H "Content-Type: application/json" \ -H "X-API-USER: $MOOLRE_USER" \ -H "X-API-PUBKEY: $MOOLRE_PUBKEY" \ -H "Idempotency-Key: live-check-1" \ -d '{ "type": 1, "channel": "MTN", "currency": "GHS", "payer": "0240000000", "amount": "1.00", "externalref": "LIVE-CHECK-1", "accountnumber": "YOUR_LIVE_ACCOUNT" }'Stage 7: the first live day
- Every live call logs its meta.requestid next to your own order or payout reference.
- You watch the first collections and payouts individually and check each against its status endpoint.
- Webhook deliveries shows no dead events; if one is dead, you fix the endpoint and use Resend webhook.
- An alert fires when a payment stays pending longer than you expect, and when the wallet balance is lower than the payouts you plan.
- You have the support route ready: quote the meta.requestid and the externalref.
Common first-day errors
| You see | Why | Fix |
|---|---|---|
| AIN01, AIN05 | Wrong user or key, or the key belongs to another wallet or environment | Check the user, the key type for this endpoint, and that live keys go to api.moolre.com and sandbox keys to sandbox.moolre.com |
| AIN04 | API access is not switched on for the wallet | Enable API access for the wallet in the Moolre app |
| TK01 | Your server IP is not whitelisted for disbursements | Add the IP in the app, then retry |
| TP07, APY18 | Missing or non-unique externalref | Generate a unique reference per business action and store it |
| TP14 | The customer must verify their phone first | Send otpcode and repeat; this is a normal step, not an error |
| OTP429 | Too many one-time code attempts | Wait, and stop retrying |
| IDEM01 | Same Idempotency-Key, different body | Use a new key for a new request |