Parsisolution Gateway

https://github.com/parsisolution/gateway
Admin
Parsisolution Gateway is a Laravel package for connecting to all Iranian payment gateways.
Tokens:82,924
Snippets:511
Trust Score:4.6
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/parsisolution/gateway/blob/master/README.md

Run this command to install the parsisolution/gateway package via Composer.

```bash
composer require parsisolution/gateway
```

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

### Gateway::of() usage examples

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/gateway-manager.md

Shows how to resolve built-in, case-insensitive, and custom drivers via the facade. The 'idpay2' example refers to a custom driver registered via extendUsing.

```php
$gateway = Gateway::of('mellat');            // built-in
$gateway = Gateway::of('PayIR');             // case-insensitive matching
$gateway = Gateway::of('idpay2');            // custom driver registered via extendUsing
```

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

### Create and authorize a payment transaction with PayIR

Source: https://github.com/parsisolution/gateway/blob/master/README.md

Walks through creating a PayIR gateway, setting callback URL, enabling stateless mode, building a RequestTransaction with amount and extra fields, authorizing it, and redirecting the user. Amount is in Toman by default; use IRR for Riyal. In stateless mode, transaction ID and required parameters come from the callback URL, and the same stateless value must be used in the callback. The example also shows retrieving supported extra fields and handling the redirect response for APIs or web flows.

```php
try {
    $gateway = Gateway::of('PayIR'); // $gateway = new Payir(app(), config('gateways.payir')); 
    $gateway->callbackUrl(route('callback')); // You can change the callback
    
    // You can make it stateless.
    // in default mode it uses session to store and retrieve transaction id 
    // (and other gateway specific or user provided (using $gateway->with) required parameters)
    // but in stateless mode it gets transaction id and other required parameters from callback url
    // Caution: you should use same stateless value in callback too
    $gateway->stateless();
    
    // You can get supported extra fields sample for each gateway and then set these fields with your desired values
    // (most gateways support `mobile` field)
    $supportedExtraFieldsSample = $gateway->getSupportedExtraFieldsSample();
    
    return compact('supportedExtraFieldsSample');

    // Then you should create a transaction to be processed by the gateway
    // Amount is in `Toman` by default, but you can set the currency in second argument as well. IRR (for `Riyal`)
    $transaction = new RequestTransaction(new Amount(12000)); // 12000 Toman
    $transaction->setExtra([
        'mobile' => '09124441122',
        'email'  => 'ali@gmail.com',
        'person' => 12345,
    ]);
    $transaction->setExtraField('description', 'توضیحات من');
    
    // if you added additional fields in your migration you can assign a value to it in the beginning like this
    $transaction['person_id'] = auth()->user()->id;
    
    $authorizedTransaction = $gateway->authorize($transaction);

    $transactionId = $authorizedTransaction->getId(); // شماره‌ی تراکنش در جدول پایگاه‌داده
    $orderId = $authorizedTransaction->getOrderId(); // شماره‌ی تراکنش اعلامی به درگاه
    $referenceId = $authorizedTransaction->getReferenceId(); // شناسه‌ی تراکنش در درگاه (در صورت وجود)
    $token = $authorizedTransaction->getToken(); // توکن درگاه (در صورت وجود)

    // در اینجا
    // شماره تراکنش(ها) را با توجه به نوع ساختار پایگاه‌داده‌ی خود 
    // در جداول مورد نیاز و بسته به نیاز سیستم‌تان ذخیره کنید.

    // this object tells us how to redirect to gateway
    $redirectResponse = $authorizedTransaction->getRedirect();

    // if you're developing an Api just return it and handle redirect in your frontend
    // (this gives you redirect method [get or post], url and fields)
    // (you can use a code like `redirector.blade.php`)
    return $redirectResponse;

    // otherwise use this solution to redirect user to gateway with proper response
    return $redirectResponse->redirect(app());

} catch (\Exception $e) {

    echo $e->getMessage();
}
```

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

### Publish Vendor Files

Source: https://github.com/parsisolution/gateway/blob/master/README.md

Publishes the gateway service provider configuration using Artisan.

```bash
php artisan vendor:publish --provider="Parsisolution\Gateway\GatewayServiceProvider"
```

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

### Run Database Migrations

Source: https://github.com/parsisolution/gateway/blob/master/README.md

Executes the database migrations required by the gateway package.

```bash
php artisan migrate
```

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

### Usage example for Gateway::of('PayIR') with callbackUrl, stateless, and with

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/abstract-provider.md

Shows how to configure a provider instance: override the configured callback URL, switch to stateless mode, and add extra query-string parameters that will be carried to the callback.

```php
$gateway = Gateway::of('PayIR');
$gateway->callbackUrl(route('callback')); // override configured callback
$gateway->stateless();                    // make it stateless
$gateway->with(['foo' => 'bar']);         // extra query-string params carried to the callback
```

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

### Create Gateway instance with Gateway::of or new Mellat

Source: https://github.com/parsisolution/gateway/blob/master/README.md

Shows three ways to obtain a Mellat gateway instance: via the Gateway facade, with the default config, or with an inline config array. Use this before creating a payment transaction.

