### Install development dependencies

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/CONTRIBUTING.md

Run this command after cloning the fork to install all required project dependencies.

```bash
composer install
```

--------------------------------

### Install Package via Composer

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Run this command in your terminal to add the package to your Laravel project.

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

--------------------------------

### Publish Vendor Files

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Commands to publish configuration and migration files, followed by running migrations.

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

```bash
php artisan migrate
```

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

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

--------------------------------

### Create Gateway Instance from Callback

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Initializes a gateway instance using the callback data returned from the payment provider.

```php
use AliYavari
IranPayment
Facades
Payment;

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

--------------------------------

### Configure Environment Variables

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Set the default gateway, currency, and sandbox mode in your .env file.

```env
# 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
```

--------------------------------

### Create a Payment

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Use the Payment facade to initiate transactions with default or specific gateways and callback URLs.

```php
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(...);
```

--------------------------------

### Initialize a Fake Gateway

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Use the Payment facade to initialize a fake gateway for testing purposes.

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

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

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

--------------------------------

### Payment::fake()

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Initializes a fake gateway instance for testing purposes. You can optionally specify a gateway key to target a specific provider.

```APIDOC
## Payment::fake()

### Description
Initializes a fake gateway instance to intercept payment calls during testing.

### Parameters
- **gateway** (string) - Optional - The gateway key to fake. If omitted, the default gateway is used.
```

--------------------------------

### Payment::gateway()->fromCallback()

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Initializes a gateway instance from the callback data received after a user returns from the payment gateway.

```APIDOC
## Payment::gateway()->fromCallback()

### Description
Creates a gateway instance using the callback payload provided by the payment provider.

### Parameters
- **gateway** (string) - Required - The name of the payment gateway.
- **callbackPayload** (array) - Required - The data received from the gateway callback.
```

--------------------------------

### Run project tests

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/CONTRIBUTING.md

Execute the test suite to verify project integrity.

```bash
composer test
```

--------------------------------

### Run unit tests

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/CONTRIBUTING.md

Execute only the unit test suite.

```bash
composer test:unit
```

--------------------------------

### Define Fake Behavior for create()

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Simulate various outcomes for the create operation, including success, failure, and connection errors.

```php
$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');
```

--------------------------------

### Check types

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/CONTRIBUTING.md

Run static type analysis on the codebase.

```bash
composer test:types
```

--------------------------------

### Payment::gateway()->noCallback()

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Initializes a gateway instance when the user does not return to the website.

```APIDOC
## Payment::gateway()->noCallback()

### Description
Used when the user does not return to the website after payment. 

### Parameters
- **gateway** (string) - Required - The name of the payment gateway.
- **transactionId** (string) - Required - The transaction ID.
```

--------------------------------

### Payment::create

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Initiates a new payment request through a specified or default gateway.

```APIDOC
## Payment::create

### Description
Creates a new payment instance. You can chain configuration methods like `gateway()` or `callbackUrl()` before calling `create()`.

### Parameters
- **amount** (int) - Required - The payment amount.
- **description** (string) - Optional - A description for the payment.
- **phone** (string|int) - Optional - The user's phone number.

### Usage
```php
use AliYavari
IranPayment
Facades\Payment;

$payment = Payment::create(10000, 'Order #123', '09120000000');
$payment = Payment::gateway('zarinpal')->callbackUrl('https://example.com/callback')->create(10000);
```
```

--------------------------------

### Lint project code

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/CONTRIBUTING.md

Execute the linter to ensure code style compliance.

```bash
composer lint
```

--------------------------------

### Define Fake Behavior for reverse()

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Simulate reversal outcomes for payment transactions.

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

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

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

--------------------------------

### Define Fake Behavior for verify()

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Simulate verification outcomes and force invalid callback exceptions.

```php
$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');
```

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

--------------------------------

### Enable Automatic Payment Storage

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Chain the store method before creating a payment to associate it with an Eloquent model.

```php
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(...);
```

--------------------------------

### Default Redirect Data for Fake create()

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

The default structure returned when redirect data is not explicitly provided.

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

--------------------------------

### Fake Behavior Methods

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Methods to define the behavior of the fake gateway for create, verify, and reverse operations.

```APIDOC
## Fake Behavior Methods

### Create Operations
- **successfulCreate($rawResponse, $gatewayPayload, $redirectData)**: Simulates a successful payment creation.
- **failedCreate($rawResponse, $errorCode, $errorMessage)**: Simulates a failed payment creation.
- **failedConnectionCreate($message)**: Simulates a connection failure during creation.

### Verify Operations
- **successfulVerify($rawResponse, $refNumber, $cardNumber)**: Simulates a successful verification.
- **failedVerify($rawResponse, $errorCode, $errorMessage)**: Simulates a failed verification.
- **failedConnectionVerify($message)**: Simulates a connection failure during verification.
- **invalidCallback($message)**: Simulates an invalid callback exception.

