Customer & Checkout API
Verify a number, or collect through a hosted payment link.
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
Verify a phone number and the wallet behind it before you charge or pay it, and create shareable checkout links when you do not want to build a payment UI yourself.
Verify Number (Account Holder Name)
Returns the registered account holder name and mobile network for any Tanzanian mobile money number. Call it from your own website or app before you pay anyone, and show the name back to your user for confirmation. Our provider credentials stay on our servers — you only ever send your API key.
Use zonmpay.com specifically (without www the request is redirected and some HTTP clients drop the POST body — which causes a server error).
Request Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone | string | Yes | 0773273617, 255773273617 or +255773273617 — all normalised for you.example: 255773273617 |
curl -X POST https://zonmpay.com/api/v1/verify-number \
-H "apiToken: SPP_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"phone":"255773273617"}'Note: Requires the collection:read scope. Payout also accepts expected_name (rejects the payout when it does not match the verified holder) and require_verified_name.
Verify a Customer by Phone Number
Confirm a phone number and the wallet behind it before you charge or pay it. This reduces failed transactions caused by a mistyped number and lets you show the recipient's name back to the payer.
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 |
|---|---|---|---|
| phone | string | Yes | 0712345678, 255712345678 or +255712345678 — all are normalised for you.example: 255712345678 |
curl https://zonmpay.com/api/v1/customer/verify/255712345678 \
-H "apiToken: SPP_live_YOUR_API_KEY"Note: Recognised networks: Vodacom (M-Pesa), Mixx by YAS, Airtel Money, Halotel and TTCL Pesa.
Hosted Checkout (Payment Link)
Create a shareable link and redirect your customer to a ZonmPay-hosted payment page. No frontend code required: we handle the UI and collection, return the customer to your callbackUrl, and send you the usual webhook.
Use zonmpay.com specifically (without www the request is redirected and some HTTP clients drop the POST body — which causes a server error).
Request Body (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
| amount | integer | Yes | Amount in TZS.example: 50000 |
| currency | string | No | Defaults to TZS.example: TZS |
| description | string | No | Shown on the checkout page.example: Order #001 |
| callbackUrl | string | No | Where the customer is returned after paying.example: https://yoursite.com/payment/complete |
| reference | string | No | Your own order id.example: ORDER-001 |
curl -X POST https://zonmpay.com/api/v1/payment/link \
-H "apiToken: SPP_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 50000,
"currency": "TZS",
"description": "Order #001",
"callbackUrl": "https://yoursite.com/payment/complete",
"reference": "ORDER-001"
}'