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

# Test your integration

> Scenarios to run in Development, and the checklist before you switch to a live key.

Development uses real phones and real prompts (up to KES 100 each), so you test the same paths your customers will take. Run these with an `sk_test_` key and a phone you hold.

## Scenarios

| # | Do this | Expect | Your code should |
| - | - | - | - |
| 1 | Send a KES 10 prompt and approve it | `completed`, with a `receipt` | Fulfil the order once, even if you poll `completed` many times |
| 2 | Send a prompt and press **Cancel** on the phone | `failed`, `failure_category: cancelled` | Offer to try again with a **new** `idempotency_key` |
| 3 | Send a prompt and ignore it | `failed`, `failure_category: timeout` (after a few minutes) | Keep polling from a background job, not the web request |
| 4 | Enter the wrong PIN | `failed`, `failure_category: wrong_pin` | Show a friendly message, not `failure_reason` verbatim |
| 5 | Send the same request twice with the same key | The same `id` both times, and only one prompt | Store the key with the order so retries reuse it |
| 6 | Same key, different `amount` | `409 idempotency_key_reused` | Treat as a bug in your key choice |
| 7 | `amount: 20000` (KES 200) | `400 test_amount_limit` | Nothing: Production allows it |
| 8 | `network: "tkash"` on a Paystack or Daraja rail | `400 network_unsupported` | Hide networks your rail can't prompt (see [Rails](https://docs.cloudpay.africa/guides/rails.md)) |
| 9 | Four prompts to one phone without answering | The fourth is `429 too_many_prompts` | Never loop prompts to the same number |
| 10 | A payout with the test key | `403 live_mode_required` | Expected: payouts only exist in Production |
| 11 | Revoke the key, call again | `401 invalid_api_key` | Alert someone; don't retry |
| 12 | Kill your process right after the `POST`, restart, resend | The original payment comes back | This is why the key must come from your own records |

> [!TIP]
>
> Need a sign-in code for a test account? Request it as usual; in Development the SMS isn't sent, and `123456` is accepted for any code you have requested.

## Go-live checklist

**1. Business approved**

Your business is approved for Production and the dashboard's environment switcher offers **Production**. See [Going live](https://docs.cloudpay.africa/environments.md#going-live).

**2. A live key, stored as a secret**

Create an `sk_live_` key with only the scopes you use (usually `read` and `collect`, plus `disburse` for payouts). Put it in your secret manager, never in code or a client app.

**3. Your code checks the environment**

Every response carries `X-CloudPay-Environment`. Fail loudly if production code ever sees `test`, or a test system sees `live`.

**4. Idempotency keys come from your records**

Order, invoice or payroll-line IDs, never a fresh random value per attempt. Scenarios 5, 6 and 12 pass.

**5. Polling runs in the background**

A job checks `initiated`/`pending` payments until `completed` or `failed`, with backoff, and `review` is treated as "not final yet".

**6. Errors are handled by code**

You branch on `errors.code`, retry only `429`, `5xx` and network errors with the same key, and log the `X-Request-Id` response header so Cloudpay support can find the request. See [Errors](https://docs.cloudpay.africa/errors/overview.md).

**7. Rail matches your customers**

`GET /v1/merchants/{id}/rails` on the live key shows the provider and networks you expect (scenario 8).

**8. One small live payment**

Send KES 10 to your own phone with the live key and see it `completed` and on your statement. Then you're live.


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