> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudpay.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment lifecycle

> Statuses, how long they last, and how to wait for the outcome.

Payments are asynchronous. Creating one returns `202 Accepted` straight away, while the customer approves the prompt or the bank confirms. Cloudpay doesn't send webhooks yet, so **poll** the payment.

## Collections and payouts

```text theme={null}
initiated ──► pending ──► completed
    │            ├─────► failed
    └──► failed  └─► review ──► completed | failed
```

| `status` | Meaning | What to do |
| - | - | - |
| `initiated` | Recorded, but the provider hasn't accepted it yet | Keep polling |
| `pending` | The provider has it. The customer is approving it, or the bank is processing it. | Keep polling |
| `completed` | Done. `receipt` holds the provider receipt. | Fulfil the order |
| `failed` | Not done. Any held money is released. | Show `failure_reason`; retry with a new key if you want |
| `review` | The outcome is unclear, for example the amount didn't match or a receipt was reused. Cloudpay operations are checking it, and any money stays held. | Don't retry. Keep polling; it ends `completed` or `failed`. |

`completed` and `failed` are final, so a payment never leaves them.

### Polling

```js theme={null}
async function waitFor(id) {
  for (let i = 0; i < 60; i++) {
    const { data } = await cloudpay.get(`/v1/merchants/${MID}/collections/${id}`);
    if (["completed", "failed"].includes(data.status)) return data;
    await new Promise((r) => setTimeout(r, i < 10 ? 3000 : 10000));
  }
  return null; // still pending or in review: check again later from a job
}
```

An M-Pesa prompt expires on the customer's phone after about a minute. Bank payouts can take longer. Poll from a background job, not inside a web request.

## Settlements

| `status` | Meaning |
| - | - |
| `requested` | Waiting for a second person to approve it |
| `processing` | Approved, and the payout is on its way |
| `awaiting_payout` | Approved, and Cloudpay staff will pay it by hand (`payout: manual`) |
| `paid` | Money sent to your destination |
| `failed` | The payout failed, and the money is back on your main account |
| `rejected` | A second person declined the request |
| `cancelled` | The requester withdrew it |

## Batches

`GET /v1/merchants/{id}/bulk/{batchID}` returns item counts by status. To list the items themselves, add `?batch_id=` to the collections or disbursements list. Each item follows the same lifecycle as a single payment.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.