PHPackages                             amyavari/iran-payment-laravel - 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. amyavari/iran-payment-laravel

ActiveLibrary[Payment Processing](/categories/payments)

amyavari/iran-payment-laravel
=============================

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

v0.1.0(3mo ago)1299↓50%MITPHPPHP ^8.3CI failing

Since Feb 4Pushed 1mo agoCompare

[ Source](https://github.com/amyavari/iran-payment-laravel)[ Packagist](https://packagist.org/packages/amyavari/iran-payment-laravel)[ Docs](https://github.com/amyavari/iran-payment-laravel)[ RSS](/packages/amyavari-iran-payment-laravel/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (9)Versions (7)Used By (0)

Iran Payment Laravel
====================

[](#iran-payment-laravel)

[![](https://camo.githubusercontent.com/82876c68f3925a66c96aa2af9de37e7750a29811c34d4313d31c00fef101fdee/68747470733a2f2f62616e6e6572732e6265796f6e64636f2e64652f4972616e2532305061796d656e742532304c61726176656c2e706e673f7468656d653d6461726b267061636b6167654d616e616765723d636f6d706f7365722b72657175697265267061636b6167654e616d653d616d7961766172692532466972616e2d7061796d656e742d6c61726176656c267061747465726e3d617263686974656374267374796c653d7374796c655f31266465736372697074696f6e3d5061792b7468726f7567682b4972616e69616e2b7061796d656e742b67617465776179732b776974682b65617365266d643d312673686f7757617465726d61726b3d3126666f6e7453697a653d313030707826696d616765733d68747470732533412532462532466c61726176656c2e636f6d253246696d672532466c6f676f6d61726b2e6d696e2e737667)](https://camo.githubusercontent.com/82876c68f3925a66c96aa2af9de37e7750a29811c34d4313d31c00fef101fdee/68747470733a2f2f62616e6e6572732e6265796f6e64636f2e64652f4972616e2532305061796d656e742532304c61726176656c2e706e673f7468656d653d6461726b267061636b6167654d616e616765723d636f6d706f7365722b72657175697265267061636b6167654e616d653d616d7961766172692532466972616e2d7061796d656e742d6c61726176656c267061747465726e3d617263686974656374267374796c653d7374796c655f31266465736372697074696f6e3d5061792b7468726f7567682b4972616e69616e2b7061796d656e742b67617465776179732b776974682b65617365266d643d312673686f7757617465726d61726b3d3126666f6e7453697a653d313030707826696d616765733d68747470732533412532462532466c61726176656c2e636f6d253246696d672532466c6f676f6d61726b2e6d696e2e737667)

[![PHP Version](https://camo.githubusercontent.com/014c6947e50a1dd9d0efb0669017ebf691621453cb8d8651e859cde8d1a5e5f6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f616d7961766172692f6972616e2d7061796d656e742d6c61726176656c)](https://camo.githubusercontent.com/014c6947e50a1dd9d0efb0669017ebf691621453cb8d8651e859cde8d1a5e5f6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f616d7961766172692f6972616e2d7061796d656e742d6c61726176656c)[![Laravel Version](https://camo.githubusercontent.com/1afdfb8320fb2483db0127872177a4d58ab7e6381480ce60487b273a67e2e09d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f616d7961766172692f6972616e2d7061796d656e742d6c61726176656c2f696c6c756d696e617465253246636f6e7472616374733f6c6162656c3d4c61726176656c)](https://camo.githubusercontent.com/1afdfb8320fb2483db0127872177a4d58ab7e6381480ce60487b273a67e2e09d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f616d7961766172692f6972616e2d7061796d656e742d6c61726176656c2f696c6c756d696e617465253246636f6e7472616374733f6c6162656c3d4c61726176656c)[![Packagist Version](https://camo.githubusercontent.com/70d00e349d25e8e97b47d469e31ae6f10b765ce4352e110e59d666525dad0966/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616d7961766172692f6972616e2d7061796d656e742d6c61726176656c3f6c6162656c3d76657273696f6e)](https://camo.githubusercontent.com/70d00e349d25e8e97b47d469e31ae6f10b765ce4352e110e59d666525dad0966/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616d7961766172692f6972616e2d7061796d656e742d6c61726176656c3f6c6162656c3d76657273696f6e)[![Packagist Downloads](https://camo.githubusercontent.com/b601cdbcaa2a40bf02a092936f9d105bf1fd72ec83f8fa2d83c8619babd56a34/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616d7961766172692f6972616e2d7061796d656e742d6c61726176656c)](https://camo.githubusercontent.com/b601cdbcaa2a40bf02a092936f9d105bf1fd72ec83f8fa2d83c8619babd56a34/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616d7961766172692f6972616e2d7061796d656e742d6c61726176656c)[![Packagist License](https://camo.githubusercontent.com/b9078fb2bb9ac126edac637953423cde228c06f716b2a9c6effb503663ee8bc7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f616d7961766172692f6972616e2d7061796d656e742d6c61726176656c)](https://camo.githubusercontent.com/b9078fb2bb9ac126edac637953423cde228c06f716b2a9c6effb503663ee8bc7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f616d7961766172692f6972616e2d7061796d656e742d6c61726176656c)[![Tests](https://camo.githubusercontent.com/c6a771eba1d9a60495c0d3592da5109105fa1e95b59ec0882fc96c8d592121b7/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f616d7961766172692f6972616e2d7061796d656e742d6c61726176656c2f74657374732e796d6c3f6c6162656c3d7465737473)](https://camo.githubusercontent.com/c6a771eba1d9a60495c0d3592da5109105fa1e95b59ec0882fc96c8d592121b7/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f616d7961766172692f6972616e2d7061796d656e742d6c61726176656c2f74657374732e796d6c3f6c6162656c3d7465737473)

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

To view the Persian documentation, please refer to [README\_FA.md](./docs/README_FA.md).

برای مشاهده راهنمای فارسی، لطفاً به فایل [README\_FA.md](./docs/README_FA.md) مراجعه کنید.

Requirements
------------

[](#requirements)

- PHP version `8.3` or higher
- Laravel `^11.44`, or `^12.23`

List of Available Payment Gateways
----------------------------------

[](#list-of-available-payment-gateways)

Gateway Name (EN)Gateway Name (FA)Gateway WebsiteGateway KeyVersionBehpardakhtبه پرداخت ملت[behpardakht.com](https://behpardakht.com)`behpardakht`1.0.0Sepسامان کیش (سپ)[sep.ir](https://sep.ir)`sep`1.0.0Zarinpalزرین پال[zarinpal.com](https://zarinpal.com)`zarinpal`1.0.0IDPayآی دی پی[idpay.ir](https://idpay.ir)`id_pay`1.0.0Caution

Gateways have different rules for pending verifications and reversals. Please check [gateways\_note\_en.md](./docs/gateways_note_en.md).

Table of Contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Publish Vendor Files](#publish-vendor-files)
- [Configuration](#configuration)
- [Usage](#usage)
    - [Create a Payment](#create-a-payment)
    - [Checking API Call Status](#checking-api-call-status)
    - [Storing Payment Data](#storing-payment-data)
        - [Automatic Store](#automatic-store)
        - [Manual Store](#manual-store)
    - [Redirect User to Payment Page](#redirect-user-to-payment-page)
    - [Verification](#verification)
        - [Verify and Reverse](#verify-and-reverse)
        - [Successful Payment Details](#successful-payment-details)
        - [Form Request Classes](#form-request-classes)
        - [Verification Without Callback](#verification-without-callback)
- [Testing](#testing)
- [Contributing](#contributing)

Installation
------------

[](#installation)

To install the package via Composer, run:

```
composer require amyavari/iran-payment-laravel
```

Publish Vendor Files
--------------------

[](#publish-vendor-files)

### Publish All Files

[](#publish-all-files)

To publish all vendor files (config and migrations):

```
php artisan iran-payment:install
```

**Note:** To create tables from migrations:

```
php artisan migrate
```

### Publish Specific Files

[](#publish-specific-files)

To publish only the config file:

```
php artisan vendor:publish --tag=iran-payment-config
```

To publish only the migration file:

```
php artisan vendor:publish --tag=iran-payment-migrations
```

**Note:** To create tables from migrations:

```
php artisan migrate
```

Configuration
-------------

[](#configuration)

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

```
# Default gateway
PAYMENT_GATEWAY=

# Default application currency
APP_CURRENCY=

# Whether to use sandbox mode instead of the real gateway
PAYMENT_USE_SANDBOX=

# Per-gateway configuration (callback URL and credentials)
# See the "gateways" section in config/iran-payment.php
```

**Notes:**

- For the `PAYMENT_GATEWAY`, refer to the `gateway Key` column in the [List of Available Payment Gateways](#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](./config/iran-payment.php)

Usage
-----

[](#usage)

### Create a Payment

[](#create-a-payment)

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

```
use AliYavari\IranPayment\Facades\Payment;

// Using the default gateway (uses the callback URL from config)
$payment = Payment::create(int $amount, ?string $description = null, ?string|int $phone = null);

// Using the default gateway (define the callback URL at runtime)
$payment = Payment::callbackUrl(string $callbackUrl)->create(...);

// Using a specific gateway (uses the callback URL from config)
$payment = Payment::gateway(string $gateway)->create(...);

// Using a specific gateway (define the callback URL at runtime)
$payment = Payment::gateway(string $gateway)->callbackUrl(string $callbackUrl)->create(...);
```

**Note:** For the `$gateway`, refer to the `gateway Key` column in the [List of Available Payment Gateways](#list-of-available-payment-gateways).

### Checking API Call Status

[](#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:

```
$payment->successful();     // bool
$payment->failed();         // bool

// Get the error message (returns `null` if successful)
$payment->error();          // string|null

// Get the raw gateway response (useful for debugging)
$payment->getRawResponse(); // string|array
```

### Storing Payment Data

[](#storing-payment-data)

#### Automatic Store

[](#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](#manual-store) approach.

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

```
use AliYavari\IranPayment\Facades\Payment;

// Store the payment and associate it with a payable Eloquent model
Payment::store(Model $payable)->create(...);

Payment::{other configurations}->store(Model $payable)->create(...);
```

**Notes:**

- For automatic storage, you must publish and run the migration files. See [Publish Vendor Files](#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

[](#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:

```
$payment->getModel();      // \AliYavari\IranPayment\Models\Payment

// Access the associated payable model
$payment->getModel()->payable;
```

To see all available attributes, refer to [`src/Models/Payment.php`](./src/Models/Payment.php)

##### Tracking Payments via the Payable Model

[](#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:

```
// Example payable model (Course)
namespace App\Models;

use AliYavari\IranPayment\Concerns\HasPayment;
use Illuminate\Database\Eloquent\Model;

final class Course extends Model
{
    use HasPayment;

    //
}

// Payments relationship (MorphMany)
$course->payments(); // AliYavari\IranPayment\Models\Payment
```

**Note:** For more information about this relationship, see [Eloquent relationships: one-to-many polymorphic](https://laravel.com/docs/12.x/eloquent-relationships#one-to-many-polymorphic-relations).

##### Querying Stored Payments

[](#querying-stored-payments)

The `Payment` model provides query scopes for common payment states:

```
use AliYavari\IranPayment\Models\Payment as PaymentModel;

// Verified and successful payments
PaymentModel::query()->successful()->...

// Verified and failed payments
PaymentModel::query()->failed()->...

// Pending (unverified) payments
PaymentModel::query()->pending()->...

// Via a payable model using HasPayment
$course->payments()->successful()->...
$course->payments()->failed()->...
$course->payments()->pending()->...
```

#### Manual Store

[](#manual-store)

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

```
// Data required by the gateway for verification (`null` if payment creation failed)
$payment->getGatewayPayload();   // array|null

// Gateway key
$payment->getGateway();          // string

// Unique transaction ID used for tracking in your database (`null` if payment creation failed)
$payment->getTransactionId();    // string|null
```

### Redirect User to Payment Page

[](#redirect-user-to-payment-page)

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

```
$redirectData = $payment->getRedirectData(); // `null` if payment creation failed

// Redirect URL
$redirectData->url;         // string

// Redirect method (POST, GET)
$redirectData->method;      // string

// Redirect payload (POST body or GET query params)
$redirectData->payload;     // array

// Required HTTP headers
$redirectData->headers;     // array

// Get all redirect information as an array
$redirectData->toArray();   // array
```

### Verification

[](#verification)

#### Verify and Reverse

[](#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](#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](#automatic-store)

```
use AliYavari\IranPayment\Facades\Payment;

// Create a gateway instance from callback data
$payment = Payment::gateway(string $gateway)->fromCallback(array $callbackPayload);
```

If you used the internal automatic storage

```
// Call verify without any arguments
$payment->verify();
```

If you stored the payment manually,

```
// To find the payment in your database
$payment->getTransactionId();

// Call verify with the stored gateway payload
$payment->verify(array $gatewayPayload);
```

To reverse the payment:

```
// Reverse or refund the payment (call if verification fails)
$payment->reverse();

// Let the package handle reverse automatically when needed
$payment
  ->autoReverse(bool $autoReverse = true)
  ->verify(...); // Manual or automatic storage
```

**Notes:**

- To get `$callbackPayload`, this package provides basic `FormRequest` classes to validate callback data. These classes are located in `AliYavari\IranPayment\Requests\Request`. See [Form Request classes](#form-request-classes)
- If auto-reverse is enabled, the [Checking API Call Status](#checking-api-call-status) applies to **verification**.

#### Successful Payment Details

[](#successful-payment-details)

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

```
// Get the reference number assigned to the transaction by the bank. (`null` if payment verification failed)
$payment->getRefNumber();   // string|null

// Get user's card number used to pay. (`null` if payment verification failed)
$payment->getCardNumber();  // string|null
```

#### Form Request Classes

[](#form-request-classes)

To sanitize and 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):

```