```php
$gateway = Gateway::of('mellat');

$gateway = new Mellat(app(), config('gateways.mellat'));

$gateway = new Mellat(app(), [
    'username'    => '',
    'password'    => '',
    'terminal-id' => '',
]);
```

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

### Example: Gateway::settle with stateless callback and extra fields

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/gateway-manager.md

Shows how to call settle in stateless mode while persisting an extra field (person_id) on success. The first argument true enables stateless mode, and the second array contains fields to update on the transaction.

```php
$settled = Gateway::settle(true, ['person_id' => 333]); // stateless callback + extra fields to persist
```

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

### SoapClient usage example with bpPayRequest

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/core-helpers.md

Shows how to instantiate SoapClient with a WSDL URL and provider config, then call a SOAP method. The call retries twice on SoapFault per the config default.

```php
$soap = new SoapClient('https://bpm.shaparak.ir/pgwchannel/services/pgw?wsdl', $this->soapConfig());
$response = $soap->bpPayRequest($fields);   // retries twice on SoapFault per config default
```

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

### Factory::driver($driver = null)

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/types.md

Get a Gateway provider implementation for the given driver. Returns a Provider instance.

```APIDOC
## Factory::driver($driver = null)

### Description
Get a Gateway provider implementation for the given driver. Returns a Provider instance.

### Method
driver

### Parameters
- **$driver** (string) - Optional - The driver name. Defaults to null.

### Returns
- **\Parsisolution\Gateway\Contracts\Provider** - The provider implementation.
```

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

### Amount usage example

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/transactions.md

Shows how to instantiate Amount with Toman or Riyal, convert between currencies, and compare across IRT/IRR. The equals() call returns true because cross-IRT/IRR comparison works.

```php
$amount = new Amount(12000);          // 12,000 Toman
$amount = new Amount(120000, 'IRR');  // 120,000 Riyal
echo $amount->getRiyal();             // 120000
echo $amount->getToman();             // 12000

if ($amount->equals(new Amount(120000, 'IRR'))) { /* true — cross-IRT/IRR comparison works */ }
```

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

### Usage examples for availableDrivers(), getDriverName(), activeDrivers()

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/gateway-manager.md

Shows expected return values: availableDrivers() yields numeric ids like [1, 2, 3, ..., 50]; getDriverName(22) returns 'ZARINPAL'; activeDrivers('پرداخت با ') returns only drivers with config 'active' => true.

```php
$ids = Gateway::availableDrivers();          // [1, 2, 3, ..., 50]
$name = Gateway::getDriverName(22);          // 'ZARINPAL'
$active = Gateway::activeDrivers('پرداخت با '); // only drivers with config 'active' => true
```

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

### Transaction::getAmount()

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/types.md

Get the transaction amount. Returns an Amount object.

```APIDOC
## Transaction::getAmount()

### Description
Get the transaction amount. Returns an Amount object.

### Method
getAmount

### Returns
- **Amount** - The transaction amount.
```

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

### Transaction::getExtra()

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/types.md

Get the extra fields of the transaction. Returns an array.

```APIDOC
## Transaction::getExtra()

### Description
Get the extra fields of the transaction. Returns an array.

### Method
getExtra

### Returns
- **array** - The extra fields.
```

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

### SettledTransaction usage example

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/transactions.md

Example of retrieving a settled transaction via Gateway::settle(true) and accessing its properties, including getId, getAmount (returns Amount), getExtra (returns array), getReferenceId, getTraceNumber, getCardNumber, getRRN, and array access for person_id (extra fields updated on success).

```php
$settled = Gateway::settle(true);
$id = $settled->getId();
$amount = $settled->getAmount();             // Amount
$extra = $settled->getExtra();               // array
$referenceId = $settled->getReferenceId();
$traceNumber = $settled->getTraceNumber();
$cardNumber = $settled->getCardNumber();
$rrn = $settled->getRRN();
$personId = $settled['person_id'];           // extra fields updated on success (array access)
```

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

### RedirectResponse::getType

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/core-helpers.md

Returns the redirect type, either 'Get' or 'Post'.

```APIDOC
## Method: getType

### Description
Returns the redirect type, either 'Get' or 'Post'.

### Method
GET

### Signature
`public function getType()`

### Return Value
- **string** - 'Get' or 'Post'

### Example
```php
$type = $redirect->getType();
```
```

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

### HasId::getId()

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/types.md

Get the unique identifier of the transaction. Returns a string.

```APIDOC
## HasId::getId()

### Description
Get the unique identifier of the transaction. Returns a string.

### Method
getId

### Returns
- **string** - The unique identifier of the transaction.
```

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

### TransactionDao usage example with find and exception handling

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/core-helpers.md

Shows how to create a transaction and then find it by order ID. The find method throws NotFoundTransactionException if the order_id is missing, and RetryException if the transaction is already settled (e.g., payer refreshed the callback page).

