From 25b103e682dce2763871962bb3dd52a0d211e478 Mon Sep 17 00:00:00 2001 From: Jonathan Reinink Date: Wed, 15 Oct 2014 14:41:08 -0400 Subject: [PATCH 01/43] Initial commit. Setup site structure (menu, project information, etc). Add home page and simple example page. --- .gitignore | 1 + CNAME | 0 _data/images.yml | 8 ++++ _data/menu.yml | 19 +++++++++ _data/project.yml | 4 ++ _layouts/default.html | 99 +++++++++++++++++++++++++++++++++++++++++++ index.md | 33 +++++++++++++++ simple-example.md | 34 +++++++++++++++ 8 files changed, 198 insertions(+) create mode 100644 .gitignore create mode 100644 CNAME create mode 100644 _data/images.yml create mode 100644 _data/menu.yml create mode 100644 _data/project.yml create mode 100644 _layouts/default.html create mode 100644 index.md create mode 100644 simple-example.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..c08f9add --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +_site \ No newline at end of file diff --git a/CNAME b/CNAME new file mode 100644 index 00000000..e69de29b diff --git a/_data/images.yml b/_data/images.yml new file mode 100644 index 00000000..7d475040 --- /dev/null +++ b/_data/images.yml @@ -0,0 +1,8 @@ +# Path to project specific favicon.ico, leave blank to use default +favicon: + +# Path to project specific apple-touch-icon-precomposed.png, leave blank to use default +apple_touch: + +# Path to project logo +logo: \ No newline at end of file diff --git a/_data/menu.yml b/_data/menu.yml new file mode 100644 index 00000000..baab74e9 --- /dev/null +++ b/_data/menu.yml @@ -0,0 +1,19 @@ +Getting Started: + Introduction: '/' + Simple Example: '/simple-example/' + Installation: '/installation/' + Changelog: '/changelog/' +Gateways: + Available: '/gateways/available/' + Build your own: '/gateways/build-your-own/' + Configuring: '/gateways/configuring/' +API: + Cards: '/api/cards/' + Authorizing: '/api/authorizing/' + Charging: '/api/charging/' + Refunding: '/api/refunding/' + Voiding: '/api/voiding/' + Responses: '/api/responses/' + Error Handling: '/api/error-handling/' + Token Billing: '/api/token-billing/' + Recurring Billing: '/api/recurring-billing/' \ No newline at end of file diff --git a/_data/project.yml b/_data/project.yml new file mode 100644 index 00000000..7ee328d3 --- /dev/null +++ b/_data/project.yml @@ -0,0 +1,4 @@ +title: Omnipay +tagline: Multi-gateway payment processing library +description: +google_analytics_tracking_id: UA-46050814-12 \ No newline at end of file diff --git a/_layouts/default.html b/_layouts/default.html new file mode 100644 index 00000000..ceace8a6 --- /dev/null +++ b/_layouts/default.html @@ -0,0 +1,99 @@ + + + + + + + {% if page.url == '/' %} + {{ site.data.project.title }} - {{ site.data.project.tagline }} + {% else %} + {{ page.title }} - {{ site.data.project.title }} + {% endif %} + {% if site.data.project.description %} + + {% endif %} + {% if site.data.images.favicon %} + + {% else %} + + {% endif %} + {% if site.data.images.apple_touch %} + + {% else %} + + {% endif %} + + + + +
+ + The League of Extraordinary Packages + +

Our Packages:

+ +
+ +
+ + + Presented by The League of Extraordinary Packages + +
+ + + + +
+ + {% for section in site.data.menu %} +

{{ section[0] }}

+
    + {% for link in section[1] %} +
  • + {{ link[0] }} +
    • + {% endfor %} +
