Download the PHP package amyavari/iran-payment-laravel without Composer

Iran Payment Laravel

A simple and convenient way to connect your app to Iranian payment providers.

To view the Persian documentation, please refer to README_FA.md.

برای مشاهده راهنمای فارسی، لطفاً به فایل README_FA.md مراجعه کنید.

Requirements

• PHP version 8.3 or higher
• Laravel ^11.44, ^12.23, or ^13.0

List of Available Payment Gateways

[!CAUTION] Gateways have different rules for pending verifications and reversals. Please check gateways_note_en.md.

Table of Contents

• Installation
• Publish Vendor Files
• Configuration
• Usage
  • Create a Payment
  • Checking API Call Status
  • Storing Payment Data
  • Automatic Store
  • Manual Store
  • Redirect User to Payment Page
  • Verification
  • Verify and Reverse
  • Successful Payment Details
  • Form Request Classes
  • Verification Without Callback
• Testing
• Contributing

Installation

To install the package via Composer, run:

Publish Vendor Files

Publish All Files

To publish all vendor files (config and migrations):

Note: To create tables from migrations:

Publish Specific Files

To publish only the config file:

To publish only the migration file:

Note: To create tables from migrations:

Configuration

To configure payment gateways, add the following to your .env file:

Notes:

• For the PAYMENT_GATEWAY, refer to the gateway Key column in the List of Available Payment Gateways.
• For each gateway’s callback URL and credentials, define the required keys under your desired gateway(s) in the gateways section of config/iran-payment.php

Usage

Create a Payment

You can create a new payment using the facade provided by the package:

Note: For the $gateway, refer to the gateway Key column in the List of Available Payment Gateways.

Checking API Call Status

In all calls to a gateway’s API (all methods in this package), you can check the latest status and response using the following methods:

Storing Payment Data

Automatic Store

The package can automatically store payments and keep them in sync during later API calls such as verification, or reversal.

If you prefer full control, Manual Store approach.

Enable automatic storage by chaining store() before calling create():

Notes:

• For automatic storage, you must publish and run the migration files. See Publish Vendor Files.
• If payment creation fails, no record will be stored.
• Once enabled, the package will automatically update the payment record in subsequent API calls.

Accessing the Stored Payment

After a payment is created, and during any subsequent API calls such as verify(), or reverse(), you can access the underlying payment model:

To see all available attributes, refer to src/Models/Payment.php

Tracking Payments via the Payable Model

When using automatic storage, add the AliYavari\IranPayment\Concerns\HasPayment trait to your payable model to track its payments:

Note: For more information about this relationship, see Eloquent relationships: one-to-many polymorphic.

Querying Stored Payments

The Payment model provides query scopes for common payment states:

Manual Store

If you want full control over storing and tracking payments, you can use these methods:

Redirect User to Payment Page

To redirect user to the gateway’s payment page, use the data provided by the following method:

Verification

Verify and Reverse

After the user is redirected back to your application from the gateway, you can verify the payment using these methods:

Notes:

• After calling verify(), or reverse(), you can use the methods in Checking API Call Status to check the result of the API call.
• If the payment was stored in the database using this package, these methods will automatically update the payment record. To access the underlying payment model, see Automatic Store

If you used the internal automatic storage

If you stored the payment manually,

To reverse the payment:

Notes:

• To get $callbackPayload, this package provides basic FormRequest classes to validate callback data. These classes are located in AliYavari\IranPayment\Requests\<Gateway>Request. See Form Request classes
• If auto-reverse is enabled, the Checking API Call Status applies to verification.

Successful Payment Details

If the payment is successful, the following methods are available to retrieve additional payment details:

Form Request Classes

To validate callback data from each gateway, this package provides simple FormRequest classes. You can use them like this (using the sep gateway as an example):

Available Form Request classes:

Verification Without Callback

Sometimes the user does not return to your website after completing the payment. In this case, you should use the noCallback() method instead of fromCallback(). All other steps remain the same.

If you are using Automatic Store, you can directly rebuild the gateway payment instance from the stored model:

Note: Some gateways (mainly Shaparak-based gateways) automatically reverse the transaction if the callback is not received, while others allow verification without a callback. This package applies each gateway’s rules internally.

Testing

For local development or automated tests, you can fake payment responses so no real transactions are made. This allows you to test success, failure, and connection errors safely.

Note: All methods are chainable. Examples below show single calls for clarity.

Faking a Gateway

Note: For the $gateway, refer to the gateway Key column in the List of Available Payment Gateways.

Defining Fake Behavior for create()

Note: If $redirectData is null, this default is returned:

Defining Fake Behavior for verify()

Note: The fake gateway does not validate gateway payloads or callback data. You can only simulate an invalid callback exception by explicitly forcing it:

Defining Fake Behavior for reverse()

Note: If you set behavior for the same gateway and method multiple times, only the last definition will take effect.

Contributing

Thank you for considering contributing to the Iran Payment Laravel! The contribution guide can be found in the CONTRIBUTING.md.

License

Iran Payment Laravel was created by Ali Mohammad Yavari under the MIT license.