> ## 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.

# Collect payments

> Mobile-money prompts and card checkout.

`POST /v1/merchants/{merchantID}/collections` needs the `collect` scope. The money lands in a till: the one you name in `till_id`, or else your first active till.

## Mobile money prompt (STK)

```bash theme={null}
curl -X POST https://api.cloudpay.africa/cloudpay/v1/merchants/$MERCHANT_ID/collections \
  -H "Authorization: Bearer $CLOUDPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "0712345678",
    "amount": 150000,
    "reference": "INV-2207",
    "idempotency_key": "inv-2207"
  }'
```

| Field | Required | |
| - | - | - |
| `amount` | ✓ | Cents, whole shillings only (a multiple of `100`). KES 1 to KES 250,000. |
| `idempotency_key` | ✓ | 8 to 100 characters. See [Idempotency](https://docs.cloudpay.africa/concepts/idempotency.md). |
| `msisdn` | ✓ for STK | The payer's phone. |
| `network` | | `mpesa` (default), `airtel` or `tkash`. Airtel needs a SasaPay or Paystack collection rail; T-Kash needs SasaPay. See [Rails and networks](https://docs.cloudpay.africa/guides/rails.md). |
| `reference` | | Your reference, up to 100 characters. It's returned on the payment and shown in statements. |
| `till_id` | | Which till receives the money. A cashier can only collect into their own till. |

The phone shows a prompt, and the customer approves it with their own PIN. You can't pre-authorise or skip that step. Then [poll](https://docs.cloudpay.africa/concepts/lifecycle.md#polling) until the payment is `completed` or `failed`.

> [!NOTE]
>
> A phone can have at most **3 prompts waiting** at once. A fourth returns `429 too_many_prompts` until the customer answers one or about 10 minutes pass. Don't loop on prompts to the same number.

## Card checkout

Set `method: "checkout"`. This needs a Paystack collection rail. The phone number is optional:

```json theme={null}
{ "method": "checkout", "amount": 250000, "email": "jane@example.com", "idempotency_key": "cart-88" }
```

The response includes a `checkout_url`. It's filled in once the provider accepts the payment, usually while the payment is `initiated` or `pending`. Redirect the payer there, then poll as usual.

## No-code: QR codes and payment links

Every till has a QR code that leads to a hosted pay page, at `/pay/{code}`. On that page the payer chooses M-Pesa or their Cloudpay wallet. To get a page with a fixed amount, a reference or an expiry date, see [Payment links](https://docs.cloudpay.africa/guides/links.md).

## Records, attempts and why payments failed

Every collection is one prompt or charge, so `GET /v1/merchants/{id}/collections` is also your attempts list:

* `status=completed`: the payments you received (your records).
* `status=failed,review`: what didn't go through. Each one has `failure_category` and `failure_label`, worked out from what the provider said (`failure_reason`): `cancelled`, `insufficient_funds`, `wrong_pin`, `timeout`, `busy`, `limit`, `invalid_account`, `declined`, `provider_error`, `test_mode`, `review` or `other`. Filter with `category=`.
* `q=` finds a phone, receipt, reference or id. `from`/`to` set a window. `format=csv` downloads every match.

`GET /v1/merchants/{id}/collections/report` gives totals, the success rate, failures by category, and attempts per day and per provider. Payouts have the same: `GET /v1/merchants/{id}/disbursements/report`.

A collection still `pending` after the payer paid can be checked again with `POST /v1/merchants/{id}/collections/{cid}/resolve`. The payer is not prompted again. Cloudpay also asks about waiting payments every minute, so a check within a minute of the last one returns the collection as it is.

## Common errors

| Code | Why | Fix |
| - | - | - |
| `400 network_unsupported` | Airtel or T-Kash on a rail that only prompts M-Pesa | Ask Cloudpay for a SasaPay (or, for Airtel, Paystack) collection rail, or use `mpesa` |
| `400 test_amount_limit` | More than KES 100 with a test key | Use a smaller amount in Development |
| `400 test_daily_limit` | Development's daily total is reached | Wait until midnight (Nairobi time) or ask Cloudpay |
| `403 production_not_approved` | Live key, but the business isn't approved yet | Finish [going live](https://docs.cloudpay.africa/environments.md#going-live) |
| `403 service_not_enabled` | Collections are switched off for this business | Contact Cloudpay |
| `409 rail_not_configured` | No collection provider is chosen | Choose one under **Rails** |
| `429 too_many_prompts` | 3 prompts already waiting on this phone | Wait for the customer to answer |

See the [error reference](https://docs.cloudpay.africa/errors/reference.md) for the full list.


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