Version: next

Implement a custom payment plan simulator

The Product.paymentPlans core GraphQL field returns the BNPL installment plans available for a given product. The amount is derived from the product's final price (incl. or excl. tax depending on the shop's theme.priceDisplay.variants configuration), and the result is aggregated from any number of registered simulators.

How aggregation works

loaders.Payment exposes a registry similar to registerEmbeddedPaymentMethod:

Each PSP package registers its simulator in its GraphQL module's contextEnhancer.
loaders.Payment.simulatePaymentPlans(amount) calls every registered simulator in parallel with Promise.allSettled.
Plans returned by a fulfilled simulator are concatenated; rejections are logged and skipped, so a single PSP outage cannot prevent the others from rendering.

Implement the simulator

Create a new GraphQL module

The module must depend on Front-Commerce/Payment:

my-bnpl/src/graphql/index.ts
import { createGraphQLModule } from "@front-commerce/core/graphql";

export default createGraphQLModule({
  namespace: "Payments/MyBnpl",
  dependencies: ["Front-Commerce/Payment"],
  loadRuntime: () => import("./runtime"),
});

Implement the `PaymentPlanSimulator` interface

In your simulator's simulate(amount) method:

Call your PSP's API for the given amount.
Map each result to new InstallmentPlan({...}) (multiple payments with apr / debitRate) or new DeferredPlan({...}) (single future payment).
Return the array.

Monetary values use the runtime Money class from @front-commerce/core/graphql/price.

my-bnpl/src/loaders/MyBnplSimulator.ts
import {
  DeferredPlan,
  InstallmentPlan,
  type PaymentPlanSimulator,
} from "@front-commerce/core/graphql/payment";
import { Money } from "@front-commerce/core/graphql/price";

const MY_BNPL_PROVIDER = {
  id: "my-bnpl",
  label: "My BNPL",
  logoUrl: null,
};

export class MyBnplSimulator implements PaymentPlanSimulator {
  constructor(private readonly currency: string) {}

  async simulate(amount: number) {
    // Call your PSP, then map its response into InstallmentPlan or DeferredPlan instances.
    return [
      // Installment plan: N payments with APR / debit rate.
      new InstallmentPlan({
        id: "my-bnpl:3x",
        provider: MY_BNPL_PROVIDER,
        installments: [
          {
            dueDate: "2026-06-01",
            amount: new Money(amount / 3, this.currency),
            fees: new Money(0, this.currency),
          },
          // …
        ],
        apr: 0,
        debitRate: 0,
      }),
      // Deferred plan: a single payment at a future date, no APR / debit rate.
      new DeferredPlan({
        id: "my-bnpl:deferred",
        provider: MY_BNPL_PROVIDER,
        installments: [
          {
            dueDate: "2026-07-01",
            amount: new Money(amount, this.currency),
            fees: new Money(0, this.currency),
          },
        ],
      }),
    ];
  }
}

Error handling

Throw on transport or upstream errors. The registry isolates failing simulators via Promise.allSettled, so do not swallow errors silently — that hides outages instead of surfacing them in logs.

Register the simulator in the module's `contextEnhancer`

my-bnpl/src/graphql/runtime.ts
import { createGraphQLRuntime } from "@front-commerce/core/graphql";
import { MyBnplSimulator } from "../loaders/MyBnplSimulator";

export default createGraphQLRuntime({
  contextEnhancer: ({ config, loaders }) => {
    loaders.Payment.registerPaymentPlanSimulator(
      new MyBnplSimulator(config.shop.currency)
    );
    return {};
  },
});

Result

Once registered, the simulator contributes to Product.paymentPlans without any further wiring. Add the field to the product page query and your simulator shows up alongside every other registered one:

Performance

Product.paymentPlans is resolved per product, and simulator calls are not batched across products in a single GraphQL request. A query that returns N products fires N HTTP calls per registered simulator, in parallel.

Treat the field as a product-detail-page field. Avoid querying it on listings (PLP, cart, search results, related products). If your PSP exposes a batched simulation endpoint, share the call across the request with a DataLoader inside simulate(amount).

query ProductPaymentPlans($sku: String!) {
  product(sku: $sku) {
    paymentPlans {
      id
      type
      provider {
        id
        label
        logoUrl
      }
      installments {
        dueDate
        amount {
          amount
          currency
        }
        fees {
          amount
          currency
        }
      }
      apr
      debitRate
    }
  }
}

How aggregation works​

Implement the simulator​

Result​

How aggregation works

Implement the simulator

Result