Skip to main content
Version: 2.x

Stripe integration

This guide explains how Front-Commerce allows using Stripe in a headless commerce project.

There is only one way to accept payments with Stripe in your Front-Commerce application for now.

Front-Commerce Payment​

This section explains how to configure and customize the Stripe Front-Commerce Payment module into an existing Front-Commerce application. The implementation use Stripe's Payment Intents API to create payments. Customers are also created in your Stripe account so you can identify them seamlessly.

Configure your environment​

With API keys found on your Stripe’s dashboard.

.env
# Stripe payment
# API Keys from https://dashboard.stripe.com/account/apikeys
FRONT_COMMERCE_WEB_STRIPE_PUBLISHABLE_KEY=pk_xxxxxx
FRONT_COMMERCE_STRIPE_SECRET_KEY=sk_xxxxxx

# Only for Magento2 / Magento2 B2B integrations
FRONT_COMMERCE_STRIPE_ENDPOINT_SECRET=whsec_xxxxxx
info

In order to retrieve the endpoint secret, you will need to create a webhook in your Stripe dashboard. See the related Stripe documentation.

Register the Stripe 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: "Stripe", path: "server/modules/payment-stripe" }
   ]

Adobe Commerce B2B​

Since version 2.25

The Stripe payment module supports the Negotiable Quote checkout and allows customers to pay a negotiated quote with Stripe.

To enable this feature, you must have the Magento2 B2B module enabled and register an additional serverModule:

.front-commerce.js
   modules: [],
   serverModules: [
     { name: "FrontCommerce", path: "server/modules/front-commerce" },
     { name: "Magento2", path: "server/modules/magento2" },
-    { name: "Stripe", path: "server/modules/payment-stripe" }
+    { name: "Stripe", path: "server/modules/payment-stripe" },
+    { name: "StripeM2B2B", path: "server/modules/payment-stripe/magento2-b2b" },
   ]

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: "Stripe", path: "server/modules/payment-stripe/index.magento1.js" }
   ]

Register your Stripe 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 Stripe

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

    const ComponentMap = {
    +  stripe: StripeCheckout
    };

Extra steps for Magento2 / Magento2 B2B​

Magento2 and Magento2 B2B stripe integration uses IPN to check for the payment status. You will need to set up a webhook in your Stripe dashboard to send notification to Front-Commerce. In order to do so, please follow the related Stripe documentation.

The required event types to work with Front-Commerce are:

  • charge.succeeded
  • charge.failed
  • payment_intent.canceled

The configured URL for the webhook should be: https://www.your-domain.com/webhooks/payment/notification/stripe

You will also need to update the checkoutFlowOf so that Stripe payment method uses an async order flow:

src/web/theme/pages/Checkout/checkoutFlowOf.js
diff --git a/src/web/theme/pages/Checkout/checkoutFlowOf.js b/src/web/theme/pages/Checkout/checkoutFlowOf.js
index f7bd3222f..b843608da 100644
--- a/src/web/theme/pages/Checkout/checkoutFlowOf.js
+++ b/src/web/theme/pages/Checkout/checkoutFlowOf.js
@@ -11,6 +11,7 @@ const checkoutFlowOf = (method) => {
   if (method.startsWith("hipay_")) return "directOrderWithAdditionalAction";

   if (method === "payzen_embedded") return "asyncOrder";
+  if (method === "stripe") return "asyncOrder";

   return "directOrder";
 };

Optional: enable Apple Pay and/or Google Pay​

Since version 2.24

If enabled in your Stripe account, Apple Pay and Google Pay payment methods are supported and can be used in your Front-Commerce store. Please refer to the Google Pay with Stripe and the Apple Pay with Stripe documentation to learn how to configure those payment methods.

tip

For those payment methods to show up, your Front-Commerce store must use the https protocol even in a test environment.

Update your CSPs​

To allow loading stripe related remote resources:

my-module/config/website.js
  contentSecurityPolicy: {
    directives: {
-      scriptSrc: [],
-      frameSrc: [],
+      scriptSrc: ["js.stripe.com"],
+      frameSrc: ["js.stripe.com"],
      styleSrc: [],
      imgSrc: [],
      connectSrc: [],
      baseUri: []
    }
  },

Advanced: disable automatic capture​

Since version 2.19

Optionally the environment variable FRONT_COMMERCE_STRIPE_DISABLE_CAPTURE can be set to true to configure the Stripe module so that the payment is not automatically captured. If you want this behavior, you have to change your .env in the following way:

.env
# Stripe payment
# API Keys from https://dashboard.stripe.com/account/apikeys
FRONT_COMMERCE_WEB_STRIPE_PUBLISHABLE_KEY=pk_xxxxxx
FRONT_COMMERCE_STRIPE_SECRET_KEY=sk_xxxxxx
+FRONT_COMMERCE_STRIPE_DISABLE_CAPTURE=true

Advanced: customize data sent to Stripe​

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 Stripe payment module is extensible. It leverages Front-Commerce's "data transform" pattern to allow developers to customize payloads sent to Stripe for Customer and Cart content.

Both the Customer and PaymentIntent Stripe objects can be customized at application level. It allows to add additional metadata depending on your own logic. For this, you can use the registerCustomerDataTransform and registerPaymentIntentDataTransform methods of the Stripe loader to add your custom transformers.

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

Advanced: network retries​

Since version 2.27

Optionally the environment variable FRONT_COMMERCE_STRIPE_MAX_NETWORK_RETRY can be set to an integer to configure the Stripe client maxNetworkRetries option. In versions where this variable is supported, maxNetworkRetries is configured to 3 by default.

note

Support for this environment variable has also been added in 2.26.1, 2.25.3, 2.24.5, 2.23.6, 2.22.7, 2.21.8, 2.20.10 and 2.19.16 releases.

.env
FRONT_COMMERCE_STRIPE_MAX_NETWORK_RETRY=5