Transfers - PrimePay

A transfer moves money from the account that owns the API key to another PrimePay account. The money stays inside PrimePay, so a transfer is instant and final: it either succeeds straight away or is refused, never pending.

You want to send to	Endpoint
One of your own accounts, or another merchant’s account	`POST /v1/transfers/merchant-account`
A PrimePay wallet (by phone number)	`POST /v1/transfers/wallet`
An Airtel Money or TNM Mpamba number, or a bank account	Payouts

Only the available balance can be sent (not money still pending settlement). Transfers need a full secret key; payments-only keys are refused. Always show your user the recipient’s name before sending. Look it up first with the merchant account or wallet recipient endpoint.

Limits and fees

Transfer	Most per transfer	Fee
Between your own accounts	No limit	Free
To another merchant’s account	MWK 5,000,000	Free
To a PrimePay wallet	MWK 1,000,000	Free

PrimePay can change limits and fees. Any fee is paid by the sender on top of the amount and shown in the response as fee; the receiver always gets amount.

Transfer errors

Code	HTTP	Meaning
`idempotency_key_required`	400	Send an `Idempotency-Key` header (up to 64 characters).
`idempotency_key_reused`	422	That key was already used for a different transfer.
`invalid_amount`	400	Zero, negative or more than 2 decimal places.
`amount_over_limit`	400	Above the per-transfer limit for that kind of transfer.
`insufficient_funds`	400	Your available balance doesn’t cover the amount and any fee.
`recipient_not_found`	404	No active account with that code.
`recipient_type_mismatch`	400	`recipientType` doesn’t match the account’s owner. Check the code.
`invalid_phone`	400	Not a Malawi number.
`wallet_not_found`	404	No PrimePay wallet on that number.
`wallet_inactive`	400	That wallet can’t receive money right now.
`transfer_not_allowed`	403	This account type can’t make that transfer (for example, agent tills).
`sandbox_recipient_not_allowed`	400	In sandbox, transfers can only go to your own sandbox accounts, a test merchant account or a test wallet.
`account_not_ready`	409	Your account can’t send transfers yet. Contact PrimePay support.