```php
$dao = new TransactionDao(app('db'), 'gateway_transactions');
$unauthorized = $dao->create($requestTransaction, 1, request()->ip());
try {
    $authorized = $dao->find($unauthorized->getOrderId());
} catch (\Parsisolution\Gateway\Exceptions\NotFoundTransactionException $e) {
    // no such order_id
} catch (\Parsisolution\Gateway\Exceptions\RetryException $e) {
    // already settled — the payer likely refreshed the callback page
}
```

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

### RequestTransaction usage example

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/transactions.md

Creates a transaction for 12000 Toman, sets mobile and email via setExtra, and adds a description via setExtraField.

```php
$transaction = new RequestTransaction(new Amount(12000));   // 12000 Toman
$transaction->setExtra([
    'mobile' => '09124441122',
    'email'  => 'ali@gmail.com',
]);
$transaction->setExtraField('description', 'توضیحات من');
```

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

### Curl::execute usage example with custom headers

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/core-helpers.md

Shows how to call Curl::execute() with a URL, fields array, resultAsArray true, and custom CURLOPT_HTTPHEADER options. The response is destructured into $result, $http_code, and $error.

```php
[$result, $http_code, $error] = Curl::execute('https://api.idpay.ir/v1.1/payment', $fields, true, [
    CURLOPT_HTTPHEADER => ['X-API-KEY: my-key', 'X-SANDBOX: false'],
]);
```

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

### RedirectResponse type constants

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/core-helpers.md

Defines the two redirect types: GET and POST. These constants are used as the $type parameter in the constructor.

```php
const TYPE_GET = 'Get';
const TYPE_POST = 'Post';
```

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

### Transaction::getAttributes()

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/types.md

Get the full attribute bag of the transaction. Returns an array.

```APIDOC
## Transaction::getAttributes()

### Description
Get the full attribute bag of the transaction. Returns an array.

### Method
getAttributes

### Returns
- **array** - The full attribute bag.
```

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

### Curl::execute

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/core-helpers.md

Executes an HTTP GET or POST request using cURL with configurable options. Returns an array containing the decoded response, HTTP status code, and any cURL error.

```APIDOC
## Curl::execute

### Description
Executes an HTTP GET or POST request using cURL with configurable options. Returns an array containing the decoded response, HTTP status code, and any cURL error.

### Method
POST (default) or GET

### Signature
```php
public static function execute(
    string $url,
    array $fields,
    bool $resultAsArray = true,
    array $options = [],
    string $method = self::METHOD_POST
): array
```

### Parameters
- **$url** (string) - Required - Request URL
- **$fields** (array) - Required - Payload; POST → `json_encode($fields)`, GET → `http_build_query($fields)`
- **$resultAsArray** (bool) - Optional (default `true`) - Decode JSON response as array (`true`) or object (`false`)
- **$options** (array) - Optional (default `[]`) - Extra `curl_setopt` constants, merged over the defaults (e.g. `CURLOPT_HTTPHEADER`)
- **$method** (string) - Optional (default `self::METHOD_POST`) - `'GET'` or `'POST'`

### Returns
- **array** - `[$result, $http_code, $error]` — decoded response (`null` when not JSON), `CURLINFO_HTTP_CODE` int, and `curl_error()` string.

### Default Options
- `CURLOPT_URL`
- `CURLOPT_RETURNTRANSFER => true`
- `CURLOPT_ENCODING => ''`
- `CURLOPT_MAXREDIRS => 10`
- `CURLOPT_TIMEOUT => 0`
- `CURLOPT_FOLLOWLOCATION => true`
- `CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1`
- `CURLOPT_CUSTOMREQUEST` (`null` for GET)
- `CURLOPT_HTTPHEADER` (`Accept: application/json` for GET; plus `Content-Type: application/json` for POST)
- `CURLOPT_POSTFIELDS` (query string for GET, JSON for POST; omitted entirely for an empty GET)

### Example
```php
[$result, $http_code, $error] = Curl::execute('https://api.idpay.ir/v1.1/payment', $fields, true, [
    CURLOPT_HTTPHEADER => ['X-API-KEY: my-key', 'X-SANDBOX: false'],
]);
```
```

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

### RedirectResponse shape

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/types.md

RedirectResponse toArray() shape with type ('Get' or 'Post'), url, and data (hidden POST fields). Returned by AuthorizedTransaction::getRedirect(); serializable for API frontends.

```php
// toArray()
['type' => string, 'url' => string, 'data' => array|null]
```

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

### Parsisolution\Gateway\SoapClient::__construct

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/configuration.md

Constructor for the SOAP client wrapper. Initializes the SOAP client with server URL, configuration, and options.

```APIDOC
## Parsisolution\Gateway\SoapClient::__construct

### Description
Constructor for the SOAP client wrapper. Initializes the SOAP client with server URL, configuration, and options.

### Method
Constructor

### Signature
`Parsisolution\Gateway\SoapClient::__construct($soapServer, array $config, array $options = [])`

### Parameters
- `$soapServer` (mixed) - Required - The SOAP server URL or WSDL.
- `$config` (array) - Required - The driver configuration, or its `settings.soap` portion. Supports `attempts` (intval(...) ?: 1) for SOAP retry count.
- `$options` (array) - Optional - Options passed to native `SoapClient` (e.g., `['encoding' => 'UTF-8']`, or NextPay's `settings.soap.options`).
```

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

