THIS PACKAGE IS NOT MAINTAINED ANYMORE
Accept payments from payment gateways
This Laravel package enables you to accept payments from payment gateways. Currently the only implementation is Europabank.
Spatie is a webdesign agency in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.
Postcardware
You're free to use this package (it's MIT-licensed), but if it makes it to your production environment you are required to send us a postcard from your hometown, mentioning which of our package(s) you are using.
Our address is: Spatie, Samberstraat 69D, 2060 Antwerp, Belgium.
The best postcards will get published on the open source page on our website.
Installation
The package can be installed through Composer:
composer require spatie/payment
This service provider must be installed:
//for laravel <=4.2: app/config/app.php
'providers' => [
...
'Spatie\Payment\PaymentServiceProvider'
...
];Configuration
You can publish the configuration file using this command:
php artisan config:publish spatie/payment
A configuration-file with some sensible defaults will be placed in your config/packages directory:
return
[
'form' =>
[
/*
* The class or classes that you want to put on the submit button
* of the payment form
*/
'submitButtonClass' => 'test'
],
'europabank' =>
[
'clientSecret' => getenv('EUROPABANK_CLIENT_SECRET'),
'serverSecret' => getenv('EUROPABANK_SERVER_SECRET'),
/*
* MPI Account number
*/
'uid' => getenv('EUROPABANK_UID'),
/*
* The url to where the payment will take place
*/
'mpiUrl' => '',
/*
* The name of the route where Europabank will redirect to
* after the payment has been made
*
*/
'paymentLandingPageRoute' => 'verifyPayment',
/*
* Optional url of the css which must be applied on the payment form
*/
'formCss'=> '',
/*
* Url of the template which will be applied on Europabank pages
*/
'template'=> '',
/*
* Optional title of the payment form
*/
'formTitle' => '',
/*
* Optional e-mail address of the merchant
*/
'merchantEmail' => '',
/*
* Optional e-mail address to use as sender for the second chance
* or payment link e-mail
*/
'secondChanceEmailSender' => '',
]
];General payment flow
Though there are multiple ways to pay an order, most payment gateways except you to follow the following flow in your checkout process:
1. The customer is redirected to the payment provider
After the customer has gone through the checkout process and is ready to pay, the customer must be redirected to site of the payment provider.
The redirection is accomplished by submitting a form with some hidden fields. The form must post to the site of the payment provider. The hidden fields minimally specify the amount that must be paid, the order id and a hash.
The hash is calculated using the hidden form fields and a non-public secret. The hash used by the payment provider to verify if the request is valid.
2. The customer pays on the site of the payment provider
The customer arrived on the site of the payment provider and gets to choose a payment method. All steps necessary to pay the order are taken care of by the payment provider.
3. The customer gets redirected back
After having paid the order the customer is redirected back. In the redirection request to the shop-site some values are returned. The values are usually the order id, a paymentresult and a hash.
The hash is calculated out of some of the fields returned and a secret non-public value. This hash is used to verify if the request is valid and comes from the payment provider. It is paramount that this hash is thoroughly checked.
The payment result can be something like "payment ok", "customer cancelled payment" or "payment declined".
Usage
This package can greatly help you with step 1. and 3. of the general flow
1. Redirecting to customer to the payment provider
Let's get technical. In the controller in which you will present a view to redirect to user to the payment provider you must inject the payment gateway like so:
use Spatie\Payment\PaymentGateway;
class CheckoutConfirmOrderController extends BaseController {
/**
* @var PaymentGateway
*/
protected $paymentGateway;
public function __construct(.. PaymentGateway $paymentGateway ...)
{
...
$this->paymentGateway = $paymentGateway;
...
}In the same controller in the method in which you present the view you must set the $order that you've probably build up during the checkout-process.
public function showOrderDetails()
{
$order = $this->orderRepo->getCurrentOrder();
$paymentGateway = $this->paymentGateway->setOrder($order);
return View::make('front.checkout.confirmOrder')->with(compact('order', 'paymentGateway'));
}The $order you pass to the payment gateway must adhere to the PayableOrder-interface:
interface PayableOrder {
/**
* @return string
*/
public function getPaymentOrderId();
/**
* @return double
*/
public function getPaymentAmount();
/**
* @return string
*/
public function getPaymentDescription();
/**
* @return string
*/
public function getCustomerEmail();
/**
* @return string
*/
public function getCustomerLanguage();
} So your Order-model should look something like
....
use Spatie\Payment\PayableOrder;
class Order extends Eloquent implements PayableOrder
{
...
/**
* @return string
*/
public function getPaymentOrderId()
{
return $this->id;
}
/**
* Should be in eurocents for most payments providers
* @return double
*/
public function getPaymentAmount()
{
return $this->getTotal() * 100;
}
/**
* @return string
*/
public function getPaymentDescription()
{
return 'Order ' . $this->id;
}
/**
* @return string
*/
public function getCustomerEmail()
{
return $this->email;
}
/**
* @return string
*/
public function getCustomerLanguage()
{
return App::getLocale();
}
}Please note that for most payment providers the result of getPaymentAmount()should be specified in eurocents.
After you've taken care of all steps above you can generate the form that will redirect the customer to the payment provider.
In your view you can simply use the getPaymentForm()-method
{{ $paymentGateway->getPaymentForm() }}
The result of this form is something like:
<form method="POST" action="https://www.ebonline.be/test/mpi/authenticate" accept-charset="UTF-8">
<input name="Uid" type="hidden" value="9063470101">
<input name="Orderid" type="hidden" value="11">
<input name="Amount" type="hidden" value="5163">
<input name="Description" type="hidden" value="Order 11">
<input name="Hash" type="hidden" value="dee1c95c13aa037ded1a97482be4d10cb9a25e92">
<input name="Beneficiary" type="hidden" value="Shopname">
<input name="Redirecttype" type="hidden" value="DIRECT">
<input name="Redirecturl" type="hidden" value="http://shopname.com/verify-payment">
<input type="submit" value="Pay order">
</form>
When clicking the submit button the customer gets redirected to the site of payment provider.
You can also pass html attributes for the form element as an array.
{{ $paymentGateway->getPaymentForm(['class' => 'form']) }}
<form method="POST" action="https://www.ebonline.be/test/mpi/authenticate" accept-charset="UTF-8" class="form">
<!-- ... -->
</form>
2. Verifying the payment
So now we've redirected the customer to the payment provider. The customer did some actions there (hopefully he or she paid the order) and now gets redirected back to our shop site.
The payment provider will redirect the customer to the url of the route that is specified in the paymentLandingPageRoute-option of the config-file.
We must validate if the redirect to our site is a valid request (we don't want imposters to wrongfully place non-paid order).
In the controller that handles the request coming from the payment provider inject the PaymentGateway
use Spatie\Payment\PaymentGateway;
class CheckoutPaymentVerificationController extends BaseController {
protected $paymentGateway;
public function __construct(PaymentGateway $paymentGateway)
{
$this->paymentGateway = $paymentGateway;
}
...Then, in the same controller, in the method you use to handle the request coming from the payment provider, use the validateGatewayResponse-method:
public function verifyPayment()
{
$this->paymentGateway->validateGatewayResponse(Checkout::getCurrentOrderId());
}That method requires the order id that you are expecting a payment for. Usually you should have stored that order id in session prior to redirecting to user to the site of payment provider.
Notice that in previous example Checkout::getCurrentOrderId() is used. If you want such an elegant syntax check out the spatie/checkout-package.
If the validateGatewayResponse-method concludes that the request was not valid a Spatie\Payment\Exceptions\PaymentVerificationFailedException-exception is thrown.
3. Getting the payment result
After you've verified that the redirect from the payment provider to your site is valid you can determine the result of the payment.
To determine the result you can use the getPaymentResult()-method. It can return these constants:
Spatie\Payment\PaymentGateway::PAYMENT_RESULT_OK: all is well, the order has been paidSpatie\Payment\PaymentGateway::PAYMENT_RESULT_CANCELLED_BY_CARDHOLDER: the customer has cancelled the paymentSpatie\Payment\PaymentGateway::PAYMENT_RESULT_DECLINED: the customer tried to pay, but his payment got declined by that financial institution that handles the paymentSpatie\Payment\PaymentGateway::PAYMENT_RESULT_FAILED: an unexpected error occured.
Here is an example controller in which we verify the payment-request and determine the result:
use Spatie\Payment\PaymentGateway;
class CheckoutPaymentVerificationController extends BaseController {
protected $paymentGateway;
public function __construct(PaymentGateway $paymentGateway)
{
$this->paymentGateway = $paymentGateway;
}
public function verifyPayment()
{
$this->paymentGateway->validateGatewayResponse(Checkout::getCurrentOrderId());
switch($this->paymentGateway->getPaymentResult())
{
case PaymentGateway::PAYMENT_RESULT_OK:
//take necessary actions to mark order as confirmed
break;
case PaymentGateway::PAYMENT_RESULT_CANCELLED_BY_CARDHOLDER:
//take necessary actions to mark order as failed
break;
case PaymentGateway::PAYMENT_RESULT_DECLINED:
//take necessary actions to mark order as failed
break;
case PaymentGateway::PAYMENT_RESULT_FAILED:
//take necessary actions to mark order as failed
break;
case PaymentGateway::PAYMENT_TIMED_OUT:
//take necessary actions to mark order as failed
break;
default:
throw new Exception('Unknown payment gateway answer');
break;
}
}
}Remarks
Currently the only implemented gateway provider is Europabank. They can give feedback on a payment in many different ways, but this package only supports the 'DIRECT'-redirecttype.
The Europabank API has many more options than this package currently provides.
All the examples above are coded to an interface: it should be fairly easy to swap out Europabank and use an other provider like Ingenico. You most certainly are welcome to send pull requests to implement other providers.
About Spatie
Spatie is a webdesign agency in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent