README

A fluent, elegant, and extensible PHP SDK for integrating with Pesapal API 3.0. Designed with SOLID principles to provide a clean and intuitive developer experience.

Features

• Fluent Interface: Chain methods for a readable and expressive syntax.
• Automatic Token Management: Handled internally; you never have to worry about expiring tokens.
• Environment Switching: Seamless toggle between Sandbox and Live environments.
• Object-Oriented: Uses OrderData and BillingAddress objects to structure your data.
• PSR-Compliant: Built for modern PHP applications.

Installation

Install via Composer:

composer require levizwannah/pesapal-sdk-php

Configuration

Initialize the SDK with your credentials. You can pass these directly or load them from your environment variables.

use LeviZwannah\PesapalSdk\Pesapal;

$config = [
    'env' => 'sandbox', // or 'live'
    'key' => 'YOUR_CONSUMER_KEY',
    'secret' => 'YOUR_CONSUMER_SECRET',
];

// Create a new instance
$pesapal = Pesapal::new($config);

Note: when env is set to sandbox, the SDK automatically uses the test URLs. For production, set it to live.

Usage Guide

1. Registering an IPN URL (One-time Setup)

Pesapal API 3.0 requires you to register an Instant Payment Notification (IPN) URL. You must do this before placing any orders. You only need to do this once (or whenever your URL changes).

try {
    $pesapal->registerIpn("https://your-domain.com/ipn-callback", "POST");

    // Check if successful
    if($pesapal->accepted()){
        $ipnId = $pesapal->response()->ipn_id;
        echo "IPN Registered. ID: " . $ipnId;
        // SAVE THIS ID! You need it for every order.
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

2. Processing a Payment

The SDK uses a fluent builder pattern for orders.

Step A: Customer Billing Details

use LeviZwannah\PesapalSdk\BillingAddress;

$billing = (new BillingAddress())
    ->email("john.doe@example.com")
    ->phone("0722000000")
    ->firstName("John")
    ->lastName("Doe")
    ->countryCode("KE");
   // ->city, ->street, etc. are also available

Step B: Order Details

use LeviZwannah\PesapalSdk\OrderData;

$order = (new OrderData())
    ->id("ORD-" . time()) // Your unique Order ID
    ->amount(100.00)
    ->currency("KES")
    ->description("Payment for Order #1234")
    ->callback("https://your-domain.com/payment-callback") // Where user is returned
    ->ipnId($savedIpnId) // The ID you got from Step 1
    ->billingAddress($billing);

Step C: Submit the Order

try {
    $response = $pesapal->order($order);

    if ($pesapal->accepted()) {
        // Success! Redirect the user to Pesapal
        $redirectUrl = $response->response()->redirect_url;
        $orderTrackingId = $response->response()->order_tracking_id;

        // redirect($redirectUrl);
    } else {
        // Handle errors
        $error = $pesapal->error();
        echo "Failed: " . $error->message;
    }

} catch (Exception $e) {
    // Handle SDK or Network errors
    var_dump($e->getMessage());
}

3. Handling the Callback (User Redirect)

When the user returns to your website, Pesapal appends OrderTrackingId and OrderMerchantReference to your callback URL. verify the transaction status immediately.

$trackingId = $_GET['OrderTrackingId'];
$merchantRef = $_GET['OrderMerchantReference'];

$pesapal->status($trackingId);

if ($pesapal->response()->payment_status_description == 'Completed') {
    // Payment Successful!
    // Give value to the user
} elseif ($pesapal->response()->payment_status_description == 'Failed') {
    // Payment Failed
}

4. Handling IPN (Server-to-Server)

Pesapal will hit your registered IPN URL asynchronously to update the status. You must acknowledge this request.

// In your IPN script (e.g., ipn.php)

// 1. Get the data
$trackingId = $_GET['OrderTrackingId'];
$notificationType = $_GET['OrderNotificationType'];

// 2. Verify status from Pesapal (Security Best Practice)
$pesapal->status($trackingId);
$status = $pesapal->response()->payment_status_description;

// 3. Update your database
if ($status == 'Completed') {
    // Mark order as paid in DB
}

// 4. Acknowledge receipt to Pesapal
// This sends the required JSON response: {"status": 200, ...}
$pesapal->received();

SDK Architecture & Extensibility

This SDK is built with SOLID principles to ensure it is easy to maintain and extend.

Fluent Data Objects

Both OrderData and BillingAddress use the PropertyTrait. This allows you to set any property as a method call or a direct property access.

// Method call (Fluent)
$order->amount(500);

// Direct Access
$order->amount = 500;

The Pesapal Class

The main LeviZwannah\PesapalSdk\Pesapal class acts as a facade for the API. It handles:

• Authentication: It automatically requests and caches the Bearer Token. you never need to call token() manually unless debugging.
• HTTP Client: Uses Guzzle internally for robust HTTP handling.

Response Handling

Every API request updates the $pesapal->response public property.

• $pesapal->response(): Returns the raw object from Pesapal.
• $pesapal->accepted(): Returns true if the API HTTP status was 200.
• $pesapal->error(): Helper to get error details if a request failed.

License

MIT License. Free to use and modify.