Moolre Documentation

Step-by-step guides

Collect payments, step by step

The mobile money collection flow end to end: the one-time code, the prompt, statuses, webhooks versus polling, unknown outcomes such as TP18, and a checklist.

How a collection works

A collection (Mobile Money Collection) asks a customer to approve a payment on their own phone. You send the request, the customer sees a prompt and enters their PIN, and the money lands in your wallet. You learn the result from a webhook or by asking for the status.

The whole flow has three moving parts: the one-time code step (the first time Moolre sees a phone number), the prompt, and the result. Your job is to hold the order as pending until the result is final, and to make sure you can never fulfil an order twice.

StageWhat happensYou hold the order as
1. Verify phoneA new payer must confirm their phone with an SMS code (TP14, then TP17)pending
2. Prompt sentThe customer sees the approval prompt (TR099)pending
3. Resulttxstatus 1 paid, 2 failed (with a reason), 0 still pendingpaid, failed or still pending

Before you start

  • A wallet with API access on, and the public key (X-API-PUBKEY) for it.
  • A wallet callback URL if you want webhooks.
  • A way to create a unique externalref per payment attempt and store it with the order.
  • The sandbox test number 0240000111 (always succeeds) for your first run.

Step by step

  1. Create the order in your database with status pending and a unique externalref, for example ORDER-1001-1. Use a new externalref for every new attempt at the same order; reuse the same one only to retry the very same request.
  2. Send Mobile Money Collection with type 1, channel (MTN, TELECEL or AT), currency, payer (local format, for example 0240000001), amount as a string with two decimals, the externalref and your accountnumber. Do not add an Idempotency-Key to this first request: it may answer TP14 and the one-time code steps must run again (see step 5).
  3. If the reply is TP14, the payer must verify their phone: Moolre sent them an SMS code. Ask the customer for it.
  4. Send the same request again with otpcode set to the code. The reply TP17 means the phone is verified.
  5. Send the original request one more time (without otpcode), now with an Idempotency-Key header equal to the externalref. The reply TR099 means the prompt was sent. Tell the customer to approve on their phone. If this request times out, send it again unchanged: the same key returns the stored answer instead of a second prompt.
  6. Wait for the result: the payment.succeeded or payment.failed webhook, or poll Payment Status with idtype 1 and your externalref every few seconds for the first minute, then less often.
  7. On txstatus 1 (or P01) mark the order paid and fulfil it exactly once. On txstatus 2 (or P02) show data.reason and offer a new attempt with a new externalref. On txstatus 0, keep waiting.
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" \  -d '{    "type": 1,    "channel": "MTN",    "currency": "GHS",    "payer": "0240000001",    "amount": "25.00",    "externalref": "ORDER-1001",    "accountnumber": "1000000000001"  }'

The same flow in code

A complete collection with the OTP loop, using the helper from the API keys guide. It never fulfils the order itself: it only records what Moolre says.

async function collect(order, otpcode, verified = false) {  const request = {    type: 1, channel: order.network, currency: 'GHS', payer: order.phone,    amount: order.amount, externalref: order.externalref, accountnumber: process.env.MOOLRE_ACCOUNT,    ...(otpcode ? { otpcode } : {}),  };  const res = await moolre('/open/transact/payment', request, { key: 'public', idempotencyKey: verified ? order.externalref : undefined });​  switch (res.code) {    case 'TP14': return { next: 'ask-otp' };                        // show an OTP field to the customer    case 'TP17': return collect(order, undefined, true);             // phone verified: send the prompt, now idempotent    case 'TR099': return { next: 'wait-for-result' };               // webhook or poll    case 'TP18': return { next: 'wait-for-result', unknown: true }; // may still be sent: do not retry    case 'OTP429': return { next: 'try-later' };    default: return { next: 'show-error', code: res.code, message: res.error?.message ?? res.message };  }}

Statuses and what to do

Payment Status returns data.txstatus (0 pending, 1 succeeded, 2 failed). Branch on it, together with status and code. A code that means unknown (TP11, TP18, PY01, PY02, TR01, TR02, APY10, APY16, ASL06 or SYS500) is pending, never failed: check the status again before you do anything.

txstatusResultWebhookWhat you do
0pendingNone yetKeep the order pending. Poll gently. Do not release goods
1succeededpayment.succeeded (P01)Mark paid and fulfil once. Check data.amount against the order
2failedpayment.failed (P02)Show data.reason. Offer a retry with a new externalref

A failed callback is not a debit

Never conclude that money left the customer, or arrived in your wallet, from a failed callback. Never fulfil from it.

Polling versus webhooks

Use both. Treat the webhook as the fast path and a periodic status check as the safety net: every few minutes, look at orders that are still pending and ask Moolre.

WebhooksPolling Payment Status
SpeedYou hear within seconds of the resultAs fast as your interval
ReliabilityRetried for 72 hours, can be resentAlways works, costs requests
Best forMarking orders paidA safety net for orders still pending after a few minutes, and reconciliation

When the answer is unknown

TP18 means the request to the mobile money network timed out. The customer may still receive the prompt and the payment may still complete. The same applies to an HTTP timeout or a 5xx on your side.

  1. Do not send a new request and do not create a new externalref.
  2. Keep the order pending.
  3. Wait for the webhook, or ask Payment Status for the same externalref.
  4. If the status says txstatus 2, offer a new attempt with a new externalref. If it says 1, fulfil. If it is still 0 after your timeout, keep checking: the status endpoint, not a new request, answers the question.

Common errors and fixes

CodeMeaningFix
TP07externalref is required and must be uniqueSend a unique externalref per attempt
TP05Amount is required and must be greater than 0.01Send a positive amount string such as 25.00
TP06Payer details are requiredSend payer in local format
TP14Phone must be verified firstAsk for the SMS code, resend with otpcode
TP15Wrong or expired codeAsk the customer to request a new code (5 wrong codes invalidate it)
TP18Timeout, the request may still be sentDo not retry; wait for the webhook or check status
OTP429Too many code attemptsWait; do not retry immediately
TP02, TP03, TP04Wallet invalid, inactive or not foundCheck accountnumber and that the wallet is active
IDEM01Idempotency-Key reused with a different bodyUse a new key for a different request

Checklist

  • Every attempt has its own unique externalref, stored before the request is sent.
  • The order is fulfilled only when txstatus is 1 and the amount matches, and only once.
  • You never retry TP18, a timeout or a 5xx with a new reference.
  • You verify the webhook signature and ignore a repeated event_id.
  • A job re-checks orders that stay pending.
  • You log meta.requestid next to externalref.