shetabit/payment

An Invoice represents a single payment request. Before initiating a payment, you must create an invoice and set its amount and metadata. You can use the detail method to attach arbitrary key-value pairs to the invoice.

Available Invoice Methods:

• amount($amount): Sets the amount to be paid.
• getAmount(): Retrieves the invoice amount.
• detail($key, $value) or detail(['key' => 'value']): Adds metadata/details to the invoice.
• getDetails(): Retrieves all attached details.
• uuid(): Sets a unique identifier for the invoice.
• getUuid(): Retrieves the invoice UUID.
• transactionId($id): Sets the transaction ID.
• getTransactionId(): Retrieves the transaction ID.
• via($driver): Specifies the driver to be used for this invoice.
• getDriver(): Retrieves the selected driver.

use Shetabit//
use Shetabit\Multipay\Invoice;

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

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

// Add invoice details (multiple syntax options available)
$invoice->detail(['detailName' => 'your detail goes here']);
$invoice->detail('detailName', 'your detail goes here');
$invoice->detail(['name1' => 'detail1', 'name2' => 'detail2']);
$invoice->detail('detailName1', 'detail1')->detail('detailName2', 'detail2');

Once a purchase request is registered and you have a transactionId, you can redirect the user to the bank's payment page. Use the pay() method following a purchase() call.

• Use render() to get the redirect response (suitable for returning from a controller).
• Use toJson() to get the redirection data in JSON format if you want to handle the redirection manually via JavaScript.

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

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

// Redirect user to the bank page (Standard usage)
return Payment::purchase($invoice, function($driver, $transactionId) {
    // Store transactionId in database
})->pay()->render();

// Get JSON format for manual redirection handling
return Payment::purchase(
    (new Invoice)->amount(1000), 
    function($driver, $transactionId) {
        // Store transactionId in database
    }
)->pay()->toJson();

To add a new payment gateway, follow these steps:

1. Define Configuration: Add your driver's name and required settings to the drivers array in config/payment.php.
2. Implement the Driver Class: Create a class that extends Shetabit\Multipay\Abstracts\Driver. You must implement the following methods:
   • purchase(): Request a transaction ID from the gateway and return it.
   • pay(): Handle the redirection to the bank's URL.
   • verify(): Communicate with the gateway to confirm the payment status. If invalid, throw InvalidPaymentException. If valid, return a Receipt object.
3. Map the Driver: In config/payment.php, add your driver to the map array, ensuring the key matches the name used in the drivers array.

// 1. config/payment.php
'drivers' => [
    'my_driver' => ['some_config' => 'value'],
],
'map' => [
    'my_driver' => App\Packages\PaymentDriver\MyDriver::class,
]

// 2. Implementation
namespace App\Packages\PaymentDriver;

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

class MyDriver extends Driver
{
    protected $invoice;
    protected $settings;

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

    public function purchase() 
    {
        // ... logic to get transaction ID
        $transId = 'generated_id';
        $this->invoice->transactionId($transId);
        return $transId;
    }
    
    public function pay() 
    {
        $bankUrl = $this->settings->bankApiUrl;
        $payUrl = $bankUrl . $this->invoice->getTransactionId();
        return redirect()->to($payUrl);
    }
    
    public function verify(): ReceiptInterface 
    {
        // ... logic to verify with gateway
        $isValid = true; 

        if (!$isValid) {
            throw new InvalidPaymentException('Payment failed');
        }
        
        return new Receipt('my_driver', 'receipt_number');
    }
}

To add a new payment gateway, follow these three steps:

1. Register the driver in your config/payment.php file under the drivers array.
2. Implement the Driver class by extending Shetabit\Multipay\Abstracts\Driver. You must implement:
   • purchase(): Request a transaction ID from the provider and return it.
   • pay(): Handle the redirection to the bank's URL.
   • verify(): Call the provider's verification API. Throw InvalidPaymentException if invalid, or return a Receipt object if successful.
3. Map the driver in the map section of config/payment.php so the system knows which class to instantiate.

Note: The key in the map array must be identical to the key in the drivers array.

namespace App\
Packages\\\nPaymentDriver;

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

class MyDriver extends Driver
{
    protected $invoice;
    protected $settings;

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

    public function purchase() {
        // ... logic to get transaction ID
        $this->invoice->transactionId($transId);
        return $transId;
    }
    
    public function pay() {
        $bankUrl = $this->settings->bankApiUrl;
        $payUrl = $bankUrl . $this->invoice->getTransactionId();
        return redirect()->to($payUrl);
    }
    
    public function verify(): ReceiptInterface {
        // ... logic to verify
        // throw new InvalidPaymentException('message') if failed
        return new Receipt('driverName', 'payment_receipt_number');
    }
}