Payments

A payment collects money from a customer’s mobile money account into your account. The customer approves it on their phone, so the result arrives later, by webhook: to your endpoints under Settings › Webhooks, or to the payment’s own callbackUrl. You can also check a payment at any time with GET /v1/payments/{reference}.

Operators

Operator	`shortCode`	How the customer approves
Airtel Money	`airtel`	A PIN prompt on their phone
TNM Mpamba	`tnm`	A PIN prompt on their phone
PrimePay Wallet	`primepay_wallet`	In the PrimePay app. In sandbox, use a test wallet number.

Get the operators with GET /mobile-money/operators?country=MW and send an operator’s refId as provider when you create a payment. A publishable key is enough for this call.

How a payment runs

You create the payment

POST /v1/payments/mobile-money with the amount, the customer’s number, the operator and your merchantOrderId. The payment collects into the account that owns the API key.

PrimePay answers 202 Accepted

The response has a reference and "status": "processing". If the operator refuses the request straight away, the answer is 402 with "status": "failed" and a failureCode.

The customer approves on their phone

This can take a few seconds or a couple of minutes.

You get the result

A webhook tells you the payment is success or failed. Hand over the goods only on success.

Never treat a timeout or an error from PrimePay as a failed payment. Check its status first.

Fields

Field	Required	Notes
`amount`	Yes	What your customer owes. Depending on your fee setting, the customer may pay PrimePay’s fee on top.
`currency`	Yes	`MWK`.
`customerPhone`	Yes	International format, `+265` and 9 digits. Must belong to the operator.
`provider`	Yes	An operator `refId` from `GET /mobile-money/operators`.
`merchantOrderId`	Yes	Your order or invoice number, up to 64 characters (letters, digits, `- _ . /`). One active or paid payment per order.
`description`	No	Up to 140 characters.
`email`, `firstName`, `lastName`	No	The customer, for receipts and your records.
`callbackUrl`	No	Sends this payment’s webhooks here as well as to your endpoints. Must be HTTPS, on one of your webhook or allowed callback hosts. Required if you have no webhook endpoint.
`metadata`	No	Your own key/value pairs, echoed back in webhooks.

Payment status

Status	Meaning
`pending`, `processing`	Waiting for the customer or the operator.
`success`	Paid. Final.
`failed`	Declined, or not approved in time. `failureCode` says why. Final.
`expired`, `cancelled`	Never paid. Final.
`reversed`	Paid, then returned.

Check a payment with GET /v1/payments/{reference}, or find the newest payment for an order with GET /v1/payments?merchantOrderId=ORDER-5531.

Collecting for a sub-merchant (aggregators)

Aggregator accounts collect on behalf of sub-merchants linked to them, with POST /v1/sub-merchants/{subMerchantCode}/payments/mobile-money. The body is the same as an ordinary payment, and subMerchantCode is the sub-merchant’s 8-digit account code. The sub-merchant is credited and you keep the fee the sub-merchant agreed to when they accepted your link. That fee can’t be set or changed per payment. Don’t send subMerchantAccountCode or aggregatorFee in the body.

Refunds

POST /v1/payments/{reference}/refunds sends money back to the number that paid, in full or in part. Leave out amount to refund everything still refundable.

Refunds need a full secret key and an Idempotency-Key header. Payments-only keys are refused.
A refund comes out of the payment’s money not yet settled first, then your available balance. PrimePay’s fee isn’t returned.
It is processing until the network answers, then success or failed. A failed refund’s money goes back to your balance.
Several partial refunds are fine until they add up to the payment’s amount.

GET /v1/payments/{reference}/refunds lists a payment’s refunds with refundable (what is left). GET /v1/refunds/{reference} returns one refund.

Payment errors

Code	HTTP	Meaning
`idempotency_key_required` / `idempotency_key_invalid`	400	The `Idempotency-Key` header is missing, or isn’t 8 to 255 characters.
`idempotency_key_reused`	422	That key was already used for a different payment.
`request_in_progress`	409	The first request with that key is still running. Try again shortly.
`invalid_provider`	400	`provider` isn’t an operator id.
`provider_not_supported`	400	That operator isn’t available right now.
`invalid_currency`	400	The operator doesn’t support that currency.
`invalid_phone`	400	The number isn’t in the operator’s country.
`invalid_amount`	400	Zero, negative or more than 2 decimal places.
`amount_too_low` / `amount_too_high`	400	Outside the operator’s limits, counting any fee the customer pays. For sub-merchant payments, also when nothing would be left for the sub-merchant after the fees.
`wallet_not_found` / `wallet_inactive`	400	PrimePay Wallet: no active wallet on that number.
`use_sub_merchant_endpoint`	400	You sent `subMerchantAccountCode` in the body. Use the sub-merchant endpoint instead.
`aggregator_fee_not_allowed`	400	You sent `aggregatorFee`. The agreed fee always applies.
`not_an_aggregator`	403	Only aggregator accounts can collect for a sub-merchant.
`sub_merchant_not_found`	404	No active sub-merchant with that code is linked to your account.
`invalid_callback_url` / `callback_host_not_allowed`	400	`callbackUrl` isn’t HTTPS, or isn’t on your hosts.
`webhook_url_required`	400	Add a webhook endpoint, or send `callbackUrl`.
`duplicate_order`	409	This `merchantOrderId` already has a payment in progress or paid. The response includes its `reference`.

Refund errors

Code	HTTP	Meaning
`payment_not_found`	404	No payment with that reference on this account.
`not_refundable`	400	The payment wasn’t successful, or nothing is left to refund.
`amount_exceeds_refundable`	400	More than what’s left; the response includes `refundable`.
`insufficient_funds`	400	Your balance can’t cover the refund yet.
`idempotency_key_required` / `idempotency_key_reused`	400 / 422	The key is missing, or was already used for a different refund.

Get started

Hosted checkout

Webhooks

Transfers

Payouts

Payment links

Payments

Operators

How a payment runs

Fields

Payment status

Collecting for a sub-merchant (aggregators)

Refunds

Payment errors

Refund errors

​Operators

​How a payment runs

​Fields

​Payment status

​Collecting for a sub-merchant (aggregators)

​Refunds

​Payment errors

​Refund errors

Operators

How a payment runs

Fields

Payment status

Collecting for a sub-merchant (aggregators)

Refunds

Payment errors

Refund errors