PHP Payments with Omnipay
CONFOO MONTREAL 2017
A presentation at ConFoo Montreal in March 2017 in Montreal, QC, Canada by Drew McLellan
CONFOO MONTREAL 2017
Hello!
I’m Drew McLellan.
Lead dev on Perch CMS.
@drewm
github.com/drewm
Nasty bespoke checkout methods. Promotions and shipping and carts. OMG taxes! Payment gateways really suck!
We all end up building solutions that are tightly coupled to a given gateway’s solution.
This makes it really hard to change gateway, to move code from project to project, or add additional payment options.
We wanted to support as many payment gateways globally as we could.
We didn’t want to support any gateways, really.
An abstraction layer sounded like a great idea.
omnipay.thephpleague.com
Omnipay is a payment processing library for PHP.
It acts as an abstraction layer between your code and the implementation details of using a payment gateway API.
It has drivers for many different gateways.
Omnipay will fix your payment gateway problems like PDO fixes your MySQL problems.
Omnipay gives you a consistent API across different implementations.
That makes it easy to move code from project to project, and means less code needs to be changed if the underlying gateway changes.
Omnipay won’t make your MSSQL queries run on Postgres. (So to speak.)
Different gateways still have different process flows, and different weird requirements.
Omnipay just eases some of the pain and unifies the interface.
Gateway drivers Payment gateways are supported by drivers - a basic Adaptor pattern. Omnipay core provides the framework. Each gateway then has its own driver. There are o ffi cial, third party and then custom gateway drivers.
O
ffi
cial Gateways
2Checkout
Authorize.Net
Buckaroo
CardSave
Coinbase
Dummy
eWAY
First Data
GoCardless
Manual
Migs
Mollie
MultiSafepay
Netaxept (BBS)
Netbanx
PayFast
Pay
fl
ow
PaymentExpress (DPS)
PayPal
Pin Payments
Sage Pay
SecurePay
Stripe
Ta r g e t P a y
WorldPay
Third-party gateways Agms Alipay Barclays ePDQ CardGate Cybersource Cybersource SOAP DataCash ecoPayz Fasapay Fat Zebra Globalcloudpay Helcim Neteller Network Merchants Inc. (NMI) Pacnet PaymentSense PayPro PayU Realex SecPay Sisow Skrill Wirecard
Let’s take a look.
Calling Omnipay::create() instantiates a new gateway object.
To make that gateway object useful, we need to set the security credentials. For Stripe, that’s an API key.
Other gateways have different credentials that need to be set.
The gateway’s purchase() method takes an amount, a currency and details of the payment card. This can be literal card details as shown, but is often a card token. After detailing the purchase, the send() method sends the message to the gateway.
For token payments (like when using stripe.js) you can pass in a token instead of a card.
The response has an isSuccessful() method to check for success.
Many gateways respond to a payment request with a URL to send the customer to. This is often the case for payment fl ows where the customer gives their card details direct to the gateway and not the merchant site.
The response has an isSuccessful() method to check for success. Some gateways take payment o ff -site. Those will test true for isRedirect(). If neither is the case, the payment failed.
After redirection, the gateway will usually make a call back to your code to indicate whether the transaction was successful or not.
Complete after redirect
$gateway->completePurchase([
'amount' => '10.00',
'currency' => 'USD',
'transactionId' => '1234'
])->send();
When returning from an off - site gateway, you need to complete the purchase using the same options. Some gateways validate options to make sure the transaction hasn’t been messed with.
Options
Options Most actions involve an $options array. It’s often quite hard to fi gure out what should be in it, as every gateway expects something di ff erent. There are a few common options, however.
Options card token amount currency description transactionId clientIp returnUrl cancelUrl
Setting options $response
=
$gateway -> purchase ([
'amount'
=>
'10.00' ,
'currency'
=>
'USD' ,
'card'
=> [ ... ],
'description'
=>
'Event tickets' ,
'transactionId'
=>
$order -> id ,
'clientIp'
=>
$_SERVER [ 'REMOTE_ADDR' ],
'returnUrl'
=>
‘https://.../complete-payment/' ,
'cancelUrl'
=>
‘https://.../failed-payment/'
]) -> send (); Options are passed into most Omnipay action methods as an associative array.
Cards firstName lastName number expiryMonth expiryYear startMonth startYear cvv issueNumber type billingAddress1 billingAddress2 billingCity billingPostcode billingState billingCountry billingPhone shippingAddress1 shippingAddress2 shippingCity shippingPostcode shippingState shippingCountry shippingPhone company email
Yay abstraction! billingAddress1 ==> adrStreet
What can we do?
Types of transaction Authorize (and then capture) Purchase Refund Void
Authorize gateway
= Omnipay :: create ( 'Stripe' ); $gateway -> setApiKey ( 'abc123' ); $response
=
$gateway -> authorize ([
'amount'
=>
'10.00' ,
'currency'
=>
'USD' ,
'card'
=> [ ... ] ]) -> send (); if ( $response -> isSuccessful ()) {
$transactionId
=
$response -> getTransactionReference ();
$response
=
$gateway -> capture ([
'amount'
=>
'10.00' ,
'currency'
=>
'USD' ,
'transactionId'
=>
$transactionId
]) -> send (); } Authorization is performed with the authorize() method. This enables us to get the transaction reference. When we want to take the money, we use the capture()
method.
Purchase // Send token purchase request $response
=
$gateway -> purchase ([
'amount'
=>
'10.00' ,
'currency'
=>
'USD' ,
'token'
=>
'abcd1234'
]) -> send ();
$transactionId
=
$response -> getTransactionReference (); Very straightforward, as we’ve already seen.
Refund $response
=
$gateway -> refund ([
'amount'
=>
'10.00' ,
'currency'
=>
'USD' ,
'transactionId'
=>
'abc123'
]) -> send (); Transactions can be refunded, although the bounds within this can be performed may depend on the gateway.
Void $response
=
$gateway -> void ([
'amount'
=>
'10.00' ,
'currency'
=>
'USD' ,
'transactionId'
=>
'abc123'
]) -> send (); A transaction can generally only be voided within the fi rst 24 hours.
To ke n b i l l i n g $response
=
$gateway -> createCard ([
'card'
=> [ ... ], ]) -> send (); $cardId
=
$response -> getTransactionReference (); Create, update and delete cards. Creating a card gives you a cardReference which can be used in future transactions.
To ke n b i l l i n g $gateway -> purchase ([
'amount'
=>
'10.00' ,
'cardReference'
=>
'abc123'
]) -> send(); Create, update and delete cards. Creating a card gives you a cardReference which can be used in future transactions.
What can’t we do?
Limitations No recurring billing. Not much of anything else.
e.g. getting location details Omnipay has a fetchTransaction() method which returns details of the transaction. The response is gateway dependant, so may or may not have the information we need. If it doesn’t there may not be an Omnipay method available.
Going out of scope When you need to do something the gateway driver doesn’t provide, things can get messy. You either need to try to extend the driver, or fall back to code outside of Omnipay. If your requirement is common, you might want to submit a patch.
Going out of scope What you’re trying to do might not be a goal for the project. See also: recurring payments.
Contributing
Contributing Gateway drivers are maintained as individual open source projects with their own maintainers. Making a change is as easy as making a Github pull request… which is to say it’s of unknown ease. Could be accepted, or rejected, or ignored. Yay open source.
Contributing You can develop your own gateway driver. There are guidelines to follow if you’d like it to be adopted as o ffi cial. Yay open source.
What’s good?
What’s good Learn one API to use with all providers Write code that can be moved between projects Makes the friction of switching between providers much lower Open source: bene fi t from others’ work Open source: fi x and contribute back when needed
What’s bad?
What’s bad? API is abstracted, but gateway fl ow is not Limited to a lowest common denominator for functionality No recurring payments Open source: gateways are sometimes incomplete Open source: getting PRs accepted can be hit and miss
On balance… Omnipay is a useful library that takes a lot of friction away. Be aware of what problems it isn’t solving for you, and use it for the problems it does solve.
Thanks! @drewm
