PHP Payment Gateway

https://github.com/shetabit/multipay
Admin
A PHP package for integrating multiple payment gateways, supporting PHP 7.2+ and allowing for custom...
Tokens:11,202
Snippets:48
Trust Score:7.6
License:MIT
Update:11 months ago
Show doc for...
Tokens:
Raw
### Change Payment Driver on the Fly in PHP

Source: https://github.com/shetabit/multipay/blob/master/README.md

This example illustrates how to change the payment gateway driver at runtime using the `via` method before initiating a purchase. This allows for flexible integration with different payment providers. Dependencies include the Shetabit Multipay library.

```php
// At the top of the file.
use Shetabit\Multipay\Invoice;
use Shetabit\Multipay\Payment;
...

// load the config file from your project
$paymentConfig = require('path/to/payment.php');

$payment = new Payment($paymentConfig);


// Create new invoice.
$invoice = (new Invoice)->amount(1000);

// Purchase the given invoice.
$payment->via('driverName')->purchase(
    $invoice, 
    function($driver, $transactionId) {
    // We can store $transactionId in database.
  	}
);
```

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

### Instantiate Payment class with configuration

Source: https://github.com/shetabit/multipay/blob/master/README.md

Loads the payment configuration file and creates a Payment instance. This object is used for purchasing and paying invoices. Requires the Shetabit\Multipay package.

```php
use Shetabit\Multipay\Payment;

// load the config file from your project
$paymentConfig = require('path/to/payment.php');

$payment = new Payment($paymentConfig);
```

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

### Install Multipay via Composer

Source: https://context7.com/shetabit/multipay/llms.txt

This command installs the Shetabit Multipay package using Composer, a dependency manager for PHP. Ensure Composer is installed and accessible in your project's root directory.

```bash
composer require shetabit/multipay
```

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

### Create and configure an Invoice with details

Source: https://github.com/shetabit/multipay/blob/master/README.md

Creates an Invoice object, sets the amount, and attaches custom details using various syntax options. The invoice can later be purchased or paid. No external dependencies beyond the Multipay library.

```php
use Shetabit\Multipay\Invoice;

// Create new invoice.
$invoice = new Invoice;

// Set invoice amount.
$invoice->amount(1000);

// Add details – method 1
$invoice->detail(['detailName' => 'your detail goes here']);

// Add details – method 2
$invoice->detail('detailName','your detail goes here');

// Add details – method 3
$invoice->detail(['name1' => 'detail1','name2' => 'detail2']);

// Add details – method 4 (fluent)
$invoice->detail('detailName1','your detail1 goes here')
        ->detail('detailName2','your detail2 goes here');
```

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

### Register Pay Event Listener in PHP

Source: https://github.com/shetabit/multipay/blob/master/README.md

Demonstrates registering multiple callback listeners for the pay event, which triggers when an invoice is prepared for payment. Each listener receives the driver name and invoice instance. Listeners execute sequentially in registration order.

```php
// add pay event listener
Payment::addPayListener(function($driver, $invoice) {
    echo 'first listener';
});

// we can add multiple listeners
Payment::addPayListener(function($driver, $invoice) {
    echo 'second listener';
});
```

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

### Configure gateway credentials in drivers array

Source: https://github.com/shetabit/multipay/blob/master/README.md

Specifies the required URLs and credentials for a payment gateway (e.g., Zarinpal). These settings are read from the configuration file when the Payment class is instantiated.

```php
'drivers' => [
    'zarinpal' => [
        // Fill in the credentials here.
        'apiPurchaseUrl' => 'https://www.zarinpal.com/pg/rest/WebGate/PaymentRequest.json',
        'apiPaymentUrl' => 'https://www.zarinpal.com/pg/StartPay/',
        'apiVerificationUrl' => 'https://www.zarinpal.com/pg/rest/WebGate/PaymentVerification.json',
        'merchantId' => '',
        'callbackUrl' => 'http://yoursite.com/path/to',
        'description' => 'payment in '.config('app.name'),
    ],
    ...
]
```

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

### Initiate and Pay with Local Driver

Source: https://github.com/shetabit/multipay/blob/master/README.md

This snippet shows how to initiate a payment using the 'local' driver, simulate a purchase, and render the payment form. It generates a fake transaction ID and redirects to the callback URL upon simulated completion. The `purchase` method accepts a closure to handle the transaction ID.

```php
$invoice = (new Invoice)->amount(10000);
$payment->via('local')->purchase($invoice, function($driver, $transactionId) {
    // a fake transaction ID is generated and returned.
})->pay()->render();
```

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

### Configure Payment Gateway and Drivers

Source: https://context7.com/shetabit/multipay/llms.txt

This PHP code demonstrates how to configure the Multipay payment system. It involves loading a configuration file or defining an array with gateway details, specifying the default driver, and mapping drivers to their respective classes. This setup allows for seamless switching between payment providers.

```php
<?php

use Shetabit\Multipay\Payment;
use Shetabit\Multipay\Invoice;

// Load the configuration file
$paymentConfig = require('config/payment.php');

// Create Payment instance
$payment = new Payment($paymentConfig);

// Configure for specific gateway (Zarinpal example)
$config = [
    'default' => 'zarinpal',
    'drivers' => [
        'zarinpal' => [
            'apiPurchaseUrl' => 'https://api.zarinpal.com/pg/v4/payment/request.json',
            'apiPaymentUrl' => 'https://www.zarinpal.com/pg/StartPay/',
            'apiVerificationUrl' => 'https://api.zarinpal.com/pg/v4/payment/verify.json',
            'merchantId' => 'YOUR_MERCHANT_ID',
            'callbackUrl' => 'https://yoursite.com/payment/callback',
            'description' => 'Payment for order',
            'currency' => 'T', // T for Toman, R for Rial
        ],
    ],
    'map' => [
        'zarinpal' => \Shetabit\Multipay\Drivers\Zarinpal\Zarinpal::class,
    ],
];

$payment = new Payment($config);

```

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

### Local Driver - Simulate Failed Purchase

Source: https://github.com/shetabit/multipay/blob/master/README.md

This snippet shows how to configure the 'local' driver to simulate a failed purchase initialization. By setting the `failedPurchase` parameter in the invoice details, the `purchase` method will throw a `PurchaseFailedException`, mimicking a scenario where a gateway cannot initialize the payment.

```php
$invoice->detail([
    // setting this value will cause `purchase` method to throw an `PurchaseFailedException` 
    // to simulate when a gateway can not initialize the payment.
        'failedPurchase' => 'custom message to decribe the error',

    // Setting this parameter will be shown in payment form.
        'orderId' => 4444,
]);
```

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

### Purchase an invoice with callback

Source: https://github.com/shetabit/multipay/blob/master/README.md

Uses the Payment instance to purchase an invoice, receiving a transaction ID via a callback for later verification. The callback can store the transaction ID in a database. Supports optional custom callback URL.

```php
use Shetabit\Multipay\Invoice;
use Shetabit\Multipay\Payment;

$paymentConfig = require('path/to/payment.php');
$payment = new Payment($paymentConfig);

$invoice = (new Invoice)->amount(1000);

$payment->purchase($invoice, function($driver, $transactionId) {
    // Store $transactionId in database.
});

// With custom callback URL
$payment->callbackUrl('http://yoursite.com/verify')->purchase(
    $invoice,
    function($driver, $transactionId) {
        // Store $transactionId in database.
    }
);
```

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

### Set Callback URL at Runtime in PHP

Source: https://github.com/shetabit/multipay/blob/master/README.md

This code shows how to dynamically set the callback URL for a payment transaction at runtime. It involves creating a payment instance, initializing an invoice with an amount, and then using the `callbackUrl` method before initiating the purchase. Dependencies include the Shetabit Multipay library.

```php
// At the top of the file.
use Shetabit\Multipay\Invoice;
use Shetabit\Multipay\Payment;
...

// load the config file from your project
$paymentConfig = require('path/to/payment.php');

$payment = new Payment($paymentConfig);


// Create new invoice.
$invoice = (new Invoice)->amount(1000);

// Purchase the given invoice.
$payment->callbackUrl($url)->purchase(
    $invoice, 
    function($driver, $transactionId) {
    // We can store $transactionId in database.
  	}
);
```

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

### Verify Payment with Local Driver

Source: https://github.com/shetabit/multipay/blob/master/README.md

This code demonstrates how to verify a payment after receiving a callback request using the 'local' driver. The `verify()` method returns a receipt array containing details of the transaction if successful, or throws a `PurchaseFailedException` if the payment is canceled or fails verification.

```php
$receipt = $payment->via('local')->verify();
```

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

### Manage Verify Event Listeners in PHP

Source: https://github.com/shetabit/multipay/blob/master/README.md

Shows how to register and remove listeners for the verify event, which fires after successful payment verification. Demonstrates adding multiple listeners, removing specific listeners by reference, and removing all listeners at once. Useful for cleaning up event handlers dynamically.

```php
// we can add multiple listeners and also remove them!!!

$firstListener = function($driver, $invoice) {
    echo 'first listener';
};

$secondListener = function($driver, $invoice) {
    echo 'second listener';
};

Payment::addVerifyListener($firstListener);
Payment::addVerifyListener($secondListener);

// remove first listener
Payment::removeVerifyListener($firstListener);

// if we call remove listener without any arguments, it will remove all listeners
Payment::removeVerifyListener(); // remove all verify listeners :D
```

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

### Pay invoice and redirect to bank gateway

Source: https://github.com/shetabit/multipay/blob/master/README.md

After purchasing, call pay() to obtain a redirect response. The response can be rendered directly or converted to JSON for custom handling. Returns the payment page URL for the user.

```php
use Shetabit\Multipay\Invoice;
use Shetabit\Multipay\Payment;

$paymentConfig = require('path/to/payment.php');
$payment = new Payment($paymentConfig);

$invoice = (new Invoice)->amount(1000);

// Redirect user to bank page
return $payment->purchase($invoice, function($driver, $transactionId) {
    // Store transactionId in database.
})->pay()->render();

// One‑liner version
return $payment->purchase(
    (new Invoice)->amount(1000),
    function($driver, $transactionId) {
        // Store transactionId.
    }
)->pay()->render();

// Get JSON representation of redirection
return $payment->purchase(
    (new Invoice)->amount(1000),
    function($driver, $transactionId) {
        // Store transactionId.
    }
)->pay()->toJson();
```

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

### Set Driver Configurations on the Fly in PHP

Source: https://github.com/shetabit/multipay/blob/master/README.md

This snippet shows how to set specific driver configurations on the fly using the `config` method. It can be used to set individual configuration values or multiple values at once, such as merchant IDs or specific gateway settings like wages for Zarinpal. Dependencies include the Shetabit Multipay library.

```php
// At the top of the file.
use Shetabit\Multipay\Invoice;
use Shetabit\Multipay\Payment;
...

// load the config file from your project
$paymentConfig = require('path/to/payment.php');

$payment = new Payment($paymentConfig);


// Create new invoice.
$invoice = (new Invoice)->amount(1000);

// Purchase the given invoice with custom driver configs.
$payment->config('mechandId', 'your mechand id')->purchase(
    $invoice,
    function($driver, $transactionId) {
    // We can store $transactionId in database.
  	}
);

// We can also change multiple config values at the same time.
// To use wages in Zarinpal, you can configure it as shown in the example below.
$payment->config(['wages' => [use Zarinpal documentation for values], 'key1' => 'value1', 'key2' => 'value2'])->purchase(
    $invoice,
    function ($driver, $transactionId) {
        // We can store $transactionId in the database.
    }
);
```

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

### Set default payment driver in configuration

Source: https://github.com/shetabit/multipay/blob/master/README.md

Defines the default payment gateway to be used by the Multipay package. Adjust the value to switch gateways without changing code. No external dependencies beyond the config file.

```php
'default' => 'zarinpal',
```

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

### Local Driver - Form Appearance Configuration

Source: https://github.com/shetabit/multipay/blob/master/README.md

This configuration block defines the appearance and behavior of the payment form rendered by the 'local' driver. It includes settings for the default callback URL, form title, description, custom labels for order and amount, and the text for the payment and cancel buttons.

```php
'local' => [
    // default callback url of the driver
    'callbackUrl' => '/callback',

    // main title of the form
    'title' => 'Test gateway',
  
    // a description to show under the title for more clarification
    'description' => 'This gateway is for using in development environments only.',
  
    // custom label to show as order No.
    'orderLabel' => 'Order No.',
  
    // custom label to show as payable amount
    'amountLabel' => 'Payable amount',
  
    // custom label of successful payment button
    'payButton' => 'Successful Payment',
  
    // custom label of cancel payment button
    'cancelButton' => 'Cancel Payment',
],
```

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

### Implement Custom Payment Driver Class in PHP

Source: https://github.com/shetabit/multipay/blob/master/README.md

Creates a custom payment driver by extending the abstract Driver class. This implementation handles purchase requests, payment redirection, and transaction verification. Requires Shetabit\Multipay package classes and implements three core methods: purchase(), pay(), and verify(). Returns transaction IDs, redirection forms, and payment receipts respectively.

```php
namespace App\Packages\Multipay\Driver;

use Shetabit\Multipay\Abstracts\Driver;
use Shetabit\Multipay\Exceptions\InvalidPaymentException;
use Shetabit\Multipay\{Contracts\ReceiptInterface, Invoice, RedirectionForm, Receipt};

class MyDriver extends Driver
{
    protected $invoice; // Invoice.

    protected $settings; // Driver settings.

    public function __construct(Invoice $invoice, $settings)
    {
        $this->invoice($invoice); // Set the invoice.
        $this->settings = (object) $settings; // Set settings.
    }

    // Purchase the invoice, save its transactionId and finaly return it.
    public function purchase() {
        // Request for a payment transaction id.
        ...

        $this->invoice->transactionId($transId);

        return $transId;
    }

    // Redirect into bank using transactionId, to complete the payment.
    public function pay() : RedirectionForm {
        // It is better to set bankApiUrl in config/payment.php and retrieve it here:
        $bankUrl = $this->settings->bankApiUrl; // bankApiUrl is the config name.

        // Prepare payment url.
        $payUrl = $bankUrl.$this->invoice->getTransactionId();

        // Redirect to the bank.
        $url = $payUrl;
        $inputs = [];
        $method = 'GET';

        return $this->redirectWithForm($url, $inputs, $method);
    }
  
    // Verify the payment (we must verify to ensure that user has paid the invoice).
    public function verify(): ReceiptInterface {
        $verifyPayment = $this->settings->verifyApiUrl;
  
        $verifyUrl = $verifyPayment.$this->invoice->getTransactionId();
  
        ...
  
        /**
			Then we send a request to $verifyUrl and if payment is not valid we throw an InvalidPaymentException with a suitable message.
        **/
        throw new InvalidPaymentException('a suitable message');
  
        /**
        	We create a receipt for this payment if everything goes normally.
        **/
        return new Receipt('driverName', 'payment_receipt_number');
    }
}
```

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

### Register Purchase Event Listener in PHP

Source: https://github.com/shetabit/multipay/blob/master/README.md

Registers a callback listener for the purchase event, which fires after an invoice is successfully purchased. The listener receives the driver name and invoice instance as parameters. Multiple listeners can be registered and will execute in the order they were added.

```php
// add purchase event listener
Payment::addPurchaseListener(function($driver, $invoice) {
    echo $driver;
    echo $invoice;
});
```

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

### Set Invoice Amount Directly in PHP

Source: https://github.com/shetabit/multipay/blob/master/README.md

This snippet demonstrates setting the invoice amount directly using the `amount` method, bypassing the need to create an `Invoice` object explicitly. This is useful for simple payment scenarios where only the amount is required. Dependencies include the Shetabit Multipay library.

```php
// At the top of the file.
use Shetabit\Multipay\Invoice;
use Shetabit\Multipay\Payment;
...

// load the config file from your project
$paymentConfig = require('path/to/payment.php');

$payment = new Payment($paymentConfig);


// Purchase (we set invoice to null).
$payment->callbackUrl($url)->amount(1000)->purchase(
    null,
    function($driver, $transactionId) {
    // We can store $transactionId in database.
  	}
);
```

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

### Configure Custom Driver in payment.php

Source: https://github.com/shetabit/multipay/blob/master/README.md

