# Cloudpay - [Cloudpay](https://docs.cloudpay.africa/index.md): Collect, pay out and settle across Kenya with one integration. - [Quickstart](https://docs.cloudpay.africa/quickstart.md): From a test key to a paid M-Pesa prompt in five minutes. - [Test your integration](https://docs.cloudpay.africa/testing.md): Scenarios to run in Development, and the checklist before you switch to a live key. - [Environments](https://docs.cloudpay.africa/environments.md): Development and Production share one URL. Your key chooses between them. - [Requests and responses](https://docs.cloudpay.africa/concepts/requests.md): Authentication, the response envelope, phone numbers and paging. - [Money and fees](https://docs.cloudpay.africa/concepts/money.md): Amounts, limits and fees. - [Idempotency](https://docs.cloudpay.africa/concepts/idempotency.md): Retry any money request safely without paying twice. - [Payment lifecycle](https://docs.cloudpay.africa/concepts/lifecycle.md): Statuses, how long they last, and how to wait for the outcome. - [Collect payments](https://docs.cloudpay.africa/guides/collections.md): Mobile-money prompts and card checkout. - [Rails and networks](https://docs.cloudpay.africa/guides/rails.md): Which provider can prompt which phone, take cards or pay out, and how to choose. - [Pay out](https://docs.cloudpay.africa/guides/payouts.md): Send money to phones, bank accounts, tills and paybills. - [Bulk payments](https://docs.cloudpay.africa/guides/bulk.md): Up to 1,000 collections or payouts in one request. - [Payment links](https://docs.cloudpay.africa/guides/links.md): A link to share by WhatsApp or SMS. The payer picks M-Pesa or their wallet. - [Withdrawals](https://docs.cloudpay.africa/guides/settlements.md): Move money from your main account to your own bank account or phone. - [Handling errors](https://docs.cloudpay.africa/errors/overview.md): How errors look, which to retry, and a client that handles them. - [Error reference](https://docs.cloudpay.africa/errors/reference.md): Every errors.code the API returns: what causes it and what to do. - [Payment failures](https://docs.cloudpay.africa/errors/payment-failures.md): Why an accepted payment ends failed or in review. - [Signing in](https://docs.cloudpay.africa/security/authentication.md): Sessions for people, keys for systems. - [Roles and permissions](https://docs.cloudpay.africa/security/roles.md): Decided by the API on every call; the dashboards only hide what you can't use. - [Audit log and sign-ins](https://docs.cloudpay.africa/security/audit.md): Who did what, when, and from where. - [Merchant dashboard](https://docs.cloudpay.africa/dashboards/merchant.md): What each page does. - [Changelog](https://docs.cloudpay.africa/changelog.md): API changes that affect your integration, newest first. - [Liveness and database check](https://docs.cloudpay.africa/api-reference/health/liveness-and-database-check.md) - [Send a one-time code by SMS](https://docs.cloudpay.africa/api-reference/auth/send-a-one-time-code-by-sms.md): Sends a 6-digit code valid for 5 minutes. At most 3 codes per number per 15 minutes, and 5 wrong guesses per code. - [Register a customer](https://docs.cloudpay.africa/api-reference/auth/register-a-customer.md): Verifies the register OTP, then creates the party (KYC tier 0), its KES wallet, the PIN, binds the device and starts a session. - [Log in with PIN](https://docs.cloudpay.africa/api-reference/auth/log-in-with-pin.md): Checks the PIN (5 wrong attempts lock it for 30 minutes). If the device is not bound to the customer yet, the response is `403 device_verification_required`; send a `login` OTP and retry with `otp`. A successful login ends every other session of the customer. - [End the current session](https://docs.cloudpay.africa/api-reference/auth/end-the-current-session.md) - [Switch between live and test](https://docs.cloudpay.africa/api-reference/auth/switch-between-live-and-test.md): Moves the session to the paired environment without logging in again. The same phone number's person account in the other environment is used and the current device is bound to it. Switching to test creates the test account (no PIN) if missing. Returning to production requires the session you switch… - [Change PIN](https://docs.cloudpay.africa/api-reference/auth/change-pin.md) - [Slide the session's idle window and get a fresh token](https://docs.cloudpay.africa/api-reference/auth/slide-the-sessions-idle-window-and-get-a-fresh-token.md): Same session id. Fails with session_ended once the session is revoked, idle past JWT_TTL, or 12h old. - [Where you are signed in](https://docs.cloudpay.africa/api-reference/auth/where-you-are-signed-in.md): Your sessions from the last 30 days, live first. `current` marks the one making this call. - [Sign out one of your sessions](https://docs.cloudpay.africa/api-reference/auth/sign-out-one-of-your-sessions.md) - [Your sign-in history](https://docs.cloudpay.africa/api-reference/auth/your-sign-in-history.md): Every sign-in attempt on your account, successful or not, newest first. - [Current customer and wallet balance](https://docs.cloudpay.africa/api-reference/wallet/current-customer-and-wallet-balance.md) - [Wallet balance](https://docs.cloudpay.africa/api-reference/wallet/wallet-balance.md) - [Wallet statement, newest first](https://docs.cloudpay.africa/api-reference/wallet/wallet-statement-newest-first.md): One line per wallet movement. A transfer and its fee appear as one debit line (`amount` = -(amount + fee)); the split is in `metadata`. Page with `before=next_before`. - [Look up a recipient's name](https://docs.cloudpay.africa/api-reference/payments/look-up-a-recipients-name.md): Returns only the registered name, for the "Send to Bob Otieno?" confirmation. - [Send money to another CloudPay customer (P2P)](https://docs.cloudpay.africa/api-reference/payments/send-money-to-another-cloudpay-customer-p2p.md): Order of checks: PIN -> recipient -> tier limits (per transaction and daily) -> risk -> ledger (funds, account status). The fee from the tenant's fee bands is charged on top of `amount`. Returns `201` for a new transfer and `200` with `replayed: true` for a retry. - [Top up the wallet from M-Pesa (STK push)](https://docs.cloudpay.africa/api-reference/payments/top-up-the-wallet-from-m-pesa-stk-push.md): Records the top-up and asks cloudpay-rails to send an STK prompt to `msisdn` (default: the customer's own number). **No money moves yet.** The wallet is credited once rails confirms the payment, which core re-checks with rails before posting. - [Get a top-up](https://docs.cloudpay.africa/api-reference/payments/get-a-top-up.md) - [Hosted pay page (HTML)](https://docs.cloudpay.africa/api-reference/merchant-pay/hosted-pay-page-html.md): What the QR opens. Optional `amount` (whole KES) prefills the amount for fixed-price QR codes. - [Merchant QR code (PNG)](https://docs.cloudpay.africa/api-reference/merchant-pay/merchant-qr-code-png.md): QR encoding the pay page URL (also returned in the `X-Pay-URL` header), with the Cloudpay mark in the middle. Works for a till code and a pay-link code. A pay-link's QR carries its fixed amount and reference, so the payer types nothing but their M-Pesa PIN. Print it, show it on a till screen, or put… - [Merchant info for the pay page](https://docs.cloudpay.africa/api-reference/merchant-pay/merchant-info-for-the-pay-page.md) - [Pay a merchant by M-Pesa (STK push)](https://docs.cloudpay.africa/api-reference/merchant-pay/pay-a-merchant-by-m-pesa-stk-push.md): Sends an STK prompt to the payer's phone. The payer needs no CloudPay account. Same lifecycle as top-ups (`initiated` -> `pending` -> `completed` | `failed` | `review`); the merchant till is credited only after rails confirms. Poll `GET /v1/pay/{code}/payments/{id}`. - [Status of an M-Pesa merchant payment](https://docs.cloudpay.africa/api-reference/merchant-pay/status-of-an-m-pesa-merchant-payment.md) - [Price a payment before the payer confirms](https://docs.cloudpay.africa/api-reference/merchant-pay/price-a-payment-before-the-payer-confirms.md): Returns what the payer will be charged. `fee` is non-zero only when the merchant passes the fee on to the payer (a payer-borne fee rule); a fee the merchant absorbs is not shown to payers. - [Pay a merchant from the CloudPay wallet](https://docs.cloudpay.africa/api-reference/merchant-pay/pay-a-merchant-from-the-cloudpay-wallet.md): Signed-in customer pays the merchant instantly: PIN -> limits (`payments.merchant`) -> risk -> ledger (wallet -> merchant till). No fee yet. The merchant must be in the customer's tenant. - [CloudPay-branded checkout page (Paystack popup)](https://docs.cloudpay.africa/api-reference/merchant-pay/cloudpay-branded-checkout-page-paystack-popup.md): HTML. Opens Paystack's popup over a CloudPay page; the outcome comes from Paystack's webhook and verify, never from the page. - [Checkout status (what the page polls)](https://docs.cloudpay.africa/api-reference/merchant-pay/checkout-status-what-the-page-polls.md) - [Your test tenant and the magic values](https://docs.cloudpay.africa/api-reference/sandbox/your-test-tenant-and-the-magic-values.md) - [Create a ready-to-use test customer](https://docs.cloudpay.africa/api-reference/sandbox/create-a-ready-to-use-test-customer.md): Registers a customer without SMS: PIN set, device bound, KYC-tiered and already logged in. The wallet starts empty; it fills only by a real STK top-up (max KES 100). Sending `balance` is refused with 400 `balance_not_supported`. Use the returned `access_token` with the normal `/v1` API. - [Create a QR merchant](https://docs.cloudpay.africa/api-reference/sandbox/create-a-qr-merchant.md): Opens a merchant (business party + main account) owned by an existing customer, with a first till, and returns its pay page and QR paths. - [The merchant's audit trail (audit permission)](https://docs.cloudpay.africa/api-reference/merchant/the-merchants-audit-trail-audit-permission.md): Who changed what on this merchant, with IP, device and session where known. Read-only. - [Where a member is signed in (members permission)](https://docs.cloudpay.africa/api-reference/merchant/where-a-member-is-signed-in-members-permission.md) - [Sign a member out of one session (members permission, audited)](https://docs.cloudpay.africa/api-reference/merchant/sign-a-member-out-of-one-session-members-permission-audited.md) - [A member's sign-in history (members permission)](https://docs.cloudpay.africa/api-reference/merchant/a-members-sign-in-history-members-permission.md) - [Businesses I act for, with my role](https://docs.cloudpay.africa/api-reference/merchant-api/businesses-i-act-for-with-my-role.md) - [Open a business (you become its owner)](https://docs.cloudpay.africa/api-reference/merchant-api/open-a-business-you-become-its-owner.md): Creates the business party, its main account, the owner membership and a first till with a QR code. Unless the tenant turned `signup_approval_required` off, the business starts with `access_approved_at: null`: until CloudPay approves it, only `GET /v1/merchants/{id}` and the `/kyb` routes answer; ev… - [The merchant and who I am to it](https://docs.cloudpay.africa/api-reference/merchant-api/the-merchant-and-who-i-am-to-it.md): Returns the merchant, the caller's role (members) and permissions. Needs `read`. - [Tills (a pinned cashier sees only theirs)](https://docs.cloudpay.africa/api-reference/merchant-api/tills-a-pinned-cashier-sees-only-theirs.md) - [Open another till](https://docs.cloudpay.africa/api-reference/merchant-api/open-another-till.md): Needs `settings`. - [Open or suspend a till](https://docs.cloudpay.africa/api-reference/merchant-api/open-or-suspend-a-till.md): Needs `settings`. - [Balances: main plus every till](https://docs.cloudpay.africa/api-reference/merchant-api/balances:-main-plus-every-till.md): A pinned cashier sees only their till. Needs `read`. - [Postings on the merchant's accounts, newest first](https://docs.cloudpay.africa/api-reference/merchant-api/postings-on-the-merchants-accounts-newest-first.md): Without `till_id`: main and every till. A pinned cashier is limited to their till. Needs `read`. - [How the business is doing over a period](https://docs.cloudpay.africa/api-reference/merchant-api/how-the-business-is-doing-over-a-period.md): Totals for `from`..`to` and for the equal window before it (`previous`, for "vs last period"), a zero-filled series, money in by till and by rail, the top 10 payers, a day-of-week x hour heatmap, new vs returning payers and the last 6 monthly cohorts. Collections count when `completed`; success rate… - [Sweep a till to main](https://docs.cloudpay.africa/api-reference/merchant-api/sweep-a-till-to-main.md): Internal transfer between the merchant's own accounts. Replays with the same key return 200. Needs `transfer`. - [The fees this merchant pays, per fee type](https://docs.cloudpay.africa/api-reference/merchant-api/the-fees-this-merchant-pays-per-fee-type.md): Needs `read`. `set_at` says whether the price is this merchant's own, its tenant's, or CloudPay's. - [What CloudPay charges this merchant for a transaction](https://docs.cloudpay.africa/api-reference/merchant-api/what-cloudpay-charges-this-merchant-for-a-transaction.md): Needs `read`. - [Pay-links, newest first (a pinned cashier sees only their till's)](https://docs.cloudpay.africa/api-reference/merchant-api/pay-links-newest-first-a-pinned-cashier-sees-only-their-tills.md): Needs `links`. - [Create a pay-link](https://docs.cloudpay.africa/api-reference/merchant-api/create-a-pay-link.md): A link is paid exactly like a till QR: share `{PUBLIC_BASE_URL}/pay/{code}` (QR at `/pay/{code}/qr.png`). The payer picks M-Pesa or wallet; the money lands in the link's till. `amount` (whole KES, in cents) fixes the amount; omit it to let the payer choose. `max_uses` caps completed payments, `expir… - [Disable or re-enable a pay-link](https://docs.cloudpay.africa/api-reference/merchant-api/disable-or-re-enable-a-pay-link.md): Needs `links`. - [Settings that apply to this merchant](https://docs.cloudpay.africa/api-reference/merchant-api/settings-that-apply-to-this-merchant.md): Resolved: a staff override where set, else the tenant default. `overrides` shows which are overridden (null = inherited). Needs `read`. - [KYB status, details and documents](https://docs.cloudpay.africa/api-reference/merchant-api/kyb-status-details-and-documents.md): Needs `read`. - [Business details for KYB](https://docs.cloudpay.africa/api-reference/merchant-api/business-details-for-kyb.md): Editable while `unverified` or `changes_requested` (else 409 `kyb_locked`). Needs `settings`. - [Upload (or replace) a KYB document](https://docs.cloudpay.africa/api-reference/merchant-api/upload-or-replace-a-kyb-document.md): Send the file as the raw body with its Content-Type: PDF, JPEG or PNG, at most 5 MB. One live document per kind. Required before submitting: registration_certificate, kra_pin_certificate, director_id. Needs `settings`. - [Submit KYB for review](https://docs.cloudpay.africa/api-reference/merchant-api/submit-kyb-for-review.md): Needs the details and every required document (422 `kyb_incomplete`). Staff then review. Needs `settings`. - [Where settlements may go](https://docs.cloudpay.africa/api-reference/merchant-api/where-settlements-may-go.md): Needs `read`. - [Add a settlement destination](https://docs.cloudpay.africa/api-reference/merchant-api/add-a-settlement-destination.md): CloudPay staff verify every destination before money can go there, so a stolen session cannot redirect payouts. Details by kind: `mobile` {msisdn, network?: mpesa|airtel|tkash} (`mpesa` {msisdn} still accepted); `bank` {bank, account_number, account_name, bank_code?}; `paybill` {paybill, account}; `… - [Remove a destination](https://docs.cloudpay.africa/api-reference/merchant-api/remove-a-destination.md): Needs `settle`. - [Settlements (withdrawals), newest first](https://docs.cloudpay.africa/api-reference/merchant-api/settlements-withdrawals-newest-first.md): Shown as Withdrawals in the dashboard. `status` filters what is shown: a rail settlement reads `paid` or `failed` once its payout is. `q` searches the id, receipt and note. Needs `read`. - [Request a settlement from the main account](https://docs.cloudpay.africa/api-reference/merchant-api/request-a-settlement-from-the-main-account.md): Needs KYB approved (unless staff waived `kyb_required`) and a verified destination. Within the merchant's auto-approve limits it is approved and paid at once (`approved_by: system:auto-approve`); otherwise someone else approves. Payout: an M-Pesa destination on a custodial disbursement rail is paid… - [One settlement](https://docs.cloudpay.africa/api-reference/merchant-api/one-settlement.md): Needs `read`. - [Approve (second person) and pay](https://docs.cloudpay.africa/api-reference/merchant-api/approve-second-person-and-pay.md): The requester cannot approve (403 `same_approver`). A manual payout holds the money until staff record the receipt. Needs `settle`. - [Reject a requested settlement](https://docs.cloudpay.africa/api-reference/merchant-api/reject-a-requested-settlement.md): Needs `settle`. - [Cancel a requested settlement](https://docs.cloudpay.africa/api-reference/merchant-api/cancel-a-requested-settlement.md): Needs `settle`. - [SMS sent for this merchant](https://docs.cloudpay.africa/api-reference/merchant-api/sms-sent-for-this-merchant.md): Payer receipts (when `sms_receipts` is on: from the merchant's `sender_id`, billed per segment with fee kind `messaging.sms`) and free owner alerts (settlement paid or failed, KYB decisions). Status: `sent`, `failed` (fee released), `unpaid` (main could not cover the fee; nothing sent). Needs `read`… - [Members and roles](https://docs.cloudpay.africa/api-reference/merchant-api/members-and-roles.md): Needs `members`. - [Add a person (by phone) or change their role](https://docs.cloudpay.africa/api-reference/merchant-api/add-a-person-by-phone-or-change-their-role.md): Roles: owner (everything), manager (read, collect, links, transfer, members, settings, rails), finance (read, transfer, settle, disburse), cashier (read, collect, links; `till_id` pins them to one till). Only an owner can add, change or remove an owner. Needs `members`. - [Remove a member](https://docs.cloudpay.africa/api-reference/merchant-api/remove-a-member.md): The last owner cannot be removed. Needs `members`. - [Merchant API keys (no secrets)](https://docs.cloudpay.africa/api-reference/merchant-api/merchant-api-keys-no-secrets.md): Needs `keys` (owners). - [Issue a merchant API key (shown once)](https://docs.cloudpay.africa/api-reference/merchant-api/issue-a-merchant-api-key-shown-once.md): Scopes: read, collect, disburse, rails, credentials, links, transfer, settle, settings. A key can never manage members or keys. Use it as `Authorization: Bearer sk_...` or `X-Api-Key`. Needs `keys`. A live merchant not yet approved for production gets `403 production_not_approved`: use Development (… - [Revoke a key (immediate)](https://docs.cloudpay.africa/api-reference/merchant-api/revoke-a-key-immediate.md): Needs `keys`. - [Banks the merchant's payout rail can pay](https://docs.cloudpay.africa/api-reference/merchant-rails/banks-the-merchants-payout-rail-can-pay.md): The `bank_code` list for bank payees and bank settlement destinations (SasaPay channel codes). 409 `bank_payouts_unavailable` when the disbursement rail is M-Pesa; 403 `service_not_enabled` when payouts are off. Needs `read`. - [Services, selected rail and eligible rails](https://docs.cloudpay.africa/api-reference/merchant-rails/services-selected-rail-and-eligible-rails.md): Both services are always listed. `enabled` is decided by CloudPay staff; `provider` is chosen by the merchant (or staff) among `eligible_providers`. `custody` tells whose account the chosen rail moves money through: `byok` (the merchant's own keys: recorded only, never in the CloudPay ledger) or `pl… - [Choose the rail for an enabled service](https://docs.cloudpay.africa/api-reference/merchant-rails/choose-the-rail-for-an-enabled-service.md): Capability matrix: `mpesa` and `sasapay` collect (STK) and disburse (B2C); `paystack` collects only (`paystack_mode`: `charge` = server-side M-Pesa prompt, `checkout` = Paystack popup on a CloudPay page, `both`). The rail must have credentials that can perform the service (merchant, else tenant, els… - [The merchant's own provider keys (masked) and fallbacks](https://docs.cloudpay.africa/api-reference/merchant-rails/the-merchants-own-provider-keys-masked-and-fallbacks.md) - [Bring your own keys (BYOK)](https://docs.cloudpay.africa/api-reference/merchant-rails/bring-your-own-keys-byok.md): Write-only (responses are masked), AES-256-GCM at rest. Money then moves in the merchant's own provider account (custody `byok`). Fields: `mpesa`: consumer_key, consumer_secret, shortcode; passkey (collect), initiator + security_credential (disburse), optional till_number, b2c_shortcode. `sasapay`:… - [Remove the merchant's own keys (falls back to tenant or CloudPay keys)](https://docs.cloudpay.africa/api-reference/merchant-rails/remove-the-merchants-own-keys-falls-back-to-tenant-or-cloudpay-keys.md) - [List collections (payment attempts), newest first](https://docs.cloudpay.africa/api-reference/merchant-rails/list-collections-payment-attempts-newest-first.md): Every collection is one prompt or charge sent to the payer, so this is also the attempts list: filter `status=completed` for payment records, or `category` for why attempts failed. Needs `read`. - [Collect from a payer on the merchant's collection rail](https://docs.cloudpay.africa/api-reference/merchant-rails/collect-from-a-payer-on-the-merchants-collection-rail.md): `method`: `stk` (default: an M-Pesa prompt via M-Pesa, SasaPay or a Paystack charge) or `checkout` (Paystack popup; send the payer to `checkout_url`). Whole shillings on M-Pesa/SasaPay. No money moves until the rail confirms: poll `GET .../collections/{id}`. A cashier collects into their own till on… - [How collections went over a window](https://docs.cloudpay.africa/api-reference/merchant-rails/how-collections-went-over-a-window.md): Totals, success rate, why attempts failed, attempts per day (Africa/Nairobi) and per provider. Default window: the last 30 days. A cashier sees their own till. Needs `read`. - [One collection](https://docs.cloudpay.africa/api-reference/merchant-rails/one-collection.md) - [Check a waiting collection with the provider again](https://docs.cloudpay.africa/api-reference/merchant-rails/check-a-waiting-collection-with-the-provider-again.md): For a collection still `initiated` or `pending` (e.g. the payer paid but no answer came back). The outcome arrives shortly; read the collection again. A finished collection, or one asked about in the last minute (CloudPay also asks about waiting payments every minute), is returned as it is. Needs `r… - [List disbursements, newest first](https://docs.cloudpay.africa/api-reference/merchant-rails/list-disbursements-newest-first.md) - [Pay a phone (B2C) on the merchant's disbursement rail](https://docs.cloudpay.africa/api-reference/merchant-rails/pay-a-phone-b2c-on-the-merchants-disbursement-rail.md): Custody `platform`: amount + fee are held on the merchant's main account at once (`insufficient_funds` otherwise), committed when the rail confirms, released if it fails. Custody `byok`: paid from the merchant's own provider float; recorded only. Whole shillings. Needs `disburse`. Test environment:… - [How payouts went over a window](https://docs.cloudpay.africa/api-reference/merchant-rails/how-payouts-went-over-a-window.md): Same shape as the collections report; `method` is the payee type. Needs `read`. - [One disbursement](https://docs.cloudpay.africa/api-reference/merchant-rails/one-disbursement.md) - [Bulk collections (1-1000 items)](https://docs.cloudpay.africa/api-reference/merchant-rails/bulk-collections-1-1000-items.md): `kind`: `collections` (needs `collect`) or `disbursements` (needs `disburse`). The whole batch is validated first; a custodial payout batch must be covered by the main balance (amounts + fees) or is refused. Answered 202, then items start in the background, each with its own idempotency key. Track w… - [Bulk disbursements (1-1000 items)](https://docs.cloudpay.africa/api-reference/merchant-rails/bulk-disbursements-1-1000-items.md): `kind`: `collections` (needs `collect`) or `disbursements` (needs `disburse`). The whole batch is validated first; a custodial payout batch must be covered by the main balance (amounts + fees) or is refused. Answered 202, then items start in the background, each with its own idempotency key. Track w… - [A batch with item counts by status](https://docs.cloudpay.africa/api-reference/merchant-rails/a-batch-with-item-counts-by-status.md) ## OpenAPI Specs - [openapi](/openapi.yaml) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.