Quick start
- Log in to Zivo and open Settings.
- Open ZivoPay API and generate a dedicated API key.
- Save the key securely. It is shown only once.
- Create an invoice with customer details and line items.
- Send the hosted invoice link over WhatsApp or trigger M-Pesa STK push.
- Check invoice and payment status from your own system.
ZivoPay API answers
Quick answers for teams connecting orders, service calls, bookings, or balances to ZivoPay invoice and M-Pesa collection workflows.
What can the ZivoPay API do?
The ZivoPay API lets an external system create invoices, send hosted payment links on WhatsApp, trigger M-Pesa STK push, and check invoice or payment status.
Can I create invoices from my own system?
Yes. Send customer details and line items to the invoice endpoint. Zivo returns an invoice number, balance, status, and public payment URL.
Can ZivoPay send the payment link on WhatsApp?
Yes. After creating an invoice, call the send endpoint to deliver the hosted payment link through the connected Zivo WhatsApp workspace.
Can I trigger M-Pesa STK push?
Yes. Use the STK endpoint to request payment for the invoice balance or a partial amount.
Which API key should I use?
Use the dedicated ZivoPay API key generated in Settings > ZivoPay API. Existing shared Zivo API keys remain supported for older integrations.
Authentication
Every request needs your Zivo partnerID and ZivoPay API key. Send the key as a Bearer token or as an apikey field.
| Field | Required | Description |
|---|---|---|
partnerID |
Yes | Your Zivo business ID, shown in Settings > ZivoPay API. |
apikey |
Yes | Your generated ZivoPay API key, such as zivopay_live_xxxxx. You may also send it as a Bearer token. |
workspace_id |
No | Use this when a business has more than one Zivo workspace. If omitted, Zivo uses the default workspace. |
Authorization: Bearer zivopay_live_xxxxx
Content-Type: application/json
{
"partnerID": "1376"
}Create invoice
Create a hosted ZivoPay invoice with a public payment URL and line items.
curl -X POST "https://zivo.co.ke/api/zivo/zivopay/invoices" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer zivopay_live_xxx" \
-d '{
"partnerID": "1376",
"workspace_id": 12,
"customer_name": "Solomon",
"phone": "254742097330",
"external_id": "ORDER-10045",
"items": [
{ "description": "Starlink wall mount stand", "quantity": 1, "unit_price": 12500 }
],
"notes": "Delivery after payment confirmation"
}'Response
{
"ok": true,
"invoice": {
"invoice_number": "ZV-12-260715-AB123",
"external_id": "ORDER-10045",
"amount": 12500,
"paid_amount": 0,
"balance": 12500,
"status": "pending",
"public_url": "https://zivo.co.ke/zchat/pay/..."
}
}Request fields
| Field | Required | Description |
|---|---|---|
customer_name |
Yes | Name shown on the invoice and in payment context. |
phone |
Yes | Customer phone in international format, such as 2547.... |
items |
Yes | One or more invoice lines. Each item needs description and unit_price; quantity defaults to 1. |
external_id |
No | Your own order, booking, job, or account reference. |
List invoices
Return recent invoices for a workspace. Filter by status, search text, and limit.
curl "https://zivo.co.ke/api/zivo/zivopay/invoices?partnerID=1376&workspace_id=12&status=paid&limit=25" \
-H "Authorization: Bearer zivopay_live_xxx"Send payment link
Send the hosted invoice link to the customer through the connected Zivo WhatsApp workspace. The invoice can be referenced by ID, invoice number, or external ID.
curl -X POST "https://zivo.co.ke/api/zivo/zivopay/invoices/ZV-12-260715-AB123/send" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer zivopay_live_xxx" \
-d '{
"partnerID": "1376",
"phone": "254742097330"
}'Trigger STK push
Start an M-Pesa STK push for the invoice balance or a partial amount.
curl -X POST "https://zivo.co.ke/api/zivo/zivopay/invoices/ZV-12-260715-AB123/stk-push" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer zivopay_live_xxx" \
-d '{
"partnerID": "1376",
"amount": 12500,
"phone": "254742097330"
}'Invoice status
Return invoice status, balance, public URL, line items, timestamps, and payment progress.
curl "https://zivo.co.ke/api/zivo/zivopay/invoices/ZV-12-260715-AB123?partnerID=1376" \
-H "Authorization: Bearer zivopay_live_xxx"{
"ok": true,
"invoice": {
"invoice_number": "ZV-12-260715-AB123",
"amount": 12500,
"paid_amount": 12500,
"balance": 0,
"status": "paid",
"public_url": "https://zivo.co.ke/zchat/pay/..."
}
}Payment status
Look up a recorded payment by payment ID or M-Pesa receipt number.
curl "https://zivo.co.ke/api/zivo/zivopay/payments/RG123ABC?partnerID=1376" \
-H "Authorization: Bearer zivopay_live_xxx"Webhook events
Inspect recent M-Pesa/ZivoPay webhook processing events for reconciliation and support.
curl "https://zivo.co.ke/api/zivo/zivopay/webhook-events?partnerID=1376&workspace_id=12&status=failed" \
-H "Authorization: Bearer zivopay_live_xxx"API activity
Review recent API calls with request IDs, HTTP status, endpoint, source IP, and error message.
curl "https://zivo.co.ke/api/zivo/zivopay/api-events?partnerID=1376&workspace_id=12&limit=50" \
-H "Authorization: Bearer zivopay_live_xxx"Errors
ZivoPay returns JSON errors with an HTTP status code and a readable message.
| Status | Meaning | What to check |
|---|---|---|
401 |
Invalid credentials | Confirm partnerID and the ZivoPay API key from Settings > ZivoPay API. |
422 |
Validation failed | Check required fields such as customer name, phone, and invoice items. |
423 |
Billing paused | The Zivo tenant may be suspended or cancelled until billing is resolved. |