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, or ^12.23

List of Available Payment Gateways

Gateway Name (EN)	Gateway Name (FA)	Gateway Website	Gateway Key	Version
Behpardakht	به پرداخت ملت	behpardakht.com	behpardakht	1.0.0
Sep	سامان کیش (سپ)	sep.ir	sep	1.0.0
Zarinpal	زرین پال	zarinpal.com	zarinpal	1.0.0
IDPay	آی دی پی	idpay.ir	id_pay	1.0.0
Pep	پرداخت الکترونیک پاسارگاد	[pep.co.ir]	pep	Unreleased

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:

composer require amyavari/iran-payment-laravel

Publish Vendor 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

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

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

# Default gateway
PAYMENT_GATEWAY=<default_gateway>

# Default application currency
APP_CURRENCY=<Toman or Rial>

# Whether to use sandbox mode instead of the real gateway
PAYMENT_USE_SANDBOX=<true or false>

# 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.
• 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:

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.

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

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():

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.
• 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:

$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

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.

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

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

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

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

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\<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:

// 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

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):

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use AliYavari\IranPayment\Http\Requests\SepRequest;
use App\Http\Controllers\Controller;
use Illuminate\Http\RedirectResponse;

final class SepVerificationController extends Controller
{
    public function update(SepRequest $request): RedirectResponse
    {
        $callbackData = $request->validated();

        // Verification logic, product delivery, etc.
    }
}

Available Form Request classes:

// Behpardakht
use AliYavari\IranPayment\Http\Requests\BehpardakhtRequest;

// Sep
use AliYavari\IranPayment\Http\Requests\SepRequest;

// Zarinpal
use AliYavari\IranPayment\Http\Requests\ZarinpalRequest;

// IDPay
use AliYavari\IranPayment\Http\Requests\IdPayRequest;

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.

use AliYavari\IranPayment\Facades\Payment;

$payment = Payment::gateway(string $gateway)->noCallback(string $transactionId);

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

$payment = $paymentModel->toGatewayPayment();

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

use AliYavari\IranPayment\Facades\Payment;
use AliYavari\IranPayment\Dtos\PaymentRedirectDto;

// Default gateway
$fake = Payment::fake();

// Specific gateway
$fake = Payment::fake($gateway);

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

Defining Fake Behavior for create()

$fake->successfulCreate($rawResponse = 'Creation raw response', $gatewayPayload = ['payload' => 'test value'], ?PaymentRedirectDto $redirectData = null);

$fake->failedCreate($rawResponse = 'Creation raw response', $errorCode = 0, $errorMessage = 'Creation failed');

$fake->failedConnectionCreate($message = 'Creation connection failed');

Notes:

• If $gatewayPayload is null, a gateway‑specific default payload (correct keys, dummy values) is used.
• If $redirectData is null, this default is returned:

'url'     => 'https://gateway.test',
'method'  => 'POST',
'payload' => ['status' => 'successful'],
'headers' => ['X-IranPayment-Fake' => 'true'],

Defining Fake Behavior for verify()

$fake->successfulVerify($rawResponse = 'Verification raw response', $refNumber = '123456789', $cardNumber = '1234-****-****-1234');

$fake->failedVerify($rawResponse = 'Verification raw response', $errorCode = 0, $errorMessage = 'Verification failed');

$fake->failedConnectionVerify($message = 'Verification connection failed');

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

$fake->invalidCallback($message = 'Invalid callback data');

Defining Fake Behavior for reverse()

$fake->successfulReverse($rawResponse = 'Reversal raw response');

$fake->failedReverse($rawResponse = 'Reversal raw response', $errorCode = 0, $errorMessage = 'Reversal failed');

$fake->failedConnectionReverse($message = 'Reverse connection failed');

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.