commercetools-mollie

@evolve-framework/commercetools-mollie · v1.0.0

Mollie payments for the commercetools engine: a payment adapter that lists Mollie's payment methods, starts payments, and processes the shopper's return and Mollie's webhooks, recording each on the commercetools payment.

When to use

Use it when Mollie is a payment provider of a shop on @evolve-framework/commercetools. There is one package per provider, and a shop can register several. It only works behind the commercetools engine.

The adapter runs in one of two ways: as a payment service of its own, with PaymentProviderModule mounting its routes, as in the example below; or inside the commercetools service, registered in the PaymentRegistry that the cart, checkout and payment modules are given.

• Payment methods: Whatever is active on the Mollie profile, named in the shopper's language.
• Webhook route: POST /webhook, Mollie's payment-status webhook. The storefront resolves a returning shopper's payment with POST /payment-status. Inside the commercetools service, registered in a PaymentRegistry, the routes are prefixed with /mollie, for example /mollie/webhook.

Get started

1. Install the package with the peer dependencies it needs. It comes from the Evolve registry, which needs a one-time sign-in.

   pnpm add @evolve-framework/commercetools-mollie @evolve-framework/commercetools @evolve-framework/core fastify

   Requirements5

   @evolve-framework/commercetools	>= 0.10.0 < 2.0.0
   @evolve-framework/core	>= 1.0.0 < 2.0.0
   @types/node	>=22optional
   fastify	>= 5.12.1 < 6.0.0
   msw	^2.14.6 || ^3.0.1optional

For example:

import {
  ClientFactory,
  type CommercetoolsLoaderContext,
  PaymentProviderModule,
} from "@evolve-framework/commercetools";
import { MolliePaymentAdapter } from "@evolve-framework/commercetools-mollie";
import {
  CompositeModule,
  createApplication,
  HealthModule,
} from "@evolve-framework/core";

const clientFactory = ClientFactory.create({
  projectKey: process.env.CTP_PROJECT_KEY!,
  apiUrl: process.env.CTP_API_URL!,
  authUrl: process.env.CTP_AUTH_URL!,
  clientId: process.env.CTP_CLIENT_ID!,
  clientSecret: process.env.CTP_CLIENT_SECRET!,
  scopes: process.env.CTP_SCOPES?.split(",") ?? [],
});

const app = await createApplication({
  name: "payment-commercetools-mollie",
  module: new CompositeModule<CommercetoolsLoaderContext>([
    new PaymentProviderModule({
      adapter: new MolliePaymentAdapter({
        clientFactory,
        config: {
          apiKey: process.env.MOLLIE_API_KEY!,
          serverUrl: process.env.SERVER_URL!,
        },
      }),
      internalRoutes: true,
      externalRoutes: true,
    }),
    // Serves /healthcheck for the liveness probe and /readiness for the
    // dependency check. `graphql: false` because this service has no schema.
    new HealthModule({ name: "commercetools-mollie", graphql: false }),
  ]),
  http: {
    address: {
      host: process.env.HTTP_HOST ?? "localhost",
      port: Number(process.env.HTTP_PORT ?? 4026),
    },
  },
});

await app.start();

Adapters

MolliePaymentAdapter

Mollie as a commercetools payment provider.

import { MolliePaymentAdapter } from "@evolve-framework/commercetools-mollie";

new MolliePaymentAdapter(options: MolliePaymentAdapterOptions)

Option	Type	Description
clientFactory	ClientFactory	Pre-configured commercetools ClientFactory, used to build a system request builder for commercetools reads/writes.
config	MollieConfig	Mollie credentials and runtime settings used by the SDK and routes.

MollieConfig3The fields of config.

Field	Type	Description
apiKey	string	Mollie API key (test_* or live_*).
serverUrl	string	Externally reachable base URL of this service; used to build the webhook URL passed to Mollie when creating payments.
shopName?	string	The shop's name as the shopper's bank statement shows it. With it, a payment for an order is described as " order "; without it, as "Webshop payment ".

Method	Description
openPaymentRedirect(payment: Payment): Promise<string | undefined>	Mollie's checkout page for the payment, while Mollie still reports it open.

Extends BasePaymentAdapter.

Entry points

@evolve-framework/commercetools-mollie	MolliePaymentAdapter and its options, configuration and client.2 exports
@evolve-framework/commercetools-mollie/testing	An MSW server with the mocked commercetools project, for testing a service that uses the adapter.1 export