PHPackages larapardakht/larapardakht - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Payment Processing](/categories/payments) 4. / 5. larapardakht/larapardakht ActiveLibrary[Payment Processing](/categories/payments) larapardakht/larapardakht ========================= A modern, extensible payment gateway integration package for Laravel supporting Iranian payment providers. V2.0(2mo ago)220MITPHPPHP ^8.2 Since Feb 16Pushed 2mo agoCompare [ Source](https://github.com/TheXERC/LaraPardakht)[ Packagist](https://packagist.org/packages/larapardakht/larapardakht)[ RSS](/packages/larapardakht-larapardakht/feed)WikiDiscussions main Synced 3d ago READMEChangelog (7)Dependencies (15)Versions (10)Used By (0) LaraPardakht ============ [](#larapardakht) [English](README.md) | [فارسی](README.fa.md) Badge Wall ---------- [](#badge-wall) [![Packagist Version](https://camo.githubusercontent.com/0acfb0dbcf80cbf8372b341a3a07cf5a5ed38535564bae45d081fe647134c70a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c61726170617264616b68742f6c61726170617264616b68743f6c6162656c3d5061636b616769737426636f6c6f723d304539463645)](https://packagist.org/packages/larapardakht/larapardakht)[![Total Downloads](https://camo.githubusercontent.com/444011e8e57c97fd57c226985854000b50e0a6afea757811476702bd3c1dd963/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6c61726170617264616b68742f6c61726170617264616b68743f6c6162656c3d446f776e6c6f61647326636f6c6f723d323536334542)](https://packagist.org/packages/larapardakht/larapardakht)[![PHP Version](https://camo.githubusercontent.com/ccaa43fc634d348cffccb1d8db7b55d9f17c5d46944bc99a15c3c982724b387d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d3737374242343f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://www.php.net/releases/)[![Laravel](https://camo.githubusercontent.com/d9ee4708df76c3020e1cfe806419871e9ab3ad3b2b4e9ea1b8b0e6d37f5c4402/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d3131253230253743253230313225323025374325323031332d4646324432303f6c6f676f3d6c61726176656c266c6f676f436f6c6f723d7768697465)](https://laravel.com/)[![Tests](https://camo.githubusercontent.com/0030d763c8d688d2b68d83d88c7848d13a9b7e4ae39079a82ad510e38393134c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f54657374732d506573742d313641333441)](https://pestphp.com/)[![License](https://camo.githubusercontent.com/efce7cdac050171483fe86b87b06222a067c395fd99fe82bc49f484d08321e0c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d463539453042)](LICENSE) A modern, extensible payment gateway integration package for Laravel 11, 12, and 13, supporting Iranian payment providers. Features -------- [](#features) - **Driver-based architecture** — easily add new gateways without modifying core code - **Fluent API** — clean, chainable interface for purchases, payments and verifications - **Sandbox/test support** — every driver supports sandbox mode out of the box - **Events** — fires events after purchase and first-time successful verification for easy integration - **Runtime configuration** — switch drivers and override settings on the fly - **Typed exceptions** — distinct exception classes for different failure scenarios Supported Gateways ------------------ [](#supported-gateways) GatewayNormal ModeSandbox Mode[Zarinpal](https://www.zarinpal.com/)✅✅[Zibal](https://zibal.ir/)✅✅[IDPay](https://idpay.ir/)✅✅More gateways coming soon! You can also [create custom drivers](#creating-custom-drivers). Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 11, 12, or 13 Installation ------------ [](#installation) ``` composer require larapardakht/larapardakht ``` ### Publish Configuration [](#publish-configuration) ``` php artisan vendor:publish --tag=larapardakht-config ``` This will create `config/larapardakht.php` in your application. Configuration ------------- [](#configuration) Set your gateway credentials in `.env`: ``` PAYMENT_GATEWAY=zarinpal # Zarinpal ZARINPAL_MERCHANT_ID=your-merchant-id-here ZARINPAL_SANDBOX=false # Zibal ZIBAL_MERCHANT=your-zibal-merchant ZIBAL_SANDBOX=false # IDPay IDPAY_API_KEY=your-idpay-api-key IDPAY_SANDBOX=false # Shared PAYMENT_CALLBACK_URL=https://yoursite.com/payment/callback ``` Usage ----- [](#usage) ### Purchase & Redirect [](#purchase--redirect) ``` use LaraPardakht\Facades\Payment; use LaraPardakht\DTOs\Invoice; $invoice = new Invoice(); $invoice->amount(50000) ->description('Order #123') ->detail('mobile', '09121234567') ->detail('email', 'customer@example.com'); return Payment::purchase($invoice, function ($driver, $transactionId) { // Persist $transactionId in your own storage (for example, your order record) })->pay()->render(); ``` For `idpay`, `order_id` is required by the API. Set it on invoice details before purchase/verify: ``` $invoice->detail('order_id', 'ORD-123'); ``` ### Verify Payment [](#verify-payment) ``` use LaraPardakht\Facades\Payment; use LaraPardakht\Exceptions\InvalidPaymentException; try { $receipt = Payment::amount(50000) ->transactionId($transactionId) ->verify(); // Payment was successful echo $receipt->getReferenceId(); echo $receipt->getDriver(); } catch (InvalidPaymentException $e) { // Payment verification failed echo $e->getMessage(); } ``` ### Switch Driver at Runtime [](#switch-driver-at-runtime) ``` Payment::via('zibal')->purchase($invoice, function ($driver, $transactionId) { // ... }); ``` ### Override Config at Runtime [](#override-config-at-runtime) ``` Payment::config('merchant_id', 'another-merchant-id')->purchase($invoice); // Or multiple values: Payment::config([ 'merchant_id' => 'another-merchant-id', 'sandbox' => true, ])->purchase($invoice); ``` ### Override Callback URL [](#override-callback-url) ``` Payment::callbackUrl('https://yoursite.com/custom-callback') ->purchase($invoice); ``` ### Get JSON Redirect Data [](#get-json-redirect-data) ``` $redirect = Payment::purchase($invoice)->pay(); return $redirect->toJson(); ``` Security and Reliability Notes ------------------------------ [](#security-and-reliability-notes) - `PaymentManager` is now container-scoped (request/job lifecycle) to avoid cross-request state leakage in long-lived workers. - Facade root caching is disabled for `Payment`, so each call resolves from the current container scope. - `pay()` now validates that a transaction identifier exists and throws `InvalidPaymentException` when missing. - `verify()` now validates that a reference identifier exists in successful gateway responses and throws `InvalidPaymentException` when missing. - `verify()` now requires a positive invoice amount (`amount > 0`) before contacting the gateway. - `Zibal` verify performs consistency checks against local invoice data: - Gateway `amount` must match local invoice amount when returned by gateway. - If invoice `order_id` detail is set and gateway returns `orderId`, values must match. - Already-verified responses (`code=101` for Zarinpal, `result=201` for Zibal, `status=101` for IDPay) are still accepted as valid verify results, but now include `already_verified=true` in receipt raw data. - `PaymentVerified` event is dispatched only for first-time successful verification, not for already-verified gateway responses. - Malformed/non-JSON gateway responses are handled safely and converted to typed exceptions (`PurchaseFailedException` / `InvalidPaymentException`). ### Compatibility Impact [](#compatibility-impact) No public method signatures changed and no config changes are required. If your integration previously called `pay()` before a successful `purchase()`, or relied on low-level runtime errors for malformed gateway responses, update your error handling to catch typed gateway exceptions. `verify()` now requires invoice amount to be set to a positive value before calling it. If you were verifying only by transaction identifier, update your flow to include the original invoice amount. `PaymentVerified` is no longer dispatched for gateway responses that indicate the transaction was already verified (`code=101` / `result=201` / `status=101`). If you had listeners relying on repeated verify calls, make sure they depend on your own idempotent persistence flow instead of repeated event dispatches. For `Zibal`: verify may throw `InvalidPaymentException` when gateway-reported `amount` / `orderId` conflicts with your local invoice data. This is a security hardening change. No API update is required on your side, but ensure your verify flow handles this exception and keeps local invoice values authoritative. Gateway Codes (English Translations) ------------------------------------ [](#gateway-codes-english-translations) These translations are used by the package when possible so exception messages are predictable. ### Zarinpal - Common Codes [](#zarinpal---common-codes) CodeMeaning-9Validation error-10Terminal is not valid (check merchant\_id or IP)-11Terminal is not active-12Too many attempts-13Terminal limit reached-14Callback domain does not match registered terminal domain-15Terminal user is suspended-16Terminal user level is not valid-17Terminal user level is not valid-18Referrer address does not match registered domain-19Terminal transactions are banned100Success101Already verified### Zarinpal - Purchase Codes [](#zarinpal---purchase-codes) CodeMeaning-30Terminal does not allow floating wages-31Terminal does not allow wages (default bank account missing)-32Invalid wages (floating total exceeds max amount)-33Invalid floating wages-34Invalid wages (fixed total exceeds max amount)-35Floating wages reached max parts limit-36Minimum floating wage amount is 10,000 Rials-37One or more wage IBAN values are inactive-38Wage IBAN setup is invalid-39Generic wages error-40Invalid `expire_in`-41Maximum amount is 100,000,000 Tomans### Zarinpal - Verify Codes [](#zarinpal---verify-codes) CodeMeaning-50Session invalid (amount mismatch)-51Session invalid (payment not successful / inactive session)-52Unexpected system error-53Session does not belong to this merchant\_id-54Invalid authority-55Manual payment request not found### Zibal - Request Result Codes [](#zibal---request-result-codes) CodeMeaning100Success102Merchant not found103Merchant inactive / gateway contract not signed104Invalid merchant105Amount must be greater than 1,000 Rials106Invalid callbackUrl (must start with http/https)107Invalid percentMode (only 0 or 1)108One or more beneficiaries in multiplexingInfos are invalid109One or more beneficiaries in multiplexingInfos are inactive110`id=self` missing in multiplexingInfos111Amount is not equal to total shares in multiplexingInfos112Insufficient fee wallet balance113Amount exceeds transaction limit114Invalid national code115IP is not registered in panel### Zibal - Verify Result Codes [](#zibal---verify-result-codes) CodeMeaning100Success102Merchant not found103Merchant inactive104Invalid merchant201Already verified202Order not paid or payment unsuccessful203Invalid trackId### Zibal - Payment Status Codes [](#zibal---payment-status-codes) StatusMeaning-1Waiting for payment-2Internal error1Paid and verified2Paid and unverified3Cancelled by user4Invalid card number5Insufficient funds6Invalid password/PIN7Too many requests8Daily internet payment count limit exceeded9Daily internet payment amount limit exceeded10Invalid card issuer11Switch error12Card not accessible15Refunded16Refund in progress18Reversed21Invalid merchant### IDPay - Transaction Status Codes [](#idpay---transaction-status-codes) StatusMeaning1Payment not made2Payment failed3Error occurred4Blocked5Refunded to payer6System refund7Canceled by payer8Redirected to payment gateway10Waiting for verification100Verified101Already verified200Settled to payeeCreating Custom Drivers ----------------------- [](#creating-custom-drivers) ### 1. Create a Gateway Class [](#1-create-a-gateway-class) Create a new directory under `src/Drivers/YourGateway/` and implement `GatewayInterface`: ```