PaymentProviderModule

Module in @evolve-framework/commercetools

Hosts a PaymentAdapter as a Domain Service — the server side of the remote bridge.

It serves no healthcheck of its own: compose HealthModule alongside it, with graphql: false since this service has no schema.

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

new PaymentProviderModule(options: PaymentProviderModuleOptions)

Option	Type	Description
adapter	PaymentAdapter	The payment adapter to host. The module owns its lifecycle: init() initializes the adapter, and getHttpConfig() mounts its routes.
internalRoutes?	boolean	Publish the request-level routes (/payment-methods, /create) so remote checkout services can reach this adapter over HTTP. Disable when checkout calls the adapter in-process. Defaults to true.
externalRoutes?	boolean	Register the adapter's external routes (webhooks/redirects) via adapter.getRoutes(). Defaults to true.
secret?	string	Shared secret required on the internal routes (/payment-methods, /create, ...). When set, remote checkout callers must present authorization: Bearer <secret>; construct the matching RemotePaymentAdapter/Remote(...) with the same secret. Only the internal routes are guarded — the adapter's public webhook/redirect routes stay open.

PaymentAdapter16The fields of adapter.

Field	Type	Description
identifier	string
getPaymentMethods	(args: { targetId?: string | undefined; locale: string; targetType: "cart" | "order" | "invoice"; currency: string; country: string; device: "WEB" | "IOS" | "AN…	Resolve the available payment methods for a cart/order.
createTransaction	(req: { collected?: { currency: string; centAmount: number; } | undefined; customer: { ipAddress: string; }; locale: string; targetId: string; targetType: "cart…	Create (start) a transaction for a payment.
init	() => Promise<void>	One-shot, idempotent initialization (build SDK clients, etc.).
getRoutes	() => ((app: FastifyInstance<RawServerDefault, IncomingMessage, ServerResponse<IncomingMessage>, FastifyBaseLogger, FastifyTypeProviderDefault>) => void) | unde…	Provider-specific external routes to publish when this adapter is hosted as a service — principally the webhook endpoint the PSP calls with async payment updates, plus any redirect-return routes. Returns a Fastify callback the host mounts, or undefined when there are none. More A RemotePaymentAdapter returns undefined: it is only a client bridge, so the webhook routes live on the remote service that hosts the real adapter, not here.
inFlightWindowMs?	((payment: Payment) => number | undefined)	How long, in milliseconds, a transaction this adapter started may stay open before it counts as abandoned rather than in flight. Undefined -- or no method at all -- means it may stay open indefinitely. More Only the adapter can say, because the answer depends on the method: a redirect the provider itself expires within the hour is abandoned long before a bank transfer that is still legitimately on its way. The window has to outlast the provider's own, since a transaction counted as abandoned no longer stops the buyer paying again.
openPaymentRedirect?	((payment: Payment) => Promise<string | undefined>)	The page where the shopper can still complete a payment this adapter started, while the provider holds it open. Undefined -- or no method at all -- when there is no such page to send them back to. Asked on every read, so the answer is the provider's current one rather than a guess at when it expires.
partialAmount?	((target: Cart | Order, methodArgs: Record<string, unknown>) => Promise<number>)	The most this method can cover of what the target still owes, for a method that pays only part of it, such as a gift card. Its presence is what marks a method as partial: the payment is planned for the smaller of this and what is left to pay, several such payments may sit on one cart, and the cart is not frozen until the payment that completes the coverage starts.
captureReserved?	((payment: Payment) => Promise<void>)	Take the money a partial payment reserved, called once the order exists. Idempotent: it may be called again after a failure, and it must not capture twice. A failure leaves the order's balance due and is logged, never undone.
releaseReserved?	((payment: Payment, centAmount?: number | undefined) => Promise<void>)	Give back what a partial payment reserved, up to centAmount or all of it when absent. Called when the buyer removes the payment, when a cart change leaves it covering more than is owed, and when the order is never created.
reservationExpiresAt?	((payment: Payment) => Date | undefined)	When what a partial payment reserved lapses at the provider, if it does. A reservation past that moment stops counting as secured on a read, and is recorded as cancelled when its cart is next paid. Absent for a provider whose reservations do not lapse.
onOrderCreated?	((listener: OrderCreatedListener) => void)	Registers what the adapter calls once an order exists for a cart it settled, or an order it settled was placed before it was paid. The registry sets it to take the money partial payments reserved; an adapter that does not extend BasePaymentAdapter may ignore it.
validateApplePaySession?	((args: { cartId: string; displayName: string; domainName: string; merchantIdentifier: string; }) => Promise<{ data: string; }>)	Validate an Apple Pay session. Optional — not every provider supports it.
updateExpressCheckout?	((args: { amount: { currency: string; centAmount: number; }; paymentId: string; paymentData: string; deliveryMethods: { reference: string; amount: { currency: s…	Bring a wallet payment in progress up to date with the cart, for a wallet whose own sheet changes the address or shipping, such as PayPal Express. Optional — not every provider supports it.
submitPaymentDetails?	((args: { targetId: string; targetType: "cart" | "order" | "invoice"; paymentId: string; details: { [x: string]: any; }; }) => Promise<{ status: string; payload…	Continue a transaction whose start answered with an action for the provider's component, with what that component reported. Answers like createTransaction and settles the target as a provider notification would. Optional — only a provider that answers with an action needs it.
cancelPayment?	((args: { targetId: string; targetType: "cart" | "order" | "invoice"; paymentId: string; }) => Promise<{ cancelled: boolean; }>)	Withdraw a payment the shopper abandoned in the provider's component, and release its target. Answers false, changing nothing, once the provider has taken money or is deciding on it. Optional, like submitPaymentDetails.

Extends AbstractModule<CommercetoolsLoaderContext>.