Skip to main content
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)

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 until the payment is completed or failed.
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:
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. 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.

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

See the error reference for the full list.