JMSPaymentCoreBundle¶

Installation¶

Install with composer:

composer require jms/payment-core-bundle

Configuration¶

The configuration is as simple as setting an encryption key which will be used for encrypting data. You can generate a random key with the following command:

bin/console jms_payment_core:generate-key

And then use it in your configuration:

# config/packages/payment.yaml
jms_payment_core:
    encryption:
        secret: output_of_above_command

Create database tables¶

This bundle requires a few database tables, which you can create as follows.

If you’re not using database migrations:

bin/console doctrine:schema:update

Or, if you’re using migrations:

bin/console doctrine:migrations:diff
bin/console doctrine:migrations:migrate

# config/packages/doctrine.yaml
doctrine:
    orm:
        auto_mapping: true

# config/packages/doctrine.yaml
doctrine:
    orm:
        mappings:
            JMSPaymentCoreBundle: ~

Configure a payment backend¶

In addition to setting up this bundle, you will also need to install a plugin for each payment backend you intend to support. Plugins are simply bundles you add to your application, as you would with any other Symfony bundle.

Using the Paypal plugin as an example, you would install it with composer:

composer require jms/payment-paypal-bundle

And configure it:

# config/packages/payment.yaml

jms_payment_paypal:
    username: your api username
    password: your api password
    signature: your api signature

Next steps¶

If you have no prior experience with this bundle or payment processing in general, you should follow the Accepting payments guide. Otherwise, proceed to the Payment form chapter.

Creating the form¶

When creating the form you need to specify at least the amount and currency options. See below for all the available options.

// src/App/Controller/OrdersController.php

use JMS\Payment\CoreBundle\Form\ChoosePaymentMethodType;

$form = $this->createForm(ChoosePaymentMethodType::class, null, [
    'amount'   => '10.42',
    'currency' => 'EUR',
]);

// src/App/Controller/OrdersController.php

$form = $this->createForm('jms_choose_payment_method', null, [
    'amount'   => '10.42',
    'currency' => 'EUR',
]);

Changing how the form looks¶

If you need to change how the form looks, you can use form theming, which allows you to customize how each element of the form is rendered. Our theme will be implemented in a separate Twig file, which we will then reference from the template where the form is rendered.

Start by creating an empty theme file:

