Skip to main content
This guide takes a mobile money payment in the sandbox: you ask a customer’s number to pay, then check the result. It uses curl, so there is nothing to install.

​
Before you begin

  • A PrimePay account. Sign up on the dashboard.
  • A test secret key (sk_test_…) from your account’s API keys page.
  • A webhook endpoint added under Settings › Webhooks: a public https:// address on your server where PrimePay sends payment results. A payment is refused with webhook_url_required until you have one.
Keep secret keys on your server. Never put one in a mobile app, a web page or a public repository.

​
Take a test payment

1

List the operators

Each mobile money operator has an id. You send that id as provider when you create a payment.
Copy the refId of Airtel Money or TNM Mpamba from the response.
2

Create the payment

Send the amount, the customer’s number, the operator and your own order number. The Idempotency-Key makes a retry safe: the same key never charges twice.
You get 202 Accepted with a reference and "status": "processing". On the live API the customer now sees a PIN prompt on their phone. In the sandbox any number pays, and the payment finishes on its own about 3 seconds later.
3

Check the result

Use the reference from the last step.
When status is success, the payment is complete and you can hand over the goods.
Never treat a timeout or an error as a failed payment. Check the payment’s status, or wait for the webhook, before you decide.

​
Next steps

Payments

Every field, the payment statuses and refunds.

Webhooks

Receive results and check their signature.

Testing in sandbox

What the sandbox does and doesn’t cover.

Payment links

Take payments without building a checkout.
Need help? Visit primepay.mw/help.