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

# Rails and networks

> Which provider can prompt which phone, take cards or pay out, and how to choose.

A **rail** is the provider Cloudpay uses to move your money: Safaricom Daraja (`mpesa`), SasaPay (`sasapay`) or Paystack (`paystack`). Each business has one collection rail and one payout rail. Your code doesn't change when the rail changes: you always call the same endpoints, and the response's `provider` and `method` say which rail did the work.

## What each rail can do

| | Daraja (`mpesa`) | SasaPay (`sasapay`) | Paystack (`paystack`) |
| - | - | - | - |
| **Prompt an M-Pesa phone** | ✓ | ✓ | ✓ |
| **Prompt an Airtel Money phone** | — | ✓ | ✓ |
| **Prompt a T-Kash phone** | — | ✓ | — |
| **Card checkout** | — | — | ✓ |
| **Pay out to phones** | M-Pesa | M-Pesa, Airtel, T-Kash | — |
| **Pay out to banks, tills, paybills** | — | ✓ | — |
| `method` in responses | `stk` | `stk` | `charge` (prompt) or `checkout` (card page) |

Ask for a network the rail can't prompt and you get `400 network_unsupported` before anything is sent.

## Prompt a phone on any network

Send `network` with the collection. Leave it out for M-Pesa.

```bash M-Pesa 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-77" }'
```

```bash Airtel Money 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-78" }'
```

```bash T-Kash (SasaPay only) theme={null}
curl -X POST $CLOUDPAY_API/v1/merchants/$MERCHANT_ID/collections \
  -H "Authorization: Bearer $CLOUDPAY_KEY" -H "Content-Type: application/json" \
  -d '{ "msisdn": "0771123456", "network": "tkash", "amount": 50000, "idempotency_key": "order-79" }'
```

The payer approves on their phone in every case, and you [poll](https://docs.cloudpay.africa/concepts/lifecycle.md#polling) the same way. If you let customers pick their network, show only the networks your rail supports: read them from `GET /v1/merchants/{id}/rails` (below) once at start-up.

> [!TIP]
>
> Paystack prompts expire after about 180 seconds. Daraja and SasaPay prompts expire after about a minute on the phone. Keep polling until a final status either way.

## Card checkout (Paystack)

With a Paystack rail in `checkout` or `both` mode, send `method: "checkout"`. The phone number is optional.

```json theme={null}
{ "method": "checkout", "amount": 250000, "email": "jane@example.com", "idempotency_key": "cart-88" }
```

Redirect the payer to the `checkout_url` in the response (it appears while the payment is `initiated` or `pending`), then poll as usual.

## See and change your rails

`GET /v1/merchants/{id}/rails` (scope `read`) shows each service's provider, whether it is enabled and which providers you may choose:

```json theme={null}
[
  { "service": "collection", "enabled": true, "provider": "paystack", "paystack_mode": "charge",
    "eligible_providers": ["mpesa", "paystack", "sasapay"], "custody": "platform" },
  { "service": "disbursement", "enabled": false, "eligible_providers": ["mpesa", "sasapay"] }
]
```

An owner can switch in the dashboard (**Settings → Rails**) or with a key that has the `rails` scope:

```bash theme={null}
curl -X PUT $CLOUDPAY_API/v1/merchants/$MERCHANT_ID/rails/collection \
  -H "Authorization: Bearer $CLOUDPAY_KEY" -H "Content-Type: application/json" \
  -d '{ "provider": "paystack", "paystack_mode": "both" }'
```

`paystack_mode` is `charge` (phone prompts only), `checkout` (card page only) or `both`. With `charge` or `both`, a plain collection prompts the phone; with `checkout` only, it opens a card page.

## Whose provider account?

`custody` says whose account the money passes through:

* `platform`: Cloudpay's own provider accounts. Nothing to set up; this is the default.
* `byok`: your own provider keys (bring your own keys), set under **Settings → Rails** or `PUT /v1/merchants/{id}/credentials/{provider}`. Keys are write-only: Cloudpay never returns them.

## Choosing a rail

| You want | Use |
| - | - |
| M-Pesa only, simplest | Daraja or Paystack |
| M-Pesa and Airtel Money prompts, plus cards | Paystack (`both`) |
| Every network, and payouts to banks, tills and paybills | SasaPay |


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