commercetools-pay-on-account

@evolve-framework/commercetools-pay-on-account · v1.0.0

Pay on account for the commercetools engine: a payment adapter that lets a business unit pay by invoice. It is an offline provider, with no external payment service, so it has internal routes only and no shopper redirect or webhook.

When to use

Use it in a B2B shop on commercetools where some companies may order now and pay later. Whether a business unit may pay on account is read from a custom field on it. It runs next to, or instead of, an online provider such as commercetools-mollie.

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: One: invoice, offered only when the buyer's business unit is eligible.
• Webhook route: None. Paying on account involves no payment service, so there is no shopper redirect and nothing calls back.

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-pay-on-account @evolve-framework/commercetools @evolve-framework/core

   Requirements4

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

For example:

import {
  ClientFactory,
  type CommercetoolsLoaderContext,
  PaymentProviderModule,
} from "@evolve-framework/commercetools";
import { PayOnAccountPaymentAdapter } from "@evolve-framework/commercetools-pay-on-account";
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-pay-on-account",
  module: new CompositeModule<CommercetoolsLoaderContext>([
    new PaymentProviderModule({
      adapter: new PayOnAccountPaymentAdapter({ clientFactory }),
      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-pay-on-account", graphql: false }),
  ]),
  http: {
    address: {
      host: process.env.HTTP_HOST ?? "localhost",
      port: Number(process.env.HTTP_PORT ?? 4024),
    },
  },
});

await app.start();

Adapters

PayOnAccountPaymentAdapter

Paying on account, for B2B: it offers the invoice method to a business unit whose canPayOnAccount field allows it, and moves the payment to the PaymentCreditGranted state, refusing to start when that state is missing.

import { PayOnAccountPaymentAdapter } from "@evolve-framework/commercetools-pay-on-account";

new PayOnAccountPaymentAdapter(options: PayOnAccountPaymentAdapterOptions)

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

Extends BasePaymentAdapter.

Entry points

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