3. If you use resolveJsonModule: true, confirm package.json is in scope so version can be imported inside createMollieClient.ts.

4. Set credentials via environment variables and read them at startup:

// src/mollie-client.ts
import createMollieClient from './mollie/createMollieClient';

export const mollie = createMollieClient({
  apiKey: process.env.MOLLIE_API_KEY!, // e.g. "test_dHar4XY7..."
});

5. For OAuth-based integrations, replace apiKey with accessToken:

export const mollie = createMollieClient({
  accessToken: process.env.MOLLIE_ACCESS_TOKEN!,
});

6. Never set Authorization, User-Agent, Accept, Accept-Encoding, or Content-Type in Options.headers; the library overwrites them.

Public API

createMollieClient

import createMollieClient from './mollie/createMollieClient';

function createMollieClient(options: Options): MollieClient;

The single entry point. Pass either { apiKey: string } or { accessToken: string }. Optionally supply versionStrings, headers, and apiEndpoint. Returns a fully initialised MollieClient with a property for every Mollie API namespace (payments, orders, customers, methods, etc.). Throws TypeError immediately if neither credential is supplied.

Options

import type Options from './mollie/Options';

type Options =
  | { apiKey: string;      versionStrings?: string | string[]; headers?: Record<string, string>; apiEndpoint?: string }
  | { accessToken: string; versionStrings?: string | string[]; headers?: Record<string, string>; apiEndpoint?: string };

Used to configure the client. apiKey covers direct API-key access; accessToken covers OAuth flows. apiEndpoint defaults to https://api.mollie.com:443/v2/ and can be overridden for testing against a mock server.

MollieClient

import type { MollieClient } from './mollie/types';

The return type of createMollieClient. Exposes namespaced binders as properties:

mollieClient.payments        // PaymentsBinder
mollieClient.orders          // OrdersBinder
mollieClient.customers       // CustomersBinder
mollieClient.methods         // MethodsBinder
mollieClient.refunds         // top-level refunds binder
mollieClient.subscriptions   // top-level subscriptions binder
// ... and every other Mollie namespace

Use this type for dependency injection in services and tests.

Working examples

Scenario - Create and redirect to a payment

Create a Mollie payment and obtain the checkout URL to redirect the customer.

import createMollieClient from './mollie/createMollieClient';

const mollie = createMollieClient({ apiKey: process.env.MOLLIE_API_KEY! });

async function startPayment(orderId: string, amountEur: string): Promise<string> {
  const payment = await mollie.payments.create({
    amount: { value: amountEur, currency: 'EUR' },
    description: `Order ${orderId}`,
    redirectUrl: `https://yourshop.example/order/${orderId}/return`,
    webhookUrl:  `https://yourshop.example/webhooks/mollie`,
    metadata: { orderId },
  });

  const checkoutUrl = payment.getCheckoutUrl();
  if (!checkoutUrl) throw new Error('No checkout URL returned');
  return checkoutUrl;
}

Scenario - Handle a webhook and check payment status

Receive a Mollie webhook, retrieve the updated payment, and update your database.

import { IncomingMessage, ServerResponse } from 'http';
import createMollieClient from './mollie/createMollieClient';
import type { MollieClient } from './mollie/types';

const mollie: MollieClient = createMollieClient({ apiKey: process.env.MOLLIE_API_KEY! });

async function handleMollieWebhook(req: IncomingMessage, res: ServerResponse): Promise<void> {
  const body = await readBody(req); // your own helper
  const paymentId: string = body.id;

  const payment = await mollie.payments.get(paymentId);

  switch (payment.status) {
    case 'paid':
      await fulfillOrder(payment.metadata?.orderId);
      break;
    case 'failed':
    case 'expired':
      await cancelOrder(payment.metadata?.orderId);
      break;
  }

  res.writeHead(200).end();
}

async function fulfillOrder(orderId?: string): Promise<void> { /* ... */ }
async function cancelOrder(orderId?: string): Promise<void>  { /* ... */ }
async function readBody(req: IncomingMessage): Promise<any>   { /* ... */ }

Scenario - List available payment methods

Retrieve the active payment methods for a given currency and amount to populate a checkout UI.

import createMollieClient from './mollie/createMollieClient';
import type { MethodsListParams } from './mollie/types';

