Introduction

This document provides the complete technical reference for ZenoPay's Mobile Money Payments API for Tanzania. It covers all endpoints, request/response formats, and webhook implementations.

Authentication

All API requests require authentication via an API key sent in the request header:

x-api-key: YOUR_API_KEY

Note: Replace YOUR_API_KEY with the key provided in your ZenoPay dashboard.

Base URL

The base URL for all API endpoints is:

https://zenoapi.com

All endpoint paths are relative to this base URL.

POST 1. Initiate Mobile Money Payment

Initiate a mobile money payment transaction via USSD push.

Endpoint

/api/payments/mobile_money_tanzania

Request Parameters

Example Request

{
  "order_id": "3rer407fe-3ee8-4525-456f-ccb95de38250",
  "buyer_email": "customer@example.com",
  "buyer_name": "John Joh",
  "buyer_phone": "0744963858",
  "amount": 1000,
  "webhook_url": "https://yourdomain.com/webhook"
}

Responses

Success Response (200 OK)

{
  "status": "success",
  "resultcode": "000",
  "message": "Request in progress. You will receive a callback shortly",
  "order_id": "3rer407fe-3ee8-4525-456f-ccb95de38250"
}

Error Responses

GET 2. Check Order Status

Check the current status of a payment order.

Endpoint

/api/payments/order-status?order_id={order_id}

Query Parameters

Example Request

curl -X GET "https://zenoapi.com/api/payments/order-status?order_id=3rer407fe-3ee8-4525-456f-ccb95de38250" \
-H "x-api-key: YOUR_API_KEY"

Success Response (200 OK)

{
  "reference": "0936183435",
  "resultcode": "000",
  "result": "SUCCESS",
  "message": "Order fetch successful",
  "data": [
    {
      "order_id": "3rer407fe-3ee8-4525-456f-ccb95de38250",
      "creation_date": "2025-05-19 08:40:33",
      "amount": "1000",
      "payment_status": "COMPLETED",
      "transid": "CEJ3I3SETSN",
      "channel": "MPESA-TZ",
      "reference": "0936183435",
      "msisdn": "255744963858"
    }
  ]
}

Response Fields

Webhook Notifications

ZenoPay can send automatic notifications to your server when payment status changes to COMPLETED.

Setup Instructions

1. Include the webhook_url parameter in your payment initiation request
2. Ensure your endpoint is publicly accessible via HTTPS
3. Implement verification of the x-api-key header
4. Return HTTP 200 OK response to acknowledge receipt

Example Payment Request with Webhook

{
  "order_id": "3rer407fe-3ee8-4525-456f-ccb95de38250",
  "buyer_email": "customer@example.com",
  "buyer_name": "John Joh",
  "buyer_phone": "0744963858",
  "amount": 1000,
  "webhook_url": "https://yourdomain.com/webhook"
}

Webhook Payload

When a payment status changes to COMPLETED, ZenoPay will POST a JSON payload to your webhook URL.

Headers

x-api-key: YOUR_API_KEY
Content-Type: application/json

Payload Example

{
  "order_id": "677e43274d7cb",
  "payment_status": "COMPLETED",
  "reference": "1003020496",
  "metadata": {}
}

Payload Fields

Support & Resources

Get help with integration, troubleshooting, and account management through our comprehensive support channels.

Support Channels

Common Integration Issues

Implementation Guides

• Guzzle Implementation - Recommended for modern PHP applications
• cURL Implementation - For systems without Composer
• Native PHP Implementation - Basic implementation without dependencies

Additional Resources

• ZenoPay Website - Official ZenoPay website
• ZenoPay GitHub Repository - Official GitHub page for various ZenoPay repositories
• Quickstart - Guzzle Documentation - A quick introduction to Guzzle and introductory examples.
• Webhook Best Practices - How to properly implement and secure webhooks

Isaiah's Integration Tip

API Developer & Documentation Author

When debugging API issues, I always recommend including these in your support requests:

• Test API key (mask the first few characters for security)
• Request samples (both successful and failing ones)
• Timestamps in UTC format
• Expected vs actual behavior

This helps me reproduce and resolve issues much faster. Feel free to follow me on LinkedIn!