### AbstractProvider::__construct

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/configuration.md

Constructor for the abstract provider class. Initializes a gateway provider with the application container, provider ID, and configuration array.

```APIDOC
## AbstractProvider::__construct

### Description
Constructor for the abstract provider class. Initializes a gateway provider with the application container, provider ID, and configuration array.

### Method
Constructor

### Signature
`AbstractProvider::__construct(Illuminate\Container\Container $app, $id, array $config)`

### Parameters
- `$app` (Illuminate\Container\Container) - Required - The Laravel application container.
- `$id` (mixed) - Required - The provider ID (e.g., `GatewayManager::MELLAT`).
- `$config` (array) - Required - The driver configuration array (same keys as the config file table).

### Notes
- When built through `GatewayManager::buildProvider()`, `formatConfig()` ensures `callback-url` and `settings.soap` exist before construction.
- The README documents two-argument construction (`new Mellat(app(), config('gateways.mellat'))`); the current source constructor requires three arguments `($app, $id, $config)`. Use `Gateway::of('mellat')` or pass all three: `new Mellat(app(), GatewayManager::MELLAT, config('gateways.mellat'))`.
```

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

### AbstractProvider::with(array $parameters)

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/configuration.md

Adds extra parameters to the callback URL query string.

```APIDOC
## AbstractProvider::with(array $parameters)

### Description
Adds extra parameters to the callback URL query string.

### Method
`with`

### Parameters
- **$parameters** (array) - Required - Associative array of extra query parameters.

### Returns
- (void) - No return value specified.
```

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

### buildProvider() method signature

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/gateway-manager.md

Declares the method that builds a Gateway provider instance from a driver id and provider class FQCN. Throws GatewayException on failure.

```php
/**
 * Build a Gateway provider instance.
 *
 * @throws GatewayException
 */
public function buildProvider(int $id, string $provider): AbstractProvider
```

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

### Public configuration method signatures with docblocks

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/abstract-provider.md

Lists the public configuration methods available on the abstract provider: callbackUrl, getCallback, setRequest, stateless, with, and getSupportedExtraFieldsSample. Each method includes its docblock and signature as shown in the source.

```php
/**
 * {@inheritdoc}
 */
public function callbackUrl($url)

/**
 * Gets callback url
 *
 * @param  bool  $encode
 * @return string
 */
public function getCallback(UnAuthorizedTransaction $transaction, $encode = false)

/**
 * Set the request instance.
 *
 * @return self
 */
public function setRequest(Request $request)

/**
 * Indicates that the provider should operate as stateless.
 *
 * @return self
 */
public function stateless()

/**
 * Set the custom parameters of the request.
 *
 * @return self
 */
public function with(array $parameters)

/**
 * Get supported extra fields sample
 *
 * @return array
 */
public function getSupportedExtraFieldsSample()
```

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

### Transaction::getExtraField($key, $default = null)

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/types.md

Get a single extra field by (dot) key. Returns the value or the default if not found.

```APIDOC
## Transaction::getExtraField($key, $default = null)

### Description
Get a single extra field by (dot) key. Returns the value or the default if not found.

### Method
getExtraField

### Parameters
- **$key** (string) - Required - The dot-notation key of the extra field.
- **$default** (mixed) - Optional - The default value if the key is not found.

### Returns
- **mixed** - The value of the extra field or the default.
```

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

### buildProvider($id, $provider)

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/gateway-manager.md

Builds a Gateway provider instance from the given ID and provider class.

```APIDOC
## buildProvider($id, $provider)

### Description
Builds a Gateway provider instance from the given ID and provider class.

### Method
buildProvider(int $id, string $provider): AbstractProvider

### Parameters
- **$id** (int) - Required - One of the driver-id constants.
- **$provider** (string) - Required - Provider class FQCN, e.g. Mellat::class.

### Returns
- **AbstractProvider** - The provider instance.

### Exceptions
- **GatewayException** - Thrown when the config is missing (NullConfigException).

### Description
Reads the config at `config('gateways.<strtolower(driverName)>')`; throws `NullConfigException` when missing. Otherwise returns `new $provider(app(), $id, $this->formatConfig($config))`.
```

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

### FieldsToMatch usage in validateSettlementRequest

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/transactions.md

Example of constructing FieldsToMatch inside a provider's validateSettlementRequest method, passing request inputs for OrderId, Token, and Amount with currency 'IRR'.

```php
// in a provider's validateSettlementRequest:
return new FieldsToMatch($request->input('OrderId'), null, $request->input('Token'),
    new Amount($request->input('Amount'), 'IRR'));
```

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

### DigiPayGateway public client class

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/providers-third-party.md

Public client class for DigiPay OAuth2 + REST integration. Constructor accepts settings with keys username, password, client_id, client_secret, access_token, refresh_token, live_api (bool), and type (UPG|IPG|WPG). authenticate() returns bool; createTicket() returns ['url' => ..., 'ticket' => ...] and throws DigiPayException; verifyTicket() returns decoded response array and throws DigiPayException.

