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

# Paystack

> M-Pesa and Airtel Money prompts and card payments through Paystack, on Cloudpay's account or your own.

Paystack is one of Cloudpay's collection rails. It can:

* **Prompt a phone** (`charge`): an M-Pesa or Airtel Money prompt, fully server side. The payer never sees Paystack.
* **Take a card** (`checkout`): a Paystack payment page for cards and mobile money.

It can't pay out; use Daraja or SasaPay for payouts. See [Rails and networks](https://docs.cloudpay.africa/guides/rails.md) for the full comparison.

## Turn it on

**Settings → Rails → Collection → Paystack**, and choose the mode:

| `paystack_mode` | A collection without `method` | `method: "checkout"` |
| - | - | - |
| `charge` | Prompts the phone | Refused |
| `checkout` | Opens a card page | Opens a card page |
| `both` | Prompts the phone | Opens a card page |

## Collect

```bash M-Pesa prompt theme={null}
curl -X POST $CLOUDPAY_API/v1/merchants/$MERCHANT_ID/collections \
  -H "Authorization: Bearer $CLOUDPAY_KEY" -H "Content-Type: application/json" \
  -d '{ "msisdn": "0712345678", "amount": 50000, "idempotency_key": "order-90" }'
```

```bash Airtel Money prompt theme={null}
curl -X POST $CLOUDPAY_API/v1/merchants/$MERCHANT_ID/collections \
  -H "Authorization: Bearer $CLOUDPAY_KEY" -H "Content-Type: application/json" \
  -d '{ "msisdn": "0733123456", "network": "airtel", "amount": 50000, "idempotency_key": "order-91" }'
```

```bash Card page theme={null}
curl -X POST $CLOUDPAY_API/v1/merchants/$MERCHANT_ID/collections \
  -H "Authorization: Bearer $CLOUDPAY_KEY" -H "Content-Type: application/json" \
  -d '{ "method": "checkout", "amount": 250000, "email": "jane@example.com", "idempotency_key": "cart-88" }'
```

Responses show `provider: "paystack"` and `method: "charge"` or `"checkout"`. For a card page, send the payer to `checkout_url`. Then [poll](https://docs.cloudpay.africa/concepts/lifecycle.md#polling) or listen with [webhooks](https://docs.cloudpay.africa/guides/webhooks.md). Paystack gives the payer about **180 seconds** to approve a prompt.

T-Kash isn't on Paystack: `network: "tkash"` returns `400 network_unsupported`.

## Cloudpay's account or your own

| | Cloudpay's Paystack account (default) | Your own Paystack account (BYOK) |
| - | - | - |
| Setup | Nothing | Add your keys, paste one webhook URL |
| Money lands | In your Cloudpay balance | In your Paystack balance |
| `custody` | `platform` | `byok` |

### Using your own keys

**1. Add your keys**

**Settings → Rails → Your own provider keys → Paystack → Use your own keys**: your **secret key** and **public key** from Paystack's dashboard (**Settings → API Keys & Webhooks**). Use `sk_live_` / `pk_live_` keys: Production refuses test keys. Keys are stored encrypted and never shown again.

**2. Paste Cloudpay's webhook URL into Paystack**

Copy the Paystack address from **Settings → Webhooks → Cloudpay IPN addresses** (or `GET /v1/merchants/{id}/ipn-urls`), for example:

```text theme={null}
https://api.cloudpay.africa/rails/ipn/paystack
```

In Paystack: **Settings → API Keys & Webhooks → Live Webhook URL**, paste it, and save.

**3. Send one small live payment**

Prompt your own phone for KES 10 and check it's `completed`.

> [!WARNING]
>
> Paystack allows **one** webhook URL per account. If another system already uses yours, pasting Cloudpay's address takes those notifications away from it. Payments still settle without it (Cloudpay asks Paystack about waiting payments every minute), just more slowly.

Cloudpay checks each Paystack notification's signature with the secret key of the payment it is about, and then confirms the payment with Paystack before marking it paid, so a forged notification can't mark anything paid.

## In Development

Development (`sk_test_` Cloudpay keys) always uses Cloudpay's own provider accounts, whatever keys you've added, with real prompts up to KES 100. Your own Paystack keys take effect in Production.


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