Skip to main content
POST
Pay a mobile money number

Authorizations

Authorization
string
header
required

Your API key: sk_live_… / sk_test_… (secret), pk_live_… / pk_test_… (publishable, read-only reference data) or rk_live_… / rk_test_… (payments only).

Headers

Idempotency-Key
string
required

A new value for every new request (a UUID is ideal), up to 64 characters. If your request times out, send it again with the same key. The same key for a different request returns 422 idempotency_key_reused.

Maximum string length: 64
Example:

"3c9a7e1f2b6d4a8e9f0c1b2a3d4e5f60"

Body

application/json
amount
number
required

MWK, at most 2 decimal places.

Example:

25000

currency
enum<string>
required
Available options:
MWK
provider
enum<string>
required
Available options:
airtel,
tnm
phone
string
required

The recipient's Malawi number.

Example:

"+265991234567"

recipientName
string

For your records and the payout description.

Example:

"Chikondi Banda"

reference
string

Your own reference. It can be paid once, unless the earlier payout failed.

Maximum string length: 100
Example:

"INV-2041"

description
string
Maximum string length: 140

Response

A repeat of the same payout. The header Idempotent-Replayed is true. It is never paid twice.

reference
string
Example:

"PO-8d3f0c1e6b2a4f7e9c5d1a3b7e2f4c6d"

type
enum<string>
Available options:
mobile_money,
bank
status
enum<string>
Available options:
processing,
success,
failed,
reversed
amount
number
fee
number
levy
number
currency
string
Example:

"MWK"

merchantReference
string | null

Your own reference.

description
string
recipient
object

{ provider, phone } for mobile money, { bankName, accountLast4, accountName } for a bank account.

providerReference
string | null
failureCode
string | null
Example:

null

createdAt
string<date-time>
completedAt
string<date-time> | null