silverstripe / silverstripe-omnipay
SilverStripe Omnipay Payment Module
Installs: 95 072
Dependents: 17
Suggesters: 0
Security: 1
Stars: 39
Watchers: 16
Forks: 67
Open Issues: 17
Type:silverstripe-vendormodule
Requires
- php: ^8.1
- omnipay/common: ^3
- silverstripe/framework: ^5
Requires (Dev)
- guzzlehttp/psr7: ^2.5
- moneyphp/money: ^4.5
- omnipay/dummy: ^3
- omnipay/paymentexpress: ^3.1.1
- omnipay/paypal: ^3
- php-http/guzzle7-adapter: ^1
- phpunit/phpunit: ^9.5
- silverstripe/versioned: *
- symfony/http-foundation: ^5.4.25 || ^6.3.1
Suggests
- bummzack/silverstripe-omnipay-ui: Adds UI Components to manage payments in the SilverStripe CMS.
- dev-main / 4.x-dev
- 4.1.0
- 4.0.0
- 3.x-dev
- 3.2.x-dev
- 3.2.2
- 3.2.1
- 3.2.0
- 3.1.x-dev
- 3.1.4
- 3.1.3
- 3.1.2
- 3.1.1
- 3.1.0
- 3.0.x-dev
- 3.0.2
- 3.0.1
- 3.0.0
- 3.0.0-alpha3
- 3.0.0-alpha2
- 3.0.0-alpha1
- 2.x-dev
- 2.5.2
- 2.5.1
- 2.5.0
- 2.4.0
- 2.3.0
- 2.2.0
- 2.1.0
- 2.0.x-dev
- 2.0.0
- 2.0-alpha
- 1.x-dev
- 1.3.0
- 1.2.x-dev
- 1.1.1
- 1.1.0
- 1.0.2
- 1.0.1
- 1.0.0
- 1.0.0-beta1
- dev-fixes/246-dynamic-props
This package is auto-updated.
Last update: 2024-12-03 09:24:07 UTC
README
Live chat: ![Gitter](https://badges.gitter.im/Join Chat.svg)
The aim of this module is to make it easy for developers to add online payments to their SilverStripe application. In a nutshell, it wraps the PHP Omnipay payments library and provides some additional functionality. To understand more about omnipay, see: https://github.com/thephpleague/omnipay
Requirements
- PHP 8.1+
- silverstripe framework v5 +
- omnipay 3 & its dependencies - which include guzzle and some symphony libraries.
Features
- Gateway configuration via YAML config.
- Payment / transaction model handling.
- Detailed + structured logging in the database.
- Provide visitors with one, or many gateways to choose from.
- Provides form fields, which can change per-gateway.
- Caters for different types of gateways: on-site capturing, off-site capturing, and manual payment.
- Wraps the Omnipay php library.
- Multiple currencies.
Compatible Payment Gateways
There are many gateways available, which you can install separately.
Searching packagist is useful: https://packagist.org/search/?q=omnipay
It is not too difficult to write your own gateway integration either, if needed.
Installation
Composer is currently the only supported way to set up this module:
composer require silverstripe/silverstripe-omnipay ^3@dev
You will also need to pull in your payment adapter of choice. Have a look at http://omnipay.thephpleague.com/gateways/official/ where the second column is the package name.
For example, if your site uses PayPal you would also need to run:
composer require omnipay/paypal
There's also short guide how to enable manual payments or PayPal Express available.
Configuration
Silverstripe Omnipay offers a lot of configuration options. A full list can be found in our dedicated configuration documentation.
Gateway naming conventions
The way gateways are named is dictated by the Omnipay module. Since there might be different gateways in one Omnipay-Payment-Driver, we need a way to address these via different names.
The rules are pretty simple: Class names beginning with a namespace marker (\
) are left intact. Non-namespaced classes are expected to be in the \Omnipay
namespace. In non-namespaced classes, underscores or slashes (\
) are used to denote a specific gateway instance.
Examples:
\Custom\Gateway
→\Custom\Gateway
\Custom_Gateway
→\Custom_Gateway
Stripe
→\Omnipay\Stripe\Gateway
PayPal\Express
→\Omnipay\PayPal\ExpressGateway
PayPal_Express
→\Omnipay\PayPal\ExpressGateway
And another example: Omnipay PayPal comes with three different gateway implementations: ExpressGateway
, ProGateway
and RestGateway
. The gateway names for these gateways would be:
PayPal_Express
, PayPal_Pro
and PayPal_Rest
.
Please follow the rules above to choose the correct gateway name in your configuration files.
Throughout the documentation and examples of this module, you'll find the syntax with underscores. It's easier to read and less error-prone (escaping) than the syntax with namespace markers (\
).
Usage
We have produced a comprehensive getting started guide in our documentation pages
The Payment Services and Service Factory
There are currently five payment services available, which map to methods exposed by Omnipay. Which one you can use in practice depends on the capabilities of the individual gateway. Some gateways will support all services, while some support only a few (eg. the "Manual" gateway doesn't support "purchase").
The services are:
PurchaseService
: Directly purchase/capture an amount.AuthorizeService
: Authorize an amount.CaptureService
: Capture a previously authorized amount.RefundService
: Refund a previously captured amount.VoidService
: Void/Cancel an authorized payment.
Each of these services implements an initiate
and a complete
method. The initiate
method is always required and
initiates a service. Depending on how the gateway handles requests, you might also need the complete
method.
This is the case with offsite payment forms, where initiate
will redirect the user to the payment form and once he returns
from the offsite form, complete
will be called to finalize the payment.
Another (less common) case is, when the payment provider uses asynchronous notifications to confirm changes to payments.
While you can instantiate the services explicitly, the recommended approach is to use the ServiceFactory
.
The service factory allows easy customization of which classes should be instantiated for which intent. The
service-factory can also automatically return an AuthorizeService
or PurchaseService
, depending on what was configured
for the chosen Gateway.
The following constants are available to instantiate Services:
INTENT_PURCHASE
requests a purchase service.INTENT_AUTHORIZE
requests an authorize service.INTENT_CAPTURE
requests a capture service.INTENT_REFUND
requests a refund service.INTENT_VOID
requests a void service.INTENT_PAYMENT
returns authorize- or purchase-service, depending on selected Gateway.
In code:
$payment = Payment::create()->init("PxPayGateway", 100, "NZD"); // The service will be a `PurchaseService` $service = ServiceFactory::create()->getService($payment, ServiceFactory::INTENT_PURCHASE); // Initiate the payment $response = $service->initiate($data);
Passing correct data to the purchase function
The omnipay library has a defined set of parameters that need to be passed in. Here is a list of parameters that you should map your data to:
transactionId
firstName
lastName
email
company
billingAddress1
billingAddress2
billingCity
billingPostcode
billingState
billingCountry
billingPhone
shippingAddress1
shippingAddress2
shippingCity
shippingPostcode
shippingState
shippingCountry
shippingPhone
Note: transactionId
can be a reference that identifies the thing you are paying for, such as an order reference id.
It usually shows up on bank statements for reconciliation purposes, but ultimately depends how the gateway uses it.
Security
When customizing the payment flow (e.g. subclassing PaymentForm
or OrderProcessor
), please take care to only pass
whitelisted user input to PurchaseService
and the underlying omnipay gateways. The easiest way to ensure no arbitrary
data can be injected is by using Form->getData()
rather than acessing $_REQUEST
directly, since this will only
return you data for fields originally defined in the form.
Debugging payments
Please read the logging documentation on how to set up logging.
Renaming gateways and translation
You can change the front-end visible name of a gateway using the translation system. The gateway name must match what
you entered in the allowed_gateways
YAML config.
For example, inside mysite/lang/en.yml
:
en: Gateway: Paystation_Hosted: "Credit Card" PayPal_Express: "PayPal"
This approach can also be used to provide different translations. For further information about module translations, please read docs/en/Translating.md
Further Documentation
https://github.com/silverstripe/silverstripe-omnipay/blob/master/docs/en/index.md