Use Pledg with Gezy

Configure the Pledg extension to retrieve its credentials from a Gezy back-office.

With the gezy flavor, the Pledg extension reads its configuration directly from the Gezy back-office. You enable and configure Pledg on the Gezy side (modules and credentials), and Front-Commerce picks the configuration up automatically at startup. There is no manual mapping to maintain on the Front-Commerce side — the only environment variable involved is FRONT_COMMERCE_PLEDG_HOST (which selects the Pledg API host). See Environment and credentials below.

Prerequisites

• The @front-commerce/gezy extension must be installed and configured.
• Pledg must be enabled in your Gezy back-office, with at least one module carrying valid credentials.

Front-Commerce configuration

After installing the Pledg package, enable the extension with the gezy flavor in your front-commerce.config.ts:

front-commerce.config.ts

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

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

That is the only wiring required on the Front-Commerce side. As soon as Pledg is active in Gezy, Front-Commerce starts resolving plans through Pledg's API.

Where it appears on the storefront

The theme-chocolatine package wires the PaymentPlansBanners component on the product page out of the box. As soon as Pledg is active and returns plans for the current product price, banners are displayed next to the price without any additional work on the theme side.

Amount bounds

Each Pledg payment method in Gezy can be restricted to a montant_min / montant_max range (configured on the corresponding mode de règlement). These bounds are exposed through the Gezy webservice and propagated to the storefront on each plan.

When the product price is within the bounds, the banner shows its regular label and the Learn more CTA opens the simulator modal as usual. When the price is out of bounds, the banner switches to a dedicated label that references the range (for example "Pay in 3 installments for purchases from 100 € to 2,000 € with Pledg"), the Learn more CTA is hidden, and the modal cannot be opened — the simulated installments wouldn't reflect what Pledg would actually honour for this amount.

No additional Front-Commerce configuration is required: as long as Pledg exposes the bounds for the matching reglement_mode, the storefront adapts automatically.

Environment and credentials

Each Pledg module configured on the Gezy side carries two sets of OAuth2 credentials: a test set and a prod set. At startup, the extension picks one set based on FRONT_COMMERCE_ENV:

• FRONT_COMMERCE_ENV=production → the prod credentials are used.
• any other value (or unset) → the test credentials are used.

The Pledg API host is independent: it comes from the FRONT_COMMERCE_PLEDG_HOST environment variable and defaults to Pledg's staging host. Make sure to keep FRONT_COMMERCE_ENV and FRONT_COMMERCE_PLEDG_HOST consistent — for example, when targeting the Pledg production host, set FRONT_COMMERCE_ENV=production so production credentials are used. Otherwise the extension will call the production host with test credentials (or vice versa) and every request will fail.

Debug

To inspect the configuration resolved from Gezy at startup, run Front-Commerce with the matching debug flag:

Run Front-Commerce with Pledg's Gezy config debug flag

DEBUG=front-commerce:pledg:config:gezy pnpm run dev

The log line reports the detected environment (staging or production) and the number of Pledg modules resolved.