Transaction Status API
Verify, poll and retry a payment by reference.
Authentication
Every request is authenticated with your secret key in the apiToken header. There is one base URL and one key: your account behaves as a sandbox until go-live is approved, on the same URL. Keep the key server-side only, and note that rotating it expires the previous one immediately.
Required Headers
apiToken
sp_sk_prod_XXXXXXXXXXXX
Content-Type
application/json
Overview
Treat SUCCESSFUL, PAID, FAILED, REJECTED, CUSTOMER_REJECTED and CANCELLED as terminal; anything else can still change. Use webhooks first. If you must poll, use GET /api/v1/payment/reference/{reference} no more than once every 10 seconds and stop after 5 minutes.
Verify Payment Status
Verifies the status of a payment using its reference code. Same data as the reference lookup, with the status confirmed against the operator before it answers.
Use zonmpay.com specifically (without www the request is redirected and some HTTP clients drop the POST body — which causes a server error).
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| reference | string | Yes | The payment reference to verify.example: SP008985 |
curl https://zonmpay.com/api/v1/payment/verify/SP008985 \
-H "apiToken: SPP_live_YOUR_API_KEY"Get Payment by Reference
Poll-based status check, for when your webhook is unreachable. Use it no more than once every 10 seconds and stop after 5 minutes: a collection that has not resolved within the 90-second USSD window is not going to resolve because you asked again.
Use zonmpay.com specifically (without www the request is redirected and some HTTP clients drop the POST body — which causes a server error).
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| reference | string | Yes | The ZonmPay reference returned when you created the payment.example: SP008985 |
curl https://zonmpay.com/api/v1/payment/reference/SP008985 \
-H "apiToken: SPP_live_YOUR_API_KEY"Note: feeAmount, feePercent and netAmount are omitted entirely on older payments. Read them with a null check, not a falsy check — an absent feeAmount is not the same as a fee of zero.
Retry Collection
Retries a previously failed or pending collection using its reference, re-sending the prompt to the same customer without creating a new payment.
Use zonmpay.com specifically (without www the request is redirected and some HTTP clients drop the POST body — which causes a server error).
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| reference | string | Yes | The collection reference to retry.example: SP008985 |
curl https://zonmpay.com/api/v1/payment/retry/SP008985 \
-H "apiToken: SPP_live_YOUR_API_KEY"Transaction Statuses
PENDING
Created, but the customer has not acted yet: the push is waiting for a PIN, or a link has not been opened.
Action: Wait. Collection only.
PROCESSING
Dispatch is in flight inside ZonmPay.
Action: Wait — no webhook fires on this state.
PROCESSED
Handed to the operator, who accepted it and will call back with the final outcome.
Action: Wait for the final webhook.
AWAITING_APPROVAL
Payout created and waiting for approval. No money has moved.
Action: Approve it with POST /api/v2/payment/approve.
APPROVED
Approved and debited from your wallet; being dispatched.
Action: Wait for payout.confirmed or payout.failed.
SUCCESSFUL
Completed. Money has moved.
Action: Terminal — fulfil the order.
PAID
The requested amount has been received in full.
Action: Terminal — collection only.
PARTIAL
Some of the amount has been paid. Compare paidAmount with amount.
Action: FLEXIBLE collections only. Keep waiting for the balance.
FAILED
Could not complete. failureReason says why. A failed payout is refunded automatically.
Action: Terminal — retry with a new reference.
CUSTOMER_REJECTED
The customer declined the prompt.
Action: Terminal.
REJECTED
Rejected by ZonmPay or the operator before reaching the customer.
Action: Terminal — read the message.
CANCELLED
Cancelled before completion.
Action: Terminal.