```php
class DigiPayGateway
{
    public function __construct($settings, $tokenUpdaterHook = null)
    // settings keys: username, password, client_id, client_secret, access_token,
    //                refresh_token, live_api (bool), type (UPG|IPG|WPG)

    public function authenticate($refreshToken = true): bool
    public function createTicket($amount, $providerId, $redirectUrl, $cellNumber = null)
    // returns ['url' => ..., 'ticket' => ...]; throws DigiPayException
    public function verifyTicket($trackingCode)
    // returns decoded response array; throws DigiPayException
}
```

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

### RedirectResponse constructor and getters

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/core-helpers.md

Constructor accepts type, URL, and optional data array. Getters return the type, URL, and data (POST fields only meaningful for type 'Post').

```php
/**
 * RedirectResponse constructor.
 *
 * @param  string  $type
 * @param  string  $url
 * @param  array  $data
 */
public function __construct($type, $url, array $data = null)

public function getType()   // string — 'Get' | 'Post'
public function getUrl()    // string — gateway URL
public function getData()   // array|null — POST fields (only meaningful for type 'Post')
```

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

### Provider::callbackUrl($url)

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/types.md

Set an optional callback URL override. Falls back to config if not set.

```APIDOC
## Provider::callbackUrl($url)

### Description
Set an optional callback URL override. Falls back to config if not set.

### Method
callbackUrl

### Parameters
- **$url** (string) - Required - The callback URL.

### Returns
- **self** - The provider instance.
```

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

### with(array $parameters)

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/abstract-provider.md

Sets additional parameters that are merged into the callback URL query string.

```APIDOC
## with(array $parameters)

### Description
Sets additional parameters that are merged into the callback URL query string.

### Method
with

### Parameters
- **$parameters** (array) - Required - The additional parameters to include.

### Returns
- **self** - The provider instance for chaining.

```

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

### formatConfig() and formatCallbackUrl() method signatures

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/gateway-manager.md

Declares the configuration formatting methods. formatConfig merges defaults into the driver config; formatCallbackUrl resolves a leading-`/` URI through app('url')->to() and leaves absolute URLs untouched.

```php
/**
 * Format the server configuration.
 *
 * @return array
 */
public function formatConfig(array $config)

/**
 * Format the callback URL, resolving a relative URI if needed.
 *
 * @return string
 */
protected function formatCallbackUrl(array $config)
```

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

### Comparable interface with compareTo method

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/types.md

Defines a contract for comparing objects, returning an integer indicating order. Throws UncomparableException when comparison is not possible.

```php
interface Comparable
{
    /**
     * @param  mixed  $value
     * @return int
     *     Negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the
     *     specified value.
     *
     * @throws UncomparableException
     */
    public function compareTo($value);
}
```

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

### API consumer serialization usage

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/core-helpers.md

Serializes the redirect data for frontend handling. The output array contains type, url, and data fields; example shows a POST redirect to asan.shaparak.ir with RefId and mobileap fields.

```php
// API consumers — serialize and redirect on the frontend:
return $authorizedTransaction->getRedirect()->toArray();
// => ['type' => 'Post', 'url' => 'https://asan.shaparak.ir', 'data' => ['RefId' => '...', 'mobileap' => null]]
```

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

### of() method with docblock

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/gateway-manager.md

Resolves a driver by name, delegating to Manager::driver(). Throws NullConfigException if no gateways.<driver> config exists for a built-in driver, and InvalidArgumentException if a driver is requested with no name.

```php
/**
 * Get a driver instance.
 *
 * @param  string  $driver
 * @return \Parsisolution\Gateway\AbstractProvider
 */
public function of($driver)
```

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

### createMellatDriver() method signature

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/gateway-manager.md

All 31 driver creation methods share this exact signature. Each calls buildProvider() with the corresponding provider class.

```php
protected function createMellatDriver()
```

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

### Provider interface with callbackUrl, authorize, settle

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/types.md

Defines the contract for Gateway providers. Implemented by AbstractProvider and every driver class. Methods may throw various exceptions as documented.

```php
interface Provider
{
    public function callbackUrl($url);

    public function authorize(RequestTransaction $transaction);

    public function settle(AuthorizedTransaction $authorizedTransaction, $fieldsToUpdateOnSuccess);
}
```

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

### AbstractProvider::setRequest(Request $request)

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/configuration.md

Replaces the request used during settle.

```APIDOC
## AbstractProvider::setRequest(Request $request)

### Description
Replaces the request used during settle.

### Method
`setRequest`

### Parameters
- **$request** (Request) - Required - The new request object.

### Returns
- (void) - No return value specified.
```

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

### formatConfig($config)

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/gateway-manager.md

Formats the server configuration by merging defaults into the driver config.

