README

Laravel package for integrating with the Paynow Zimbabwe payment API.

Disclaimer: This is an unofficial community package and is not affiliated with or endorsed by Paynow Zimbabwe.

Requirements

• PHP 8.2+
• Laravel 11 or 12
• ext-mbstring

Installation

composer require kajuzi/paynow-laravel

Publish the configuration file:

php artisan vendor:publish --tag=paynow-config

Add your credentials to .env:

PAYNOW_ID=your-integration-id
PAYNOW_KEY=your-integration-key
PAYNOW_RETURN_URL="${APP_URL}/paynow/return"
PAYNOW_RESULT_URL="${APP_URL}/paynow/webhook"
PAYNOW_BASE_URL=https://www.paynow.co.zw/interface

Usage

Web checkout

use Paynow\Facades\Paynow;

$payment = Paynow::createPayment('Invoice 35', 'user@example.com')
    ->addItem('Bananas', 2.50)
    ->addItem('Apples', 3.40);

$response = Paynow::send($payment);

if ($response->success()) {
    return redirect()->away($response->redirectUrl());
    // or: return $response->redirect();
}

Save the poll URL if you want to check payment status later:

$pollUrl = $response->pollUrl();

Per-transaction return URLs

Override config URLs at runtime when you need query parameters on the return URL:

Paynow::setReturnUrl(route('paynow.return', ['order' => $order->id]));
Paynow::setResultUrl(route('paynow.webhook'));

Mobile express (EcoCash / OneMoney)

use Paynow\Enums\MobileMoneyMethod;
use Paynow\Facades\Paynow;

$payment = Paynow::createPayment('Invoice 35', 'user@example.com')
    ->addItem('Sadza and Beans', 1.25);

$response = Paynow::sendMobile($payment, '0777777777', MobileMoneyMethod::Ecocash);

if ($response->success()) {
    $instructions = $response->instructions();
    $pollUrl = $response->pollUrl();
}

Poll transaction status

$status = Paynow::poll($pollUrl);

if ($status->paid()) {
    // Payment completed
}

Webhook handling

Define your own route and verify the callback with the package:

use Illuminate\Http\Request;
use Paynow\Facades\Paynow;

Route::post('/paynow/webhook', function (Request $request) {
    $status = Paynow::processWebhook($request);

    if ($status->paid()) {
        // Fulfill the order
    }

    return response('OK', 200);
});

The webhook handler always verifies the Paynow hash using POST body fields only (query parameters are ignored).

Dependency injection

You can also inject the client contract directly:

use Paynow\Contracts\PaynowClient;

public function checkout(PaynowClient $paynow)
{
    $payment = $paynow->createPayment('Invoice 35', 'user@example.com')
        ->addItem('Bananas', 2.50);

    return $paynow->send($payment);
}

Migration from paynow/php-sdk (Paynow's Official SDK)

Example migration:

// Before
$paynow = new Paynow\Payments\Paynow($id, $key, $returnUrl, $resultUrl);
$payment = $paynow->createPayment('Invoice 35', 'user@example.com');
$payment->add('Bananas', 2.50);
$response = $paynow->send($payment);
$response->redirect();

// After
$payment = Paynow::createPayment('Invoice 35', 'user@example.com')
    ->add('Bananas', 2.50);
$response = Paynow::send($payment);
return $response->redirect();

Behavioral notes

• Outbound request hashes use the same field order and SHA-512 algorithm as the legacy SDK.
• Init/poll responses verify the hash when present; webhooks always require a valid hash.
• amount() returns -1.0 when missing, matching legacy behavior.
• Unknown status values are returned as lowercased strings (not forced into an enum).

Testing

composer install
./vendor/bin/phpunit

License

This package is open-source software licensed under the MIT license.