Defines driver configuration arrays in the payment configuration file. The drivers array registers available payment drivers with their settings, while the map array links driver names to their corresponding handler classes. Ensure keys match between both arrays for proper driver resolution.

```php
'drivers' => [
    'zarinpal' => [...],
    'my_driver' => [
        ... // Your Config Params here.
    ]
]
```

```php
'map' => [
    ...
    'my_driver' => App\Packages\Multipay\Driver\MyDriver::class,
]
```

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

### Verify Payment with Shetabit Multipay in PHP

Source: https://github.com/shetabit/multipay/blob/master/README.md

This snippet demonstrates how to verify a payment after a user completes a transaction. It uses the transaction ID to ensure the invoice has been paid successfully and handles potential invalid payment exceptions. Dependencies include the Shetabit Multipay library and a payment configuration file.

```php
// At the top of the file.
use Shetabit\Multipay\Payment;
use Shetabit\Multipay\Exceptions\InvalidPaymentException;
...

// load the config file from your project
$paymentConfig = require('path/to/payment.php');

$payment = new Payment($paymentConfig);


// You need to verify the payment to ensure the invoice has been paid successfully.
// We use transaction id to verify payments
// It is a good practice to add invoice amount as well.
try {
	$receipt = $payment->amount(1000)->transactionId($transaction_id)->verify();

    // You can show payment referenceId to the user.
    echo $receipt->getReferenceId();

    // And also you can access verify receipt detail
    echo $receipt->getDetail('give-a-name')
    // Or if you want all details
    $receiptDetails = $receipt->getDetails()
    ...
} catch (InvalidPaymentException $exception) {
    /**
    	when payment is not verified, it will throw an exception.
    	We can catch the exception to handle invalid payments.
    	getMessage method, returns a suitable message that can be used in user interface.
    **/
    echo $exception->getMessage();
}
```

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

### Local Driver - Successful Payment Receipt

Source: https://github.com/shetabit/multipay/blob/master/README.md

In case of a successful payment verification with the 'local' driver, the `$receipt` variable will contain an array with the following parameters: `orderId`, `traceNo` (to be stored in the database), `referenceNo` (the transaction ID from the `purchase` method), and `cardNo` (fake last four digits of the card).

```php
[
'orderId' => // fake order number 
'traceNo' => // fake trace number (this should be stored in databse)
'referenceNo' => // generated transaction ID in `purchase` method callback
'cardNo' => // fake last four digits of card 
]
```

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

### Use Custom Fields for Gateways in PHP

Source: https://github.com/shetabit/multipay/blob/master/README.md

This code demonstrates how to use custom fields for gateways that support them, like SEP. It utilizes the `detail` method on the `Invoice` object to set up to four custom fields, each with a string value up to 50 characters. These fields are useful for storing additional order or customer information visible in gateway reports. Dependencies include the Shetabit Multipay library.

```php
// At the top of the file.
use Shetabit\Multipay\Invoice;
...


// Create new invoice.
$invoice = (new Invoice)->amount(1000);

// Use invoice bag to store custom field values.
$invoice->detail([
              'ResNum1' => $order->orderId,
              'ResNum2' => $customer->verifiedCode,
              'ResNum3' => $someValue,
              'ResNum4' => $someOtherValue,
              ]);
```

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

### Initiate Payment Purchase in PHP

Source: https://context7.com/shetabit/multipay/llms.txt

This PHP code demonstrates how to initiate a payment purchase using the Shetabit Multipay library. It requires the Payment and Invoice classes, a payment configuration, and optionally database or session storage for transaction IDs. Inputs include invoice amount and optional details; outputs are HTML forms for gateway redirection or JSON for AJAX. Limitations include dependency on specific payment gateways and proper error handling for database operations.

```php
<?php

use Shetabit\Multipay\Payment;
use Shetabit\Multipay\Invoice;

$paymentConfig = require('config/payment.php');
$payment = new Payment($paymentConfig);

// Complete payment flow: purchase and redirect to gateway
$invoice = (new Invoice)->amount(100000);

return $payment->purchase($invoice, function($driver, $transactionId) {
    // Save transaction to database
    $stmt = $pdo->prepare("INSERT INTO payments (transaction_id, amount, status) VALUES (?, ?, ?)");
    $stmt->execute([$transactionId, 100000, 'pending']);
})->pay()->render();

// All-in-one payment initiation
return $payment
    ->via('zarinpal') // Specify gateway driver
    ->callbackUrl('https://example.com/payment/callback')
    ->purchase(
        (new Invoice)->amount(250000)->detail('orderId', 'ORDER-001'),
        function($driver, $transactionId) {
            $_SESSION['tx_id'] = $transactionId;
        }
    )
    ->pay()
    ->render(); // Returns HTML form that auto-submits to gateway

// Get JSON format instead of HTML (useful for AJAX)
$paymentJson = $payment->purchase(
    (new Invoice)->amount(50000),
    function($driver, $transactionId) {
        redis_set('payment:' . $transactionId, json_encode(['amount' => 50000, 'status' => 'pending']));
    }
)->pay()->toJson();

// Returns: {"action":"https://gateway.url","inputs":{"token":"..."},"method":"POST"}
header('Content-Type: application/json');
echo $paymentJson;
```

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

### Dynamic Driver and Configuration Changes in PHP

Source: https://context7.com/shetabit/multipay/llms.txt

Demonstrates how to switch payment gateways at runtime and override configuration settings like merchant ID, callback URL, and description. It also shows how to configure split payments (wages) for specific gateways.

