Home

Awesome

Omnipay

An easy to use, consistent payment processing library for PHP 5.3+

Build Status Latest Stable Version Total Downloads

Omnipay is a payment processing library for PHP. It has been designed based on ideas from Active Merchant, plus experience implementing dozens of gateways for CI Merchant. It has a clear and consistent API, is fully unit tested, and even comes with an example application to get you started.

Why use Omnipay instead of a gateway's official PHP package/example code?

Important Note: Upgrading from < 2.0

If you are upgrading from a pre-2.0 version of Omnipay, please note that the project has now been split into multiple packages. There have also been some changes to how gateway instances are created. See the full release notes for more details.

TL;DR

Just want to see some code?

use Omnipay\Omnipay;

$gateway = Omnipay::create('Stripe');
$gateway->setApiKey('abc123');

$formData = ['number' => '4242424242424242', 'expiryMonth' => '6', 'expiryYear' => '2016', 'cvv' => '123'];
$response = $gateway->purchase(['amount' => '10.00', 'currency' => 'USD', 'card' => $formData])->send();

if ($response->isSuccessful()) {
    // payment was successful: update database
    print_r($response);
} elseif ($response->isRedirect()) {
    // redirect to offsite payment gateway
    $response->redirect();
} else {
    // payment failed: display message to customer
    echo $response->getMessage();
}

As you can see, Omnipay has a consistent, well thought out API. We try to abstract as much as possible the differences between the various payments gateways.

Package Layout

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 gateways 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.

If you want to transfer your gateway 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.

Installation

Omnipay is installed via Composer. For most uses, you will need to require an individual gateway:

composer require omnipay/paypal:~2.0

To install all officially supported gateways:

composer require omnipay/omnipay:~2.0

This will require ALL ~25 Omnipay gateways and is generally discouraged.

Payment Gateways

All payment gateways must implement GatewayInterface, and will usually extend AbstractGateway for basic functionality.

The following gateways are available:

GatewayComposer PackageMaintainer
2Checkoutomnipay/2checkoutKayla Daniels
Alipaylokielse/omnipay-alipayLoki Else
Authorize.Netomnipay/authorizenetKayla Daniels
Barclays ePDQsamvaughton/omnipay-barclays-epdqSam Vaughton
Buckarooomnipay/buckarooKayla Daniels
CardSaveomnipay/cardsaveKayla Daniels
Coinbaseomnipay/coinbaseKayla Daniels
Cybersourcedioscouri/omnipay-cybersourceDioscouri Design
Cybersource SOAPdabsquared/omnipay-cybersource-soapDABSquared
DataCashcoatesap/omnipay-datacashAndrew Coates
Dummyomnipay/dummyKayla Daniels
ecoPayzdercoder/omnipay-ecopayzAlexander Fedra
eWAYomnipay/ewayKayla Daniels
First Dataomnipay/firstdataAndrew Coates
Fasapayandreas22/omnipay-fasapayAndreas Christodoulou
GoCardlessomnipay/gocardlessKayla Daniels
Manualomnipay/manualKayla Daniels
Migsomnipay/migsKayla Daniels
Mollieomnipay/mollieKayla Daniels
MultiSafepayomnipay/multisafepayAlexander Deruwe
Netaxept (BBS)omnipay/netaxeptKayla Daniels
Netbanxomnipay/netbanxMaks Rafalko
Netelleralfaproject/omnipay-netellerJoão Dias
Network Merchants Inc. (NMI)mfauveau/omnipay-nmiMatthieu Fauveau
Pacnetmfauveau/omnipay-pacnetMatthieu Fauveau
PayFastomnipay/payfastKayla Daniels
Payflowomnipay/payflowKayla Daniels
PaymentExpress (DPS)omnipay/paymentexpressKayla Daniels
PaymentSensecoatesap/omnipay-paymentsenseAndrew Coates
PayPalomnipay/paypalKayla Daniels
PayUomnipay/payuefesaid
Pin Paymentsomnipay/pinKayla Daniels
Realexcoatesap/omnipay-realexAndrew Coates
Sage Payomnipay/sagepayKayla Daniels
SecurePayomnipay/securepayKayla Daniels
SecPayjustinbusschau/omnipay-secpayJustin Busschau
Sisowfruitcakestudio/omnipay-sisowFruitcake Studio
Skrillalfaproject/omnipay-skrillJoão Dias
Stripeomnipay/stripeKayla Daniels
TargetPayomnipay/targetpayAlexander Deruwe
WorldPayomnipay/worldpayKayla Daniels
WorldPay XML Directteaandcode/omnipay-worldpay-xmlDave Nash
Veritransandylibrian/omnipay-veritransAndy Librian
Yandex.MoneyaTastyCookie/yandexmoney_omnipayRoman Ananyev

Gateways are created and initialized like so:

use Omnipay\Omnipay;

$gateway = Omnipay::create('PayPal_Express');
$gateway->setUsername('adrian');
$gateway->setPassword('12345');

Most settings are gateway specific. If you need to query a gateway to get a list of available settings, you can call getDefaultParameters():

$settings = $gateway->getDefaultParameters();
// default settings array format:
array(
    'username' => '', // string variable
    'testMode' => false, // boolean variable
    'landingPage' => array('billing', 'login'), // enum variable, first item should be treated as default
);

Generally most payment gateways can be classified as one of two types:

However, there are some gateways such as Sage Pay Direct, where you take credit card details on site, then optionally redirect if the customer's card supports 3D Secure authentication. Therefore, there is no point differentiating between the two types of gateway (other than by the methods they support).

Credit Card / Payment Form Input

User form input is directed to an CreditCard object. This provides a safe way to accept user input.

The CreditCard object has the following fields:

Even off-site gateways make use of the CreditCard object, because often you need to pass customer billing or shipping details through to the gateway.

