commercetools-paynl

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

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

When to use

Use it when Pay.nl 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: The checkout options of the Pay.nl service, in its own checkout order, cached for 15 minutes.
• Webhook route: POST /webhook, Pay.nl's exchange. The shopper returns to GET /redirect. Inside the commercetools service, registered in a PaymentRegistry, the routes are prefixed with /paynl, for example /paynl/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-paynl @evolve-framework/commercetools @evolve-framework/core fastify zod

   Requirements6

   @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
   zod	>= 4.4.0 < 5.0.0

For example:

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

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(",") ?? [],
});

await cache.configure({ url: process.env.REDIS_URL });

const app = await createApplication({
  name: "payment-commercetools-paynl",
  module: new CompositeModule<CommercetoolsLoaderContext>([
    new PaymentProviderModule({
      adapter: new PaynlPaymentAdapter({
        clientFactory,
        config: {
          credentials: {
            atCode: process.env.PAYNL_AT_CODE!,
            apiToken: process.env.PAYNL_API_TOKEN!,
            serviceId: process.env.PAYNL_SERVICE_ID!,
            serviceSecret: process.env.PAYNL_SERVICE_ID_SECRET!,
          },
          serverUrl: process.env.SERVER_URL!,
          environment: process.env.ENVIRONMENT ?? "development",
          paymentLogos: JSON.parse(process.env.PAYMENT_LOGOS ?? "{}"),
        },
      }),
      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-paynl", graphql: false }),
  ]),
  http: {
    address: {
      host: process.env.HTTP_HOST ?? "localhost",
      port: Number(process.env.HTTP_PORT ?? 4023),
    },
  },
});

await app.start();

Adapters

PaynlPaymentAdapter

Pay.nl as a commercetools payment provider.

import { PaynlPaymentAdapter } from "@evolve-framework/commercetools-paynl";

new PaynlPaymentAdapter(options: PaynlPaymentAdapterOptions)

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

PaynlConfig5The fields of config.

Field	Type	Description
credentials	{ atCode: string; apiToken: string; serviceId: string; serviceSecret: string; }
serverUrl	string	Externally reachable base URL of the service. Used to build redirect and exchange (webhook) URLs sent to Pay.nl.
environment	string	Logical environment name. When not "production" the integration tells Pay.nl to use its sandbox / test mode.
paymentLogos?	Record<string, string>	Optional payment-method logo overrides keyed by Pay.nl tag (e.g. PG_4, PM_10_5080). When set, the URL replaces the default image returned by Pay.nl.
componentName?	string	Component name returned by /healthcheck. Defaults to "commercetools-paynl".

Extends BasePaymentAdapter.

Entry points

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