```php
<?php

use Shetabit\Multipay\Payment;
use Shetabit\Multipay\Invoice;

$paymentConfig = require('config/payment.php');
$payment = new Payment($paymentConfig);

// Switch to different driver on the fly
$invoice = (new Invoice)->amount(100000);

$payment->via('parsian') // Use Parsian instead of default
    ->purchase($invoice, function($driver, $transactionId) {
        file_put_contents('parsian_tx.log', $transactionId . PHP_EOL, FILE_APPEND);
    });

// Override configuration at runtime (single config)
$payment->config('merchantId', 'NEW_MERCHANT_ID')
    ->purchase($invoice, function($driver, $transactionId) {
        echo "Using custom merchant ID";
    });

// Override multiple configurations
$payment->config([
    'merchantId' => 'CUSTOM_MERCHANT',
    'callbackUrl' => 'https://custom-callback.com/verify',
    'description' => 'VIP Customer Payment'
])
->via('zarinpal')
->purchase($invoice, function($driver, $transactionId) {
    redis_set('vip:tx:' . $transactionId, time());
});

// Configure Zarinpal wages (split payment)
$payment->config([
    'wages' => [
        ['iban' => 'IR123456789012345678901234', 'amount' => 5000, 'description' => 'Commission'],
        ['iban' => 'IR987654321098765432109876', 'amount' => 2000, 'description' => 'Service Fee']
    ]
])->purchase($invoice, function($driver, $transactionId) {
    echo "Payment with wage distribution initiated";
});

```

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

### PHP: Configure and Test Local Payment Driver

Source: https://context7.com/shetabit/multipay/llms.txt

Demonstrates how to set up the local driver in Shetabit Multipay's configuration and simulate payment flows, including successful purchases, failed purchases, and verification. It utilizes `Shetabit\Multipay\Payment` and `Shetabit\Multipay\Invoice` for managing payment operations. Dependencies include the Shetabit Multipay package. Input involves creating `Invoice` objects with amounts and details. Output includes echoed messages for transaction IDs, verification status, or failure reasons.

```php
<?php

use ShetabitMultipayPayment;
use Shetabit\Multipay\Invoice;
use Shetabit\Multipay\Exceptions\PurchaseFailedException;

// Configure local driver in payment.php
$config = [
    'default' => 'local',
    'drivers' => [
        'local' => [
            'callbackUrl' => '/payment/callback',
            'title' => 'Test Payment Gateway',
            'description' => 'This gateway is for development environments only',
            'orderLabel' => 'Order Number',
            'amountLabel' => 'Amount to Pay',
            'payButton' => 'Successful Payment',
            'cancelButton' => 'Cancel Payment',
        ],
    ],
    'map' => [
        'local' => \Shetabit\Multipay\Drivers\Local\Local::class,
    ],
];

$payment = new Payment($config);

// Simulate successful payment flow
$invoice = (new Invoice)->amount(10000);
$invoice->detail(['orderId' => 'TEST-001']);

try {
    $payment->via('local')->purchase($invoice, function($driver, $transactionId) {
        echo "Fake transaction ID: $transactionId\n";
        $_SESSION['test_tx'] = $transactionId;
    })->pay()->render(); // Displays HTML form with Accept/Cancel buttons

} catch (PurchaseFailedException $e) {
    echo "Purchase failed: " . $e->getMessage();
}

// Simulate purchase failure
$failedInvoice = (new Invoice)->amount(5000);
$failedInvoice->detail([
    'orderId' => 'TEST-FAIL-001',
    'failedPurchase' => 'Simulated gateway connection error' // Triggers failure
]);

try {
    $payment->via('local')->purchase($failedInvoice, function($driver, $transactionId) {
        // This won't execute due to failedPurchase setting
    });
} catch (PurchaseFailedException $e) {
    echo "Expected failure: " . $e->getMessage();
}

// Verify local payment (after callback)
$transactionId = $_GET['transactionId'] ?? null;

try {
    $receipt = $payment->via('local')
        ->transactionId($transactionId)
        ->verify();

    // Successful verification returns fake data
    $details = $receipt->getDetails();
    // Contains: orderId, traceNo, referenceNo, cardNo (last 4 digits)

    echo "Payment verified: " . $receipt->getReferenceId();

} catch (InvalidPaymentException $e) {
    // Thrown when user clicks "Cancel Payment" button
    echo "Payment cancelled or failed";
}

```

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

### Create Custom Payment Gateway Driver - PHP

Source: https://context7.com/shetabit/multipay/llms.txt

Implements a complete custom payment gateway driver by extending the Driver abstract class. The driver handles payment token acquisition, redirects users to payment gateway, and verifies payment completion. Requires Shetabit\Multipay package, HTTP client library, and proper API configuration.

