SilverStripe Omnipay Payment Module
The aim of this module is to make it easy for developers to add online payments to their SilverStripe application. It makes heavy use of the Omnipay Library. There are many gateway options to choose from, and integrating with additional gateways has a structured approach that should be understandable.
A high quality, simple to use payment module will help to boost the SilverStripe ecosystem, as it allows applications to be profitable.
This module is a complete rewrite of the past Payment module. It is not backwards-compatible, but a migration task is available. 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
- silverstripe framework 3.1+
- omnipay 2.4 + its dependencies - which include guzzle and some symphony libraries.
- 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.
There are many gateways available, which you can install separately. Note that currently this module uses version 2.x of the Ominpay library.
Searching packagist is useful: https://packagist.org/search/?q=omnipay
It is not too difficult to write your own gateway integration either, if needed.
Composer is currently the only supported way to set up this module:
composer require silverstripe/silverstripe-omnipay
As of version 2.0 this module only requires
omnipay/common so 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
Silverstripe Omnipay offers a lot of configuration options. A full list can be found in our dedicated configuration documentation.
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.
And another example: Omnipay PayPal comes with three different gateway implementations:
RestGateway. The gateway names for these gateways would be:
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 (
We have produced a comprehensive getting started guide in our documentation pages
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
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
The service factory allows easy customization of which classes should be instantiated for which intent. The
service-factory can also automatically return an
PurchaseService, depending on what was configured
for the chosen Gateway.
The following constants are available to instantiate Services:
INTENT_PURCHASErequests a purchase service.
INTENT_AUTHORIZErequests an authorize service.
INTENT_CAPTURErequests a capture service.
INTENT_REFUNDrequests a refund service.
INTENT_VOIDrequests a void service.
INTENT_PAYMENTreturns authorize- or purchase-service, depending on selected Gateway.
$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);
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
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.
When customizing the payment flow (e.g. subclassing
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
since this will only return you data for fields originally defined in the form.
A useful way to debug payment issues is to enable file logging:
--- Name: payment --- Payment: file_logging: true #or use 'verbose' for more detailed output
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
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
Logs will be saved to
debug.log in the root of your SilverStripe directory.
- Payments have both an amount and a currency. That means you should check if all currencies match if you will be adding them up.
It's highly recommended that you enable general error-logging on production environments.
Example for your
// log warnings and errors to file. // Make sure the logfile is not accessible via HTTP. Best put it in a folder outside of the webroot. SS_Log::add_writer(new SS_LogFileWriter('/var/log/silverstripe-log.log'), SS_Log::WARN, '<=');
Before you import your database and do a DB/build, add the following YAML config to your site:
--- Name: payment --- Payment: db: Status: "Enum('Created,Authorized,Captured,Refunded,Void,Incomplete,Success,Failure,Pending','Created')"
This will re-introduce old enumeration values to the DB.
Run the migration task: yoursite.com/dev/tasks/MigratePaymentTask