# Send payouts, step by step

Validate the name, send the payout with an Idempotency-Key and sendername, confirm the result, and retry safely when the outcome is unknown (PY02, APY16).

## How a payout works

A payout (Initiate Transfer) sends money from your wallet to a mobile money number or a bank account. Payouts are charge-first: the amount plus the fee is reserved from your wallet when the payout is accepted. A failed payout gives the money back.

Payouts need your private key (X-API-KEY), the server IP on the disbursement whitelist, and a unique externalref. The one rule that matters most: never send the same payout twice because you were not sure what happened the first time.

| Step | Endpoint | Why |
| --- | --- | --- |
| 1 | Validate Name | Catch a wrong number or account before money moves |
| 2 | Initiate Transfer | Send the money, with an Idempotency-Key |
| 3 | Transfer Status or the payout webhook | Confirm the final state |

## Before you start



- [ ] The private API key for the wallet, in your secret manager.
- [ ] Your server IP is on the wallet disbursement whitelist (otherwise TK01).
- [ ] Enough balance for the amount plus the fee.
- [ ] A unique externalref per payout, created and stored before you send.
- [ ] A wallet callback URL, so you receive payout.succeeded and payout.failed.

## Step by step



1. Create the payout record in your database with status pending, the receiver, the amount and a unique externalref such as PAYOUT-77. Create it before the request: it is your guard against paying twice.
2. Call Validate Name with the receiver, channel (MTN, TELECEL, AT or BANK) and currency. For BANK also send sublistid, the bank code from Get banks. The reply data is the holder name. Show it to the person who is sending the money and let them confirm. If it is not found (AVD02), stop and ask for the number again.
3. Call Initiate Transfer with type 1, channel, currency, amount (a string), receiver, externalref, an optional reference (a narration) and an optional sendername, and your accountnumber. Send an Idempotency-Key header equal to the externalref.
4. Read the reply and record it: OBGH01 and the other success codes mean the payout was accepted; APY16 means it is in progress. Store the code, data.txstatus and the transactionid.
5. Do not mark the payout paid yet unless txstatus is 1. Wait for the payout.succeeded or payout.failed webhook, or ask Transfer Status with idtype 1 and your externalref.
6. On success mark it paid. On failure read data.reason or the code, and decide: fix the cause (wrong number, balance) and send a NEW payout with a NEW externalref. A failed externalref is spent.

```curlvalidate
curl https://api.moolre.com/open/transact/validate \
  -H "Content-Type: application/json" \
  -H "X-API-USER: $MOOLRE_USER" \
  -H "X-API-KEY: $MOOLRE_KEY" \
  -d '{
    "type": 1,
    "receiver": "0240000001",
    "channel": "MTN",
    "currency": "GHS",
    "accountnumber": "1000000000001"
  }'
```

```jsonvalidate
{
  "status": 1,
  "code": "AVD01",
  "message": "Successful",
  "data": "KOFI ASARE",
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

```curltransfer
curl https://api.moolre.com/open/transact/transfer \
  -H "Content-Type: application/json" \
  -H "X-API-USER: $MOOLRE_USER" \
  -H "X-API-KEY: $MOOLRE_KEY" \
  -H "Idempotency-Key: PAYOUT-77" \
  -d '{
    "type": 1,
    "channel": "MTN",
    "currency": "GHS",
    "amount": "25.00",
    "receiver": "0240000001",
    "externalref": "PAYOUT-77",
    "reference": "Commission October",
    "sendername": "Acme",
    "accountnumber": "1000000000001"
  }'