```php
<?php

namespace App\Payment\Drivers;

use Shetabit\Multipay\Abstracts\Driver;
use Shetabit\Multipay\Exceptions\InvalidPaymentException;
use Shetabit\Multipay\Exceptions\PurchaseFailedException;
use Shetabit\Multipay\Contracts\ReceiptInterface;
use Shetabit\Multipay\Invoice;
use Shetabit\Multipay\RedirectionForm;
use Shetabit\Multipay\Receipt;
use GuzzleHttp\Client;

class CustomGateway extends Driver
{
    protected $invoice;
    protected $settings;
    protected $httpClient;

    public function __construct(Invoice $invoice, $settings)
    {
        $this->invoice = $invoice;
        $this->settings = (object) $settings;
        $this->httpClient = new Client();
    }

    public function purchase()
    {
        // Request payment token from gateway
        $response = $this->httpClient->post($this->settings->apiPurchaseUrl, [
            'json' => [
                'merchant_id' => $this->settings->merchantId,
                'amount' => $this->invoice->getAmount(),
                'callback_url' => $this->settings->callbackUrl,
                'description' => $this->settings->description ?? 'Payment',
            ],
            'headers' => [
                'Authorization' => 'Bearer ' . $this->settings->apiKey,
            ]
        ]);

        $result = json_decode($response->getBody()->getContents(), true);

        if (!isset($result['success']) || $result['success'] !== true) {
            throw new PurchaseFailedException($result['message'] ?? 'Purchase failed');
        }

        $transactionId = $result['data']['token'];
        $this->invoice->transactionId($transactionId);

        return $transactionId;
    }

    public function pay(): RedirectionForm
    {
        $paymentUrl = $this->settings->apiPaymentUrl . $this->invoice->getTransactionId();

        // Return redirection form (GET method)
        return $this->redirectWithForm($paymentUrl, [], 'GET');

        // Or for POST method with parameters:
        // return $this->redirectWithForm($paymentUrl, [
        //     'token' => $this->invoice->getTransactionId(),
        //     'lang' => 'en'
        // ], 'POST');
    }

    public function verify(): ReceiptInterface
    {
        $transactionId = $this->invoice->getTransactionId();

        // Verify payment with gateway
        $response = $this->httpClient->post($this->settings->apiVerificationUrl, [
            'json' => [
                'merchant_id' => $this->settings->merchantId,
                'token' => $transactionId,
                'amount' => $this->invoice->getAmount(),
            ],
            'headers' => [
                'Authorization' => 'Bearer ' . $this->settings->apiKey,
            ]
        ]);

        $result = json_decode($response->getBody()->getContents(), true);

        if (!isset($result['success']) || $result['success'] !== true) {
            throw new InvalidPaymentException($result['message'] ?? 'Payment verification failed');
        }

        // Create receipt with reference ID
        $receipt = new Receipt('customgateway', $result['data']['reference_id']);

        // Add additional details to receipt
        $receipt->detail('trace_number', $result['data']['trace_number']);
        $receipt->detail('card_number', $result['data']['card_number']);
        $receipt->detail('paid_at', $result['data']['paid_at']);

        return $receipt;
    }
}

// Register driver in config/payment.php
$config = [
    'drivers' => [
        'customgateway' => [
            'apiPurchaseUrl' => 'https://api.customgateway.com/v1/purchase',
            'apiPaymentUrl' => 'https://gateway.customgateway.com/pay/',
            'apiVerificationUrl' => 'https://api.customgateway.com/v1/verify',
            'merchantId' => 'YOUR_MERCHANT_ID',
            'apiKey' => 'YOUR_API_KEY',
            'callbackUrl' => 'https://yoursite.com/payment/callback',
            'description' => 'Payment via CustomGateway',
        ],
    ],
    'map' => [
        'customgateway' => \App\Payment\Drivers\CustomGateway::class,
    ],
];

// Use custom driver
$payment = new Payment($config);
$invoice = (new Invoice)->amount(100000);

$payment->via('customgateway')
    ->purchase($invoice, function($driver, $transactionId) {
        echo "Custom gateway transaction: $transactionId";
    })->pay()->render();
```

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

### Manage Invoices with Amount, UUID, and Details

Source: https://context7.com/shetabit/multipay/llms.txt

This PHP code illustrates how to create and manage payment invoices using the Multipay library. It shows how to set the invoice amount, assign a unique identifier (UUID), and add custom details. Method chaining is supported for concise invoice creation, and methods are provided to retrieve invoice data.

```php
<?php

use Shetabit\Multipay\Invoice;

// Create new invoice with amount
$invoice = new Invoice();
$invoice->amount(50000); // Amount in configured currency

// Set custom invoice UUID
$invoice->uuid('custom-unique-id-12345');

// Add custom details to invoice (4 different syntaxes available)
$invoice->detail('orderId', '12345');
$invoice->detail(['customerName' => 'John Doe', 'customerEmail' => 'john@example.com']);

// Method chaining
$invoice = (new Invoice())
    ->amount(100000)
    ->uuid('order-2023-001')
    ->detail('orderId', 'ORD-12345')
    ->detail('productName', 'Premium Subscription')
    ->detail('customerEmail', 'customer@example.com');

// Retrieve invoice data
$amount = $invoice->getAmount(); // 100000
$uuid = $invoice->getUuid(); // 'order-2023-001'
$details = $invoice->getDetails(); // Array of all details
$orderId = $invoice->getDetail('orderId'); // 'ORD-12345'

```

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

### Purchase Invoice and Handle Transaction ID

Source: https://context7.com/shetabit/multipay/llms.txt

This PHP code demonstrates initiating a payment transaction using the Multipay library. It involves creating an invoice, purchasing it via the payment gateway, and handling the returned transaction ID. The transaction ID can be stored in a database or session for later verification. The code also shows how to specify a custom callback URL and how to purchase without explicitly creating an Invoice object.

