zenopay/zenopay-php

A PHP package for ZenoPay payment processing.

v1.0.0 2024-07-24 16:06 UTC

MIT

README

Here's a polished and structured README.md for your ZenoPay PHP Integration GitHub project:

# ZenoPay PHP Integration

> A simple PHP client for ZenoPay Mobile Money Tanzania API  
> Create payment orders, check status, and handle webhooks with ease.

---

## Table of Contents

- [Features](#features)  
- [Prerequisites](#prerequisites)  
- [Installation](#installation)  
- [Configuration](#configuration)  
- [Usage](#usage)  
  - [1. Create Order](#1-create-order)  
  - [2. Check Order Status](#2-check-order-status)  
  - [3. Handle Webhook Notifications](#3-handle-webhook-notifications)  
- [Error Logging](#error-logging)  
- [Support](#support)  

---

## Features

✅ Create Mobile Money payment orders in Tanzania  
✅ Check transaction/order status  
✅ Handle webhook callbacks for status updates  
✅ Log errors and webhook payloads  

---

## Prerequisites

- PHP 7.0+  
- cURL extension enabled  
- Write permissions in project directory (for log files)

---

## Installation

```bash
git clone https://github.com/your-username/zenopay-php-client.git
cd zenopay-php-client

Configuration

Create a file named config.php in the root directory:

<?php
// config.php

// Your ZenoPay API key
define('ZP_API_KEY', 'YOUR_API_KEY_HERE');

// Base URL for ZenoPay endpoints
define('ZP_BASE_URL', 'https://zenoapi.com/api/payments');

Usage

1. Create Order

Save as create_order.php:

<?php
require 'config.php';

$orderData = [
    'order_id'    => uniqid('', true),
    'buyer_email' => '[e-mail]',
    'buyer_name'  => 'John Doe',
    'buyer_phone' => '0744963858', // Tanzanian format
    'amount'      => 1000,         // Amount in TZS
    'webhook_url' => 'https://your-domain.com/webhook', // Optional
];

$ch = curl_init(ZP_BASE_URL . '/mobile_money_tanzania');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'x-api-key: ' . ZP_API_KEY,
    ],
    CURLOPT_POSTFIELDS     => json_encode($orderData),
]);

$response = curl_exec($ch);
if ($response === false) {
    file_put_contents('error_log.txt', date('[Y-m-d H:i:s] ') . 'cURL Error: ' . curl_error($ch) . PHP_EOL, FILE_APPEND);
    exit('Request failed. Check error_log.txt');
}

$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode !== 200) {
    file_put_contents('error_log.txt', date('[Y-m-d H:i:s] ') . "HTTP Error: {$httpCode} - {$response}" . PHP_EOL, FILE_APPEND);
    exit("HTTP {$httpCode}: {$response}");
}

$data = json_decode($response, true);
if ($data['status'] === 'success') {
    echo "✅ Order created! Order ID: {$data['order_id']}\n";
} else {
    echo "❌ Error: {$data['message']}\n";
}

Sample Success Response:

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

2. Check Order Status

Save as check_status.php:

<?php
require 'config.php';

$orderId = '3rer407fe-3ee8-4525-456f-ccb95de38250';

$url = ZP_BASE_URL . '/order-status?order_id=' . urlencode($orderId);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'x-api-key: ' . ZP_API_KEY,
    ],
]);

$response = curl_exec($ch);
if ($response === false) {
    exit('cURL Error: ' . curl_error($ch));
}

$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode !== 200) {
    exit("HTTP {$httpCode}: {$response}");
}

$data = json_decode($response, true);
if (!empty($data['data']) && $data['result'] === 'SUCCESS') {
    foreach ($data['data'] as $order) {
        echo "🔎 Order ID: {$order['order_id']}\n";
        echo "   Status: {$order['payment_status']}\n";
        echo "   Amount: {$order['amount']} TZS\n";
        echo "   Reference: {$order['reference']}\n";
    }
} else {
    echo "❌ Error: {$data['message']}\n";
}

3. Handle Webhook Notifications

Save as webhook.php:

<?php
require 'config.php';

if ($_SERVER['HTTP_X_API_KEY'] !== ZP_API_KEY) {
    http_response_code(403);
    exit('Invalid API key');
}

$payload = file_get_contents('php://input');

file_put_contents(
    'weblogs.txt',
    date('[Y-m-d H:i:s] ') . $payload . PHP_EOL,
    FILE_APPEND
);

$data = json_decode($payload, true);

// Example payload:
// {
//   "order_id":"677e43274d7cb",
//   "payment_status":"COMPLETED",
//   "reference":"1003020496",
//   "metadata":{
//     "product_id":"12345",
//     "color":"blue",
//     "size":"L",
//     "custom_notes":"Please gift-wrap this item."
//   }
// }

// TODO: update your DB, send email, etc.

http_response_code(200);
echo 'OK';

Error Logging

• error_log.txt: Stores cURL and HTTP errors
• weblogs.txt: Stores raw webhook payloads

Ensure these files are writable by the web server.

Support

Need help? Contact us:

📧 Email: [e-mail] 🌐 Website: https://zenoapi.com 🐛 GitHub Issues: Open an issue

Built by ZenoPay · Simplifying Digital Payments in Tanzania 🇹🇿

---