noorani-mm/irankish-laravel-gateway

Laravel package for integrating IranKish payment gateway (درگاه پرداخت ایران کیش برای لاراول)

v1.0.0 2025-11-09 14:57 UTC

Requires

• php: >=8.1
• ext-curl: *
• ext-json: *
• ext-openssl: *
• illuminate/support: >=10.0

Requires (Dev)

• orchestra/testbench: ^8.0 || ^9.0
• phpunit/phpunit: ^10.5

MIT

• Mohammad Mahdi Noorani

• payment
• gateway
• laravel
• iran
• shaparak
• payment-gateway
• irankish
• laravel-payment
• iran kish
• irankish-laravel-gateway
• laravel-irankish

README

A modern and developer-friendly Laravel integration for the IranKish Payment Gateway (IPG),
implemented fully according to the official technical documentation V9.

🚀 Installation

composer require noorani-mm/irankish-laravel-gateway

⚙️ Configuration

After installation, publish the configuration file:

php artisan vendor:publish --provider="IranKish\IranKishServiceProvider" --tag="config"

This creates the file: config/irankish.php

.env variables

IRANKISH_TERMINAL_ID=12345678
IRANKISH_ACCEPTOR_ID=87654321
IRANKISH_PASSWORD=YourSecurePassword
IRANKISH_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----"
IRANKISH_REVERT_URL=https://example.com/payment/callback

config/irankish.php

return [
    'terminal_id' => env('IRANKISH_TERMINAL_ID'),
    'acceptor_id' => env('IRANKISH_ACCEPTOR_ID'),
    'password'    => env('IRANKISH_PASSWORD'),
    'public_key'  => env('IRANKISH_PUBLIC_KEY'),
    'revert_url'  => env('IRANKISH_REVERT_URL'),
];

💳 Example Usage

use IranKish\Facades\IranKish;
use IranKish\Enums\TransactionType;
use IranKish\Exceptions\IranKishException;
use Illuminate\Http\Request;

class PaymentController extends Controller
{
    public function pay()
    {
        try {
            // Step 1: Request token
            $response = IranKish::requestToken(150000, TransactionType::PURCHASE, [
                'paymentId' => 'ORDER-1234',
            ]);

            // Step 2: Redirect user to payment page (auto-submit form)
            return IranKish::redirect($response['token']);

            // OR (manual redirect data)
            // $redirect = IranKish::redirectData($response['token']);
            // return view('payments.redirect', compact('redirect'));
        }
        catch (IranKishException $e) {
            return back()->withErrors($e->getMessage());
        }
    }

    public function callback(Request $request)
    {
        try {
            // Step 3: Confirm transaction
            $confirmation = IranKish::confirm(
                $request->input('tokenIdentity'),
                $request->input('retrievalReferenceNumber'),
                $request->input('systemTraceAuditNumber')
            );

            return response()->json(['status' => 'success', 'data' => $confirmation]);
        }
        catch (IranKishException $e) {
            return response()->json(['status' => 'failed', 'message' => $e->getMessage()]);
        }
    }
}

📘 Methods Reference

Method	Description
requestToken(int $amount, ?TransactionType $type = null, array $options = [])	Create a payment token using the /tokenization/make endpoint.
requestSpecialToken(int $amount, ?TransactionType $type = null, array $options = [])	Same as requestToken but for special merchants (e.g., AsanShpWPP, IsacoWPP).
redirect(string $token)	Automatically renders a POST form and redirects the payer to IranKish payment page.
redirectData(string $token)	Returns redirection data array for manual handling or SPA redirects.
confirm(string $token, string $rrn, string $stan)	Confirms the transaction after return from payment page.
reverse(string $token, string $rrn, string $stan)	Reverses a previously successful transaction (before settlement).
inquiry(array $criteria)	Checks transaction status by RRN, tokenIdentity, or requestId.

🧠 Transaction Types

Enum	Meaning
Purchase	Standard purchase
Bill	Bill payment
AsanShpWPP	AsanShp wallet
SpecialBill	Special bill payments
AsanShpWPPDrug	AsanShp Drug Wallet
IsacoWPP	ISACO Wallet Payment

🧪 Running Tests

The package includes a complete test suite using Orchestra Testbench and Http::fake().

composer install
composer test

To re-run cleanly:

rm -rf vendor
composer install && composer test

📁 All tests are located in /tests. A fake public key (tests/stubs/pubkey.pem) is included for encryption testing.

💡 Development Notes

• Compatible with Laravel 10.x – 14.x
• Built following PSR-4, PSR-12, and Laravel package conventions
• Fully supports Http::fake() for integration testing
• AES-128 + RSA encryption exactly as per IranKish API Guide V9

🤝 Contributing

Contributions are welcome! If you encounter a bug or have a feature request, please open an issue at:

👉 GitHub Issues

To contribute code:

git clone https://github.com/noorani-mm/irankish-laravel-gateway.git
composer install
phpunit

Follow PSR-12 and submit a Pull Request 💪

🧾 License

This package is open-source software licensed under the MIT License.

MIT License © Mohammad Mahdi Noorani

👥 Contributors

🌐 Also available in Persian: README-Fa.md