```php
<?php

use Shetabit\Multipay\Payment;
use Shetabit\Multipay\Invoice;

$paymentConfig = require('config/payment.php');
$payment = new Payment($paymentConfig);

// Create invoice
$invoice = (new Invoice)->amount(50000);

// Purchase invoice and store transaction ID
$payment->purchase($invoice, function($driver, $transactionId) {
    // Store transaction ID in database for later verification
    // Example: DB::table('transactions')->insert([
    //     'transaction_id' => $transactionId,
    //     'amount' => 50000,
    //     'status' => 'pending',
    //     'created_at' => now()
    // ]);

    error_log("Transaction ID: " . $transactionId);
});

// Purchase with custom callback URL
$payment->callbackUrl('https://yoursite.com/payment/verify')
    ->purchase($invoice, function($driver, $transactionId) {
        $_SESSION['transaction_id'] = $transactionId;
        $_SESSION['payment_amount'] = $invoice->getAmount();
    });

// Purchase without creating invoice object (set amount directly)
$payment->amount(75000)
    ->callbackUrl('https://example.com/callback')
    ->purchase(null, function($driver, $transactionId) {
        file_put_contents('transactions.log', $transactionId . PHP_EOL, FILE_APPEND);
    });

```

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

### Payment Event Listeners in PHP

Source: https://context7.com/shetabit/multipay/llms.txt

Illustrates how to register and manage listeners for various stages of the payment lifecycle, including purchase, pay, and verify events. It covers adding, removing, and triggering these listeners to perform actions like logging or sending notifications.

```php
<?php

use Shetabit\Multipay\Payment;
use Shetabit\Multipay\Invoice;

// Register event listeners (should be done at application bootstrap)

// Purchase event - triggered after successful purchase
Payment::addPurchaseListener(function($driver, $invoice) {
    error_log("Purchase completed via {$driver->getInvoice()->getDriver()} for amount: {$invoice->getAmount()}");

    // Log to monitoring service
    // Monitoring::track('payment.purchase', ['amount' => $invoice->getAmount()]);
});

// Pay event - triggered when redirecting to gateway
Payment::addPayListener(function($driver, $invoice) {
    echo "Redirecting to payment gateway...";
});

// Multiple pay listeners
Payment::addPayListener(function($driver, $invoice) {
    file_put_contents('payment_logs.txt', date('Y-m-d H:i:s') . " - Payment started\n", FILE_APPEND);
});

// Verify event - triggered after successful verification
$verifyListener = function($receipt, $driver, $invoice) {
    $referenceId = $receipt->getReferenceId();
    $amount = $invoice->getAmount();

    // Send notification
    sendSlackNotification("Payment verified: $referenceId - Amount: $amount");

    // Update analytics
    // Analytics::recordPayment($amount, $driver->getInvoice()->getDriver());
};

Payment::addVerifyListener($verifyListener);

// Remove specific listener
Payment::removeVerifyListener($verifyListener);

// Remove all verify listeners
Payment::removeVerifyListener();

// Using payment with registered listeners
$paymentConfig = require('config/payment.php');
$payment = new Payment($paymentConfig);

$invoice = (new Invoice)->amount(50000);

$payment->purchase($invoice, function($driver, $transactionId) {
    $_SESSION['tx'] = $transactionId;
})->pay()->render(); // Purchase and pay events will fire

```

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

### Verify Payment Completion in PHP

Source: https://context7.com/shetabit/multipay/llms.txt

This PHP code shows how to verify a payment after the user returns from the payment gateway using the Shetabit Multipay library. It depends on the Payment class, stored transaction data (from database or session), and proper exception handling. Inputs are transaction ID and amount; outputs include a receipt with reference ID or error messages. Limitations involve gateway-specific callbacks and the need for persistent storage to match transactions accurately.

```php
<?php

use Shetabit\Multipay\Payment;
use Shetabit\Multipay\Exceptions\InvalidPaymentException;

$paymentConfig = require('config/payment.php');
$payment = new Payment($paymentConfig);

// Get transaction ID from request (gateway sends this back)
$transactionId = $_GET['Authority'] ?? $_POST['token'] ?? null;

// Retrieve stored payment amount from database
$stmt = $pdo->prepare("SELECT amount FROM payments WHERE transaction_id = ?");
$stmt->execute([$transactionId]);
$paymentData = $stmt->fetch();

try {
    // Verify payment with amount and transaction ID
    $receipt = $payment
        ->amount($paymentData['amount'])
        ->transactionId($transactionId)
        ->verify();

    // Payment successful - get reference ID
    $referenceId = $receipt->getReferenceId();

    // Access receipt details
    $driver = $receipt->getDriver(); // Gateway name
    $allDetails = $receipt->getDetails(); // All receipt data

    // Update database
    $updateStmt = $pdo->prepare("UPDATE payments SET status = ?, reference_id = ? WHERE transaction_id = ?");
    $updateStmt->execute(['completed', $referenceId, $transactionId]);

    echo "Payment successful! Reference ID: " . $referenceId;

} catch (InvalidPaymentException $exception) {
    // Payment failed or invalid
    $errorMessage = $exception->getMessage();

    // Update database with failed status
    $updateStmt = $pdo->prepare("UPDATE payments SET status = ?, error = ? WHERE transaction_id = ?");
    $updateStmt->execute(['failed', $errorMessage, $transactionId]);

    echo "Payment failed: " . $errorMessage;
}

// Verify with callback
$payment->amount(50000)
    ->transactionId($transactionId)
    ->verify(function($receipt, $driver) {
        // Custom logic after successful verification
        $referenceId = $receipt->getReferenceId();

        // Send confirmation email
        mail('customer@example.com', 'Payment Confirmed', "Your payment reference: $referenceId");

        // Trigger fulfillment
        processOrder($receipt->getDetail('orderId'));
    });
```

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

### Custom Gateway Fields with PHP

Source: https://context7.com/shetabit/multipay/llms.txt

Shows how to use gateway-specific custom fields, such as ResNum1-4 for the SEP gateway, to store additional order or customer information. It also includes configuration for a local testing driver.