```

```jsonaccepted
{
  "status": "1",
  "code": "OBGH01",
  "message": [
    "Pay out Successful",
    "The payout request was received."
  ],
  "data": {
    "txstatus": 1,
    "transactionid": "10000001",
    "externalref": "PAYOUT-77",
    "receiver": "0240000001",
    "receivername": "KOFI ASARE",
    "amount": "25.00"
  },
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

- [Validate Name](https://docs.moolre.com/api/transfers/validate-name)
- [Initiate Transfer](https://docs.moolre.com/api/transfers/initiate)
- [Transfer Status](https://docs.moolre.com/api/transfers/status)

## The sender name

sendername is optional. It is the name the recipient sees as the sender. Send 2 to 30 characters: letters, spaces, full stops, apostrophes and hyphens, starting with a letter (no digits). Anything else returns APY22 and the payout is not sent. Leave it out to use the default.

## Safe retries, step by step

A payout request can fail in three ways, and each needs a different response.

| What you see | Is money moving? | What to do |
| --- | --- | --- |
| A validation error (APY01 to APY09, APY12 to APY15, APY22) | No. The request was refused before anything happened | Fix the request and send it again. You may reuse the externalref, because the payout never existed |
| An authentication or whitelist error (AIN*, TK01) | No | Fix the credentials or whitelist, then send again with the same externalref |
| A timeout, a dropped connection or a 5xx | Unknown | Resend with the same externalref and the same Idempotency-Key, or check Transfer Status first. Never create a new externalref |
| PY02, PY01, TR01, TR02, APY16, APY10, TP11, TP18, ASL06, SYS500 or a txstatus of 0 | Probably yes, in progress | Do not resend. Check Transfer Status by externalref and wait for the webhook |
| txstatus 2 (failed) | No. The reservation was returned | Fix the cause and send a new payout with a new externalref |

1. Save the externalref before the first request.
2. If the call fails without a clear answer, call Transfer Status with that externalref.
3. If the status says it exists and is pending or successful, you are done: record it, do not resend.
4. If the status says it does not exist (SS07 Transaction not found) after a reasonable wait, resending with the same externalref and Idempotency-Key is safe.

> **Never assume a payout failed:** Only txstatus 2 on the payout response or the status check means failed. A timeout, a pending code (PY01, PY02, TR01, TR02, TP11, TP18, APY10, APY16, ASL06, SYS500), a txstatus of 0 or a missing answer means unknown. Treat unknown as pending until you can prove otherwise.

## The same flow in code



```nodejs
async function pay(payout) {
  // 1. who is this number registered to?
  const who = await moolre('/open/transact/validate', {
    type: 1, receiver: payout.receiver, channel: payout.channel, currency: 'GHS',
    accountnumber: process.env.MOOLRE_ACCOUNT,
  });
  if (who.status !== 1) return { ok: false, reason: 'name-not-found', code: who.code };
  if (who.data.toUpperCase() !== payout.expectedName.toUpperCase()) return { ok: false, reason: 'name-mismatch', name: who.data };

  // 2. send the money once
  const res = await moolre('/open/transact/transfer', {
    type: 1, channel: payout.channel, currency: 'GHS', amount: payout.amount, receiver: payout.receiver,
    externalref: payout.externalref, sendername: 'Acme', accountnumber: process.env.MOOLRE_ACCOUNT,
  }, { idempotencyKey: payout.externalref });

  // 3. record what Moolre said; never decide "failed" from silence
  const state = outcomeOf(res);
  if (state === 'succeeded') return { ok: true, final: true };
  if (state === 'failed') return { ok: false, final: true, code: res.code, message: res.error?.message ?? res.message };
  return { ok: null, final: false };   // pending or unknown: wait for the webhook, or poll Transfer Status
}

// Moolre has no "outcome" field: decide from status, code and data.txstatus (0 pending, 1 succeeded, 2 failed).
const UNKNOWN = ['PY01', 'PY02', 'TR01', 'TR02', 'TP11', 'TP18', 'APY10', 'APY16', 'ASL06', 'SYS500']; // may still succeed: pending
const DONE = ['TR08', 'OBGH01', 'OTGH01', 'OBNG01', 'GHQ03', 'OM03'];                                 // status 1 and final
function outcomeOf(res) {
  const tx = res.data && typeof res.data === 'object' ? res.data.txstatus : undefined;
  if (tx !== undefined && tx !== null && tx !== '') return Number(tx) === 1 ? 'succeeded' : Number(tx) === 2 ? 'failed' : 'pending';
  if (String(res.status) === '1') return DONE.includes(res.code) ? 'succeeded' : 'pending';
  return UNKNOWN.includes(res.code) ? 'pending' : 'failed';
}
```

```python
def pay(payout):
    who = moolre("/open/transact/validate", {"type": 1, "receiver": payout["receiver"], "channel": payout["channel"],
                                              "currency": "GHS", "accountnumber": os.environ["MOOLRE_ACCOUNT"]})
    if who.get("status") != 1:
        return {"ok": False, "reason": "name-not-found", "code": who.get("code")}

    res = moolre("/open/transact/transfer", {
        "type": 1, "channel": payout["channel"], "currency": "GHS", "amount": payout["amount"],
        "receiver": payout["receiver"], "externalref": payout["externalref"], "sendername": "Acme",
        "accountnumber": os.environ["MOOLRE_ACCOUNT"]}, idempotency_key=payout["externalref"])

    state = outcome_of(res)
    if state == "succeeded":
        return {"ok": True, "final": True}
    if state == "failed":
        return {"ok": False, "final": True, "code": res.get("code")}
    return {"ok": None, "final": False}   # pending or unknown: wait for the webhook, or poll Transfer Status


# Moolre has no "outcome" field: decide from status, code and data.txstatus (0 pending, 1 succeeded, 2 failed).
UNKNOWN = {"PY01", "PY02", "TR01", "TR02", "TP11", "TP18", "APY10", "APY16", "ASL06", "SYS500"}  # may still succeed: pending
DONE = {"TR08", "OBGH01", "OTGH01", "OBNG01", "GHQ03", "OM03"}                                  # status 1 and final


def outcome_of(res):
    data = res.get("data")
    tx = data.get("txstatus") if isinstance(data, dict) else None
    if tx not in (None, ""):
        return {1: "succeeded", 2: "failed"}.get(int(tx), "pending")
    if str(res.get("status")) == "1":
        return "succeeded" if res.get("code") in DONE else "pending"
    return "pending" if res.get("code") in UNKNOWN else "failed"
```

## Common errors and fixes



| Code | Meaning | Fix |
| --- | --- | --- |
| AVD02 | Name or number not found | Ask for the number again; do not send |
| AVD03 | Lookup timed out | Try again; if it keeps failing, confirm the number another way |
| APY18 | externalref missing or not unique | Use a unique externalref per payout |
| APY08 | This channel does not support API payout | Use MTN, TELECEL, AT or BANK |
| APY20 | sublistid is required for BANK | Send the bank code from Get banks |
| APY21 | Insufficient wallet balance | Fund the wallet and send a new payout |
| APY22 | Invalid sendername | Send 2 to 30 characters: letters, spaces, full stop, apostrophe, hyphen; start with a letter |
| OM14 | Insufficient balance | Fund the wallet and send a new payout |
| OM16, OM12 | Could not be started, not charged | Safe to send again (bulk payouts do this automatically) |
| TK01 | IP not whitelisted | Add the server IP in the app |
| PY02, PY01, APY16 | Outcome unknown or in progress | Check Transfer Status by externalref; never resend |

## Checklist



- [ ] You validate the name and show it to a person (or compare it to your records) before the first payout to a number.
- [ ] Every payout has a unique externalref saved before the request, and an Idempotency-Key.
- [ ] You never resend after a timeout, a 5xx, a pending code, PY02 or APY16 without checking Transfer Status first.
- [ ] A failed payout is retried with a new externalref only after you fixed the cause.
- [ ] You reconcile payouts against Transfer Status and the account statement every day.
- [ ] The server IPs are whitelisted and the private key is server-side only.

- [Safe retries](https://docs.moolre.com/guides/safe-retries)
- [Bulk payouts](https://docs.moolre.com/guides/bulk-payouts)
- [Account statements](https://docs.moolre.com/guides/statements)
