The League of Extraordinary Packages

Our Packages:

Presented by The League of Extraordinary Packages

Getting Started

Gateways

API

Build your own driver

Omnipay is a collection of packages which all depend on the omnipay/common package to provide a consistent interface. There are no dependencies on official payment gateway PHP packages - we prefer to work with the HTTP API directly. Under the hood, we use the popular and powerful Guzzle library to make HTTP requests.

New drivers can be created by cloning the layout of an existing package. When choosing a name for your package, please don’t use the omnipay vendor prefix, as this implies that it is officially supported. You should use your own username as the vendor prefix, and prepend omnipay- to the package name to make it clear that your package works with Omnipay. For example, if your GitHub username was santa, and you were implementing the giftpay payment library, a good name for your composer package would be santa/omnipay-giftpay.

Make your driver official

If you want to transfer your driver to the omnipay GitHub organization and add it to the list of officially supported gateways, please open a pull request on the omnipay/common package. Before new gateways will be accepted, they must have 100% unit test code coverage, and follow the conventions and code style used in other Omnipay gateways.

Omnipay Terminology

Omnipay Conventions

When developing your own payment gateway driver, it’s worth remembering that ideally the person using your driver should be able to switch between drivers easily, without modifying their own code. With that in mind, here are some conventions that are used in Omnipay: - transactionId vs transactionReference - transactionId is the Merchant’s reference to the transaction - so typically the ID of the payment record in the Merchant Site’s database. transactionReference is the Payment Gateway’s reference to the transaction. They will usually generate a unique reference for each payment attempt a customer makes. It is common practice to store this value in the Merchant Site’s database, so that the transaction can be cross-referenced with the Payment Gateway’s own records. Some Omnipay drivers also rely on this value being available in order to process refunds or repeat payments. - returnUrl vs notifyUrl - returnUrl is used by drivers when they need to tell the Payment Gateway where to redirect the customer following a transaction. Typically this is used by off-site ‘redirect’ gateway integrations. notifyUrl is used by drivers to tell the Payment Gateway where to send their server-to-server notification, informing the Merchant Site about the outcome of a transaction. The notifyUrl will typically be a script on the Merchant Site that handles the updating of the database to record whether a payment was successful or not.