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

🧠 Transaction Types

🧪 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