```APIDOC
## formatConfig($config)

### Description
Formats the server configuration by merging defaults into the driver config.

### Method
formatConfig(array $config)

### Parameters
- **$config** (array) - Required - The driver configuration array.

### Returns
- **array** - The formatted configuration array.

### Description
Merges defaults into the driver config: `'callback-url' => $this->formatCallbackUrl($config)` (which resolves a leading-`/` URI through `app('url')->to()` and leaves absolute URLs untouched) and `'settings' => ['soap' => Arr::get(app()['config'], 'soap', [])]`. Note that the `soap` key is read from the root of the config repository as written in the source (`config('soap')`, not `config('gateways.soap')`); if no such root key exists this resolves to `[]`.
```

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

### Comparable::compareTo($value)

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/types.md

Compares this object with the specified value for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified value.

```APIDOC
## Comparable::compareTo($value)

### Description
Compares this object with the specified value for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified value.

### Method
compareTo

### Parameters
- **$value** (mixed) - Required - The value to compare against.

### Returns
- **int** - Negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified value.

### Throws
- **UncomparableException** - If the comparison cannot be made.
```

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

### AbstractProvider::__construct

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/abstract-provider.md

Creates a new provider instance with the given application container, provider ID, and configuration.

```APIDOC
## [METHOD] __construct

### Description
Creates a new provider instance with the given application container, provider ID, and configuration.

### Method
__construct

### Parameters
#### Parameters
- **$app** (Illuminate\Container\Container) - Required - Laravel application container.
- **$id** (int) - Required - Provider ID (one of the GatewayManager driver constants or a custom ID).
- **$config** (array) - Required - Driver configuration; GatewayManager::buildProvider() passes formatConfig($config) which guarantees callback-url and settings.soap.

```

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

### extendUsing() method signature

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/gateway-manager.md

Declares the method that registers a custom driver creator Closure. It takes a driver key, a numeric id that must match the provider's getProviderId(), and a fully-qualified AbstractProvider subclass name.

```php
/**
 * Register a custom driver creator Closure.
 */
public function extendUsing(string $driver, int $id, string $provider): self
```

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

### Basic authorize call and settle callback with provider error handling

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/abstract-provider.md

Shows a typical usage: create a `RequestTransaction` with an `Amount`, set extra data, call `$gateway->authorize($transaction)`, then redirect using the returned `AuthorizedTransaction`. In the callback, `Gateway::settle(true, ['person_id' => 333])` is wrapped in a try/catch that catches `TransactionException` to retrieve the attached `AuthorizedTransaction` and report the error message and code.

```php
// basic authorize call
$transaction = new RequestTransaction(new Amount(12000));
$transaction->setExtra(['mobile' => '09124441122']);
$authorized = $gateway->authorize($transaction);
$transactionId = $authorized->getId();
$orderId = $authorized->getOrderId();
return $authorized->getRedirect()->redirect(app());

// settle in the callback — catching a provider error
try {
    $settled = Gateway::settle(true, ['person_id' => 333]);
} catch (\Parsisolution\Gateway\Exceptions\TransactionException $e) {
    /** @var \Parsisolution\Gateway\Transactions\AuthorizedTransaction $transaction */
    $transaction = $e->getTransaction(); // HasTransaction trait
    report($e->getMessage().' code '.$e->getCode());
}
```

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

### Abstract template method signatures with docblocks

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/abstract-provider.md

Lists the abstract methods each provider must implement: authorizeTransaction, validateSettlementRequest, and settleTransaction. Each method includes its docblock and signature as shown in the source.

```php
/**
 * Authorize payment request from provider's server and return
 * authorization response as AuthorizedTransaction
 * or throw an Error (most probably SoapFault)
 *
 * @return AuthorizedTransaction
 *
 * @throws Exception
 */
abstract protected function authorizeTransaction(UnAuthorizedTransaction $transaction);

/**
 * Validate the settlement request to see if it has all necessary fields
 *
 * @return FieldsToMatch
 *
 * @throws InvalidRequestException|TransactionException
 */
abstract protected function validateSettlementRequest(Request $request);

/**
 * Verify and Settle the transaction and return
 * settlement response as SettledTransaction
 * or throw a TransactionException
 *
 * @return SettledTransaction
 *
 * @throws TransactionException
 * @throws Exception
 */
abstract protected function settleTransaction(Request $request, AuthorizedTransaction $transaction);
```

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

### DigiPayGateway::__construct

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/configuration.md

Constructor for the DigiPay gateway provider. Initializes with settings and an optional token updater hook.

```APIDOC
## Parsisolution\Gateway\Providers\DigiPay\DigiPayGateway::__construct

### Description
Constructor for the DigiPay gateway provider. Initializes with settings and an optional token updater hook.

### Method
Constructor

### Signature
`Parsisolution\Gateway\Providers\DigiPay\DigiPayGateway::__construct($settings, $tokenUpdaterHook = null)`

### Parameters
- `$settings` (array) - Required - Configuration keys: `username`, `password`, `client_id`, `client_secret`, `access_token`, `refresh_token`, `live_api` (bool, `?? true`), `type` (`'UPG'`/`'IPG'`/`'WPG'`, mapped to `'11'`/`'0'`/`'2'`, default `'11'`).
- `$tokenUpdaterHook` (callable) - Optional - A closure `function ($accessToken, $refreshToken)` invoked after each successful OAuth refresh. `DigiPay::initDP()` wires it to Laravel cache keys `dp_access_token`/`dp_refresh_token` (`Cache::forever`).
```

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

