Download the PHP package ht3aa/zain-cash without Composer

ZainCash Integration For Laravel

A comprehensive Laravel package for integrating ZainCash payment gateway into your application. This package provides a simple and elegant way to handle payment transactions, webhooks, and transaction tracking with ZainCash.

Features

• ✅ Easy integration with ZainCash payment gateway
• ✅ Automatic transaction tracking and management
• ✅ Polymorphic relationships - link transactions to any order model
• ✅ Webhook handling for payment status updates
• ✅ Check transaction status with ZainCash API
• ✅ Support for both production and test environments
• ✅ JWT token generation and validation
• ✅ Database transaction logging
• ✅ Custom webhook URL support
• ✅ Built-in error handling and logging

Installation

You can install the package via composer:

Publish the configuration file:

Publish and run the migrations:

Configuration

Add the following environment variables to your .env file:

Configuration Options

• ZAIN_CASH_IS_PRODUCTION: Set to true for production environment, false for testing
• ZAIN_CASH_MERCHANT_ID: Your ZainCash merchant ID
• ZAIN_CASH_MERCHANT_SECRET: Your ZainCash merchant secret key
• ZAIN_CASH_MSISDN: Your registered mobile number with ZainCash
• ZAIN_CASH_WEBHOOK_URL: The URL where ZainCash will send payment status updates
• ZAIN_CASH_CUSTOM_WEBHOOK_URL: (Optional) Custom URL to receive payment notifications in your app

Usage

Creating a Payment Transaction

To initiate a payment transaction, create a new ZainCashTransaction instance and pass it to the initiateTransaction method.

Basic Usage (Simple Order ID)

Advanced Usage (Polymorphic Relationship)

Link the transaction directly to your Order model using polymorphic relationships:

Now you can access the order from the transaction:

Transaction Model

The ZainCashTransaction model includes the following attributes:

• amount: Payment amount in IQD
• service_type: Description of the service/product
• order_id: Unique order identifier (can be string or model ID for polymorphic relationship)
• order_type: Model class name for polymorphic relationship (e.g., App\Models\Order)
• redirect_url: URL to redirect after payment
• token: JWT token for the transaction
• iat: Token issued at timestamp
• exp: Token expiration timestamp
• zain_cash_response: Full response from ZainCash API
• status: Transaction status (pending, completed, failed, etc.)
• payment_redirect_url: URL to redirect user for payment
• transaction_id: ZainCash transaction ID

Polymorphic Relationship

The model includes a polymorphic order() relationship that allows you to link transactions to any order model:

Webhook Handling

The package automatically registers a webhook route at /api/zain-cash/webhook to handle payment status updates from ZainCash.

When a payment is completed, ZainCash will send a callback to this URL with the transaction status. The webhook controller will:

1. Decode the JWT token from ZainCash
2. Update the transaction status in your database
3. (Optional) Forward the notification to your custom webhook URL

Custom Webhook Notifications

If you want to receive notifications in your own application when a payment status is updated, set the ZAIN_CASH_CUSTOM_WEBHOOK_URL in your .env file:

The package will POST to this URL with the following payload:

You can then create your own controller to handle this:

Checking Transaction Status

From Local Database

You can check the status of a transaction from your local database:

From ZainCash API

You can also verify the transaction status directly from ZainCash API:

This is useful for:

• Verifying payment status before fulfilling orders
• Reconciling payments with ZainCash
• Handling edge cases where webhook might have failed

Using the Facade

The package provides a facade for easy access to all methods:

Complete Example Flow

Here's a complete example of a payment flow with polymorphic relationships:

Setting Up Your Order Model

To use polymorphic relationships, add the inverse relationship to your Order model:

Now you can easily access transactions from orders:

Testing

The package includes test credentials for the ZainCash sandbox environment. Make sure ZAIN_CASH_IS_PRODUCTION is set to false when testing.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Hasan Tahseen
• All Contributors

License

The MIT License (MIT). Please see License File for more information.