Docs

Hosted checkout

Your server creates a session. The customer pays on pay.steadipay.ltd. You confirm the result with a webhook or verify.

Create a session

POST /v1/checkout_sessions

Field	Required	Notes
amount	Yes	Kwacha as a string, for example 250 or 250.50. `amount_minor` (tambala) still works.
currency	No	Must be MWK if sent.
merchant_reference	Yes	Your order id. At least 3 characters. Use it to match webhooks.
return_url	Yes	Where we send the customer after a successful payment. Must start with https:// or http://.
cancel_url	No	Optional separate cancel URL.
description	No	Shown on checkout.
customer_email	No	If you already have it.
customer_msisdn	No	Malawi mobile number. We format it.

curl -X POST https://api.steadipay.ltd/v1/checkout_sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "250",
    "currency": "MWK",
    "merchant_reference": "TICKET-8841",
    "description": "389 Tickets · Saturday show",
    "return_url": "https://tickets.example/orders/8841/return"
  }'

Response

{
  "id": "cs_...",
  "amount_minor": "25000",
  "currency": "MWK",
  "merchant_reference": "TICKET-8841",
  "checkout_url": "https://pay.steadipay.ltd/cs_...",
  "expires_at": "2026-09-19T16:00:00.000Z"
}

Redirect the customer to checkout_url. They choose the method. Steadi Pay chooses the provider. You do not pick Airtel vs TNM vs card for them.

POST /v1/payments accepts the same body and returns checkout_url if you already named the route that way.

Read a session

GET /v1/checkout_sessions/:id returns the session and, once they have started paying, the payment_id.

Return URL

return_url must be a web address that starts with https:// or http://. After a successful payment, checkout shows the receipt for five seconds and then sends the customer there. It uses your address exactly as you gave it and adds nothing to it, so put your own order reference in it.

Treat return as “the customer is back”, not “the money is in”. On the return page, look up the payment by merchant reference or payment id and call verify, or wait for the webhook. If the payment fails or expires, checkout shows that and offers a button back to you instead of redirecting.

Checkout page

Hosted checkout is English and Chichewa, works on a small phone, and never asks for a card number. Cards open the bank's hosted page (N-Genius). Mobile money is a push prompt or a pay-by-reference number. Bank is a pay-by-reference number with steps for the customer's own bank. When the customer covers the fees, they see one line called handling fee.