const mollie = createMollieClient({ apiKey: process.env.MOLLIE_API_KEY! });

async function getAvailableMethods(currency: string, value: string) {
  const params: MethodsListParams = {
    amount: { currency, value },
    locale: 'en_US',
  };

  const methods = await mollie.methods.list(params);

  return methods.map(m => ({
    id:          m.id,
    description: m.description,
    imageSize2x: m.image.size2x,
  }));
}

File walkthrough

• createMollieClient.ts - Imports all binders and data transformers, calls checkCredentials, constructs a TransformingNetworkClient, instantiates every binder, and returns the assembled client object.
• types.ts - Re-exports createMollieClient as default and named, exposes MollieClient, MollieOptions, and every resource/parameter type for consumer-side type imports.
• Options.ts - Defines the Options union type (apiKey XOR accessToken plus optional fields) and exports checkCredentials, which throws TypeError on missing credentials.
• certs.d.ts - Ambient module declaration allowing TypeScript to import .pem files as strings for the bundled CA certificate chain.
• binders/ - One binder class per resource namespace. Each extends Binder and exposes CRUD methods (create, get, list, update, delete) with typed parameter interfaces co-located in parameters.ts.
• communication/ - NetworkClient wraps node-fetch for raw HTTP; TransformingNetworkClient applies data transform functions before returning responses to callers.
• data/ - Plain TypeScript model interfaces and transform functions that convert raw Mollie API JSON into typed domain objects with helper methods (e.g. payment.getCheckoutUrl()).
• errors/ - Structured error types surfaced when the Mollie API returns a non-2xx response.
• plumbing/ - Shared internal helpers including alias (used to add shorthand properties to the client) and pagination utilities.
• types/ - Generic utility types (MaybeArray<T>, Xor<A,B>) used throughout the library.

Common pitfalls and fixes

• Missing resolveJsonModule: createMollieClient.ts imports version from package.json; add "resolveJsonModule": true to tsconfig.json.
• apiKey and accessToken both provided: The Options type is a strict XOR; TypeScript will error and checkCredentials may behave unexpectedly — supply exactly one credential.
• Setting reserved headers: Passing Authorization or Content-Type in Options.headers has no effect; the library silently ignores them. Set credentials only via apiKey / accessToken.
• Node.js < 14: node-fetch v2 (the version used here) targets Node 14+; running on older runtimes will throw at runtime with obscure fetch errors — upgrade Node or polyfill fetch.
• ESM/CJS interop with node-fetch: If your project uses "type": "module", pin node-fetch to ^2.x (CJS build) or add "esModuleInterop": true in tsconfig.json to avoid default-import errors.
• Pagination — iterating beyond page 1: mollie.payments.list() returns a Page object; call page.nextPage() or use mollie.payments.iterate() to walk all records rather than slicing a single page.

Vibe-coding prompt template

I have dropped the Mollie API client source into `src/mollie/` in my project.
The integration guide is in `USAGE.md`. The upstream package is `@mollie/api-client@4.5.0`.

Please help me integrate it into my existing Node.js/TypeScript project step by step:

1. Read `USAGE.md` and `src/mollie/types.ts` to understand every public export.
2. Add a `src/mollie-client.ts` singleton that reads MOLLIE_API_KEY from process.env
   and exports a typed `MollieClient` instance.
3. Create a payment service (`src/services/payment.service.ts`) with methods:
   - `createPayment(orderId, amountEur)` → returns checkout URL string
   - `getPaymentStatus(paymentId)` → returns payment.status
   - `listPayments(cursor?)` → returns a Page of Payment objects
4. Add an Express webhook handler at POST /webhooks/mollie that calls getPaymentStatus
   and updates a local order record.
5. Show me every import path using the local `src/mollie/` source, not the npm package.
6. Add TypeScript types for all function parameters and return values using the
   exported types from `src/mollie/types.ts` (e.g. MollieClient, PaymentCreateParams).
7. Flag any tsconfig.json changes needed (resolveJsonModule, paths, etc.).

License and credit

The upstream project is released under the BSD 2-Clause License (see source/LICENSE if present, or the GitHub repository). This block is a redistribution of @mollie/api-client@4.5.0 published by Mollie B.V.. Refer to the upstream repository for the full license text and contributor list.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Square TypeScript SDK for Node.js Payments

eCommerce, Marketplace & POS Systems

Free