Skip to main content
Version: 2.x

PayZen / Lyra Collect integration

This guide explains how Front-Commerce allows using PayZen / Lyra Collect in a headless commerce project.

There are different ways for you to accept payments with PayZen or Lyra Collect in your Front-Commerce application.

note

Each integration method is independent from the others, meaning that you don't have to install additional modules on your eCommerce platform if using Front-Commerce payments.

Front-Commerce Payment​

This section explains how to configure and customize the PayZen Front-Commerce Payment module into an existing Front-Commerce application. The implementation use PayZen embedded form / Javascript with REST API to create payments.

Lyra Collect support​

Lyra Collect is a payment solution that shares the same infrastructure and API with Payzen. In Front-Commerce, it is the exact same module that is used. The only differences are:

  • the FRONT_COMMERCE_PAYZEN_PRODUCT environment variable (to be set to lyra_collect)
  • the URLs to use when updating your CSPs should be api.lyra.com instead of static.payzen.eu

Configure your environment​

Define environment variables​

Get your access keys by following the Payzen documentation. Update your .env with the following values:

.env
FRONT_COMMERCE_PAYZEN_PUBLIC_KEY=58039770:testpublickey_xxxxxxx
FRONT_COMMERCE_PAYZEN_PRIVATE_KEY=58039770:testpassword_yyyyyyy
FRONT_COMMERCE_PAYZEN_SHA256=xxxxxxxxx
#FRONT_COMMERCE_PAYZEN_PRODUCT=payzen # use lyra_collect to switch to Lyra Collect's API URLs

Configure notifications in your account​

You must also configure notifications in Payzen or Lyra "expert mode" to ensure only one notification is sent upon payment, to prevent multiple orders being created for a single payment:

PayZen notification rules configuration with only one notification enabled for "URL de notification à la fin du paiement"

Ensure Lyra's IP addresses are allowed​

If your server has a firewall, or your staging environment is protected by a HTTP basic authentication, you must allow Lyra's IP addresses to access your server. This is necessary for the payment confirmation to be sent to your server.

The list of IP addresses can be found in the PayZen documentation. As of 2024-10-15, the IP range to allow is: 194.50.38.0/24

Register the PayZen payment module​

In your Front-Commerce application:

Magento2​

.front-commerce.js
   modules: [],
   serverModules: [
     { name: "FrontCommerce", path: "server/modules/front-commerce" },
-    { name: "Magento2", path: "server/modules/magento2" }
+    { name: "Magento2", path: "server/modules/magento2" },
+    { name: "PayZen", path: "server/modules/payment-payzen" }
   ]

Magento1 (OpenMage LTS)​

.front-commerce.js
   modules: [],
   serverModules: [
     { name: "FrontCommerce", path: "server/modules/front-commerce" },
-    { name: "Magento1", path: "server/modules/magento1" }
+    { name: "Magento1", path: "server/modules/magento1" },
+    { name: "PayZen", path: "server/modules/payment-payzen/index.magento1.js" }
   ]
theme/pages/Checkout/checkoutFlowOf.js

const checkoutFlowOf = (method) => {
  ...

-  if (method === "payzen_embedded") return "asyncOrder";
+  if (method === "payzen_embedded") return "directOrder";

  ...
};

Register your PayZen payment component​

  1. Override the file that lets you register additional payments forms in Front-Commerce

    mkdir -p my-module/web/theme/modules/Checkout/Payment/AdditionalPaymentInformation/
    cp -u node_modules/front-commerce/src/web/theme/modules/Checkout/Payment/AdditionalPaymentInformation/getAdditionalDataComponent.js my-module/web/theme/modules/Checkout/Payment/AdditionalPaymentInformation/getAdditionalDataComponent.js

  2. Register PayZen

    my-module/web/theme/modules/Checkout/Payment/AdditionalPaymentInformation/getAdditionalDataComponent.js
    +import PayzenEmbeddedForm from "./PayzenEmbeddedForm";

    const ComponentMap = {
    +  payzen_embedded: PayzenEmbeddedForm
    };

Update your CSPs​

To allow loading PayZen related remote resources:

my-module/config/website.js
  contentSecurityPolicy: {
    directives: {
-      scriptSrc: [],
-      frameSrc: [],
-      styleSrc: [],
-      imgSrc: [],
+      scriptSrc: ["static.payzen.eu", "secure.payzen.eu", "api.lyra.com"],
+      frameSrc: ["static.payzen.eu", "secure.payzen.eu", "api.lyra.com"],
+      styleSrc: ["static.payzen.eu", "secure.payzen.eu", "api.lyra.com"],
+      imgSrc: ["static.payzen.eu", "secure.payzen.eu", "api.lyra.com"],
      styleSrc: [],
      imgSrc: [],
      connectSrc: [],
      baseUri: []
    }
  },
Important

When using the Lyra Collect integration, use the api.lyra.com and secure.lyra.com values instead of static.payzen.eu and secure.payzen.eu in the example above.

Advanced: customize data sent to PayZen​

WIP

This advanced pattern must be documented with further details. While we are working on it, please contact us if you need further assistance.

The PayZen payment module is extensible. It leverages Front-Commerce's "data transform" pattern to allow developers to customize payloads sent to PayZen for a Payment Request creation.

The Payment request object can be customized at application level. It allows to add additional metadata depending on your own logic. For this, you can use the registerPaymentRequestDataTransform method of the Payzen loader to add your custom transformers.

See the test for an example (while a detailed documentation is being written):

Contacting Lyra's support​

If you ever have to contact Lyra's support team, here are some recommendations in order to increase efficiency and ensure your issue could be handled by people more aware of Front-Commerce.

Checklist for an efficient support request
  • mention the fact that you are using Front-Commerce
  • don't mention your backend (i.e: Magento)
  • ask that the "support grand comptes" handles your request (Nicolas, Rémi or Maxime)

Magento2 module​

PHP Module Compatibility

At the time of writing, we support the Payzen module up to version 2.5. Support for next version will be available in the future.

WIP

This integration is aimed at being transparent for administrators and developers. That is why we haven't duplicated documentation from existing Magento resources. Please contact us if you need further assistance.

Front-Commerce Magento2 module contains headless payment adapters for the PayZen Standard method (Lyra's official Magento module).

The PayZen module must be configured in a normal way, as for a non-headless Magento store.