{# templates/Orders/theme.html.twig #}

{% extends 'form_div_layout.html.twig' %}

And then reference it from the template where the form is rendered:

{# templates/Orders/show.html.twig #}

{% form_theme form 'Orders\theme.html.twig' %}

{{ form_start(form) }}
    {{ form_widget(form) }}
    <input type="submit" value="Pay € {{ order.amount }}" />
{{ form_end(form) }}

{# templates/Orders/theme.html.twig #}

{# Don't render the radio button's label #}
{% block _jms_choose_payment_method_method_label %}
{% endblock %}

{# Hide each entry in the radio button #}
{% block _jms_choose_payment_method_method_widget %}
    <div style="display: none;">
        {{ parent() }}
    </div>
{% endblock %}

Available options¶

// src/App/Controller/OrdersController.php

use JMS\Payment\CoreBundle\Form\ChoosePaymentMethodType;

$form = $this->createForm(ChoosePaymentMethodType::class, null, [
    'amount'   => '10.42',
    'currency' => 'EUR',
]);

// src/App/Controller/OrdersController.php

use JMS\Payment\CoreBundle\Entity\ExtendedData;
use JMS\Payment\CoreBundle\Form\ChoosePaymentMethodType;

$amount = '10.42';

$amountClosure = function ($currency, $paymentSystemName, ExtendedData $data) use ($amount) {
    if ($paymentSystemName === 'paypal_express_checkout') {
        return $amount * 1.05;
    }

    return $amount;
};

$form = $this->createForm(ChoosePaymentMethodType::class, null, [
    'amount'   => $amountClosure,
    'currency' => 'EUR',
]);

// src/App/Controller/OrdersController.php

use JMS\Payment\CoreBundle\Form\ChoosePaymentMethodType;

$form = $this->createForm(ChoosePaymentMethodType::class, null, [
    'amount'   => '10.42',
    'currency' => 'EUR',
]);

// src/App/Controller/OrdersController.php

use JMS\Payment\CoreBundle\Form\ChoosePaymentMethodType;

$predefinedData = [
    'stripe_checkout' => [
        'description' => 'My product',
    ],
];

$form = $this->createForm(ChoosePaymentMethodType::class, null, [
    'amount'          => '10.42',
    'currency'        => 'EUR',
    'predefined_data' => $predefinedData,
]);

// src/App/Controller/OrdersController.php

$predefinedData = [
    'paypal_express_checkout' => [...],
    'stripe_checkout'         => [...],
];

// src/App/Controller/OrdersController.php

use JMS\Payment\CoreBundle\Form\ChoosePaymentMethodType;

$form = $this->createForm(ChoosePaymentMethodType::class, null, [
    'amount'          => '10.42',
    'currency'        => 'EUR',
    'allowed_methods' => ['paypal_express_checkout']
]);

// src/App/Controller/OrdersController.php

use JMS\Payment\CoreBundle\Form\ChoosePaymentMethodType;

$form = $this->createForm(ChoosePaymentMethodType::class, null, [
    'amount'          => '10.42',
    'currency'        => 'EUR',
    'default_method'  => 'paypal_express_checkout',
]);

// src/App/Controller/OrdersController.php

use JMS\Payment\CoreBundle\Form\ChoosePaymentMethodType;

$form = $this->createForm(ChoosePaymentMethodType::class, null, [
    'amount'         => '10.42',
    'currency'       => 'EUR',
    'choice_options' => [
        'expanded' => false,
    ],
]);

// src/App/Controller/OrdersController.php

use JMS\Payment\CoreBundle\Form\ChoosePaymentMethodType;

$form = $this->createForm(ChoosePaymentMethodType::class, null, [
    'amount'         => '10.42',
    'currency'       => 'EUR',
    'method_options' => [
        'paypal_express_checkout' => [
            'label' => false,
        ],
    ],
]);

PaymentInstruction State Change Event¶

Name: payment_instruction.state_change

Class: JMS\Payment\CoreBundle\PluginController\Event\PaymentInstructionStateChangeEvent

This event is dispatched after the state of a payment instruction changes.

You have access to the PaymentInstruction, the new state and the old state of the payment instruction.

Payment State Change Event¶

Name: payment.state_change

Class: JMS\Payment\CoreBundle\PluginController\Event\PaymentStateChangeEvent

This event is dispatched directly after the state of a payment changed. All related entities have already been updated.

You have access to the Payment, the PaymentInstruction, the new state and the old state of the payment.

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:

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:

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

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.

Payment-related user data¶

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;

class CreditCardType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('holder', 'text', array('required' => false))
            ->add('number', 'text', array('required' => false))
            ->add('expires', 'date', array('required' => false))
            ->add('code', 'text', array('required' => false))
        ;
    }

    public function getName()
    {
        return 'credit_card';
    }
}

use JMS\Payment\CoreBundle\Plugin\AbstractPlugin;
use JMS\Payment\CoreBundle\Model\PaymentInstructionInterface;
use JMS\Payment\CoreBundle\Plugin\ErrorBuilder;

class CreditCardPlugin extends AbstractPlugin
{
    public function checkPaymentInstruction(PaymentInstructionInterface $instruction)
    {
        $errorBuilder = new ErrorBuilder();
        $data = $instruction->getExtendedData();

        if (!$data->get('holder')) {
            $errorBuilder->addDataError('holder', 'form.error.required');
        }
        if (!$data->get('number')) {
            $errorBuilder->addDataError('number', 'form.error.required');
        }

        if ($instruction->getAmount() > 10000) {
            $errorBuilder->addGlobalError('form.error.credit_card_max_limit_exceeded');
        }

        // more checks here ...

        if ($errorBuilder->hasErrors()) {
            throw $errorBuilder->getException();
        }
    }

    public function processes($method)
    {
        return 'credit_card' === $method;
    }
}

PaymentInstruction¶

A PaymentInstruction is the first object that you need to create. It contains information such as the total amount, the payment method, the currency, and any data that is necessary for the payment method, for example credit card information.

Below you find the different states that a PaymentInstruction can go through:

Payment¶

Each PaymentInstruction may be split up into several payments. A Payment always holds an amount, and the current state of the workflow, such as initiated, approved, deposited, etc.

This allows, for example, to request a fraction of the total amount to be deposited before an order ships, and the rest afterwards.

Below, you find the different states that a Payment can go through:

FinancialTransaction¶

Each Payment may have several transactions. Each FinancialTransaction represents a specific interaction with the payment backend. In the case of a credit card payment, this could for example be an authorization transaction.

Below, you find the different states that a FinancialTransaction can go through:

The Order entity¶

The Order entity represents what is being purchased and usually contains:

• $id: The unique id of the order
• $amount: The total price
• $paymentInstruction: The PaymentInstruction instance

Here’s the full code for a minimal Order entity:

// src/App/Entity/Order.php

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use JMS\Payment\CoreBundle\Entity\PaymentInstruction;

/**
 * @ORM\Table(name="orders")
 * @ORM\Entity
 */
class Order
{
    /**
     * @ORM\Column(name="id", type="integer")
     * @ORM\Id
     * @ORM\GeneratedValue(strategy="AUTO")
     */
    private $id;

    /**
     * @ORM\OneToOne(targetEntity="JMS\Payment\CoreBundle\Entity\PaymentInstruction")
     */
    private $paymentInstruction;

    /**
     * @ORM\Column(type="decimal", precision=10, scale=5)
     */
    private $amount;

    public function __construct($amount)
    {
        $this->amount = $amount;
    }

    public function getId()
    {
        return $this->id;
    }

    public function getAmount()
    {
        return $this->amount;
    }

    public function getPaymentInstruction()
    {
        return $this->paymentInstruction;
    }

    public function setPaymentInstruction(PaymentInstruction $instruction)
    {
        $this->paymentInstruction = $instruction;
    }
}

Before proceeding, make sure you update your database schema, in order to create the orders table:

bin/console doctrine:schema:update

Or, if using migrations:

bin/console doctrine:migrations:diff
bin/console doctrine:migrations:migrate

The Controller¶

Each step of our Checkout process will be implemented as an action in an OrdersController. All routes will be namespaced under /orders.

Go ahead and create the controller:

// src/App/Controller/OrdersController.php

namespace App\Controller;

use Symfony\Component\Routing\Annotation\Route;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

/**
 * @Route("/orders")
 */
class OrdersController extends AbstractController
{
}

Creating an Order¶

The first step in our Checkout process is to create an Order, which we will do in a newAction. This action acts as the bridge between the Checkout process and the rest of your application.

To simplify, we will only be passing an amount (the total price of the items being purchased) as a parameter to the action. In a real world application you would probably pass the $id of a Shopping Cart, or a similar entity that holds information about the items being purchased.

Create the newAction in the OrdersController:

// src/App/Controller/OrdersController.php

use AppBundle\Entity\Order;
use Symfony\Component\Routing\Annotation\Route;

/**
 * @Route("/new/{amount}")
 */
public function newAction($amount)
{
    $em = $this->getDoctrine()->getManager();

    $order = new Order($amount);
    $em->persist($order);
    $em->flush();

    return $this->redirectToRoute('app_orders_show', [
        'orderId' => $order->getId(),
    ]);
}

If you navigate to /orders/new/42.24, a new Order will be inserted in the database with 42.24 as the amount and you will be redirected to the showAction, which we will create next.

Creating the payment form¶

Once the Order has been created, the next step in our Checkout process is to display it, along with the payment form. We will be doing this in a showAction:

// src/App/Controller/OrdersController.php

use App\Entity\Order;
use JMS\Payment\CoreBundle\Form\ChoosePaymentMethodType;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\HttpFoundation\Request;

/**
 * @Route("/{orderId}/show")
 */
public function showAction($orderId, Request $request, PluginController $ppc)
{
    $order = $this->getDoctrine()->getManager()->getRepository(Order::class)->find($orderId);

    $form = $this->createForm(ChoosePaymentMethodType::class, null, [
        'amount'   => $order->getAmount(),
        'currency' => 'EUR',
    ]);

    return $this->render('Orders/show.html.twig', [
        'order' => $order,
        'form'  => $form->createView(),
    ]);
}

// src/AppBundle/Controller/OrdersController.php

$form = $this->createForm('jms_choose_payment_method', null, [
    'amount'   => $order->getAmount(),
    'currency' => 'EUR',
]);

And the corresponding template:

{# templates/Orders/show.html.twig #}

Total price: € {{ order.amount }}

{{ form_start(form) }}
    {{ form_widget(form) }}
    <input type="submit" value="Pay € {{ order.amount }}" />
{{ form_end(form) }}

If you now refresh the page in your browser, you should see the template rendered, with all the payment methods you have installed. The form includes a radio button so the user can select the payment method they wish to use.

Handling form submission¶

We’ll handle form submission in the same action which renders the form. Upon binding, the form type will validate the data for the chosen payment method and, on success, give us back a valid PaymentInstruction instance.

We’ll attach this PaymentInstruction to the Order and then redirect to the paymentCreateAction. In case the form is not valid, we don’t redirect and the template is re-rendered with form errors displayed.

Note that no remote calls to the payment backend are made in this action, we’re simply manipulating data in the local database.

// src/App/Controller/OrdersController.php

use App\Entity\Order;
use JMS\Payment\CoreBundle\Form\ChoosePaymentMethodType;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\HttpFoundation\Request;

/**
 * @Route("/{orderId}/show")
 */
public function showAction($orderId, Request $request, PluginController $ppc)
{
    $form = $this->createForm(ChoosePaymentMethodType::class, null, [
        'amount'   => $order->getAmount(),
        'currency' => 'EUR',
    ]);

    $form->handleRequest($request);

    if ($form->isSubmitted() && $form->isValid()) {
        $ppc->createPaymentInstruction($instruction = $form->getData());

        $order->setPaymentInstruction($instruction);

        $em = $this->getDoctrine()->getManager();
        $em->persist($order);
        $em->flush($order);

        return $this->redirectToRoute('app_orders_paymentcreate', [
            'orderId' => $order->getId(),
        ]);
    }

    return $this->render('Orders/show.html.twig', [
        'order' => $order,
        'form'  => $form->createView(),
    ]);
}

Depositing money¶

In the previous section, we created our PaymentInstruction and redirected to the paymentCreateAction. In this section we will be implementing that action.

// src/App/Controller/OrdersController.php

use App\Entity\Order;
use JMS\Payment\CoreBundle\PluginController\PluginController;

private function createPayment(Order $order, PluginController $ppc)
{
    $instruction = $order->getPaymentInstruction();
    $pendingTransaction = $instruction->getPendingTransaction();

    if ($pendingTransaction !== null) {
        return $pendingTransaction->getPayment();
    }

    $amount = $instruction->getAmount() - $instruction->getDepositedAmount();

    return $ppc->createPayment($instruction->getId(), $amount);
}

// src/App/Controller/OrdersController.php

use App\Entity\Order;
use Symfony\Component\Routing\Annotation\Route;
use JMS\Payment\CoreBundle\PluginController\PluginController;
use JMS\Payment\CoreBundle\PluginController\Result;

/**
 * @Route("/{orderId}/payment/create")
 */
public function paymentCreateAction($orderId, PluginController $ppc)
{
    $order = $this->getDoctrine()->getManager()->getRepository(Order::class)->find($orderId);

    $payment = $this->createPayment($order, $ppc);

    $result = $ppc->approveAndDeposit($payment->getId(), $payment->getTargetAmount());

    if ($result->getStatus() === Result::STATUS_SUCCESS) {
        return $this->redirectToRoute('app_orders_paymentcomplete', [
            'orderId' => $order->getId(),
        ]);
    }

    throw $result->getPluginException();

    // In a real-world application you wouldn't throw the exception. You would,
    // for example, redirect to the showAction with a flash message informing
    // the user that the payment was not successful.
}

// src/App/Controller/OrdersController.php

use JMS\Payment\CoreBundle\Plugin\Exception\Action\VisitUrl;
use JMS\Payment\CoreBundle\Plugin\Exception\ActionRequiredException;
use JMS\Payment\CoreBundle\PluginController\Result;

if ($result->getStatus() === Result::STATUS_PENDING) {
    $ex = $result->getPluginException();

    if ($ex instanceof ActionRequiredException) {
        $action = $ex->getAction();

        if ($action instanceof VisitUrl) {
            return $this->redirect($action->getUrl());
        }
    }
}

throw $result->getPluginException();

// src/App/Controller/OrdersController.php

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

/**
 * @Route("/{orderId}/payment/complete")
 */
public function paymentCompleteAction($orderId)
{
    return new Response('Payment complete');
}

Copying the mapping files¶

Start by copying the mapping files from this bundle to your application:

cd my-app
mkdir -p config/packages/JMSPaymentCoreBundle
cp vendor/jms/payment-core-bundle/JMS/Payment/CoreBundle/Resources/config/doctrine/* config/packages/JMSPaymentCoreBundle/

You now have a copy of the following mapping files under config/packages/JMSPaymentCoreBundle:

• Credit.orm.xml
• FinancialTransaction.orm.xml
• Payment.orm.xml
• PaymentInstruction.orm.xml

Configuring custom mapping¶

The next step is to tell Symfony to use your copy of the files instead of the ones supplied by this bundle:

# config/packages/doctrine.yml

doctrine:
    orm:
        # ...
        mappings:
            JMSPaymentCoreBundle:
                type: xml
                dir: '%kernel.root_dir%/config/packages/JMSPaymentCoreBundle'
                prefix: JMS\Payment\CoreBundle\Entity
                alias: JMSPaymentCoreBundle

Overriding decimal columns¶

Symfony is now using your custom mapping. Taking PaymentInstruction.orm.xml as an example, we can increase the maximum value of the amount column as follows:

<!-- config/packages/JMSPaymentCoreBundle/PaymentInstruction.orm.xml -->

<!-- Set maximum value to 9999999999.99999 -->
<field name="amount" type="decimal" precision="15" scale="5" />

Updating the database¶

Now that you changed the mapping, you need to update your database schema.

If you’re not using database migrations:

bin/console doctrine:schema:update

Or, if you’re using migrations:

bin/console doctrine:migrations:diff
bin/console doctrine:migrations:migrate