Skip to main content
POST
Pay a phone (B2C) on the merchant's disbursement rail

Authorizations

Authorization
string
header
required

A merchant-scoped API key, issued by CloudPay staff or the merchant's owner. Acts with exactly its scopes.

Path Parameters

merchantID
string<uuid>
required

Body

application/json

Give msisdn (an M-Pesa phone) or payee (400 payee_unsupported when the merchant's rail can't reach it).

amount
integer<int64>
required

Cents, whole shillings, KES 1 to 250,000.

idempotency_key
string
required
Required string length: 8 - 100
msisdn
string
Example:

712345678

payee
object

Where a payout goes. M-Pesa rails pay M-Pesa phones only; SasaPay pays phones on M-Pesa, Airtel and T-Kash, bank accounts (bank_code from GET /v1/merchants/{merchantID}/banks), M-Pesa tills and paybills.

reference
string
Maximum string length: 100
narrative
string
Maximum string length: 100
pin
string

Required when a person (bearer session) sends money: their PIN, re-checked with lockout (403 pin_required, 401 invalid_pin). API keys omit it. Never stored.

Pattern: ^[0-9]{4}$

Response

Replay of the same idempotency key.

status
object
required
data
object