Skip to content

Zain Cash payment Integration Gateway package API laravel (ZainCash)

Notifications You must be signed in to change notification settings

waadmawlood/zaincash

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

17 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

ZainCash Integration API Laravel Package

This is a Laravel package to integrate ZainCash payment gateway API. For local financial transactions in Iraqi dinars inside Iraq. This package is based on the official ZainCash API documentation. You can find the official documentation (https://docs.zaincash.iq).

Total Downloads Latest Stable Version License

๐ŸŽ€ Requirements

Package Version Laravel Version PHP Version
6.x 6.x 7.2+
7.x 7.x 7.2.5+
8.x 8.x 7.3+ | 8.0+
9.x 9.x 8.0+
10.x 10.x 8.1+
11.x 11.x 8.2+

๐Ÿ“Œ Installation

composer require waad/zaincash

publish config file to config/zaincash.php

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

update config zaincash in config/zaincash.php or from .env file

Key Type Default Description
msisdn string 9647835077893 The mobile phone number for your wallet, provided by Zain Cash. Example format: 9647835077893.
merchant_id string 5ffacf6612b5777c6d44266f The Merchant ID obtained from ZainCash.
secret string $2y$10$h................ The secret used to decode and encode JWT during requests. Obtain from ZainCash.
test bool true Specify the environment for using the ZainCash API. Set 'test' to false for the live environment after obtaining all credentials from ZainCash.
test_url string https://test.zaincash.iq/ URL for the ZainCash test environment.
live_url string https://api.zaincash.iq/ URL for the ZainCash live environment.
language string ar Set the language for the ZainCash payment page. Use 'ar' for Arabic or 'en' for English.
prefix_order_id string wa3d_ Prefix for the order ID.
is_redirect bool false Specify whether or not to redirect to the ZainCash payment page. If false, ZainCash returns a Transaction ID to the backend. If true, redirection after the request.
min_amount int 1000 Set the minimum amount for a valid transaction in Iraqi Dinar (IQD). Transactions with amounts less than this value will be considered invalid.
timeout int 10 Set the timeout for the request in seconds.
verify_ssl bool true Set the verify SSL for the request to ZainCash's API.

Configurations to .env file

ZAINCASH_MSISDN=9647835077893                  # Test Credentials
ZAINCASH_MERCHANT_ID=5ffacf6612b5777c6d44266f  # Test Credentials
ZAINCASH_SECRET=$2y$10$h................       # Test Credentials
ZAINCASH_TEST=true                             # default true 
ZAINCASH_PREFIX_ORDER_ID=wa3d_                 # default wa3d_
ZAINCASH_LANGUAGE=ar                           # optional default ar
ZAINCASH_IS_REDIRECT=false                     # optional default false
ZAINCASH_MIN_AMOUNT=1000                       # optional default 1000
ZAINCASH_TEST_URL=https://test.zaincash.iq/    # optional
ZAINCASH_LIVE_URL=https://api.zaincash.iq/     # optional
ZAINCASH_TIMEOUT=10                            # optional
ZAINCASH_VERIFY_SSL=true                       # optional
php artisan optimize


๐Ÿ” Usage

use ZainCash Facade or Class example

Facade
<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Requests\Payment
\InitialPaymentRequest;
use Illuminate\Support\Str;
use Waad\ZainCash\Facades\ZainCash;

class PaymentController extends Controller
{
    /**
     * Create Request Transaction
     *
     * @param InitialPaymentRequest $request
     * @return \Illuminate\Http\JsonResponse
     */
    public function initialTransaction
    (InitialPaymentRequest $request)
    {
        $zainCashPayment = 
            ZainCash::setAmount($request->amount)
            ->setServiceType('Book')
            ->setOrderId(Str::random(36))
            ->setIsTest(true)
            ->setIsReturnArray(true);

        return response()->json( 
            $zainCashPayment->createTransaction()
            );
    }
}
Class
<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Requests\Payment
\InitialPaymentRequest;
use Illuminate\Support\Str;
use Waad\ZainCash\ZainCash;

class PaymentController extends Controller
{
    /**
     * Create Request Transaction
     *
     * @param InitialPaymentRequest $request
     * @return \Illuminate\Http\JsonResponse
     */
    public function initialTransaction
    (InitialPaymentRequest $request)
    {
        $zainCashPayment = ZainCash::make()
            ->setAmount($request->amount)
            ->setServiceType('Book')
            ->setOrderId(Str::random(36))
            ->setIsTest(true)
            ->setIsReturnArray(true);

        return response()->json( 
        $zainCashPayment->createTransaction()
        );
    }
}

- Getter And Setter Attributes Table

Attribute Important Type Getter Setter Default
amount ๐ŸŸข int-float-null getAmount() setAmount($amount) -
serviceType ๐ŸŸข string-null getServiceType() setServiceType($serviceType) -
orderId ๐ŸŸข string-int-float-null getOrderId() setOrderId($orderId) -
transactionID ๐ŸŸข string-null getTransactionID() setTransactionID($transactionID) -
isReturnArray ๐ŸŸข bool getIsReturnArray() setIsReturnArray($isReturnArray) false
minAmount ๐Ÿ”ด int-float-null getMinAmount() setMinAmount($minAmount) -
msisdn ๐Ÿ”ด string-null getMsisdn() setMsisdn($msisdn) -
secret ๐Ÿ”ด string-null getSecret() setSecret($secret) -
merchantId ๐Ÿ”ด string-null getMerchantId() setMerchantId($merchantId) -
isTest ๐Ÿ”ด bool-null getIsTest() setIsTest($isTest) -
language ๐Ÿ”ด string-null getLanguage() setLanguage($language) -
baseUrl ๐Ÿ”ด string-null getBaseUrl() setBaseUrl($baseUrl) -
isRedirect ๐Ÿ”ด bool getIsRedirect() setIsRedirect($isRedirect) -
tUrl ๐Ÿ”ด string-null getTUrl() setTUrl($tUrl) -
cUrl ๐Ÿ”ด string-null getCUrl() setCUrl($cUrl) -
rUrl ๐Ÿ”ด string-null getRUrl() setRUrl($rUrl) -
processingUrl ๐Ÿ”ด string-null getProcessingUrl() setProcessingUrl($processingUrl) -
processingOtpUrl ๐Ÿ”ด string-null getProcessingOtpUrl() setProcessingOtpUrl($processingOtpUrl) -
cancelUrl ๐Ÿ”ด string-null getCancelUrl() setCancelUrl($cancelUrl) -
timeout ๐Ÿ”ด int-null getTimeout() setTimeout($timeout) -
verifySsl ๐Ÿ”ด bool-null getVerifySsl() setVerifySsl($verifySsl) -

โš ๏ธ Important column means that this attribute is constantly used and has no default value. On the contrary, we can change it, but it will take the default value from config/zaincash.php.


- Steps from create a transaction To Complete Payment

Step 1 - Create a transaction

    $zainCashPayment = ZainCash::make()
        ->setAmount($request->amount)
        ->setServiceType('Book')
        ->setOrderId(Str::random(36))
        ->setIsTest(true);
  • setAmount($amount) : Set the amount of the transaction in Iraqi Dinar (IQD). The amount must be greater than or equal to the minimum amount specified in the configuration file.
  • setServiceType($serviceType) : Set the service type for the transaction. The service type must be one of the following: Book, Food, Grocery, Pharmacy, Transportation, Other.
  • setOrderId($orderId) : Set the order ID for the transaction. The order ID must be unique for each transaction.
  • setIsTest($isTest) : Set the environment for using the ZainCash API. Set true for the test environment and false for the live environment.
  • setIsReturnArray(bool) : Set the return type for the transaction. Set true to return an array and false to return an object stdClass. The default value is false.
  • createTransaction() : Create a transaction and return the transaction Details (array or object stdClass).

    $transaction = $zainCashPayment->createTransaction();

Response example

{
  "source": "web",
  "type": "MERCHANT_PAYMENT",
  "amount": "1000",
  "to": "5ffacf6612b5777c6d44266f",
  "serviceType": "Book",
  "lang": "ar",
  "orderId": "wa3d_Q9IpdkNw7EVypwLRuE2PDDoVLA4FPhAjhlyO",
  "currencyConversion": {},
  "referenceNumber": "RGUR9Q",
  "credit": false,
  "status": "pending",
  "reversed": false,
  "createdAt": "2023-11-18T08:24:32.467Z",
  "updatedAt": "2023-11-18T08:24:32.467Z",
  "id": "655874c00227c4d2ec58f710"
}
// if return array use ->setIsReturnArray(true);

    $transactionId = $transaction['id'];

// if return object use ->setIsReturnArray(false); -- default
    $transactionId = $transaction->id;


Step 2 - Check a transaction

    $zainCashPayment = ZainCash::make()
        ->setTransactionID($transactionID)
        ->setIsReturnArray(true);
  • setTransactionID($transactionID) : Set the transaction ID for the transaction.
  • setIsReturnArray(bool) : Set the return type for the transaction. Set true to return an array and false to return an object stdClass. The default value is false.
  • checkTransaction() : Check the transaction and return the transaction details (array or stdClass).

    $transactionDetails = $zainCashPayment->checkTransaction();

Response Example dependent by status:

{
    "to": {
        "name": "Karrar",
        "msisdn": "9647835077893",
        "currency": "IQD",
        "deleted": false,
        "pay_by_reference": "1",
        "createdAt": "2021-01-10T09:56:54.180Z",
        "updatedAt": "2021-12-22T13:01:02.531Z",
        "id": "5ffacf6612b5777c6d44266f"
    },
    "source": "web",
    "type": "MERCHANT_PAYMENT",
    "amount": "1000",
    "serviceType": "Book",
    "lang": "ar",
    "orderId": "wa3d_2eTDlz8umPE3DwtocL5O8Xpe10yLH4pepci2",
    "currencyConversion": [],
    "referenceNumber": "MDJN1I",
    "credit": false,
    "status": "pending",  // pending, pending_otp, completed, failed, cancel
    "reversed": false,
    "createdAt": "2023-11-18T11:37:16.574Z",
    "updatedAt": "2023-11-18T11:37:16.574Z",
    "id": "6558a1ec0227c4d2ec58f717"
}
*****************************************
{
  "to": {
    ....
  },
  ...
  "status": "pending_otp", // <--- status pending_otp after processing
  "sofOwnerId": 18482,
  "traveldiscount": "10000",
  "from": "9647802999569",
  "onCustomerFees": "50000000",
  "onMerchantFees": "0",
  "totalFees": 500,
  ...
}
*****************************************
{
  "to": {
    ...
  },
  ...
  "status": "completed", // <--- status completed after complete (Payment)
  "sofOwnerId": 18482,
    "traveldiscount": "1000",
    "from": "9647802999569",
    "onCustomerFees": "50000000",
    "onMerchantFees": "0",
    "totalFees": 500,
    "operationDate": "2023-11-22T18:23:52.270Z",
    "operationId": "1173300",
  ...
}
*****************************************
{
  "to": {
    ...
  },
  ...
  "status": "failed", // <--- status failed that mean there is (expiration or a wrong)
  "sofOwnerId": 18482,
  "traveldiscount": "9900",
  "from": "9647802999569",
  "onCustomerFees": "50000000",
  "onMerchantFees": "0",
  "totalFees": 500,
  "due": "Not enough credit on balance",
  ...
}
*****************************************
{
  "to": {
    ...
  },
  ...
  "status": "cancel", // <--- status cancel it mean the user cancel the transaction
  "sofOwnerId": 18482,
  "traveldiscount": "10000",
  "from": "9647802999569",
  "onCustomerFees": "50000000",
  "onMerchantFees": "0",
  "totalFees": 500,
  "due": "transaction_already_submitted",
  ...
}
// if return array use ->setIsReturnArray(true);

    $status = $transactionDetails['status'];
    $name = $transactionDetails['to']['name'];

// if return object use ->setIsReturnArray(false); -- default
    $status = $transactionDetails->status;
    $name = $transactionDetails->to->name;


Step 3 - Processing a transaction

    $zainCashPayment = ZainCash::make()
        ->setTransactionID($transactionID)
        ->setIsReturnArray(true);
  • setTransactionID($transactionID) : Set the transaction ID for the transaction.
  • setIsReturnArray(bool) : Set the return type for the transaction. Set true to return an array and false to return an object stdClass. The default value is false.
  • processingTransaction($phonenumber, $pin) : Processing the transaction and return the transaction details (array or object stdClass).

$processingDetails = $zainCashPayment->processingTransaction("9647802999569", '1234');

Response Example dependent by success:

{
  "success": 1,
  "transactionid": "655883cd0227c4d2ec58f712",
  "initialAmount": "1000",
  "totalFees": 500,
  "discount": "1000",
  "total": 1500,
  "onCustomerFees": "50000000",
  "onMerchantFees": "0"
}
********************************************
{
  "success": 0,
  "error": "ุงู„ุนู…ู„ูŠุฉ ู‚ุฏ ู‚ุฏู…ุช ู…ู† ู‚ุจู„"
}
********************************************
{
  "success": 0,
  "error": "ุฑู‚ู… ุงู„ู…ุญูุธุฉ-ุงู„ู‡ุงุชู ุฃูˆ ุงู„ุฑู…ุฒ ุงู„ุณุฑูŠ ุบูŠุฑ ุตุญูŠุญ"
}
// if return array use ->setIsReturnArray(true);

    $success = $processingDetails['success'];

// if return object use ->setIsReturnArray(false); -- default
    $success = $processingDetails->success;


Step 4 - Complete a transaction

    $zainCashPayment = ZainCash::make()
        ->setTransactionID($transactionID)
        ->setIsReturnArray(true);
  • setTransactionID($transactionID) : Set the transaction ID for the transaction.
  • setIsReturnArray(bool) : Set the return type for the transaction. Set true to return an array and false to return an object stdClass. The default value is false.
  • payTransaction($phonenumber, $pin, $otp) : Complete pay the transaction and return the transaction details (array or object stdClass).

$payDetails = $zainCashPayment->payTransaction("9647802999569", '1234', '1111');

Response Example dependent by success:

{
  "success": 1,
  "msg": "succesful_transaction"
}
********************************************
{
  "success": 0,
  "msg": "You have entered an incorrect OTP. In the next try, please enter the correct PIN delivered to your mobile by SMS "
}
********************************************
{
  "success": 0,
  "msg": "Not enough credit on balance"
}
// if return array use ->setIsReturnArray(true);

    $success = $payDetails['success'];

// if return object use ->setIsReturnArray(false); -- default
    $success = $payDetails->success;


Step 5 - Cancel a transaction

    $zainCashPayment = ZainCash::make()
        ->setTransactionID($transactionID)
        ->setIsReturnArray(true);
  • setTransactionID($transactionID) : Set the transaction ID for the transaction.
  • setIsReturnArray(bool) : Set the return type for the transaction. Set true to return an array and false to return an object stdClass. The default value is false.
  • cancelTransaction() : Cancel the transaction and return the transaction details (array or object stdClass).

$cancelDetails = $zainCashPayment->cancelTransaction();

Response Example dependent by success:

{
  "success":0,
  "msg":"ู„ู‚ุฏ ู‚ู…ุช ุจุงู„ุบุงุก ุงู„ุนู…ู„ูŠุฉ"
}
************************************
{
  "success":0,
  "msg":"ุงู„ุนู…ู„ูŠุฉ ู‚ุฏ ู‚ุฏู…ุช ู…ู† ู‚ุจู„"
}
// if return array use ->setIsReturnArray(true);

    $success = $cancelDetails['success'];

// if return object use ->setIsReturnArray(false); -- default
    $success = $cancelDetails->success;


๐Ÿง” Author

โš–๏ธ License

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