Skip to content

Latest commit

 

History

History
183 lines (145 loc) · 10.4 KB

2.0.md

File metadata and controls

183 lines (145 loc) · 10.4 KB
Raw

2.0

Overview

  • Omnipay 2.x compatible (requires Omnipay 2.4 or higher)
  • Deprecated old config API in favor of a more flexible config structure (#105)
  • Deprecated snake_case static methods (transition to PSR-2) (#104)
  • Implemented services for all common omnipay methods: Purchase, authorize, capture, refund, void.
  • Services return a ServiceResponse and not a GatewayResponse. This change was mainly done to avoid confusion with Omnipay
  • UI Components such as the Payment Admin and Gridfield actions have been moved to a separate module.
  • Implemented support for asynchronous status notifications from payment providers.
  • Unit-Test coverage greatly increased.

Upgrading

Gateways in Omnipay 2.0

Compared to the 1.x version, Omnipay 2.0 doesn't bundle any gateways. These have to be installed separately. If you've used PayPal_Express and the Manual Gateway before, you would upgrade your installation like this:

composer require silverstripe/silverstripe-omnipay ~2.0
composer require omnipay/paypal
composer require omnipay/manual

The omnipay/common package will be installed as a dependency of silverstripe-omnipay, but all required gateways have to be installed manually.

Configuration API

2.0 introduces a new (more flexible) config API. When your payment configuration in 1.x looked like this:

Payment:
  allowed_gateways:
    - 'PayPal_Express'
    - 'Manual'
  parameters:
    PayPal_Express:
      username: 'example.username.test'
      password: 'txjjllae802325'
      signature: 'wk32hkimhacsdfa'

It should be restructured like this to be compatible with 2.0 (the old format will still work, but raise deprecation notices):

Payment:
  allowed_gateways:
    - 'PayPal_Express'
    - 'Manual'

GatewayInfo:
  PayPal_Express:
    parameters:
      username: 'example.username.test'
      password: 'txjjllae802325'
      signature: 'wk32hkimhacsdfa'

There are a lot of new configuration options, which are documented here: https://github.com/silverstripe/silverstripe-omnipay/tree/2.0#configuration

Services

In 1.x only the purchase and refund services were properly implemented. With the 2.0 release, all common gateway methods such as purchase, authorize, capture, refund and void are available.

Initiating a purchase in 1.x:

$payment = Payment::create()->init("PxPayGateway", 100, "NZD");
$response = PurchaseService::create($payment)
    ->setReturnUrl($this->Link('complete')."/".$donation->ID)
    ->setCancelUrl($this->Link()."?message=payment cancelled")
    ->purchase($form->getData());
$response->redirect();

Doing the same in 2.0:

$payment = Payment::create()->init("PxPayGateway", 100, "NZD")
    ->setSuccessUrl($this->Link('complete/' . $donation->ID))
    ->setFailureUrl($this->Link()."?message=payment cancelled");

$response = ServiceFactory::create()
    ->getService($payment, ServiceFactory::INTENT_PURCHASE)
    ->initiate($form->getData());

return $response->redirectOrRespond();

It's almost the same as it was in 1.x. The most notable differences:

  • Success and Failure (Cancel) URLs are set on Payment and not on the Service.
  • Services are now instantiated using the ServiceFactory. This makes substitution of Services much easier than before. Documentation
  • Services now all follow the same pattern (implementing instantiate and complete methods). So it's now possible to return different Services, depending on Gateway configuration (eg. when wanting to make a payment, the ServiceFactory might return an AuthorizeService or PurchaseService)

GatewayResponse becomes ServiceResponse

In 1.x, a Service would return a GatewayResponse, which was a thin wrapper around the response classes returned by Omnipay gateways. The GatewayResponse class has been removed completely and was superseded by ServiceResponse. This was done to avoid confusion with Omnipay core-classes and because a response from a service doesn't automatically have to be a response from the payment gateway! Sometimes the Service can determine success or failure without even having to run through the payment-gateway.

All service implementations now return a ServiceResponse with their initiate and complete methods.

If you didn't develop custom payment services for 1.x, the only change to your application would be to use $response->redirectOrRespond() instead of $response->redirect()

Namespaces

All classes that don't inherit from DataObject are now namespaced with SilverStripe\Omnipay

Previous New
PaymentGatewayController  SilverStripe\Omnipay\PaymentGatewayController
GatewayInfo  SilverStripe\Omnipay\GatewayInfo
GatewayFieldsFactory  SilverStripe\Omnipay\GatewayFieldsFactory
PaymentDevelopmentAdmin  SilverStripe\Omnipay\Admin\PaymentDevelopmentAdmin
 PaymentService  SilverStripe\Omnipay\Service\PaymentService
 PurchaseService  SilverStripe\Omnipay\Service\PurchaseService
 RefundService  SilverStripe\Omnipay\Service\RefundService
 VoidService  SilverStripe\Omnipay\Service\VoidService
 AuthorizeCaptureService SilverStripe\Omnipay\Service\AuthorizeService, SilverStripe\Omnipay\Service\CaptureService
GatewayResponse  Superseded by: SilverStripe\Omnipay\Service\ServiceResponse

PaymentAdmin is gone?

UI components have been removed from this module and added to a separate module. The payment UI components can be added by installing:

composer require bummzack/silverstripe-omnipay-ui

Changelog

  • Added namespace to GatewayFieldsFactory. Allow null value for the Gateway. Added unit-tests.
  • Remove UI components and suggest external UI components module.
  • Implemented distinction between "partial" and "multiple" partial payments (for capture and refunds). Changed how excess payments are stored. Updated documentation and unit-tests.
  • Added permissions for refund/capture and void. Added translation keys. Updated unit-tests.
  • Implemented support for partial payments. Module now also supports: - partial refunds - partial capture - captures that exceed authorized amount
  • No longer use PaymentMessages to store/retrieve Transaction-Reference and success- and failure URLs. These parameters are now stored on the Payment itself. Setting return- and cancel-Url on services is now deprecated. Refactored payment-services a bit. Updated services and unit-tests.
  • Fix and improve output of PaymentDevelopmentAdmin. Disable payment file-logging for unit-tests.
  • Added unit-tests for Payable. Added unit-tests for the Payment GridFieldActions Exclude deprecated methods from code-coverage.
  • Updated language file. Stripped out the Gateways and Message translations. These would only add unnecessary burdens to translators. Added project to transifex. Added deprecation notice when using Payment.Gatewayname for translations. Added Unit-Test to check this behavior. Added documentation file for translations.
  • Improve translation keys. Rename them to CamelCase (where applicable) and remove redundant translations. Move Gateway names to their own translation group (Gateway).
  • Some minor formatting changes
  • Make payment title locale-aware through a title-template. Added unit-tests to cover different title-scenarios.
  • Use the correct code-quality and coverage badges.
  • Converted to PSR-2 using php-cs-fixer
  • Added script to upload code-coverage to scrutinizer. Updated .travis.yml
  • Fix travis/scrutinizer coverage report.
  • Updated documentation. Added information about gateway naming. "Manual" Gateway is no longer a default setting (updated Docs, GatewayInfo and Unit-Test). Removed testing against SilverStripe master branch, as this interferes with the stricter version constraint in composer.json (modules standard).
  • Added changelog. Added information about versions. Added License. Moved organization from burnbright to silverstripe. Fix framework requirement in composer.json (Module standards!)
  • Fix issue where an offsite-payment form would return but payment was already marked complete due to async notification. Added unit-test to check for above issue. Added helper method to detect pending payments on Payable
  • Implemented all supported Omnipay 2.x gateway services: Purchase, Authorize, Capture, Void, Refund. Implemented support for gateways that confirm success via asynchronous notifications. Introduced namespaces for all classes that aren't DataObjects. Introduced a factory to create payment services. Added gridfield actions to enable capture, refund and void of payments via CMS.
  • Typo in composer
  • Add LICENSE
  • Update to SilverStripe org name
  • Deprecate the old config API. This means Payment should only configure the allowed_gateways. Gateway configuration should go into GatewayInfo.
  • Deprecate snake-case static methods.
  • Added configuration option Payment.token_key for Braintree
  • Added support for using token instead of card, Added hook for updating data sent to omnipay
  • Moved the isOffsite check to allow better overriding in cases where the gateway is not offsite
  • Added standard .gitattributes file
  • Fixing Test to be gateway title agnostic (as it will otherwise fail with custom translations).
  • Add an en locale file for translations. Include all the official Omnipay 2.x gateways and CreditCard Brands.
  • Added standard .editorconfig file
  • Added omnipay/dummy to require-dev
  • Fixed version constraints for require-dev
  • Changed composer requirements to use omnipay/common and updated documentation
  • Fix unit tests broken by Omnipay upgrade
  • Update dependency for Omnipay
  • Hopefully fixes Travis build
  • Remove Created field from payment-admin filter dialogue.
  • Provide an accessor for translated status value. Updated search-context and summary_fields to include translated values as well.
  • Fix YAML indentation
  • Update .travis.yml
  • Test against 3.2
  • Testing this against master and 3.2
  • NEW: Extension point for extra data to complete purchases
  • Added note to README on Payable
  • Create CONTRIBUTING.md
  • ENHANCEMENT Add ability to manage several manual payments modules.
  • BUGFIX fixed Payment filtering bug in ModelAdmin
  • Update docs/en/index.md