Collect payments, step by step
Environment: Live
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.
# 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.
| Stage | What happens | You hold the order as |
| --- | --- | --- |
| 1. Verify phone | A new payer must confirm their phone with an SMS code (TP14, then TP17) | pending |
| 2. Prompt sent | The customer sees the approval prompt (TR099) | pending |
| 3. Result | txstatus 1 paid, 2 failed (with a reason), 0 still pending | paid, 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
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"
}'
```
```curlsteptheprompt
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: ORDER-1001" \
-d '{
"type": 1,
"channel": "MTN",
"currency": "GHS",
"payer": "0240000001",
"amount": "25.00",
"externalref": "ORDER-1001",
"accountnumber": "1000000000001"
}'
```
```jsonstepverifyphone
{
"status": 1,
"code": "TP14",
"message": "Please complete the verification process sent to you via SMS and try again.",
"data": "all",
"go": null,
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": []
}
}
```
```jsonstepverified
{
"status": 1,
"code": "TP17",
"message": "Phone number verification successful.",
"data": "all",
"go": null,
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": []
}
}
```
```jsonsteppromptsent
{
"status": 1,
"code": "TR099",
"message": null,
"data": "f25fc80e-791b-495b-8799-dcf87660457d",
"go": null,
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": []
}
}
```
- [Mobile Money Collection (API reference)](https://docs.moolre.com/api/payments/initiate)
- [Payment Status (API reference)](https://docs.moolre.com/api/payments/status)
## 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.
```nodejs
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 };
}
}
```
```python
def collect(order, otpcode=None, verified=False):
request = {"type": 1, "channel": order["network"], "currency": "GHS", "payer": order["phone"],
"amount": order["amount"], "externalref": order["externalref"],
"accountnumber": os.environ["MOOLRE_ACCOUNT"]}
if otpcode:
request["otpcode"] = otpcode
res = moolre("/open/transact/payment", request, key="public",
idempotency_key=order["externalref"] if verified else None)
code = res.get("code")
if code == "TP14":
return {"next": "ask-otp"}
if code == "TP17":
return collect(order, verified=True)
if code == "TR099":
return {"next": "wait-for-result"}
if code == "TP18":
return {"next": "wait-for-result", "unknown": True} # may still be sent: do not retry
if code == "OTP429":
return {"next": "try-later"}
return {"next": "show-error", "code": code, "message": (res.get("error") or {}).get("message", res.get("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.
| txstatus | Result | Webhook | What you do |
| --- | --- | --- | --- |
| 0 | pending | None yet | Keep the order pending. Poll gently. Do not release goods |
| 1 | succeeded | payment.succeeded (P01) | Mark paid and fulfil once. Check data.amount against the order |
| 2 | failed | payment.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.
| | Webhooks | Polling Payment Status |
| --- | --- | --- |
| Speed | You hear within seconds of the result | As fast as your interval |
| Reliability | Retried for 72 hours, can be resent | Always works, costs requests |
| Best for | Marking orders paid | A safety net for orders still pending after a few minutes, and reconciliation |
- [Webhooks and callbacks](https://docs.moolre.com/guides/webhooks-and-callbacks)
- [Reconciliation playbook](https://docs.moolre.com/use-cases/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
| Code | Meaning | Fix |
| --- | --- | --- |
| TP07 | externalref is required and must be unique | Send a unique externalref per attempt |
| TP05 | Amount is required and must be greater than 0.01 | Send a positive amount string such as 25.00 |
| TP06 | Payer details are required | Send payer in local format |
| TP14 | Phone must be verified first | Ask for the SMS code, resend with otpcode |
| TP15 | Wrong or expired code | Ask the customer to request a new code (5 wrong codes invalidate it) |
| TP18 | Timeout, the request may still be sent | Do not retry; wait for the webhook or check status |
| OTP429 | Too many code attempts | Wait; do not retry immediately |
| TP02, TP03, TP04 | Wallet invalid, inactive or not found | Check accountnumber and that the wallet is active |
| IDEM01 | Idempotency-Key reused with a different body | Use 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.