This is a PHP Package for Payment Gateway Integration. This package supports PHP 7.2+
.
Donate me if you like this package đ
For Laravel integration you can use shetabit/payment package.
This packages works with multiple drivers, and you can create custom drivers if you can't find them in the current drivers list (below list).
- asanpardakht
â ď¸ (not tested) - behpardakht (mellat) âď¸
- idpay âď¸
- irankish âď¸
- nextpay âď¸
- parsian âď¸
- pasargad âď¸
- payir âď¸
- paypal (will be added soon in next version)
- payping âď¸
- paystar âď¸
- poolam âď¸
- sadad (melli) âď¸
- saman âď¸
- yekpay âď¸
- zarinpal âď¸
- zibal âď¸
- Others are under way.
Help me to add the gateways below by creating pull requests
- stripe
- authorize
- 2checkout
- braintree
- skrill
- payU
- amazon payments
- wepay
- payoneer
- paysimple
- saderat
you can create your own custom drivers if it's not exists in the list, read the
Create custom drivers
section.
Via Composer
$ composer require shetabit/multipay
a. Copy config/payment.php
and put it somewhere in your project. (you can also find it in vendor/shetabit/multipay/config/payment.php
path).
b. In the config file you can set the default driver
to use for all your payments. But you can also change the driver at runtime.
Choose what gateway you would like to use in your application. Then make that as default driver so that you don't have to specify that everywhere. But, you can also use multiple gateways in a project.
// Eg. if you want to use zarinpal.
'default' => 'zarinpal',
Then fill the credentials for that gateway in the drivers array.
'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'),
],
...
]
c. Instantiate the Payment
class and pass configs to it like the below:
use Shetabit\Multipay\Payment;
// load the config file from your project
$paymentConfig = require('path/to/payment.php');
$payment = new Payment($paymentConfig);
your Invoice
holds your payment details, so initially we'll talk about Invoice
class.
before doing any thing you need to use Invoice
class to create an invoice.
In your code, use it like the below:
// At the top of the file.
use Shetabit\Multipay\Invoice;
...
// Create new invoice.
$invoice = new Invoice;
// Set invoice amount.
$invoice->amount(1000);
// Add invoice details: There are 4 syntax available for this.
// 1
$invoice->detail(['detailName' => 'your detail goes here']);
// 2
$invoice->detail('detailName','your detail goes here');
// 3
$invoice->detail(['name1' => 'detail1','name2' => 'detail2']);
// 4
$invoice->detail('detailName1','your detail1 goes here')
->detail('detailName2','your detail2 goes here');
Available methods:
uuid
: set the invoice unique idgetUuid
: retrieve the invoice current unique iddetail
: attach some custom details into invoicegetDetails
: retrieve all custom detailsamount
: set the invoice amountgetAmount
: retrieve invoice amounttransactionId
: set invoice payment transaction idgetTransactionId
: retrieve payment transaction idvia
: set a driver we use to pay the invoicegetDriver
: retrieve the driver
In order to pay the invoice, we need the payment transactionId. We purchase the invoice to retrieve transaction id:
// 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->purchase($invoice,function($driver, $transactionId) {
// We can store $transactionId in database.
});
// Purchase method accepts a callback function.
$payment->purchase($invoice, function($driver, $transactionId) {
// We can store $transactionId in database.
});
// You can specify callbackUrl
$payment->callbackUrl('http://yoursite.com/verify')->purchase(
$invoice,
function($driver, $transactionId) {
// We can store $transactionId in database.
}
);
After purchasing the invoice, we can redirect the user to the bank payment page:
// 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 and pay the given invoice.
// You should use return statement to redirect user to the bank page.
return $payment->purchase($invoice, function($driver, $transactionId) {
// Store transactionId in database as we need it to verify payment in the future.
})->pay()->render();
// Do all things together in a single line.
return $payment->purchase(
(new Invoice)->amount(1000),
function($driver, $transactionId) {
// Store transactionId in database.
// We need the transactionId to verify payment in the future.
}
)->pay()->render();
// Retrieve json format of Redirection (in this case you can handle redirection to bank gateway)
return $payment->purchase(
(new Invoice)->amount(1000),
function($driver, $transactionId) {
// Store transactionId in database.
// We need the transactionId to verify payment in the future.
}
)->pay()->toJson();
When user has completed the payment, the bank redirects them to your website, then you need to verify your payment in order to ensure the invoice
has been paid.
// 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();
...
} 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();
}
-
// 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. } );
-
// 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. } );
-
// 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. } );
-
// 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. } ); // Also we can change multiple configs at the same time. $payment->config(['key1' => 'value1', 'key2' => 'value2'])->purchase( $invoice, function($driver, $transactionId) { // We can store $transactionId in database. } );
First you have to add the name of your driver, in the drivers array and also you can specify any config parameters you want.
'drivers' => [
'zarinpal' => [...],
'my_driver' => [
... // Your Config Params here.
]
]
Now you have to create a Driver Map Class that will be used to pay invoices.
In your driver, You just have to extend Shetabit\Multipay\Abstracts\Driver
.
Eg. You created a class: App\Packages\Multipay\Driver\MyDriver
.
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');
}
}
Once you create that class you have to specify it in the payment.php
config file map
section.
'map' => [
...
'my_driver' => App\Packages\Multipay\Driver\MyDriver::class,
]
Note: You have to make sure that the key of the map
array is identical to the key of the drivers
array.
Notice 1: event listeners will be registered globaly for all payments.
Notice 2: if you want your listeners work correctly, you must subcribe them before the target event dispatches.
Its better to subcribe events in your app's entry point or main service provider, so events will be subcribed before any events dispatches.
You can listen for 3 events:
- purchase
- pay
- verify.
- purchase: Occurs when an invoice is purchased (after purchasing invoice is done successfully).
// add purchase event listener
Payment::addPurchaseListener(function($driver, $invoice) {
echo $driver;
echo $invoice;
});
- pay: Occurs when an invoice is prepared to pay.
// 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';
});
- verify: Occurs when an invoice is verified successfully.
// 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
Please see CHANGELOG for more information on what has been changed recently.
Please see CONTRIBUTING and CONDUCT for details.
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.