### extendUsing() usage with IDPay class

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/gateway-manager.md

Registers a custom provider class via Gateway::extendUsing('idpay2', 60, IDPay::class). The commented-out README-style two-argument form does not match the current 3-argument AbstractProvider constructor; use the class directly.

```php
$createIDPay = function () {
    return new IDPay(app(), config('gateways.idpay2'));
};
// README-style two-argument form shown above does not match the current 3-argument
// AbstractProvider constructor; use the class directly:
use Parsisolution\Gateway\Providers\IDPay\IDPay;

Gateway::extendUsing('idpay2', 60, IDPay::class);
```

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

### AbstractProvider constructor

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/abstract-provider.md

Creates a new provider instance with the Laravel container, provider id, and driver config. The constructor reads the request from the container, resolves the transactions table name from config('gateways.table', 'gateway_transactions'), and instantiates a TransactionDao. Note: the README's two-argument form does not match this three-parameter signature; use Gateway::of('mellat') or pass $app, $id, $config.

```php
/**
 * Create a new provider instance.
 *
 * @param  int  $id
 * @param  array  $config
 */
public function __construct(Container $app, $id, $config)
```

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

### RedirectResponse::redirect

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/core-helpers.md

Performs the redirect. For TYPE_GET returns a Symfony RedirectResponse; for TYPE_POST returns a view with an auto-submitting form.

```APIDOC
## Method: redirect

### Description
Performs the redirect. For TYPE_GET returns a Symfony RedirectResponse; for TYPE_POST returns a view with an auto-submitting form.

### Method
GET

### Signature
`public function redirect($app)`

### Parameters
- **$app** - Required - The application instance.

### Return Value
- **\Symfony\Component\HttpFoundation\RedirectResponse** - when TYPE_GET
- **\Illuminate\Contracts\View\View** - when TYPE_POST (form auto-submit page)

### Example
```php
return $authorizedTransaction->getRedirect()->redirect(app());
```
```

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

### RedirectResponse::__construct

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/core-helpers.md

Creates a RedirectResponse instance describing how to redirect the payer to the gateway payment page.

```APIDOC
## Constructor

### Description
Creates a RedirectResponse instance describing how to redirect the payer to the gateway payment page.

### Method
Constructor

### Signature
`public function __construct($type, $url, array $data = null)`

### Parameters
- **$type** (string) - Required - `RedirectResponse::TYPE_GET` or `RedirectResponse::TYPE_POST`
- **$url** (string) - Required - absolute URL of the payment page
- **$data** (array) - Optional - hidden form fields posted to the gateway for `TYPE_POST` (default: `null`)

### Example
```php
$redirect = new RedirectResponse(RedirectResponse::TYPE_POST, 'https://gateway.example.com', ['field' => 'value']);
```
```

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

### Curl class signature with execute and executeArgs methods

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/core-helpers.md

Defines the Curl helper class with constants METHOD_GET and METHOD_POST, and static methods execute() and executeArgs(). execute() sends HTTP requests with configurable options and returns an array [$result, $http_code, $error]. executeArgs() forwards a positional array to execute() with defaults for resultAsArray, options, and method, used by Pasargad.

```php
class Curl
{
    const METHOD_GET = 'GET';
    const METHOD_POST = 'POST';

    public static function execute(
        string $url,
        array $fields,
        bool $resultAsArray = true,
        array $options = [],
        string $method = self::METHOD_POST
    ): array

    public static function executeArgs(array $args): array
}
```

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

### AbstractProvider::callbackUrl($url)

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/configuration.md

Overrides the callback-url configuration for the instance. This method allows runtime customization of the callback URL.

```APIDOC
## AbstractProvider::callbackUrl($url)

### Description
Overrides the `callback-url` config for the instance.

### Method
`callbackUrl`

### Parameters
- **$url** (string) - Required - The new callback URL.

### Returns
- (void) - No return value specified.
```

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

### Config helpers: getTable and getCachePrefix

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/gateway-manager.md

Reads the table name and cache prefix from the application config using the gateway config file name. Defaults are 'gateway_transactions' for the table and 'gateway_transactions_' for the cache prefix.

```php
private function getTable()
{
    return Arr::get(app()['config'], self::CONFIG_FILE_NAME.'.table', 'gateway_transactions');
}

private function getCachePrefix()
{
    return Arr::get(app()['config'], self::CONFIG_FILE_NAME.'.cache_prefix', 'gateway_transactions_');
}
```

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

### Curl::executeArgs

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/core-helpers.md

Forwards a positional array to `execute()` with defaults for optional parameters. Used by Pasargad.