```php
<?php

use Shetabit\Multipay\Payment;
use Shetabit\Multipay\Invoice;

$paymentConfig = require('config/payment.php');
$payment = new Payment($paymentConfig);

// SEP gateway supports up to 4 custom fields (ResNum1-4)
// These appear in gateway's reporting panel
$invoice = (new Invoice)->amount(150000);

$invoice->detail([
    'ResNum1' => 'ORDER-2023-12345',      // Order ID
    'ResNum2' => 'CUSTOMER-5678',         // Customer ID
    'ResNum3' => 'STORE-NORTH-01',        // Store location
    'ResNum4' => 'AGENT-JOHN'             // Sales agent
]);

$payment->via('sep')
    ->purchase($invoice, function($driver, $transactionId) {
        // Custom fields will be visible in SEP gateway reports
        echo "Custom fields submitted to gateway";
    });

// Local driver configuration for testing
$localInvoice = (new Invoice)->amount(10000);
$localInvoice->detail([
    'orderId' => 'TEST-ORDER-001',
    'failedPurchase' => false  // Set to error message string to simulate purchase failure
]);

$payment->via('local')
    ->purchase($localInvoice, function($driver, $transactionId) {
        echo "Test transaction: " . $transactionId;
    })->pay()->render(); // Shows test payment form with Accept/Cancel buttons

```

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

### Configure Xendit Payment Driver Settings

Source: https://github.com/shetabit/multipay/blob/master/src/Drivers/Xendit/README.md

Configures Xendit payment gateway settings including secret key, API URL, currency, and optional parameters like customer information and payment method restrictions. Required for initializing the payment driver.

```php
'xendit' => [
    'secretKey' => 'your-xendit-secret-key',
    'apiUrl' => 'https://api.xendit.co/', // Optional, defaults to production URL
    'currency' => 'IDR', // Optional, defaults to IDR
    'description' => 'Payment via Xendit', // Optional
    'invoiceDuration' => 86400, // Optional, in seconds (24 hours default)
    
    // Optional customer information
    'payerEmail' => 'customer@example.com',
    'customerName' => 'John Doe',
    'notificationEmail' => 'notifications@yoursite.com',
    
    // Optional redirect URLs
    'successReturnUrl' => 'https://yoursite.com/payment/success',
    'failureReturnUrl' => 'https://yoursite.com/payment/failure',
    
    // Optional payment methods restriction
    'paymentMethods' => ['CREDIT_CARD', 'BCA', 'MANDIRI', 'BNI'], // Leave empty for all methods
],
```

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

### Process Payment Purchase Flow

Source: https://github.com/shetabit/multipay/blob/master/src/Drivers/Xendit/README.md

Implements the basic payment flow using Multipay's Invoice and Payment classes. Creates an invoice with specified amount and UUID, optionally adds metadata details, then processes the purchase through Xendit driver and redirects user to payment page.

```php
use Shetabit\Multipay\Invoice;
use Shetabit\Multipay\Payment;

// Create an invoice
$invoice = new Invoice;
$invoice->amount(100000) // Amount in smallest currency unit (e.g., cents for IDR)
        ->uuid('unique-order-id-123');

// Optional: Add invoice details as metadata
$invoice->detail('order_id', 'ORD-123')
        ->detail('customer_id', 'CUST-456');

// Initialize payment with Xendit driver
$payment = Payment::via('xendit');

// Purchase (create invoice)
$transactionId = $payment->purchase($invoice);

// Redirect user to payment page
return $payment->pay();
```

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

### Handle Xendit Webhook Notifications

Source: https://github.com/shetabit/multipay/blob/master/src/Drivers/Xendit/README.md

Processes Xendit webhook notifications for payment status updates. Creates invoice from webhook data, verifies payment, and handles database updates and email confirmations. Includes error logging for failed verifications.

```php
// In your webhook controller
public function handleWebhook(Request $request)
{
    $payment = Payment::via('xendit');
    
    try {
        // Set the invoice ID from webhook data
        $invoice = new Invoice;
        $invoice->transactionId($request->input('id'));
        
        $receipt = $payment->verify();
        
        // Update order status in your database
        // Send confirmation emails, etc.
        
        return response('OK');
        
    } catch (\Exception $e) {
        \Log::error('Xendit webhook verification failed: ' . $e->getMessage());
        return response('Error', 400);
    }
}
```

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

### Verify Payment Transaction Status

Source: https://github.com/shetabit/multipay/blob/master/src/Drivers/Xendit/README.md

Handles payment verification process to confirm transaction status and retrieve payment details. Typically used in webhook handlers or return URL controllers. Returns receipt with transaction reference, payment method, and payment timestamp.

```php
use Shetabit\Multipay\Payment;

// Verify payment (usually in webhook or return URL handler)
$payment = Payment::via('xendit');

try {
    $receipt = $payment->verify();
    
    // Payment successful
    $transactionId = $receipt->getReferenceId();
    $paymentMethod = $receipt->getDetail('payment_method');
    $paidAt = $receipt->getDetail('paid_at');
    
    // Handle successful payment
    
} catch (\Shetabit\Multipay\Exceptions\InvalidPaymentException $e) {
    // Payment failed or invalid
    // Handle failed payment
}
```

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

### Retrieve Invoice Data Manually

Source: https://github.com/shetabit/multipay/blob/master/src/Drivers/Xendit/README.md

Retrieves invoice data manually using the Xendit driver. Useful for checking invoice status, retrieving invoice details, or verifying invoice existence before processing payments.

```php
$payment = Payment::via('xendit');
$invoiceData = $payment->getInvoice('invoice-id-here');
```
Tokens:
Raw