### Reverse Operations
- **successfulReverse($rawResponse)**: Simulates a successful reversal.
- **failedReverse($rawResponse, $errorCode, $errorMessage)**: Simulates a failed reversal.
- **failedConnectionReverse($message)**: Simulates a connection failure during reversal.
```

--------------------------------

### Verify Payment with Automatic Storage

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Verifies a payment when the package's internal automatic storage is used.

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

--------------------------------

### Available FormRequest Classes

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Lists the available FormRequest classes for different payment gateways.

```php
// 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;

// Pep
use AliYavari\IranPayment\Http\Requests\PepRequest;

// Sadad
use AliYavari\IranPayment\Http\Requests\SadadRequest;

// Zibal
use AliYavari\IranPayment\Http\Requests\ZibalRequest;

// PayPing
use AliYavari\IranPayment\Http\Requests\PaypingRequest;

// NextPay
use AliYavari\IranPayment\Http\Requests\NextpayRequest;
```

--------------------------------

### $payment->verify()

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Verifies the payment transaction status.

```APIDOC
## $payment->verify()

### Description
Verifies the payment. If automatic storage is used, no arguments are required. If stored manually, the gateway payload must be provided.

### Parameters
- **gatewayPayload** (array) - Optional - The stored gateway payload if manual storage was used.
```

--------------------------------

### Redirect User to Payment Gateway

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Retrieve the necessary URL, method, and payload to redirect the user to the payment provider.

```php
$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
```

--------------------------------

### Verify Without Callback

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Handles verification when the user does not return to the website, using the transaction ID or a stored model.

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

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

```php
$payment = $paymentModel->toGatewayPayment();
```

--------------------------------

### Payment::store

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Enables automatic storage of payment records associated with an Eloquent model.

```APIDOC
## Payment::store

### Description
Enables automatic database storage for the payment. Must be chained before `create()`.

### Parameters
- **payable** (Model) - Required - The Eloquent model to associate the payment with.

### Usage
```php
Payment::store($course)->create(10000);
```
```

--------------------------------

### Verify Payment with Manual Storage

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Verifies a payment when the transaction was stored manually in the database.

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

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

--------------------------------

### Retrieve Successful Payment Details

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Retrieves the bank reference number and user card number after a successful verification.

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

--------------------------------

### Payment::getRedirectData

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Retrieves the necessary data to redirect the user to the payment gateway.

```APIDOC
## Payment::getRedirectData

### Description
Returns an object containing the URL, method, payload, and headers required to redirect the user to the gateway.

### Returns
- **url** (string) - The gateway URL.
- **method** (string) - The HTTP method (POST/GET).
- **payload** (array) - The request body or query parameters.
- **headers** (array) - Required HTTP headers.
```

--------------------------------

### Track Payments with HasPayment Trait

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Implement the HasPayment trait in your Eloquent model to enable polymorphic payment relationships.

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

--------------------------------

### $payment->reverse()

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Reverses or refunds a payment transaction.

```APIDOC
## $payment->reverse()

### Description
Reverses or refunds the payment. This should be called if verification fails.
```

--------------------------------

### Payment Status and Response

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Methods to check the outcome of a payment request and retrieve raw gateway data.

```APIDOC
## Payment Status Methods

### Description
Methods to verify if the payment request was successful or failed, and to retrieve error messages or raw responses.

### Methods
- **successful()** (bool) - Returns true if the request was successful.
- **failed()** (bool) - Returns true if the request failed.
- **error()** (string|null) - Returns the error message if failed.
- **getRawResponse()** (string|array) - Returns the raw response from the gateway.
```

--------------------------------

### Access Stored Payment Data

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Retrieve the underlying payment model and its associated payable model after a payment is created.

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

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

--------------------------------

### Reverse or Auto-Reverse Payment

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Reverses a payment manually or configures the package to handle it automatically during verification.

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

--------------------------------

### Manual Payment Data Retrieval

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Access raw gateway data and transaction identifiers when managing storage manually.

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

--------------------------------

### Query Stored Payments

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Use built-in query scopes to filter payments by their status.

```php
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()->...
```

--------------------------------

### $payment->getCardNumber()

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Retrieves the user's card number.

```APIDOC
## $payment->getCardNumber()

### Description
Returns the user's card number used for the payment. Returns null if verification failed.
```

--------------------------------

### $payment->getRefNumber()

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Retrieves the reference number assigned by the bank.

```APIDOC
## $payment->getRefNumber()

### Description
Returns the reference number assigned to the transaction by the bank. Returns null if verification failed.
```

--------------------------------

### Check API Call Status

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Verify the outcome of gateway API calls and retrieve error messages or raw responses for debugging.

```php
$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
```

--------------------------------

### Validate Callback Data with FormRequest

Source: https://github.com/amyavari/iran-payment-laravel/blob/main/README.md

Uses a FormRequest class to validate incoming callback data in a controller.

```php
<?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.
    }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.