Skip to main content
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

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.
The payer approves on their phone in every case, and you poll 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.
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.
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:
An owner can switch in the dashboard (Settings → Rails) or with a key that has the rails scope:
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