The CreditCard object can be initialized with untrusted user input via the constructor. Any fields passed to the constructor which are not recognized will be ignored.

$formInputData = array(
    'firstName' => 'Bobby',
    'lastName' => 'Tables',
    'number' => '4111111111111111',
);
$card = new CreditCard($formInputData);

You can also just pass the form data array directly to the gateway, and a CreditCard object will be created for you.

CreditCard fields can be accessed using getters and setters:

$number = $card->getNumber();
$card->setFirstName('Adrian');

If you submit credit card details which are obviously invalid (missing required fields, or a number which fails the Luhn check), InvalidCreditCardException will be thrown. You should validate the card details using your framework's validation library before submitting the details to your gateway, to avoid unnecessary API calls.

For on-site payment gateways, the following card fields are generally required:

You can also verify the card number using the Luhn algorithm by calling Helper::validateLuhn($number).

Gateway Methods

The main methods implemented by gateways are:

On-site gateways do not need to implement the completeAuthorize and completePurchase methods. If any gateway does not support certain features (such as refunds), it will throw BadMethodCallException.

All gateway methods take an $options array as an argument. Each gateway differs in which parameters are required, and the gateway will throw InvalidRequestException if you omit any required parameters. All gateways will accept a subset of these options:

Pass the options through to the method like so:

$card = new CreditCard($formData);
$request = $gateway->authorize([
    'amount' => '10.00', // this represents $10.00
    'card' => $card,
    'returnUrl' => 'https://www.example.com/return',
]);

When calling the completeAuthorize or completePurchase methods, the exact same arguments should be provided as when you made the initial authorize or purchase call (some gateways will need to verify for example the actual amount paid equals the amount requested). The only parameter you can omit is card.

To summarize the various parameters you have available to you:

The Payment Response

The payment response must implement ResponseInterface. There are two main types of response:

Successful Response

For a successful responses, a reference will normally be generated, which can be used to capture or refund the transaction at a later date. The following methods are always available:

$response = $gateway->purchase(['amount' => '10.00', 'card' => $card])->send();

$response->isSuccessful(); // is the response successful?
$response->isRedirect(); // is the response a redirect?
$response->getTransactionReference(); // a reference generated by the payment gateway
$response->getMessage(); // a message generated by the payment gateway

In addition, most gateways will override the response object, and provide access to any extra fields returned by the gateway.

Redirect Response

The redirect response is further broken down by whether the customer's browser must redirect using GET (RedirectResponse object), or POST (FormRedirectResponse). These could potentially be combined into a single response class, with a getRedirectMethod().

After processing a payment, the cart should check whether the response requires a redirect, and if so, redirect accordingly:

$response = $gateway->purchase(['amount' => '10.00', 'card' => $card])->send();
if ($response->isSuccessful()) {
    // payment is complete
} elseif ($response->isRedirect()) {
    $response->redirect(); // this will automatically forward the customer
} else {
    // not successful
}

The customer isn't automatically forwarded on, because often the cart or developer will want to customize the redirect method (or if payment processing is happening inside an AJAX call they will want to return JS to the browser instead).

To display your own redirect page, simply call getRedirectUrl() on the response, then display it accordingly:

$url = $response->getRedirectUrl();
// for a form redirect, you can also call the following method:
$data = $response->getRedirectData(); // associative array of fields which must be posted to the redirectUrl

Error Handling

You can test for a successful response by calling isSuccessful() on the response object. If there was an error communicating with the gateway, or your request was obviously invalid, an exception will be thrown. In general, if the gateway does not throw an exception, but returns an unsuccessful response, it is a message you should display to the customer. If an exception is thrown, it is either a bug in your code (missing required fields), or a communication error with the gateway.

You can handle both scenarios by wrapping the entire request in a try-catch block:

try {
    $response = $gateway->purchase(['amount' => '10.00', 'card' => $card])->send();
    if ($response->isSuccessful()) {
        // mark order as complete
    } elseif ($response->isRedirect()) {
        $response->redirect();
    } else {
        // display error to customer
        exit($response->getMessage());
    }
} catch (\Exception $e) {
    // internal error, log exception and display a generic message to the customer
    exit('Sorry, there was an error processing your payment. Please try again later.');
}

Token Billing

Token billing allows you to store a credit card with your gateway, and charge it at a later date. Token billing is not supported by all gateways. For supported gateways, the following methods are available:

Once you have a cardReference, you can use it instead of the card parameter when creating a charge:

$gateway->purchase(['amount' => '10.00', 'cardReference' => 'abc']);

Recurring Billing

At this stage, automatic recurring payments functionality is out of scope for this library. This is because there is likely far too many differences between how each gateway handles recurring billing profiles. Also in most cases token billing will cover your needs, as you can store a credit card then charge it on whatever schedule you like. Feel free to get in touch if you really think this should be a core feature and worth the effort.

Example Application

An example application is provided in the omnipay/example repo. You can run it using PHP's built in web server (PHP 5.4+):

$ php composer.phar update --dev
$ php -S localhost:8000

For more information, see the Omnipay example application.

Support

If you are having general issues with Omnipay, we suggest posting on Stack Overflow. Be sure to add the omnipay tag so it can be easily found.

If you want to keep up to date with release anouncements, discuss ideas for the project, or ask more detailed questions, there is also a mailing list which you can subscribe to.

If you believe you have found a bug, please report it using the GitHub issue tracker for the appropriate package, or better yet, fork the library and submit a pull request.

Security

If you discover any security related issues, please email kayladnls@gmail.com instead of using the issue tracker.

Feedback

Please provide feedback! We want to make this library useful in as many projects as possible. Please head on over to the mailing list and point out what you do and don't like, or fork the project and make suggestions. No issue is too small.