Docs
Payments
List, retrieve and verify payments. Fulfil only when status is Paid. Steadi Pay never marks success without a verified provider confirmation.
Statuses
| status | What you show |
|---|---|
| created | Ready to pay |
| pending | Waiting for the customer to approve |
| processing | Waiting for confirmation from the network |
| succeeded | Paid |
| failed | Not completed, no money was taken |
| expired | This payment expired, no money was taken |
| reversed | Returned to the customer |
Use status_text in the JSON if you want the same wording we show on checkout.
Verify
GET /v1/payments/:id and GET /v1/payments/:id/verify both refresh the provider status, then return the payment. Use verify after the customer returns to your site.
curl https://api.steadipay.ltd/v1/payments/pay_.../verify \
-H "Authorization: Bearer sk_test_..."List
GET /v1/payments?q= searches your merchant reference and payment id in the key's environment (sandbox or live).
Payment object
{
"id": "pay_...",
"status": "succeeded",
"status_text": "Paid",
"merchant_reference": "TICKET-8841",
"method": "mobile_money",
"wallet": "airtel",
"environment": "sandbox",
"currency": "MWK",
"order_amount_minor": "25000",
"gross_amount_minor": "25650",
"merchant_amount_minor": "25000",
"fee_amount_minor": "650",
"fee_bearer": "customer",
"msisdn": "26599****321",
"provider_ref": "mock_...",
"return_url": "https://your.app/return",
"created_at": "2026-09-19T12:01:00.000Z",
"succeeded_at": "2026-09-19T12:01:22.000Z"
}Amounts on the payment are stored as integer tambala and returned as strings. Phone numbers are masked. order_amount_minor is the sale and gross_amount_minor is what the customer paid. When the customer covers the fees, fee_amount_minor is the combined handling fee they paid on top of the sale: the operator's fee and Steadi Pay's fee added together. merchant_amount_minor is what the merchant receives. Steadi Pay never deducts a fee from a payout.
Refunds
POST /v1/refunds with payment_id and amount in kwacha. Only a payment that is Paid can be returned, and only after the provider confirms the original collection.
Webhook events for success and failure are on Webhooks.