waad/zaincash

ZainCash payment Integration Gateway package API laravel

v11.0.0 2024-04-04 21:53 UTC

Requires

• php: ^8.2
• laravel/framework: ^11.0

MIT

• Waad Mawlood

• payment gateway
• payment integration
• zaincash
• Waad Mawlood
• Zain Cash
• Iraqi Dinar
• Zain Cash Laravel
• ZainCash Laravel
• Laravel Zain Cash
• Laravel ZainCash
• ZainCash API
• API ZainCash

README

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).

🎀 Requirements

📌 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

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

⚠️ 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

Author: Waad Mawlood

Email: [e-mail]

⚖️ License

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