Table Of Contents


You can obtain free community support for example through stackoverflow, or also through the Symfony2 mailing list.

If you think you found a bug, please create a ticket in the bug tracker.

Continuous Inspections

If you take code quality seriously, try out the new continuous inspection service.



A plugin is a flexible way of providing access to a specific payment back end, payment processor, or payment service provider. Plugins are used to execute a FinancialTransaction against a payment service provider, such as Paypal.

Implementing a custom plugin

The easiest way is to simply extend the provided AbstractPlugin class, and override the remaining abstract methods:

use JMS\Payment\CoreBundle\Plugin\AbstractPlugin;

class PaypalPlugin extends AbstractPlugin
    public function processes($name)
        return 'paypal' === $name;

Now, you only need to setup your plugin as a service, and it will be added to the plugin controller automatically:

        class: PaypalPlugin
        tags: [{name: payment.plugin}]
<service id="payment.plugin.paypal" class="PaypalPlugin">
    <tag name="payment.plugin" />

That?s it! You just created your first plugin :) Right now, it does not do anything useful, but we will get to the specific transactions that you can perform in the next section.

Available transaction types

Each plugin may implement a variety of available transaction types. Depending on the used payment method and the capabilities of the backend, you rarely need all of them.

Following is a list of all available transactions, and two exemplary payment method plugins. A ?x? indicates that the method is implement, ?-? that it is not:

Financial Transaction CreditCardPlugin ElectronicCheckPlugin
checkPaymentInstruction x x
validatePaymentInstruction x x
approveAndDeposit x x
approve x -
reverseApproval x -
deposit x x
reverseDeposit x -
credit x -
reverseCredit x -

If you are unsure which transactions to implement, have a look at the PluginInterface which contains detailed descriptions for each of them.

Tip: In cases, where a certain method does not make sense for your payment backend, you should throw a FunctionNotSupportedException. If you extend the AbstractPlugin base class, this is already done for you.

Available exceptions

Exceptions play an important part in the communication between the different payment plugin, and the PluginController which manages them.

Following is a list with available exceptions, and how they are treated by the PluginController. Of course, you can also add your own exceptions, but it is recommend that you sub-class an existing exception when doing so.

Tip: All exceptions which are relevant for plugins are located in the namespace JMS\Payment\CoreBundle\Plugin\Exception.
Class Description Payment Plugin Controller Interpretation
Exception Base exception used by all exceptions thrown from plugins. Causes any transaction to be rolled back. Exception will be re-thrown.
FunctionNotSupportedException This exception is thrown whenever a method on the interface is not supported by the plugin. In most cases, this causes any transactions to be rolled back. Notable exceptions to this rule: checkPaymentInstruction, validatePaymentInstruction
InvalidDataException This exception is thrown whenever the plugin realizes that the data associated with the transaction is invalid. Causes any transaction to be rolled back. Exception will be re-thrown.
InvalidPaymentInstructionException This exception is typically thrown from within either checkPaymentInstruction, or validatePaymentInstruction. Causes PaymentInstruction to be set to STATE_INVALID.

This exception is thrown whenever a transaction cannot be processed.

The exception must only be used when the situation is temporary, and there is a chance that the transaction can be performed at a later time successfully.

Sets the transaction to STATE_PENDING, and converts the exception to a Result object.
TimeoutException (sub-class of BlockedException) This exception is thrown when there is an enduring communication problem with the payment backend system. Sets the transaction to STATE_PENDING, and converts the exception to a Result object.
ActionRequiredException (sub-class of BlockedException)

This exception is thrown whenever an action is required before the transaction can be completed successfully.

A typical action would be for the user to visit an URL in order to authorize the payment.

Sets the transaction to STATE_PENDING, and converts the exception to a Result object.