hawkiq / laravel-zaincash

v2.0.1 2026-10-11 06:43 UTC

Requires

• firebase/php-jwt: ^7.2

Requires (Dev)

• laravel/pint: *
• orchestra/testbench: *
• pestphp/pest: *
• pestphp/pest-plugin-laravel: *
• phpstan/phpstan: *

MIT

• hawkiq

Published on Packagist.org on 2026-10-11 06:48 UTC

README

About

ZainCash provides a robust payment gateway to transfer money instantly inside Iraq. This package offers a clean and simple integration for Laravel developers, fully upgraded to support the ZainCash Payment Gateway API v2 (featuring OAuth2 authentication, structured JSON payloads, secure token verification, transaction inquiries, and full/partial reversals).

Installation

Require the package via Composer:

composer require hawkiq/laravel-zaincash

Configuration

Publish the configuration file:

php artisan vendor:publish --tag="zaincash"

Environment Variables (.env)

Add your ZainCash v2 client credentials to your .env file:

ZCASH_CLIENT_ID=your_client_id_here
ZCASH_CLIENT_SECRET=your_client_secret_here
ZCASH_LIVE=false
ZCASH_LIVE_URL=api_url_provided_by_zain_cash
ZCASH_LANG=en
ZCASH_CALLBACK_ROUTE=payment.callback

Configuration Options (config/zaincash.php)

Config	Description	Type	Default
client_id	OAuth2 Client ID provided during ZainCash v2 onboarding	string	''
client_secret	OAuth2 Client Secret (also used as the signature key for callbacks)	string	''
live	Environment toggle (true for production, false for UAT test)	bool	false
live_url	Live API url provided by ZainCash when approve your request	string	https://pg-api.zaincash.iq
lang	Language for the payment gateway page (en or ar)	string	en
order_id	Prefix used to tag transactions with your system order IDs	string	hawkiq_zaincash_
redirection_url	Named route name to handle the payment callback response	String	payment.callback

Usage

1. Initiating a Payment

In your controller, you can initialize a transaction using web redirection mode or API payload mode. You can also pass or fluently set the customer's phone number.

use Hawkiq\LaravelZaincash\Services\ZainCash;
use Illuminate\Http\Request;

public function sendPayment()
{
    $zaincash = new ZainCash();

    // Optional: Set the customer's phone number if collected during checkout
    $zaincash->setCustomerPhone('9647829744432');

    // Total price in Iraqi Dinars (Must be >= 1000 IQD)
    $amount = 5000;

    // Type of service provided
    $serviceType = 'E-commerce Order';

    // Unique order ID on your website
    $orderId = '12345';

    // Redirects the user directly to the ZainCash gateway (default asWeb = true)
    return $zaincash->request($amount, $serviceType, $orderId);

    // OR 
    // return $zainCash->request(
    //         amount: $amount,
    //         serviceType:  $serviceType,
    //         orderId: $orderId,
    //         customerPhone: '9647829744432'
    //     );
}

2. Handling the Callback & Verifying the Token

When a payment completes, ZainCash redirects the user back to your redirection_url with a JWT token query parameter. Use the parse() method to securely verify the signature and extract transaction details.

use Illuminate\Http\Request;
use Hawkiq\LaravelZaincash\Services\ZainCash;

public function handleCallback(Request $request, ZainCash$zainCash)
{
    if (!$request->has('token')) {
        return response()->json(['error' => 'No payment token provided'], 400);
    }

    $result = $zainCash->parse($request->query('token'));

    if ($result['error']) {
        return response()->json(['error' => $result['message']], 422);
    }

    // Extracted verified transaction data safely
    $status        =$result['status'];          // e.g., 'SUCCESS', 'FAILED'
    $transactionId =$result['transactionId'];   // ZainCash global transaction ID
    $orderId       =$result['orderId'];         // Your system order ID
    $amount        =$result['amount'];          // Transaction amount

    if ($status === 'SUCCESS') {
        // TODO: Mark your local order as paid.
        // CRITICAL: Save the $transactionId so you can use it for refunds later!
        
        return view('payment.success', compact('orderId', 'transactionId', 'amount'));
    }

    return view('payment.failure', compact('orderId', 'status'));
}

3. Advanced Features: Inquiry & Reversals (Refunds)

The v2 package includes built-in methods for tracking and refunding payments:

Transaction Inquiry (Reconciliation)

$zainCash = new ZainCash();
$details =$zainCash->inquiry('a801492a-f3be-477f-97ba-086adeec1726');

Full Refund (Reverse)

$zainCash = new ZainCash();
$response =$zainCash->fullReverse('a801492a-f3be-477f-97ba-086adeec1726', 'Customer cancellation');

Partial Refund

$zainCash = new ZainCash();
// Refund 2000 IQD from the original transaction
$response =$zainCash->partialReverse('a801492a-f3be-477f-97ba-086adeec1726', 2000, 'Partial item return');

Security Vulnerabilities

If you discover a security vulnerability within hawkiq Laravel Zaincash, please send an e-mail to OsaMa via [e-mail] . All security vulnerabilities will be promptly addressed.

License

Laravel Zaincash is open-sourced software licensed under the MIT license.