```APIDOC
## Curl::executeArgs

### Description
Forwards a positional array to `execute()` with defaults for optional parameters. Used by Pasargad.

### Method
POST (default) or GET

### Signature
```php
public static function executeArgs(array $args): array
```

### Parameters
- **$args** (array) - Required - Positional array forwarded to `execute()`; defaults: `$args[2] ?? true`, `$args[3] ?? []`, `$args[4] ?? self::METHOD_POST`

### Returns
- **array** - Same as `execute()`: `[$result, $http_code, $error]`
```

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

### Using AuthorizedTransaction accessors and redirect

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/transactions.md

Shows how to retrieve the DB row id, order id, PSP reference id, and PSP token from an authorized transaction, then send the user to the gateway via getRedirect()->redirect(app()) or, for an API, return the Arrayable redirect descriptor with {type, url, data}.

```php
$authorized = $gateway->authorize($requestTransaction);
$transactionId = $authorized->getId();        // DB row id
$orderId = $authorized->getOrderId();         // unique order id sent to the gateway
$referenceId = $authorized->getReferenceId(); // PSP reference id (if any)
$token = $authorized->getToken();             // PSP token (if any)

// send the user to the gateway:
return $authorized->getRedirect()->redirect(app());
// or, for an API, serialize it and redirect on the frontend:
return $authorized->getRedirect();            // Arrayable: {type, url, data}
```

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

### extendUsing($driver, $id, $provider)

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/gateway-manager.md

Registers a custom driver creator Closure for a custom provider class.

```APIDOC
## extendUsing($driver, $id, $provider)

### Description
Registers a custom driver creator Closure for a custom provider class.

### Method
extendUsing(string $driver, int $id, string $provider): self

### Parameters
- **$driver** (string) - Required - Driver key to register, e.g. 'idpay2'.
- **$id** (int) - Required - Numeric id; must equal the value returned by the provider's getProviderId().
- **$provider** (string) - Required - Fully-qualified class name of an AbstractProvider subclass.

### Returns
- **self** - Returns $this for chaining.

### Description
Registers a creator closure that instantiates `new $provider(app(), $id, array_merge(['settings' => ['soap' => config('gateways.soap')]], config('gateways.'.$driver)))`, stores it in `$this->customCreators[$driver]`, and adds `$this->available_drivers[$id] = $driver` so both the string key and the numeric id resolve.

### Example
```php
use Parsisolution\Gateway\Providers\IDPay\IDPay;

Gateway::extendUsing('idpay2', 60, IDPay::class);
```
```

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

### AbstractProvider::stateless()

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/configuration.md

Disables session-state validation. Must be used in both authorize and callback flows.

```APIDOC
## AbstractProvider::stateless()

### Description
Disables session-state validation. Must be used in both authorize and callback flows.

### Method
`stateless`

### Parameters
None.

### Returns
- (void) - No return value specified.
```

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

### Parsisolution\Gateway\Curl::execute

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/configuration.md

Executes a cURL request with the given URL, fields, and options. Returns the response as an array or string.

```APIDOC
## Parsisolution\Gateway\Curl::execute

### Description
Executes a cURL request with the given URL, fields, and options. Returns the response as an array or string.

### Method
Constructor

### Signature
`Parsisolution\Gateway\Curl::execute(string $url, array $fields, bool $resultAsArray = true, array $options = [], string $method = self::METHOD_POST)`

### Parameters
- `$url` (string) - Required - The URL to send the request to.
- `$fields` (array) - Required - The fields to send with the request.
- `$resultAsArray` (bool) - Optional - Whether to return the result as an array (default: true).
- `$options` (array) - Optional - Any `CURLOPT_*` constants, merged over the built-in defaults (see core-helpers.md).
- `$method` (string) - Optional - The HTTP method to use (default: `self::METHOD_POST`).
```

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

### Provider interface contract

Source: https://github.com/parsisolution/gateway/blob/master/_autodocs/api-reference/abstract-provider.md

Defines the required methods for a gateway provider: callbackUrl(), authorize(), and settle(). The callbackUrl() method is optional and falls back to the config file if not called. authorize() returns an AuthorizedTransaction and throws Exception on failure; settle() returns a SettledTransaction and can throw InvalidRequestException, TransactionException, RetryException, or Exception.

```php
interface Provider
{
    /**
     * Set the callback url. (Optional)
     * if it doesn't get called fallback to config file
     *
     * @param  string  $url
     * @return self
     */
    public function callbackUrl($url);

    /**
     * Authorize the transaction before send the user to the payment page.
     *
     * @return \Parsisolution\Gateway\Transactions\AuthorizedTransaction
     *
     * @throws \Exception
     */
    public function authorize(RequestTransaction $transaction);

    /**
     * Verify and Settle the transaction and get the settled transaction instance.
     *
     * @param  array  $fieldsToUpdateOnSuccess
     * @return \Parsisolution\Gateway\Transactions\SettledTransaction
     *
     * @throws \Parsisolution\Gateway\Exceptions\InvalidRequestException
     * @throws \Parsisolution\Gateway\Exceptions\TransactionException
     * @throws \Parsisolution\Gateway\Exceptions\RetryException
     * @throws \Exception
     */
    public function settle(AuthorizedTransaction $authorizedTransaction, $fieldsToUpdateOnSuccess);
}
```
Tokens:
Raw