hawkiq/laravel-zaincash

Laravel package to use in Laravel helps you to make dealing with Zain Cash API easier

1.0.6 2025-12-13 10:56 UTC

Requires

• firebase/php-jwt: ^6.3

MIT

• hawkiq

README

About hawkiq laravel zaincash

ZainCash offers a simple robust payment gateway to transfer money instantly from anywhere to everywhere inside Iraq, and this package for Laravel developers since there are no official package to use in Laravel so I've decided to create one.

Requiremnt

Version	PHP	Laravel
1.x	7.1 <= PHP	5.8 <= Laravel

Installation

composer require hawkiq/laravel-zaincash

Publish config file

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

setup redirect route in web.php to handle payment result and put route name in zaincash.php config file

Route::get('/redirect', [App\Http\Controllers\HomeController::class, 'redirect'])->name('redirect');

all config variables are well described

config	Description	Type	Default
msisdn	The mobile phone number for your wallet, example format: 9647835077893. given by Zain Cash	String	9647835077893
secret	This is used to decode and encode JWT during requests. also must be requested from ZainCash	String	secret found in config
merchantid	You can request a Merchant ID from ZainCash's support	String	5ffacf6612b5777c6d44266f
live	Test enviroment or Live server (true=live , false=test)	Bool	false
lang	setting langauge for zain cashe payment page	String	en
order_id	you can use it to help you in tagging transactions with your website IDs	String	Str::slug(env('APP_NAME')) . '_hawkiq_'
redirection_url	to handle payment after successfull First you need to Specify name for redirect route in web.php	String	redirect

or you can set those parameters inside .env file

ZCASH_MSISDN=
ZCASH_MERCHANTID=
ZCASH_SECRET=
ZCASH_LANG=en
ZCASH_LIVE=false
ZCASH_CALLBACK_ROUTE="redirect"

inside your controller

Now you can use zain cash as API or web just pass the isWeb variable value as boolean or use asApi method

//Your Controller 
use Hawkiq\LaravelZaincash\Services\ZainCash;

public function send()
{
    // Now you can use zain cash as API or web just pass the isWeb variable value as boolean or use asApi method
    $zaincash = new ZainCash(); // for normal Web version
    // OR
    $zaincash = (new ZainCash())->asApi(); // for API version
    // OR
    $zaincash = (new ZainCash())->asWeb(false); // for API version

    //The total price of your order in Iraqi Dinar only like 1000 (if in dollar, multiply it by dollar-dinar exchange rate, like 1*1500=1500)
    //Please note that it MUST BE MORE THAN 1000 IQD
    $amount = 1000;

    //Type of service you provide, like 'Books', 'ecommerce cart', 'Hosting services', ...
    $service_type="Shirt";

    //Order id, you can use it to help you in tagging transactions with your website IDs, if you have no order numbers in your website, leave it 1
    $order_id="20222009";

    $payload =  $zaincash->request($amount, $service_type, $order_id);
    return $payload;
}

if you used web version it will redirect you to payment page otherwise it will show a response with information about your payload you can use payment_url to redirect user inside app.

this will redirect us to Zain Cash page to enter user credentials ( MSISDN and Pin)

you can use this test user

MSISDN	PIN	OTP
9647802999569	1234	1111

We check for status in our callback method in controller

//get token from request Url
$token = \Request::input('token');
    if (isset($token)) {
        $zaincash = new ZainCash();
        $result = $zaincash->parse($token);
        if ($result->status == 'success'){ // success ||  failed  || pending
            return 'Thanks for Buying';
            // We can do what ever you like , insert transaction into database, send email etc..
        }

result will be in JSON format like this

{
   "status":"success",
   "orderid":"laravel_hawkiq_20222009",
   "id":"632eb6cb8726f6b4b8ea2fc3",
   "operationid":"1006596",
   "msisdn":"9647802999569"
}

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.

Preview

this class used in following sites

• O! Software.

feel free to contact me if you want to add your site.

Todo

• Add custom redirect route.
• Api version.
• Add additional views for easy integration into blade.

License

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