Skip to content
EvolveEvolveEvolve

commercetools-adyen

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

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

When to use

Use it when Adyen 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 the merchant account has enabled for the cart's country, currency, amount and channel, as Adyen's /paymentMethods returns them. Cards (scheme) carry their brands as options, and a payment can only be started with a method Adyen offered for that cart.
  • Webhook route: POST /push, Adyen's standard notifications, verified by HMAC. The shopper returns to GET /redirect. Inside the commercetools service, registered in a PaymentRegistry, the routes are prefixed with /adyen, for example /adyen/push.

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-adyen @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 { AdyenPaymentAdapter } from "@evolve-framework/commercetools-adyen";
import {
  CompositeModule,
  createApplication,
  HealthModule,
} from "@evolve-framework/core";
import { NoopPublisher } from "@evolve-framework/core/messaging";


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-adyen",
  module: new CompositeModule<CommercetoolsLoaderContext>([
    new PaymentProviderModule({
      adapter: new AdyenPaymentAdapter({
        clientFactory,
        config: {
          apiKey: process.env.ADYEN_API_KEY!,
          hmacKey: process.env.ADYEN_HMAC_KEY!,
          merchantAccount: process.env.ADYEN_MERCHANT_ACCOUNT!,
          environment: "TEST",
          serverUrl: process.env.SERVER_URL!,
        },
        messagePublisher: new NoopPublisher(),
      }),
      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-adyen", graphql: false }),
  ]),
  http: {
    address: {
      host: process.env.HTTP_HOST ?? "localhost",
      port: Number(process.env.HTTP_PORT ?? 4021),
    },
  },
});


await app.start();

Adapters

AdyenPaymentAdapter

Adyen as a commercetools payment provider.

import { AdyenPaymentAdapter } from "@evolve-framework/commercetools-adyen";
new AdyenPaymentAdapter(options: AdyenPaymentAdapterOptions)
OptionTypeDescription
clientFactoryClientFactory

Pre-configured commercetools ClientFactory, used to build a system request builder for commercetools reads/writes.

configAdyenConfig

Adyen credentials and runtime settings used by the SDK and routes.

messagePublisherMessagePublisher

Publisher used to emit Adyen notifications from the /push webhook. Pass a messagePublisher from a cloud adapter (e.g. new SqsPublisher(...)) or a NoopPublisher to disable publishing.

AdyenConfig6The fields of config.
FieldTypeDescription
apiKeystring

Adyen API key used to authenticate against the Adyen API.

hmacKeystring

HMAC key used to validate inbound webhook signatures.

merchantAccountstring

Adyen merchant account identifier.

serverUrlstring

Externally reachable base URL of this service; used to build return URLs.

environment?AdyenEnvironment

Adyen environment to target. Defaults to "TEST" when omitted.

redirectWindowMs?number

How long, in milliseconds, a shopper sent to a redirect may take before the attempt counts as abandoned and they may pay again. Defaults to one hour. Keep it longer than the redirect stays valid at Adyen for the methods you offer: a payment completed after it is still recorded, but the buyer may by then have paid a second time.

MethodDescription
inFlightWindowMs(payment: Payment): number | undefinedA redirect nobody finishes produces no notification from Adyen, so its transaction would stay Pending for good.
validateApplePaySession( args: { cartId: string; displayName: string; domainName: string; merchantIdentifier: string; }, ): Promise<{ data: string; }>Apple Pay's merchant validation, through Adyen's Apple Pay certificate, so the project needs no certificate of its own.
updateExpressCheckout( args: { paymentId: string; paymentData: string; amount: { currency: string; centAmount: number; }; deliveryMethods: { amount: { currency: string; centAmount: number; }; reference: string; description: string; selected: boolean; }[]; }, ): Promise<{ paymentData: string; }>PayPal Express's address or shipping change, through Adyen's /paypal/updateOrder: the new amount and shipping options, against the payment's PayPal order.
submitPaymentDetails( args: { paymentId: string; targetId: string; targetType: "cart" | "order" | "invoice"; details: { [x: string]: any; }; }, ): Promise<TransactionResponse>Continue a payment Adyen's component carried on in the page, with what it reported on onAdditionalDetails.
cancelPayment( args: { paymentId: string; targetId: string; targetType: "cart" | "order" | "invoice"; }, ): Promise<{ cancelled: boolean; }>Withdraw a payment the shopper abandoned in Adyen's component.

Extends BasePaymentAdapter.

Entry points

@evolve-framework/commercetools-adyenAdyenPaymentAdapter and its options, configuration and client.7 exports
@evolve-framework/commercetools-adyen/testingAn MSW server with the mocked commercetools project, for testing a service that uses the adapter.1 export