HiPay

The HiPay extension allows customer to pay using HiPay payment methods.

Prerequisites

To use this extension, you need an HiPay account that can access the HiPay console.

Installation

First, you need to install the @front-commerce/hipay package:

Command to install @front-commerce/hipay

$ pnpm install @front-commerce/hipay
# needs to be installed due to https://github.com/hipay/hipay-enterprise-sdk-nodejs/issues/3
$ pnpm install @hipay/hipay-enterprise-sdk-nodejs

Then to enable the extension, you need to add the HiPay extension definition to your front-commerce.config.ts. When doing that, you need to pass the flavor in which you want to run the extension, the flavor must be one of the following values:

• magento2: in this flavor, the extension is configured to work with Magento2.
• magento1: in this flavor, the extension is configured to work with Magento1.

front-commerce.config.ts for a Magento2 based project

import { defineConfig } from "@front-commerce/core/config";
import themeChocolatine from "@front-commerce/theme-chocolatine";
import magento2 from "@front-commerce/magento2";
import hipay from "@front-commerce/hipay";
import storesConfig from "./app/config/stores";
import cacheConfig from "./app/config/caching";

export default defineConfig({
  extensions: [
    magento2({ storesConfig }),
    themeChocolatine(),
    hipay("magento2"),
  ],
  stores: storesConfig,
  cache: cacheConfig,
  configuration: {
    providers: [],
  },
});

Configuring the HiPay console

For Front-Commerce to use the HiPay API you will need to create technical users and retrieve some informations for the environment variables.

• Go to Menu > Integration > Security Settings.
• Get the "Secret Passphrase" as FRONT_COMMERCE_HIPAY_SECRET_PASSPHRASE
• Ensure the "Hashing Algorithm" is SHA-256
• Create the public user
  • Click on "Generate new credentials"
  • Set "Credentials accessibility" to "Public"
  • Check "Tokenize a card"
  • Click on "save"
  • Get the "username" as FRONT_COMMERCE_HIPAY_PUBLIC_USERNAME
  • Get the "password" as FRONT_COMMERCE_HIPAY_PUBLIC_PASSWORD
• Create the private user
  • Click on "Generate new credentials"
  • Set "Credentials accessibility" to "Private"
  • Check all in "Order" and "Maintenance"
  • Click on "save"
  • Get the "username" as FRONT_COMMERCE_HIPAY_PRIVATE_USERNAME
  • Get the "password" as FRONT_COMMERCE_HIPAY_PRIVATE_PASSWORD

You must also configure IP restrictions to allow your server to communicate with HiPay:

• For self-hosted deployments: add your server's IP address
• For Front-Commerce cloud deployments: whitelist the IPs listed in our documentation

Add the HiPay settings to the environment

You need to define several environment variables to enable HiPay payments:

• FRONT_COMMERCE_HIPAY_SECRET_PASSPHRASE: from the HiPay console (see above)
• FRONT_COMMERCE_HIPAY_PUBLIC_USERNAME: from the HiPay console (see above)
• FRONT_COMMERCE_HIPAY_PUBLIC_PASSWORD: from the HiPay console (see above)
• FRONT_COMMERCE_HIPAY_PRIVATE_USERNAME: from the HiPay console (see above)
• FRONT_COMMERCE_HIPAY_PRIVATE_PASSWORD: from the HiPay console (see above)
• FRONT_COMMERCE_HIPAY_ENVIRONMENT: stage or production depending on your targeted environment

Optional environment variables:

• FRONT_COMMERCE_HIPAY_NOTIFICATION_DELAY: Payment capture notifications can arrive in the same time as payment authorization notifications, you can set a delay (in milliseconds) to prevent the notifications to be stored in the wrong order in the backend

Register HiPay payment components

Since version 3.17

Nothing more to do, HiPay payment components are now registered automatically.

Before version 3.17

1. Register the getAdditionalDataComponent which lets you register additional payments forms in Front-Commerce

   import HiPayCheckout from "theme/hipay/HiPayCheckout";
   
   const ComponentMap = {};
   
   const getAdditionalDataComponent = (method) => {
     if (method.code.startsWith("hipay_")) {
       return HiPayCheckout;
     }
     return ComponentMap[method.code];
   };
   
   export default getAdditionalDataComponent;

2. Register the getAdditionalActionComponent which lets you register additional payments actions in Front-Commerce

   import None from "theme/modules/Checkout/PlaceOrder/AdditionalAction/None";
   import HiPayActions from "theme/modules/Checkout/PlaceOrder/AdditionalAction/HiPay/HiPayActions";
   
   const ComponentMap = {};
   
   const getAdditionalActionComponent = (
     paymentCode,
     paymentAdditionalData
   ) => {
     if (paymentCode.startsWith("hipay_")) {
       return HiPayActions;
     }
     return ComponentMap?.[paymentCode] ?? None;
   };
   
   export default getAdditionalActionComponent;

3. Register custom Flash message components to display payment messages in an optimized way (recommended)

   theme/modules/FlashMessages/getFlashMessageComponent.ts

   import originalGetFlashMessageComponent from "@front-commerce/theme/modules/FlashMessages/getFlashMessageComponent";
   import {
     HiPayPaymentSuccess,
     HiPayPaymentError,
   } from "theme/hipay/FlashMessage";
   
   const ComponentMap = {
     hipaySuccess: HiPayPaymentSuccess,
     hipayError: HiPayPaymentError,
   };
   
   const getFlashMessageComponent = (type = "default") => {
     return ComponentMap[type] || originalGetFlashMessageComponent(type);
   };
   
   export default getFlashMessageComponent;

4. Register the HiPay payment methods labels

   theme/modules/Checkout/Payment/PaymentMethodLabel.ts

   import OriginalPaymentMethodLabel from "@front-commerce/theme/modules/Checkout/Payment/PaymentMethodLabel";
   import HiPayMethodLabels from "theme/hipay/HiPayMethodLabels";
   
   interface PaymentMethodLabelProps {
     code: string;
     fallbackLabel?: string;
   }
   
   const PaymentMethodLabel = (props: PaymentMethodLabelProps) => {
     if (props.code in HiPayMethodLabels) {
       return HiPayMethodLabels[props.code as keyof typeof HiPayMethodLabels];
     }
   
     return <OriginalPaymentMethodLabel {...props} />;
   };
   
   export default PaymentMethodLabel;