Adding a new payment method

This page is currently under review and might not be totally up to date.

Out of the box, payment methods that are registered in the Magento core automatically popup in the Loki Checkout as well. You don't need to do anything for this. However, it might be that you need more customization:

When you want to add a custom logo for the choosen payment method;
When you want to add a custom form for the choosen payment method;
When your payment provider is driven by a JavaScript API;

With Loki Checkout, we aim for an easy integration of payment methods, where the code of one solution is easily reused for another. Because of this, the Loki Checkout supports some fixed scenarios that are described here. However, if this does not apply to your own customization, do not hack the code randomly to get things working. Instead, get in touch so we can head for the best technical solution with the lowest technical debt.

Note that the payment API of Hyvä Checkout does not apply to the Loki Checkout.

Adding a custom logo

Within the payment method selection panel of the checkout (template Yireo_LokiCheckout::checkout/billing/payment-methods.phtml), payment methods are shown with a radiobox and a label. This can be extended with a logo which is displayed via the PHTML template Yireo_LokiCheckout::checkout/billing/payment-methods/icon.phtml. Within this template, a ViewModel \Yireo\LokiCheckout\ViewModel\PaymentMethodIcon is being used to determine the output of an icon image (literall, the HTML of that icon).

By default, this icon is an empty string. However, you can create a DI plugin to output an icon anyway. For instance, the Yireo_LokiCheckoutMollie module contains the following etc/frontend/di.xml file:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Yireo\LokiCheckout\ViewModel\PaymentMethodIcon">
        <plugin name="Yireo_LokiCheckoutMollie::paymentMethodIconPlugin"
                type="Yireo\LokiCheckoutMollie\Plugin\PaymentMethodIconPlugin"/>
    </type>
</config>

And then, the DI plugin looks like the following:

namespace Yireo\LokiCheckoutMollie\Plugin;

use Yireo\LokiCheckout\ViewModel\PaymentMethodIcon;

class PaymentMethodIconPlugin
{
    public function afterGetIcon(
        PaymentMethodIcon $paymentMethodIcon,
        string $result,
        string $paymentMethodCode
    ): string {
        if (false === preg_match('/^mollie_methods_(.*)$/', $paymentMethodCode, $match)) {
            return $result;
        };

        if (empty($match)) {
            return $result;
        }

        $iconFileId = 'Mollie_Payment::images/methods/'.$match[1].'.svg';
        $iconUrl = $paymentMethodIcon->getAssetRepository()->getUrl($iconFileId);

        return '<img src="'.$iconUrl.'" />';
    }
}

Adding a custom form

Similarly to the icon template, there are also child templates being added for the purpose of forms and additional things (like scripts). In this example, we'll use a custom payment method with code foobar:

Block name loki.checkout.billing-step.payment-methods.foobar.form
Block name loki.checkout.billing-step.payment-methods.foobar.additional

These blocks do not exist yet, but you can easily add them yourselves. For instance, with a XML layout file loki_checkout.xml a block for the form can be created:

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:View/Layout:etc/page_configuration.xsd">
    <body>
        <block
            name="loki.checkout.billing-step.payment-methods.foobar.form"
            template="Yireo_Example::method/foobar.phtml"/>
    </body>
</page>

In this case, you can see that the block is just a plain PHTML template. How you want to build a HTML form in the PHTML template and link this to the PHTML template, is up to you. This could be custom logic, a Loki Component or a Magewire component.

Integrating JavaScript APIs

Every time a payment method is selected, a JavaScript event checkout:payment:method-activate is triggered.

You can listen to the event as follows:

window.addEventListener('checkout:payment:method-activate', event => {
    if (event.detail.method !== 'foobar') {
        return;
    }

    // Do your magic
});

Supporting both Hyvä and Luma

Because the Loki Checkout supports both Hyvä Themes and Luma themes, as a payment provider you will need to aim for compatility with both as well. You could actually use Tailwind classes within the Luma-based Loki Checkout as well - the Yireo_LokiCheckoutLuma module uses it too.

However, when it comes to JavaScript, it is often required with Luma to load the JavaScript via RequireJS. To support both themes with different templates, we can use the hyva_ layout prefix that Hyvä Themes provide. For instance, you could create a PHTML template for Luma with a default handle loki_checkout.xml and then rewrite the PHTML template to Hyvä with another layout file hyva_loki_checkout.xml.

File hyva_loki_checkout.xml:

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:View/Layout:etc/page_configuration.xsd">
    <body>
        <referenceBlock
            name="loki.checkout.billing-step.payment-methods.foobar.form"
            template="Yireo_Example::hyva/method/foobar.phtml"/>
    </body>
</page>

Within Hyvä, you can often load JavaScript in the following way:

<script>
    (() => {
        // Do your magic
    })();
</script>

With Luma, this might need to be wrapped with RequireJS:

<script>
    require([], function () {
        // Do your magic
    });
</script>