Multipay PHP Payment Gateway Abstraction

To add a new gateway, follow these steps:

1. Register the driver in your payment.php config file under the drivers array.
2. Map the driver in the map section of the same config file, pointing to your class.
3. Implement the Driver class by extending Shetabit\Multipay\Abstracts\Driver. You must implement three core methods:
   • purchase(): Request a transaction ID from the gateway and return it.
   • pay(): Return a RedirectionForm object to redirect the user.
   • verify(): Send a request to the gateway to confirm payment status. Return a Receipt on success or throw an InvalidPaymentException on failure.

Example Driver Implementation:

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
{
    public function __construct(Invoice $invoice, array|object $settings)
    {
        $this->invoice($invoice);
        $this->settings = (object) $settings;
    }

    public function purchase() : string|int|null {
        // ... logic to get transaction ID
        $transId = '123';
        $this->invoice->transactionId($transId);
        return $transId;
    }

    public function pay() : RedirectionForm {
        $bankUrl = $this->settings->bankApiUrl;
        $payUrl = $bankUrl . $this->invoice->getTransactionId();
        return $this->redirectWithForm($payUrl, [], 'GET');
    }

    public function verify(): ReceiptInterface {
        // ... logic to verify
        if (!$isSuccessful) {
            throw new InvalidPaymentException('Payment failed');
        }
        return new Receipt('my_driver', 'receipt_number');
    }
}

To initiate a payment, create an Invoice object, set the amount (in the smallest currency unit, e.g., cents for IDR) and a unique UUID. You can add metadata using the detail() method. Then, initialize the payment via the xendit driver using Payment::via('xendit'), call purchase($invoice), and finally pay() to get the redirect URL.

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

To configure the package, follow these steps:

1. Copy the configuration file from vendor/shetabit/multipay/config/payment.php to a location in your project.
2. Set your default driver in the config/payment.php file.
3. Provide the necessary credentials for your chosen driver within the drivers array.

Example configuration for zarinpal:

'default' => 'zarinpal',

'drivers' => [
    'zarinpal' => [
        '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'),
    ],
    ...
]

// Eg. if you want to use zarinpal.
'default' => 'zarinpal',

'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'),
    ],
    ...
]

Once a user is redirected back to your site, you must verify that the payment was actually successful. Use the verify() method on the Payment instance, providing the amount and the transactionId you stored earlier.

If the verification fails, an InvalidPaymentException will be thrown. You should wrap the call in a try-catch block to handle invalid payments gracefully.

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

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

try {
    // Verify using amount and the stored transaction ID
    $receipt = $payment->amount(1000)->transactionId($transaction_id)->verify();

    // Success: access the receipt reference ID
    echo $receipt->getReferenceId();
} catch (InvalidPaymentException $exception) {
    // Handle invalid payment
    echo $exception->getMessage();
}

To start a payment process, instantiate the Payment class with your configuration and call the purchase method on an Invoice. The purchase method accepts a callback that provides the $driver and $transactionId. It is highly recommended to store the $transactionId in your database for future verification.

You can also specify a callbackUrl before calling purchase to change the redirection target at runtime.

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

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

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

// Purchase with a callback to save the transaction ID
$payment->purchase($invoice, function($driver, $transactionId) {
    // Store $transactionId in database
});

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

To initiate a payment, create an Invoice and use the Payment class to execute a purchase.

Required Details:

• mobile: The customer's mobile number.
• orderId: A unique string for your order. If omitted, the driver uses the invoice UUID.

Optional Details:

• nationalId: Customer's national ID.
• basketItems: A list of items. Each item must contain a brand (string), productType (numeric), and count (positive integer). Contact Bajet to obtain valid productType values.

Important: The driver stores the redirection URL in the invoice detail bajetReferUrl. You must preserve this detail if you recreate the invoice before calling pay(). Do not attempt to construct the URL manually from the reference ID.

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

$invoice = (new Invoice)->amount(1000)->detail([
    'orderId' => 'merchant-order-123',
    'mobile' => '09120000000',
]);

$payment = new Payment($config);
$payment->via('bajet')->purchase($invoice, function ($driver, $referenceId) {
    // Persist $referenceId, the invoice amount and currency, and
    // $driver->getInvoice()->getDetails() against your local payment attempt.
});

echo $payment->pay()->render();