+ {% endfor %} + +
+ {{ content }} +
+
+ + + + + + + +{% if site.data.project.google_analytics_tracking_id %} + +{% endif %} + + + \ No newline at end of file diff --git a/index.md b/index.md new file mode 100644 index 00000000..b72cae20 --- /dev/null +++ b/index.md @@ -0,0 +1,33 @@ +--- +layout: default +permalink: / +title: Introduction +--- + +Introduction +============ + +[![Build Status](https://travis-ci.org/thephpleague/omnipay-common.png?branch=master)](https://travis-ci.org/thephpleague/omnipay-common) +[![Latest Stable Version](https://poser.pugx.org/omnipay/omnipay/version.png)](https://packagist.org/packages/omnipay/omnipay) +[![Total Downloads](https://poser.pugx.org/omnipay/omnipay/d/total.png)](https://packagist.org/packages/omnipay/omnipay) + +Omnipay is a payment processing library for PHP. It has been designed based on +ideas from [Active Merchant](http://activemerchant.org/), plus experience implementing +dozens of gateways for [CI Merchant](http://ci-merchant.org/). 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? + +* Because you can learn one API and use it in multiple projects using different payment gateways +* Because if you need to change payment gateways you won't need to rewrite your code +* Because most official PHP payment gateway libraries are a mess +* Because most payment gateways have exceptionally poor documentation +* Because you are writing a shopping cart and need to support multiple gateways + +## 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](https://github.com/thephpleague/omnipay/releases/tag/v2.0.0) +for more details. \ No newline at end of file diff --git a/simple-example.md b/simple-example.md new file mode 100644 index 00000000..85a194ae --- /dev/null +++ b/simple-example.md @@ -0,0 +1,34 @@ +--- +layout: default +permalink: simple-example/ +title: Simple Example +--- + +Simple Example +============== + +Just want to see some code? + +~~~ php +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. \ No newline at end of file From 6ba95eb8f27c3c7baaa2bb14e08cbdc21341bd46 Mon Sep 17 00:00:00 2001 From: Jonathan Reinink Date: Wed, 22 Oct 2014 22:19:43 -0400 Subject: [PATCH 02/43] Create all pages and add existing content. --- _data/menu.yml | 5 +- _data/project.yml | 3 +- _layouts/default.html | 3 + api/authorizing.md | 50 ++++++++++++++++ api/cards.md | 85 ++++++++++++++++++++++++++ api/charging.md | 19 ++++++ api/error-handling.md | 33 +++++++++++ api/recurring-billing.md | 14 +++++ api/refunds.md | 14 +++++ api/responses.md | 60 +++++++++++++++++++ api/token-billing.md | 22 +++++++ api/voiding.md | 12 ++++ changelog.md | 89 ++++++++++++++++++++++++++++ gateways/build-your-own.md | 29 +++++++++ gateways/configuring.md | 46 ++++++++++++++ gateways/official.md | 36 +++++++++++ gateways/official/2checkout.md | 10 ++++ gateways/official/authorizenet.md | 10 ++++ gateways/official/buckaroo.md | 10 ++++ gateways/official/cardsave.md | 10 ++++ gateways/official/coinbase.md | 10 ++++ gateways/official/dummy.md | 10 ++++ gateways/official/eway.md | 10 ++++ gateways/official/firstdata.md | 10 ++++ gateways/official/gocardless.md | 10 ++++ gateways/official/manual.md | 10 ++++ gateways/official/migs.md | 10 ++++ gateways/official/mollie.md | 10 ++++ gateways/official/multisafepay.md | 10 ++++ gateways/official/netaxept.md | 10 ++++ gateways/official/netbanx.md | 10 ++++ gateways/official/payfast.md | 10 ++++ gateways/official/payflow.md | 10 ++++ gateways/official/paymentexpress.md | 10 ++++ gateways/official/paypal.md | 10 ++++ gateways/official/pin.md | 10 ++++ gateways/official/sagepay.md | 10 ++++ gateways/official/securepay.md | 10 ++++ gateways/official/stripe.md | 10 ++++ gateways/official/targetpay.md | 10 ++++ gateways/official/worldpay.md | 10 ++++ gateways/third-party.md | 20 +++++++ gateways/third-party/alipay.md | 10 ++++ gateways/third-party/datacash.md | 10 ++++ gateways/third-party/neteller.md | 10 ++++ gateways/third-party/pacnet.md | 10 ++++ gateways/third-party/paymentsense.md | 10 ++++ gateways/third-party/realex.md | 10 ++++ gateways/third-party/secpay.md | 10 ++++ gateways/third-party/sisow.md | 10 ++++ gateways/third-party/skrill.md | 10 ++++ index.md | 39 +++++++++--- installation.md | 36 +++++++++++ simple-example.md | 58 ++++++++++++++---- 54 files changed, 991 insertions(+), 22 deletions(-) create mode 100644 api/authorizing.md create mode 100644 api/cards.md create mode 100644 api/charging.md create mode 100644 api/error-handling.md create mode 100644 api/recurring-billing.md create mode 100644 api/refunds.md create mode 100644 api/responses.md create mode 100644 api/token-billing.md create mode 100644 api/voiding.md create mode 100644 changelog.md create mode 100644 gateways/build-your-own.md create mode 100644 gateways/configuring.md create mode 100644 gateways/official.md create mode 100644 gateways/official/2checkout.md create mode 100644 gateways/official/authorizenet.md create mode 100644 gateways/official/buckaroo.md create mode 100644 gateways/official/cardsave.md create mode 100644 gateways/official/coinbase.md create mode 100644 gateways/official/dummy.md create mode 100644 gateways/official/eway.md create mode 100644 gateways/official/firstdata.md create mode 100644 gateways/official/gocardless.md create mode 100644 gateways/official/manual.md create mode 100644 gateways/official/migs.md create mode 100644 gateways/official/mollie.md create mode 100644 gateways/official/multisafepay.md create mode 100644 gateways/official/netaxept.md create mode 100644 gateways/official/netbanx.md create mode 100644 gateways/official/payfast.md create mode 100644 gateways/official/payflow.md create mode 100644 gateways/official/paymentexpress.md create mode 100644 gateways/official/paypal.md create mode 100644 gateways/official/pin.md create mode 100644 gateways/official/sagepay.md create mode 100644 gateways/official/securepay.md create mode 100644 gateways/official/stripe.md create mode 100644 gateways/official/targetpay.md create mode 100644 gateways/official/worldpay.md create mode 100644 gateways/third-party.md create mode 100644 gateways/third-party/alipay.md create mode 100644 gateways/third-party/datacash.md create mode 100644 gateways/third-party/neteller.md create mode 100644 gateways/third-party/pacnet.md create mode 100644 gateways/third-party/paymentsense.md create mode 100644 gateways/third-party/realex.md create mode 100644 gateways/third-party/secpay.md create mode 100644 gateways/third-party/sisow.md create mode 100644 gateways/third-party/skrill.md create mode 100644 installation.md diff --git a/_data/menu.yml b/_data/menu.yml index baab74e9..b5e1d439 100644 --- a/_data/menu.yml +++ b/_data/menu.yml @@ -4,14 +4,15 @@ Getting Started: Installation: '/installation/' Changelog: '/changelog/' Gateways: - Available: '/gateways/available/' + Official: '/gateways/official/' + Third party: '/gateways/third-party/' Build your own: '/gateways/build-your-own/' Configuring: '/gateways/configuring/' API: Cards: '/api/cards/' Authorizing: '/api/authorizing/' Charging: '/api/charging/' - Refunding: '/api/refunding/' + Refunds: '/api/refunds/' Voiding: '/api/voiding/' Responses: '/api/responses/' Error Handling: '/api/error-handling/' diff --git a/_data/project.yml b/_data/project.yml index 7ee328d3..8a075648 100644 --- a/_data/project.yml +++ b/_data/project.yml @@ -1,4 +1,5 @@ title: Omnipay tagline: Multi-gateway payment processing library description: -google_analytics_tracking_id: UA-46050814-12 \ No newline at end of file +google_analytics_tracking_id: UA-46050814-12 +base_href: http://omnipay.thephpleague.com/ \ No newline at end of file diff --git a/_layouts/default.html b/_layouts/default.html index ceace8a6..e7471b14 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -12,6 +12,9 @@ {% if site.data.project.description %} {% endif %} + {% if site.data.project.base_href %} + + {% endif %} {% if site.data.images.favicon %} {% else %} diff --git a/api/authorizing.md b/api/authorizing.md new file mode 100644 index 00000000..b2f7d5c2 --- /dev/null +++ b/api/authorizing.md @@ -0,0 +1,50 @@ +--- +layout: default +permalink: api/authorizing/ +title: Authorizing +--- + +Authorizing +=========== + +The main methods implemented by gateways are: + +* `authorize($options)` - Authorize an amount on the customer's card. +* `completeAuthorize($options)` - Handle return from off-site gateways after authorization. On-site gateways do not need to implement the `completeAuthorize` method, and will throw `BadMethodCallException` if called. +* `capture($options)` - Capture an amount you have previously authorized. + +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: + +* card +* token +* amount +* currency +* description +* transactionId +* clientIp +* returnUrl +* cancelUrl + +Pass the options through to the method like so: + +~~~ php +$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: + +* Gateway settings (e.g. username and password) are set directly on the gateway. These settings apply to all payments, and generally you will store these in a configuration file or in the database. +* Method options are used for any payment-specific options, which are not set by the customer. For example, the payment `amount`, `currency`, `transactionId` and `returnUrl`. +* CreditCard parameters are data which the user supplies. For example, you want the user to specify their `firstName` and `billingCountry`, but you don't want a user to specify the payment `currency` or `returnUrl`. \ No newline at end of file diff --git a/api/cards.md b/api/cards.md new file mode 100644 index 00000000..3f46249b --- /dev/null +++ b/api/cards.md @@ -0,0 +1,85 @@ +--- +layout: default +permalink: api/cards/ +title: Cards +--- + +Cards +===== + +User form input is directed to an [CreditCard](https://github.com/thephpleague/omnipay-common/blob/master/src/Omnipay/Common/CreditCard.php) +object. This provides a safe way to accept user input. + +The `CreditCard` object has the following fields: + +~~~ php +[ + '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' +] +~~~ + +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. + +~~~ php +$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: + +~~~ php +$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](https://github.com/thephpleague/omnipay-common/blob/master/src/Omnipay/Common/Exception/InvalidCreditCardException.php) +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: + +* firstName +* lastName +* number +* expiryMonth +* expiryYear +* cvv + +You can also verify the card number using the Luhn algorithm by calling `Helper::validateLuhn($number)`. \ No newline at end of file diff --git a/api/charging.md b/api/charging.md new file mode 100644 index 00000000..096eb69b --- /dev/null +++ b/api/charging.md @@ -0,0 +1,19 @@ +--- +layout: default +permalink: api/charging/ +title: Charging +--- + +Charging +======== + +The main methods implemented by gateways are: + +* `purchase($options)` - authorize and immediately capture an amount on the customer's card +* `completePurchase($options)` - handle return from off-site gateways after purchase + +On-site gateways do not need to implement the `completePurchase` method, and will throw `BadMethodCallException` if called. + +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`. \ No newline at end of file diff --git a/api/error-handling.md b/api/error-handling.md new file mode 100644 index 00000000..d50ad431 --- /dev/null +++ b/api/error-handling.md @@ -0,0 +1,33 @@ +--- +layout: default +permalink: api/error-handling/ +title: Error handling +--- + +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: + +~~~ php +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.'); +} +~~~ \ No newline at end of file diff --git a/api/recurring-billing.md b/api/recurring-billing.md new file mode 100644 index 00000000..669bc55d --- /dev/null +++ b/api/recurring-billing.md @@ -0,0 +1,14 @@ +--- +layout: default +permalink: api/recurring-billing/ +title: Recurring billing +--- + +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. \ No newline at end of file diff --git a/api/refunds.md b/api/refunds.md new file mode 100644 index 00000000..94374c21 --- /dev/null +++ b/api/refunds.md @@ -0,0 +1,14 @@ +--- +layout: default +permalink: api/refunds/ +title: Refunds +--- + +Refunds +======= + +The main method implemented by gateways are: + +* `refund($options)` - refund an already processed transaction + +If any gateway does not support certain features (such as refunds), it will throw `BadMethodCallException`. \ No newline at end of file diff --git a/api/responses.md b/api/responses.md new file mode 100644 index 00000000..6ab25858 --- /dev/null +++ b/api/responses.md @@ -0,0 +1,60 @@ +--- +layout: default +permalink: api/responses/ +title: Responses +--- + +Responses +========= + +## The Payment Response + +The payment response must implement [ResponseInterface](https://github.com/thephpleague/omnipay-common/blob/master/src/Omnipay/Common/Message/ResponseInterface.php). There are two main types of response: + +* Payment was successful (standard response) +* Website requires redirect to off-site payment form (redirect 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: + +~~~ php +$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: + +~~~ php +$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: + +~~~ php +$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 +~~~ \ No newline at end of file diff --git a/api/token-billing.md b/api/token-billing.md new file mode 100644 index 00000000..5e56fb84 --- /dev/null +++ b/api/token-billing.md @@ -0,0 +1,22 @@ +--- +layout: default +permalink: api/token-billing/ +title: Token billing +--- + +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: + +* `createCard($options)` - returns a response object which includes a `cardReference`, which can be used for future transactions +* `updateCard($options)` - update a stored card, not all gateways support this method +* `deleteCard($options)` - remove a stored card, not all gateways support this method + +Once you have a `cardReference`, you can use it instead of the `card` parameter when creating a charge: + +~~~ php +$gateway->purchase(['amount' => '10.00', 'cardReference' => 'abc']); +~~~ \ No newline at end of file diff --git a/api/voiding.md b/api/voiding.md new file mode 100644 index 00000000..4cfdae5a --- /dev/null +++ b/api/voiding.md @@ -0,0 +1,12 @@ +--- +layout: default +permalink: api/voiding/ +title: Voiding +--- + +Voiding +======= + +The main method implemented by gateways are: + +* `void($options)` - generally can only be called up to 24 hours after submitting a transaction \ No newline at end of file diff --git a/changelog.md b/changelog.md new file mode 100644 index 00000000..a30b00b8 --- /dev/null +++ b/changelog.md @@ -0,0 +1,89 @@ +--- +layout: default +permalink: changelog/ +title: Changelog +--- + +Changelog +========= + +## v2.0.0 - 2013-11-17 + +### Package Separation + +As of 2.0, Omnipay has been split into separate packages. Core functionality is contained within the [omnipay/common](https://github.com/omnipay/common) repository, and all gateways have their own repositories. This means that if your project only requires on a single gateway, you can load it without installing all of the other gateways. All officially supported gateways can be found under the [Omnipay GitHub organization](http://github.com/omnipay). + +If you want to install all gateways, you can still use the `omnipay/omnipay` metapackage in `composer.json`: + +~~~ javascript +{ + "require": { + "omnipay/omnipay": "~2.0" + } +} +~~~ + +Alternatively, if you want to migrate to an individual gateway, simply change your `composer.json` file to reference the specific gateway (`omnipay/common` will be included for you automatically): + +~~~ javascript +{ + "require": { + "omnipay/paypal": "~2.0" + } +} +~~~ + +### Breaking Changes + +The `GatewayFactory` class can now longer be called in a static fashion. To help those who want to use dependency injection, you can now create an instance of GatewayFactory: + +~~~ php +$factory = new GatewayFactory(); +$gateway = $factory->create('PayPal_Express'); +~~~ + +The following code is invalid and will no longer work: + +~~~ php +$gateway = GatewayFactory::create('PayPal_Express'); // will cause PHP error! +~~~ + +If you want to continue to use static methods for simplicity, you can use the new Omnipay class: + +~~~ php +// at the top of your PHP file +use Omnipay\Omnipay; + +// further down when you need to create the gateway +$gateway = Omnipay::create('PayPal_Express'); +~~~ + +Behind the scenes, this will create a GatewayFactory instance for you and call the appropriate method on it. + +### Additions + +**Omnipay now supports sending line-item data to gateways.** Currently this is only supported by the PayPal gateway. Line item details can be added to a request like so: + +~~~ php +$request->setItems(array( + array('name' => 'Food', 'quantity' => 1, 'price' => '40.00'), + array('name' => 'Drinks', 'quantity' => 2, 'price' => '6.00'), +)); +~~~ + +For more details, see the [pull request](https://github.com/omnipay/omnipay/pull/154). + +**Omnipay now also supports modifying request data before it is sent to the gateway.**. This allows you to send arbitrary custom data with a request, even if Omnipay doesn't support a parameter directly. To modify the request data, instead of calling `send()` directly on the request, you may use the new `sendData()` method: + +~~~ php +// standard method - send default data +$response = $request->send(); + +// new method - get and send custom data +$data = $request->getData(); +$data['customParameter'] = true; + +$response = $request->sendData($data); +~~~ + +For more details, see the [pull request](https://github.com/omnipay/omnipay/pull/162). \ No newline at end of file diff --git a/gateways/build-your-own.md b/gateways/build-your-own.md new file mode 100644 index 00000000..3efd32d8 --- /dev/null +++ b/gateways/build-your-own.md @@ -0,0 +1,29 @@ +--- +layout: default +permalink: gateways/build-your-own/ +title: Build your own gateway +--- + +Build your own gateway +====================== + +Omnipay is a collection of packages which all depend on the +[omnipay/common](https://github.com/thephpleague/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](http://guzzlephp.org/) 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`. + +## Make your gateway official + +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](https://github.com/thephpleague/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. \ No newline at end of file diff --git a/gateways/configuring.md b/gateways/configuring.md new file mode 100644 index 00000000..cfe8c4d4 --- /dev/null +++ b/gateways/configuring.md @@ -0,0 +1,46 @@ +--- +layout: default +permalink: gateways/configuring/ +title: Configuring gateways +--- + +Configuring gateways +==================== + +All payment gateways must implement [GatewayInterface](https://github.com/thephpleague/omnipay-common/blob/master/src/Omnipay/Common/GatewayInterface.php), and will usually +extend [AbstractGateway](https://github.com/thephpleague/omnipay-common/blob/master/src/Omnipay/Common/AbstractGateway.php) for basic functionality. + +## Initialize a gateway + +Gateways are created and initialized like so: + +~~~ php +use Omnipay\Omnipay; + +$gateway = Omnipay::create('PayPal_Express'); +$gateway->setUsername('adrian'); +$gateway->setPassword('12345'); +~~~ + +## Gateway settings + +Most settings are gateway specific. If you need to query a gateway to get a list of available settings, you can call `getDefaultParameters()`: + +~~~ php +$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 +); +~~~ + +## Gateway types + +Generally most payment gateways can be classified as one of two types: + +- **Off-site** gateways such as PayPal Express, where the customer is redirected to a third party site to enter payment details +- **On-site** (merchant-hosted) gateways such as PayPal Pro, where the customer enters their credit card details on your site + +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). \ No newline at end of file diff --git a/gateways/official.md b/gateways/official.md new file mode 100644 index 00000000..51328152 --- /dev/null +++ b/gateways/official.md @@ -0,0 +1,36 @@ +--- +layout: default +permalink: gateways/official/ +title: Official gateways +--- + +Official gateways +================= + +Gateway | Composer Package | Maintainer +------- | ---------------- | ---------- +[2Checkout](/gateways/2checkout/) | `omnipay/twocheckout` | Adrian Macneil +[Authorize.Net](/gateways/authorizenet/) | `omnipay/authorizenet` | Adrian Macneil +[Buckaroo](/gateways/buckaroo/) | `omnipay/buckaroo` | Adrian Macneil +[CardSave](/gateways/cardsave/) | `omnipay/cardsave` | Adrian Macneil +[Coinbase](/gateways/coinbase/) | `omnipay/coinbase` | Adrian Macneil +[Dummy](/gateways/dummy/) | `omnipay/dummy` | Adrian Macneil +[eWAY](/gateways/eway/) | `omnipay/eway` | Adrian Macneil +[First Data](/gateways/firstdata/) | `omnipay/firstdata` | Andrew Coates +[GoCardless](/gateways/gocardless/) | `omnipay/gocardless` | Adrian Macneil +[Manual](/gateways/manual/) | `omnipay/manual` | Adrian Macneil +[Migs](/gateways/migs/) | `omnipay/migs` | Adrian Macneil +[Mollie](/gateways/mollie/) | `omnipay/mollie` | Adrian Macneil +[MultiSafepay](/gateways/multisafepay/) | `omnipay/multisafepay` | Alexander Deruwe +[Netaxept (BBS)](/gateways/netaxept/) | `omnipay/netaxept` | Adrian Macneil +[Netbanx](/gateways/netbanx/) | `omnipay/netbanx` | Maks Rafalko +[PayFast](/gateways/payfast/) | `omnipay/payfast` | Adrian Macneil +[Payflow](/gateways/payflow/) | `omnipay/payflow` | Adrian Macneil +[PaymentExpress (DPS)](/gateways/paymentexpress/) | `omnipay/paymentexpress` | Adrian Macneil +[PayPal](/gateways/paypal/) | `omnipay/paypal` | Adrian Macneil +[Pin Payments](/gateways/pin/) | `omnipay/pin` | Adrian Macneil +[Sage Pay](/gateways/sagepay/) | `omnipay/sagepay` | Adrian Macneil +[SecurePay](/gateways/securepay/) | `omnipay/securepay` | Adrian Macneil +[Stripe](/gateways/stripe/) | `omnipay/stripe` | Adrian Macneil +[TargetPay](/gateways/targetpay/) | `omnipay/targetpay` | Alexander Deruwe +[WorldPay](/gateways/worldpay/) | `omnipay/worldpay` | Adrian Macneil \ No newline at end of file diff --git a/gateways/official/2checkout.md b/gateways/official/2checkout.md new file mode 100644 index 00000000..1f07336e --- /dev/null +++ b/gateways/official/2checkout.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/2checkout/ +title: 2Checkout +--- + +2Checkout +========= + +[2Checkout](https://github.com/thephpleague/omnipay-2checkout) | `omnipay/twocheckout` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/authorizenet.md b/gateways/official/authorizenet.md new file mode 100644 index 00000000..e91420de --- /dev/null +++ b/gateways/official/authorizenet.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/authorizenet/ +title: Authorize.Net +--- + +Authorize.Net +============= + +[Authorize.Net](https://github.com/thephpleague/omnipay-authorizenet) | `omnipay/authorizenet` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/buckaroo.md b/gateways/official/buckaroo.md new file mode 100644 index 00000000..0ad9453a --- /dev/null +++ b/gateways/official/buckaroo.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/buckaroo/ +title: Buckaroo +--- + +Buckaroo +======== + +[Buckaroo](https://github.com/thephpleague/omnipay-buckaroo) | `omnipay/buckaroo` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/cardsave.md b/gateways/official/cardsave.md new file mode 100644 index 00000000..571e134b --- /dev/null +++ b/gateways/official/cardsave.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/cardsave/ +title: CardSave +--- + +CardSave +======== + +[CardSave](https://github.com/thephpleague/omnipay-cardsave) | `omnipay/cardsave` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/coinbase.md b/gateways/official/coinbase.md new file mode 100644 index 00000000..69ca810a --- /dev/null +++ b/gateways/official/coinbase.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/coinbase/ +title: Coinbase +--- + +Coinbase +======== + +[Coinbase](https://github.com/thephpleague/omnipay-coinbase) | `omnipay/coinbase` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/dummy.md b/gateways/official/dummy.md new file mode 100644 index 00000000..115de066 --- /dev/null +++ b/gateways/official/dummy.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/dummy/ +title: Dummy +--- + +Dummy +===== + +[Dummy](https://github.com/thephpleague/omnipay-dummy) | `omnipay/dummy` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/eway.md b/gateways/official/eway.md new file mode 100644 index 00000000..e57ef4ff --- /dev/null +++ b/gateways/official/eway.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/eway/ +title: eWAY +--- + +eWAY +==== + +[eWAY](https://github.com/thephpleague/omnipay-eway) | `omnipay/eway` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/firstdata.md b/gateways/official/firstdata.md new file mode 100644 index 00000000..38a8fb31 --- /dev/null +++ b/gateways/official/firstdata.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/firstdata/ +title: First Data +--- + +First Data +========== + +[First Data](https://github.com/thephpleague/omnipay-firstdata) | `omnipay/firstdata` | [Andrew Coates](https://github.com/coatesap) \ No newline at end of file diff --git a/gateways/official/gocardless.md b/gateways/official/gocardless.md new file mode 100644 index 00000000..46960a68 --- /dev/null +++ b/gateways/official/gocardless.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/gocardless/ +title: GoCardless +--- + +GoCardless +========== + +[GoCardless](https://github.com/thephpleague/omnipay-gocardless) | `omnipay/gocardless` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/manual.md b/gateways/official/manual.md new file mode 100644 index 00000000..3c86b8e6 --- /dev/null +++ b/gateways/official/manual.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/manual/ +title: Manual +--- + +Manual +====== + +[Manual](https://github.com/thephpleague/omnipay-manual) | `omnipay/manual` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/migs.md b/gateways/official/migs.md new file mode 100644 index 00000000..871de81d --- /dev/null +++ b/gateways/official/migs.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/migs/ +title: Migs +--- + +Migs +==== + +[Migs](https://github.com/thephpleague/omnipay-migs) | `omnipay/migs` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/mollie.md b/gateways/official/mollie.md new file mode 100644 index 00000000..59c020d6 --- /dev/null +++ b/gateways/official/mollie.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/mollie/ +title: Mollie +--- + +Mollie +====== + +[Mollie](https://github.com/thephpleague/omnipay-mollie) | `omnipay/mollie` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/multisafepay.md b/gateways/official/multisafepay.md new file mode 100644 index 00000000..ebef9e69 --- /dev/null +++ b/gateways/official/multisafepay.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/multisafepay/ +title: MultiSafepay +--- + +MultiSafepay +============ + +[MultiSafepay](https://github.com/thephpleague/omnipay-multisafepay) | `omnipay/multisafepay` | [Alexander Deruwe](https://github.com/aderuwe) \ No newline at end of file diff --git a/gateways/official/netaxept.md b/gateways/official/netaxept.md new file mode 100644 index 00000000..5e2a0d38 --- /dev/null +++ b/gateways/official/netaxept.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/netaxept/ +title: Netaxept (BBS) +--- + +Netaxept (BBS) +============== + +[Netaxept (BBS)](https://github.com/thephpleague/omnipay-netaxept) | `omnipay/netaxept` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/netbanx.md b/gateways/official/netbanx.md new file mode 100644 index 00000000..e0d63feb --- /dev/null +++ b/gateways/official/netbanx.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/netbanx/ +title: Netbanx +--- + +Netbanx +======= + +[Netbanx](https://github.com/thephpleague/omnipay-netbanx) | `omnipay/netbanx` | [Maks Rafalko](https://github.com/borNfreee) \ No newline at end of file diff --git a/gateways/official/payfast.md b/gateways/official/payfast.md new file mode 100644 index 00000000..c9475b47 --- /dev/null +++ b/gateways/official/payfast.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/payfast/ +title: PayFast +--- + +PayFast +======= + +[PayFast](https://github.com/thephpleague/omnipay-payfast) | `omnipay/payfast` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/payflow.md b/gateways/official/payflow.md new file mode 100644 index 00000000..bf840c64 --- /dev/null +++ b/gateways/official/payflow.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/payflow/ +title: Payflow +--- + +Payflow +======= + +[Payflow](https://github.com/thephpleague/omnipay-payflow) | `omnipay/payflow` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/paymentexpress.md b/gateways/official/paymentexpress.md new file mode 100644 index 00000000..a31c4d9d --- /dev/null +++ b/gateways/official/paymentexpress.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/paymentexpress/ +title: PaymentExpress (DPS) +--- + +PaymentExpress (DPS) +==================== + +[PaymentExpress (DPS)](https://github.com/thephpleague/omnipay-paymentexpress) | `omnipay/paymentexpress` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/paypal.md b/gateways/official/paypal.md new file mode 100644 index 00000000..7a787ed6 --- /dev/null +++ b/gateways/official/paypal.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/paypal/ +title: PayPal +--- + +PayPal +====== + +[PayPal](https://github.com/thephpleague/omnipay-paypal) | `omnipay/paypal` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/pin.md b/gateways/official/pin.md new file mode 100644 index 00000000..342b0aee --- /dev/null +++ b/gateways/official/pin.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/pin/ +title: Pin Payments +--- + +Pin Payments +============ + +[Pin Payments](https://github.com/thephpleague/omnipay-pin) | `omnipay/pin` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/sagepay.md b/gateways/official/sagepay.md new file mode 100644 index 00000000..db092406 --- /dev/null +++ b/gateways/official/sagepay.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/sagepay/ +title: Sage Pay +--- + +Sage Pay +======== + +[Sage Pay](https://github.com/thephpleague/omnipay-sagepay) | `omnipay/sagepay` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/securepay.md b/gateways/official/securepay.md new file mode 100644 index 00000000..ae130078 --- /dev/null +++ b/gateways/official/securepay.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/securepay/ +title: SecurePay +--- + +SecurePay +========= + +[SecurePay](https://github.com/thephpleague/omnipay-securepay) | `omnipay/securepay` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/stripe.md b/gateways/official/stripe.md new file mode 100644 index 00000000..c7b0469d --- /dev/null +++ b/gateways/official/stripe.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/stripe/ +title: Stripe +--- + +Stripe +====== + +[Stripe](https://github.com/thephpleague/omnipay-stripe) | `omnipay/stripe` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/official/targetpay.md b/gateways/official/targetpay.md new file mode 100644 index 00000000..2318f6a7 --- /dev/null +++ b/gateways/official/targetpay.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/stripe/ +title: TargetPay +--- + +TargetPay +========= + +[TargetPay](https://github.com/thephpleague/omnipay-targetpay) | `omnipay/targetpay` | [Alexander Deruwe](https://github.com/aderuwe) \ No newline at end of file diff --git a/gateways/official/worldpay.md b/gateways/official/worldpay.md new file mode 100644 index 00000000..36ee6c08 --- /dev/null +++ b/gateways/official/worldpay.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/worldpay/ +title: WorldPay +--- + +WorldPay +======== + +[WorldPay](https://github.com/thephpleague/omnipay-worldpay) | `omnipay/worldpay` | [Adrian Macneil](https://github.com/adrianmacneil) \ No newline at end of file diff --git a/gateways/third-party.md b/gateways/third-party.md new file mode 100644 index 00000000..7789d6e2 --- /dev/null +++ b/gateways/third-party.md @@ -0,0 +1,20 @@ +--- +layout: default +permalink: gateways/third-party/ +title: Third party gateways +--- + +Third party gateways +==================== + +Gateway | Composer Package | Maintainer +------- | ---------------- | ---------- +[Alipay](/gateways/alipay/) | `lokielse/omnipay-alipay` | Loki Else +[DataCash](/gateways/datacash/) | `coatesap/omnipay-datacash` | Andrew Coates +[Neteller](/gateways/neteller/) | `alfaproject/omnipay-neteller` | João Dias +[Pacnet](/gateways/pacnet/) | `mfauveau/omnipay-pacnet` | Matthieu Fauveau +[PaymentSense](/gateways/paymentsense/) | `coatesap/omnipay-paymentsense` | Andrew Coates +[Realex](/gateways/realex/) | `coatesap/omnipay-realex` | Andrew Coates +[SecPay](/gateways/secpay/) | `justinbusschau/omnipay-secpay` | Justin Busschau +[Sisow](/gateways/sisow/) | `nettob/omnipay-sisow` | Niek +[Skrill](/gateways/skrill/) | `alfaproject/omnipay-skrill` | João Dias \ No newline at end of file diff --git a/gateways/third-party/alipay.md b/gateways/third-party/alipay.md new file mode 100644 index 00000000..928d60c3 --- /dev/null +++ b/gateways/third-party/alipay.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/alipay/ +title: Alipay +--- + +Alipay +====== + +[Alipay](https://github.com/lokielse/omnipay-alipay) | `lokielse/omnipay-alipay` | [Loki Else](https://github.com/lokielse) \ No newline at end of file diff --git a/gateways/third-party/datacash.md b/gateways/third-party/datacash.md new file mode 100644 index 00000000..123ad847 --- /dev/null +++ b/gateways/third-party/datacash.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/datacash/ +title: DataCash +--- + +DataCash +======== + +[DataCash](https://github.com/coatesap/omnipay-datacash) | `coatesap/omnipay-datacash` | [Andrew Coates](https://github.com/coatesap) \ No newline at end of file diff --git a/gateways/third-party/neteller.md b/gateways/third-party/neteller.md new file mode 100644 index 00000000..021252df --- /dev/null +++ b/gateways/third-party/neteller.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/neteller/ +title: Neteller +--- + +Neteller +======== + +[Neteller](https://github.com/alfaproject/omnipay-neteller) | `alfaproject/omnipay-neteller` | [João Dias](https://github.com/alfaproject) \ No newline at end of file diff --git a/gateways/third-party/pacnet.md b/gateways/third-party/pacnet.md new file mode 100644 index 00000000..db5eaae2 --- /dev/null +++ b/gateways/third-party/pacnet.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/pacnet/ +title: Pacnet +--- + +Pacnet +====== + +[Pacnet](https://github.com/mfauveau/omnipay-pacnet) | `mfauveau/omnipay-pacnet` | [Matthieu Fauveau](https://github.com/mfauveau) \ No newline at end of file diff --git a/gateways/third-party/paymentsense.md b/gateways/third-party/paymentsense.md new file mode 100644 index 00000000..0d3decbc --- /dev/null +++ b/gateways/third-party/paymentsense.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/paymentsense/ +title: PaymentSense +--- + +PaymentSense +============ + +[PaymentSense](https://github.com/coatesap/omnipay-paymentsense) | `coatesap/omnipay-paymentsense` | [Andrew Coates](https://github.com/coatesap) \ No newline at end of file diff --git a/gateways/third-party/realex.md b/gateways/third-party/realex.md new file mode 100644 index 00000000..05544eec --- /dev/null +++ b/gateways/third-party/realex.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/realex/ +title: Realex +--- + +Realex +====== + +[Realex](https://github.com/coatesap/omnipay-realex) | `coatesap/omnipay-realex` | [Andrew Coates](https://github.com/coatesap) \ No newline at end of file diff --git a/gateways/third-party/secpay.md b/gateways/third-party/secpay.md new file mode 100644 index 00000000..c7dd45ef --- /dev/null +++ b/gateways/third-party/secpay.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/secpay/ +title: SecPay +--- + +SecPay +====== + +[SecPay](https://github.com/justinbusschau/omnipay-secpay) | `justinbusschau/omnipay-secpay` | [Justin Busschau](https://github.com/justinbusschau) \ No newline at end of file diff --git a/gateways/third-party/sisow.md b/gateways/third-party/sisow.md new file mode 100644 index 00000000..1982b6b2 --- /dev/null +++ b/gateways/third-party/sisow.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/sisow/ +title: Sisow +--- + +Sisow +===== + +[Sisow](https://github.com/nettob/omnipay-sisow) | `nettob/omnipay-sisow` | [Niek](https://github.com/nettob) \ No newline at end of file diff --git a/gateways/third-party/skrill.md b/gateways/third-party/skrill.md new file mode 100644 index 00000000..e743f506 --- /dev/null +++ b/gateways/third-party/skrill.md @@ -0,0 +1,10 @@ +--- +layout: default +permalink: gateways/skrill/ +title: Skrill +--- + +Skrill +====== + +[Skrill](https://github.com/alfaproject/omnipay-skrill) | `alfaproject/omnipay-skrill` | [João Dias](https://github.com/alfaproject) \ No newline at end of file diff --git a/index.md b/index.md index b72cae20..fdfa2319 100644 --- a/index.md +++ b/index.md @@ -16,18 +16,39 @@ ideas from [Active Merchant](http://activemerchant.org/), plus experience implem dozens of gateways for [CI Merchant](http://ci-merchant.org/). 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? +## Why use Omnipay? -* Because you can learn one API and use it in multiple projects using different payment gateways -* Because if you need to change payment gateways you won't need to rewrite your code -* Because most official PHP payment gateway libraries are a mess -* Because most payment gateways have exceptionally poor documentation -* Because you are writing a shopping cart and need to support multiple gateways +So, why use Omnipay instead of a gateway's official PHP package/example code? -## Important Note: Upgrading from < 2.0 +- Because you can learn one API and use it in multiple projects using different payment gateways +- Because if you need to change payment gateways you won't need to rewrite your code +- Because most official PHP payment gateway libraries are a mess +- Because most payment gateways have exceptionally poor documentation +- Because you are writing a shopping cart and need to support multiple gateways + +## Upgrading to 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](https://github.com/thephpleague/omnipay/releases/tag/v2.0.0) -for more details. \ No newline at end of file +[full release notes](/changelog/) +for more details. + +## Support + +If you are having general issues with Omnipay, we suggest posting on +[Stack Overflow](http://stackoverflow.com/). Be sure to add the +[omnipay tag](http://stackoverflow.com/questions/tagged/omnipay) 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](https://groups.google.com/forum/#!forum/omnipay) 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. + +## 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](https://groups.google.com/forum/#!forum/omnipay) +and point out what you do and don't like, or fork the project and make suggestions. **No issue is too small.** \ No newline at end of file diff --git a/installation.md b/installation.md new file mode 100644 index 00000000..8b93e57b --- /dev/null +++ b/installation.md @@ -0,0 +1,36 @@ +--- +layout: default +permalink: installation/ +title: Installation +--- + +Installation +============ + +Omnipay is installed via [Composer](http://getcomposer.org/). To install all officially +supported gateways, simply add the following to your `composer.json` file: + +~~~ javascript +{ + "require": { + "omnipay/omnipay": "~2.0" + } +} +~~~ + +Alternatively, you can require individual gateways: + +~~~ javascript +{ + "require": { + "omnipay/paypal": "~2.0" + } +} +~~~ + +Next, run composer to update your dependencies: + +~~~ bash +$ curl -s http://getcomposer.org/installer | php +$ php composer.phar update +~~~ \ No newline at end of file diff --git a/simple-example.md b/simple-example.md index 85a194ae..092f0026 100644 --- a/simple-example.md +++ b/simple-example.md @@ -1,34 +1,72 @@ --- layout: default permalink: simple-example/ -title: Simple Example +title: Simple example --- -Simple Example +Simple example ============== -Just want to see some code? +Here is a simple example of how to use Omnipay. As you can see, Omnipay has a consistent, well thought out API. As much as possible, we try to abstract the differences between the various payments gateways. ~~~ php use Omnipay\Omnipay; +// Setup payment gateway $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(); +// Example form data +$formData = [ + 'number' => '4242424242424242', + 'expiryMonth' => '6', + 'expiryYear' => '2016', + 'cvv' => '123' +]; +// Send purchase request +$response = $gateway->purchase( + [ + 'amount' => '10.00', + 'currency' => 'USD', + 'card' => $formData + ] +)->send(); + +// Process response if ($response->isSuccessful()) { - // payment was successful: update database + + // Payment was successful print_r($response); + } elseif ($response->isRedirect()) { - // redirect to offsite payment gateway + + // Redirect to offsite payment gateway $response->redirect(); + } else { - // payment failed: display message to customer + + // Payment failed 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. \ No newline at end of file +## Example Application + +An example application is also provided in the [omnipay/example](https://github.com/thephpleague/omnipay-example) repo. + +~~~ bash +# Clone project +git clone https://github.com/thephpleague/omnipay-example.git omnipay-example + +# Go to project directory +cd omnipay-example + +# Install dependencies +composer install + +# Run using the built-in PHP web server +php -S localhost:8000 +~~~ + +For more information, see the [Omnipay example application](https://github.com/thephpleague/omnipay-example). \ No newline at end of file From a92a6b3569de9d515ae08ba4431b575d96f40357 Mon Sep 17 00:00:00 2001 From: Jonathan Reinink Date: Wed, 22 Oct 2014 22:20:36 -0400 Subject: [PATCH 03/43] Update CNAME for GitHub Pages. --- CNAME | 1 + 1 file changed, 1 insertion(+) diff --git a/CNAME b/CNAME index e69de29b..151fc561 100644 --- a/CNAME +++ b/CNAME @@ -0,0 +1 @@ +omnipay.thephpleague.com \ No newline at end of file From 75c8c7d1b972c5bf3d8b73df8784182abc24ef2a Mon Sep 17 00:00:00 2001 From: Kayla Daniels Date: Wed, 29 Oct 2014 08:23:06 -0400 Subject: [PATCH 04/43] Update third-party.md --- gateways/third-party.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/gateways/third-party.md b/gateways/third-party.md index 7789d6e2..dfde2aec 100644 --- a/gateways/third-party.md +++ b/gateways/third-party.md @@ -17,4 +17,5 @@ Gateway | Composer Package | Maintainer [Realex](/gateways/realex/) | `coatesap/omnipay-realex` | Andrew Coates [SecPay](/gateways/secpay/) | `justinbusschau/omnipay-secpay` | Justin Busschau [Sisow](/gateways/sisow/) | `nettob/omnipay-sisow` | Niek -[Skrill](/gateways/skrill/) | `alfaproject/omnipay-skrill` | João Dias \ No newline at end of file +[Skrill](/gateways/skrill/) | `alfaproject/omnipay-skrill` | João Dias +[Cybersource](https://github.com/dioscouri/omnipay-cybersource) | `dioscouri/omnipay-cybersource` | [Dioscouri Design](https://github.com/dioscouri) From 5fc96c649481e8b9d3d83fa4bf0cd0d486e0a066 Mon Sep 17 00:00:00 2001 From: Kayla Daniels Date: Wed, 29 Oct 2014 08:37:22 -0400 Subject: [PATCH 05/43] Update third-party.md --- gateways/third-party.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gateways/third-party.md b/gateways/third-party.md index dfde2aec..f861cd49 100644 --- a/gateways/third-party.md +++ b/gateways/third-party.md @@ -16,6 +16,6 @@ Gateway | Composer Package | Maintainer [PaymentSense](/gateways/paymentsense/) | `coatesap/omnipay-paymentsense` | Andrew Coates [Realex](/gateways/realex/) | `coatesap/omnipay-realex` | Andrew Coates [SecPay](/gateways/secpay/) | `justinbusschau/omnipay-secpay` | Justin Busschau -[Sisow](/gateways/sisow/) | `nettob/omnipay-sisow` | Niek +[Sisow](https://github.com/fruitcakestudio/omnipay-sisow ) | `fruitcakestudio/omnipay-sisow` | [Fruitcake Studio](https://github.com/fruitcakestudio) [Skrill](/gateways/skrill/) | `alfaproject/omnipay-skrill` | João Dias [Cybersource](https://github.com/dioscouri/omnipay-cybersource) | `dioscouri/omnipay-cybersource` | [Dioscouri Design](https://github.com/dioscouri) From 6a550d5c86c29e034e585c4576ca68c82a031294 Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Thu, 15 Jan 2015 13:21:44 -0500 Subject: [PATCH 06/43] Fix the permalink for targetpay --- gateways/official/targetpay.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/gateways/official/targetpay.md b/gateways/official/targetpay.md index 2318f6a7..853fd17c 100644 --- a/gateways/official/targetpay.md +++ b/gateways/official/targetpay.md @@ -1,10 +1,10 @@ --- layout: default -permalink: gateways/stripe/ +permalink: gateways/targetpay/ title: TargetPay --- TargetPay ========= -[TargetPay](https://github.com/thephpleague/omnipay-targetpay) | `omnipay/targetpay` | [Alexander Deruwe](https://github.com/aderuwe) \ No newline at end of file +[TargetPay](https://github.com/thephpleague/omnipay-targetpay) | `omnipay/targetpay` | [Alexander Deruwe](https://github.com/aderuwe) From 61a3a4480ac12acf9fb318361b5567fb5abc292b Mon Sep 17 00:00:00 2001 From: Kayla Daniels Date: Wed, 29 Apr 2015 12:00:12 -0400 Subject: [PATCH 07/43] Create Agms --- gateways/third-party/Agms | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 gateways/third-party/Agms diff --git a/gateways/third-party/Agms b/gateways/third-party/Agms new file mode 100644 index 00000000..ee8e31b1 --- /dev/null +++ b/gateways/third-party/Agms @@ -0,0 +1,9 @@ +--- +layout: default +permalink: gateways/AGMS/ +title: Agms +--- + +AGMS +====== +[Agms](https://github.com/agmscode/omnipay-agms) | agmscode/omnipay-agms | [Maanas Royy](https://github.com/maanas) From 1c8226b13e7d2acb1cf192e69ff49e03363182f7 Mon Sep 17 00:00:00 2001 From: Kayla Daniels Date: Wed, 29 Apr 2015 12:00:23 -0400 Subject: [PATCH 08/43] Rename Agms to agms.md --- gateways/third-party/{Agms => agms.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename gateways/third-party/{Agms => agms.md} (100%) diff --git a/gateways/third-party/Agms b/gateways/third-party/agms.md similarity index 100% rename from gateways/third-party/Agms rename to gateways/third-party/agms.md From 3b14ce4b0f518236b783b10a7f9e0508c9a5a257 Mon Sep 17 00:00:00 2001 From: Kayla Daniels Date: Wed, 29 Apr 2015 12:01:54 -0400 Subject: [PATCH 09/43] Update third-party.md --- gateways/third-party.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/gateways/third-party.md b/gateways/third-party.md index f861cd49..c0dc4991 100644 --- a/gateways/third-party.md +++ b/gateways/third-party.md @@ -9,6 +9,7 @@ Third party gateways Gateway | Composer Package | Maintainer ------- | ---------------- | ---------- +[Agms](https://github.com/agmscode/omnipay-agms) | agmscode/omnipay-agms | [Maanas Royy](https://github.com/maanas) [Alipay](/gateways/alipay/) | `lokielse/omnipay-alipay` | Loki Else [DataCash](/gateways/datacash/) | `coatesap/omnipay-datacash` | Andrew Coates [Neteller](/gateways/neteller/) | `alfaproject/omnipay-neteller` | João Dias @@ -19,3 +20,4 @@ Gateway | Composer Package | Maintainer [Sisow](https://github.com/fruitcakestudio/omnipay-sisow ) | `fruitcakestudio/omnipay-sisow` | [Fruitcake Studio](https://github.com/fruitcakestudio) [Skrill](/gateways/skrill/) | `alfaproject/omnipay-skrill` | João Dias [Cybersource](https://github.com/dioscouri/omnipay-cybersource) | `dioscouri/omnipay-cybersource` | [Dioscouri Design](https://github.com/dioscouri) + From 9cdda1dc2f39f87a6005d913c6cdf03f8b88c1b0 Mon Sep 17 00:00:00 2001 From: Hannes Van De Vreken Date: Fri, 1 May 2015 13:02:23 +0200 Subject: [PATCH 10/43] Fixed typo now->no --- changelog.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/changelog.md b/changelog.md index a30b00b8..12bfd267 100644 --- a/changelog.md +++ b/changelog.md @@ -35,7 +35,7 @@ Alternatively, if you want to migrate to an individual gateway, simply change yo ### Breaking Changes -The `GatewayFactory` class can now longer be called in a static fashion. To help those who want to use dependency injection, you can now create an instance of GatewayFactory: +The `GatewayFactory` class can no longer be called in a static fashion. To help those who want to use dependency injection, you can now create an instance of GatewayFactory: ~~~ php $factory = new GatewayFactory(); @@ -86,4 +86,4 @@ $data['customParameter'] = true; $response = $request->sendData($data); ~~~ -For more details, see the [pull request](https://github.com/omnipay/omnipay/pull/162). \ No newline at end of file +For more details, see the [pull request](https://github.com/omnipay/omnipay/pull/162). From ace53f5b30b306eb56b5cb9250ae2a0a1216ca0f Mon Sep 17 00:00:00 2001 From: "Barry vd. Heuvel" Date: Tue, 12 May 2015 13:13:46 +0200 Subject: [PATCH 11/43] Update badges --- index.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/index.md b/index.md index fdfa2319..d6266587 100644 --- a/index.md +++ b/index.md @@ -7,8 +7,10 @@ title: Introduction Introduction ============ -[![Build Status](https://travis-ci.org/thephpleague/omnipay-common.png?branch=master)](https://travis-ci.org/thephpleague/omnipay-common) -[![Latest Stable Version](https://poser.pugx.org/omnipay/omnipay/version.png)](https://packagist.org/packages/omnipay/omnipay) +[![Source Code](http://img.shields.io/badge/source-league/omnipay-blue.svg?style=flat-square)](https://github.com/thephpleague/omnipay) +[![Build Status](https://img.shields.io/travis/thephpleague/omnipay-common/master.svg?style=flat-square)](https://travis-ci.org/thephpleague/omnipay-common) +[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](http://github.com/thephpleague/omnipay/blob/master/LICENSE) +[![Latest Stable Version](https://img.shields.io/packagist/v/omnipay/omnipay.svg?style=flat-square)](https://packagist.org/packages/omnipay/omnipay) [![Total Downloads](https://poser.pugx.org/omnipay/omnipay/d/total.png)](https://packagist.org/packages/omnipay/omnipay) Omnipay is a payment processing library for PHP. It has been designed based on @@ -51,4 +53,4 @@ for the appropriate package, or better yet, fork the library and submit a pull r **Please provide feedback!** We want to make this library useful in as many projects as possible. Please head on over to the [mailing list](https://groups.google.com/forum/#!forum/omnipay) -and point out what you do and don't like, or fork the project and make suggestions. **No issue is too small.** \ No newline at end of file +and point out what you do and don't like, or fork the project and make suggestions. **No issue is too small.** From d18b9a2c5d7aa117d006f23cbc86c37e6a07ff2d Mon Sep 17 00:00:00 2001 From: Kayla Daniels Date: Thu, 21 May 2015 22:06:42 -0400 Subject: [PATCH 12/43] Update third-party.md --- gateways/third-party.md | 1 + 1 file changed, 1 insertion(+) diff --git a/gateways/third-party.md b/gateways/third-party.md index c0dc4991..e58d4216 100644 --- a/gateways/third-party.md +++ b/gateways/third-party.md @@ -12,6 +12,7 @@ Gateway | Composer Package | Maintainer [Agms](https://github.com/agmscode/omnipay-agms) | agmscode/omnipay-agms | [Maanas Royy](https://github.com/maanas) [Alipay](/gateways/alipay/) | `lokielse/omnipay-alipay` | Loki Else [DataCash](/gateways/datacash/) | `coatesap/omnipay-datacash` | Andrew Coates +[Fat Zebra](/gateways/fatzebra) | `delatbabel/omnipay-fatzebra` | Del [Neteller](/gateways/neteller/) | `alfaproject/omnipay-neteller` | João Dias [Pacnet](/gateways/pacnet/) | `mfauveau/omnipay-pacnet` | Matthieu Fauveau [PaymentSense](/gateways/paymentsense/) | `coatesap/omnipay-paymentsense` | Andrew Coates From 07ffa8e103a67744555313f9f51f45b4ed743092 Mon Sep 17 00:00:00 2001 From: "Barry vd. Heuvel" Date: Wed, 10 Jun 2015 09:36:07 +0200 Subject: [PATCH 13/43] Update list --- gateways/third-party.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/gateways/third-party.md b/gateways/third-party.md index e58d4216..2dc2d915 100644 --- a/gateways/third-party.md +++ b/gateways/third-party.md @@ -9,16 +9,27 @@ Third party gateways Gateway | Composer Package | Maintainer ------- | ---------------- | ---------- -[Agms](https://github.com/agmscode/omnipay-agms) | agmscode/omnipay-agms | [Maanas Royy](https://github.com/maanas) +[Agms](https://github.com/agmscode/omnipay-agms) | `agmscode/omnipay-agms` | [Maanas Royy](https://github.com/maanas) [Alipay](/gateways/alipay/) | `lokielse/omnipay-alipay` | Loki Else +[Barclays ePDQ](https://github.com/samvaughton/omnipay-barclays-epdq) | `samvaughton/omnipay-barclays-epdq` | [Sam Vaughton](https://github.com/samvaughton) +[CardGate](https://github.com/cardgate/omnipay-cardgate) | `cardgate/omnipay-cardgate` | [CardGate](https://github.com/cardgate) +[Cybersource](https://github.com/dioscouri/omnipay-cybersource) | `dioscouri/omnipay-cybersource` | [Dioscouri Design](https://github.com/dioscouri) +[Cybersource SOAP](https://github.com/DABSquared/omnipay-cybersource-soap) | `dabsquared/omnipay-cybersource-soap` | [DABSquared](https://github.com/DABSquared) [DataCash](/gateways/datacash/) | `coatesap/omnipay-datacash` | Andrew Coates +[ecoPayz](https://github.com/dercoder/omnipay-ecopayz) | `dercoder/omnipay-ecopayz` | [Alexander Fedra](https://github.com/dercoder) +[Fasapay](https://github.com/andreas22/omnipay-fasapay) | `andreas22/omnipay-fasapay` | [Andreas Christodoulou](https://github.com/andreas22) [Fat Zebra](/gateways/fatzebra) | `delatbabel/omnipay-fatzebra` | Del +[Globalcloudpay](https://github.com/dercoder/omnipay-globalcloudpay) | `dercoder/omnipay-globalcloudpay` | [Alexander Fedra](https://github.com/dercoder) +[Helcim](https://github.com/academe/omnipay-helcim) | `academe/omnipay-helcim` | [Jason Judge](https://github.com/judgej) [Neteller](/gateways/neteller/) | `alfaproject/omnipay-neteller` | João Dias +[Network Merchants Inc. (NMI)](https://github.com/mfauveau/omnipay-nmi) | `mfauveau/omnipay-nmi` | [Matthieu Fauveau](https://github.com/mfauveau) [Pacnet](/gateways/pacnet/) | `mfauveau/omnipay-pacnet` | Matthieu Fauveau [PaymentSense](/gateways/paymentsense/) | `coatesap/omnipay-paymentsense` | Andrew Coates +[PayPro](https://github.com/payproNL/omnipay-paypro) | `paypronl/omnipay-paypro` | [Fruitcake Studio](https://github.com/fruitcakestudio) +[PayU](https://github.com/efesaid/omnipay-payu) | `omnipay/payu` | [efesaid](https://github.com/efesaid) [Realex](/gateways/realex/) | `coatesap/omnipay-realex` | Andrew Coates [SecPay](/gateways/secpay/) | `justinbusschau/omnipay-secpay` | Justin Busschau [Sisow](https://github.com/fruitcakestudio/omnipay-sisow ) | `fruitcakestudio/omnipay-sisow` | [Fruitcake Studio](https://github.com/fruitcakestudio) [Skrill](/gateways/skrill/) | `alfaproject/omnipay-skrill` | João Dias -[Cybersource](https://github.com/dioscouri/omnipay-cybersource) | `dioscouri/omnipay-cybersource` | [Dioscouri Design](https://github.com/dioscouri) +[Wirecard](https://github.com/igaponov/omnipay-wirecard) | igaponov/omnipay-wirecard | [Igor Gaponov](https://github.com/igaponov) From 25aa83d5ef930967037a0e77050923baa043cc70 Mon Sep 17 00:00:00 2001 From: "Barry vd. Heuvel" Date: Wed, 10 Jun 2015 09:38:00 +0200 Subject: [PATCH 14/43] Update third-party.md --- gateways/third-party.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gateways/third-party.md b/gateways/third-party.md index 2dc2d915..3a3972e7 100644 --- a/gateways/third-party.md +++ b/gateways/third-party.md @@ -31,5 +31,5 @@ Gateway | Composer Package | Maintainer [SecPay](/gateways/secpay/) | `justinbusschau/omnipay-secpay` | Justin Busschau [Sisow](https://github.com/fruitcakestudio/omnipay-sisow ) | `fruitcakestudio/omnipay-sisow` | [Fruitcake Studio](https://github.com/fruitcakestudio) [Skrill](/gateways/skrill/) | `alfaproject/omnipay-skrill` | João Dias -[Wirecard](https://github.com/igaponov/omnipay-wirecard) | igaponov/omnipay-wirecard | [Igor Gaponov](https://github.com/igaponov) +[Wirecard](https://github.com/igaponov/omnipay-wirecard) | `igaponov/omnipay-wirecard` | [Igor Gaponov](https://github.com/igaponov) From dad4f9ddce1f3c1b4384ef999c501182d2ca3041 Mon Sep 17 00:00:00 2001 From: Andrew Coates Date: Mon, 16 Nov 2015 17:43:55 +0000 Subject: [PATCH 15/43] Omnipay conventions Added information about some non-obvious omnipay conventions --- gateways/build-your-own.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/gateways/build-your-own.md b/gateways/build-your-own.md index 3efd32d8..1f71914c 100644 --- a/gateways/build-your-own.md +++ b/gateways/build-your-own.md @@ -26,4 +26,10 @@ If you want to transfer your gateway to the `omnipay` GitHub organization and ad to the list of officially supported gateways, please open a pull request on the [omnipay/common](https://github.com/thephpleague/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. \ No newline at end of file +and code style used in other Omnipay gateways. + +## 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 'our' reference to the transaction - so typically the ID of our record in the database. `transactionReference` is 'their' reference to the transaction - so the payment gateway's own reference to the transaction. + - **returnUrl vs notifyUrl** - `returnUrl` is used by drivers when they need to tell the gateway where to redirect customers to following a transaction. Typically this is used by off-site 'redirect' gateway integrations. `notifyUrl` is used by drivers where the gateway sends a server-to-server notification about the status of a customer's payment. From e55646df344eb7b7a3ae685a16dcda1e4e9a7d09 Mon Sep 17 00:00:00 2001 From: Andrew Coates Date: Tue, 24 Nov 2015 08:44:54 +0000 Subject: [PATCH 16/43] Clarified terminology --- gateways/build-your-own.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/gateways/build-your-own.md b/gateways/build-your-own.md index 1f71914c..8ba6b036 100644 --- a/gateways/build-your-own.md +++ b/gateways/build-your-own.md @@ -1,11 +1,11 @@ --- layout: default permalink: gateways/build-your-own/ -title: Build your own gateway +title: Build your own driver --- -Build your own gateway -====================== +Build your own driver +===================== Omnipay is a collection of packages which all depend on the [omnipay/common](https://github.com/thephpleague/omnipay-common) package to provide @@ -13,23 +13,31 @@ a consistent interface. There are no dependencies on official payment gateway PH we prefer to work with the HTTP API directly. Under the hood, we use the popular and powerful [Guzzle](http://guzzlephp.org/) library to make HTTP requests. -New gateways can be created by cloning the layout of an existing package. When choosing a +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 gateway official +## Make your driver official -If you want to transfer your gateway to the `omnipay` GitHub organization and add it +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](https://github.com/thephpleague/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 + +- **Merchant Site** - The website or application that initiates the payment. Typically this will be an ecommerce store or some other online system that needs to take payments from customers. +- **Merchant** - The owner or operator of the Merchant Site. +- **Payment Gateway** - The remote payment processing system that handles the communication and transfer of funds between the Merchant Site, the customer's bank, and the Merchant's bank. These are typically large companies that handle many thousands of payments for many Merchants every day. See https://en.wikipedia.org/wiki/Payment_gateway for more details. +- **Driver** - The code written to extend the core Omnipay functionality so that it can communicate with a specifc Payment Gateway. There are several 'official' Omnipay drivers, and many others written by individuals. If the Payment Gateway that you wish to use doesn't currently have a driver written for it, you can create your own and share it with the community. +- **Transaction** - An single attempt (successful or otherwise) to make a payment. + ## 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 'our' reference to the transaction - so typically the ID of our record in the database. `transactionReference` is 'their' reference to the transaction - so the payment gateway's own reference to the transaction. - - **returnUrl vs notifyUrl** - `returnUrl` is used by drivers when they need to tell the gateway where to redirect customers to following a transaction. Typically this is used by off-site 'redirect' gateway integrations. `notifyUrl` is used by drivers where the gateway sends a server-to-server notification about the status of a customer's payment. + - **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. From fb86460dec0e21ba8de7300209b8f13bb77ce8f5 Mon Sep 17 00:00:00 2001 From: Kayla Daniels Date: Wed, 13 Apr 2016 22:14:02 -0400 Subject: [PATCH 17/43] remove ci-merchant.org fixes #357 --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index d6266587..a75c550e 100644 --- a/index.md +++ b/index.md @@ -15,7 +15,7 @@ Introduction Omnipay is a payment processing library for PHP. It has been designed based on ideas from [Active Merchant](http://activemerchant.org/), plus experience implementing -dozens of gateways for [CI Merchant](http://ci-merchant.org/). It has a clear and consistent API, +dozens of gateways for [CI Merchant](https://github.com/expressodev/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? From 4f301ce7d0a0e25c0b051f1d516afa487338851d Mon Sep 17 00:00:00 2001 From: frankdejonge Date: Thu, 7 Jul 2016 15:58:31 +0200 Subject: [PATCH 18/43] support https --- _data/project.yml | 2 +- _layouts/default.html | 22 +++++++++++----------- changelog.md | 2 +- gateways/build-your-own.md | 2 +- index.md | 10 +++++----- 5 files changed, 19 insertions(+), 19 deletions(-) diff --git a/_data/project.yml b/_data/project.yml index 8a075648..39ec041a 100644 --- a/_data/project.yml +++ b/_data/project.yml @@ -2,4 +2,4 @@ title: Omnipay tagline: Multi-gateway payment processing library description: google_analytics_tracking_id: UA-46050814-12 -base_href: http://omnipay.thephpleague.com/ \ No newline at end of file +base_href: //omnipay.thephpleague.com/ diff --git a/_layouts/default.html b/_layouts/default.html index e7471b14..02daea27 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -18,20 +18,20 @@ {% if site.data.images.favicon %} {% else %} - + {% endif %} {% if site.data.images.apple_touch %} {% else %} - + {% endif %} - +
- - The League of Extraordinary Packages + + The League of Extraordinary Packages

Our Packages:

    @@ -49,7 +49,7 @@

    Our Packages:

    {{ site.data.project.title }} {{ site.data.project.tagline }} - + Presented by The League of Extraordinary Packages @@ -79,13 +79,13 @@

    {{ section[0] }}

    - - + + {% if site.data.project.google_analytics_tracking_id %}