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
Setmethod: "checkout". This needs a Paystack collection rail. The phone number is optional:
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.
Records, attempts and why payments failed
Every collection is one prompt or charge, soGET /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 hasfailure_categoryandfailure_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,revieworother. Filter withcategory=.q=finds a phone, receipt, reference or id.from/toset a window.format=csvdownloads 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.