@mollie/api-client

v4.6.0

Published

5 days ago

Official Mollie API client for Node

Mollie Node.js API Example

About

Mollie builds payment products, commerce solutions and APIs that let you accept online and mobile payments, for small online stores and Fortune 500s alike. Accepting credit and debit card (Cartes Bancaires, PostePay), Alma, Apple Pay, BACS Direct Debit, BANCOMAT Pay, Bancontact, SEPA Bank Transfer, Belfius Pay Button, Billie, BLIK, SEPA Direct Debit, EPS, iDEAL (in3), KBC Payment Button, Klarna (Pay Later, Pay Now, Pay in 3, Financing), [Pay By Bank] paybybank PayPal, paysafecard, Przelewy24, Riverty, Satispay, Trustly, TWINT, eco- gift- and meal vouchers and gift cards online payments without fixed monthly costs or any punishing registration procedures. Just use the Mollie API to receive payments directly on your website or easily refund transactions to your customers.

A note on use outside of Node.js

This library runs on any server-side JavaScript runtime that provides fetch and Node-compatible APIs — Node.js, Bun, and Deno, as well as edge runtimes such as Cloudflare Workers (with the nodejs_compat flag and a recent compatibility date). See Requirements for the versions tested in CI.

On Deno, use the named import — import { createMollieClient } from "npm:@mollie/api-client" — rather than a default import, which Deno's CommonJS interop does not yet expose as callable.

What it is not meant for is the browser. In the typical setup you make calls to the Mollie API ‒ through one of our libraries ‒ from your server, where your credentials sit safely out of reach of the outside world. If you were to include this library in a website or mobile app, your credentials would be shipped to your users, who could then act on your behalf.

To prevent this, the client throws when it detects a browser-like environment. If you understand the risk and have appropriate mitigations in place (for example a short-lived, narrowly-scoped access token rather than a full API key), you can bypass the check with the dangerouslyAllowBrowser option:

const mollieClient = createMollieClient({ apiKey: 'test_...', dangerouslyAllowBrowser: true });

Requirements

This library runs on any server-side JavaScript runtime with fetch and Node-compatible APIs. The following are verified in CI:

Node.js 14 or greater.
Bun 1.0 or greater.
Deno 2.0 or greater.

It also runs on edge runtimes such as Cloudflare Workers, provided the nodejs_compat compatibility flag is enabled and a compatibility date of 2025-08-15 or later is set.

You will also need:

A free Mollie account.
Your API keys, which you can find on your dashboard.

In order to accept payments in live mode, payment methods must be activated in your account. Just follow a few steps and let us handle the rest.

Installation

Using npm:

npm install @mollie/api-client

Using yarn:

yarn add @mollie/api-client

Manual installation

Alternatively, you may use git clone or download an archive.

Getting started

Build the client.

Using JavaScript modules:

import createMollieClient from '@mollie/api-client';

const mollieClient = createMollieClient({ apiKey: 'test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM' });

CommonJS-style:

const { createMollieClient } = require('@mollie/api-client');

const mollieClient = createMollieClient({ apiKey: 'test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM' });

Using an OAuth access token

When authenticating with an OAuth access token instead of an API key, most requests expect a profileId, and you opt into test mode with testmode. Rather than passing these on every call, you can configure them once as parameterDefaults. They are applied to every request that accepts them, unless the individual call specifies its own value (per-call values always take precedence):

const mollieClient = createMollieClient({
  accessToken: 'access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ',
  parameterDefaults: {
    profileId: 'pfl_zcfJRjkf6P',
    testmode: true,
  },
});

parameterDefaults is only available together with an accessToken. With an API key the profile and mode are fixed by the key itself, so the Mollie API rejects these parameters.

Create a new payment

const payment = await mollieClient.payments.create({
  amount: {
    value:    '10.00',
    currency: 'EUR'
  },
  description: 'My first API payment',
  redirectUrl: 'https://yourwebshop.example.org/order/123456',
  webhookUrl:  'https://yourwebshop.example.org/webhook'
});

// Forward the customer to payment.getCheckoutUrl().

When the payment is made by your customer, Mollie will send you a webhook (to the URL specified as webhookUrl) informing your server about the status change of the payment.

Check the status of a payment

const payment = await mollieClient.payments.get('tr_8WhJKGmgBy');

// Check payment.status.

Pagination and iteration

Composing one long list of all payments, orders, or customers would be too much work for the Mollie API. Furthermore, such a list could be too large for your server to process. For this reason, the Mollie API only returns a subset of the requested set of objects. In other words, the Mollie API chops the result of a certain API endpoint call into pages.

If you are designing a paginated view, you can use the page methods to retrieve one page at a time:

// Retrieve the first 15 payments.
const payments = mollieClient.payments.page({ limit: 15 });

// payments.nextPageCursor is the cursor: the ID of the first payment on the next page.

Later:

// Retrieve the second 15 payments (using the cursor from the previous page).
const payments = mollieClient.payments.page({ limit: 15, from: 'tr_8WhJKGmgBy' });

The page methods do not fit every use case. If you find yourself retrieving multiple pages to perform a single action, consider using the iterate methods instead:

// Iterate over all payments.
for await (const payment of mollieClient.payments.iterate()) {
  // (Use break to end the loop prematurely.)
}

The iterate methods perform the requests to the Mollie API for the objects you need. The following example will work regardless of whether the 10 resulting payments appear on the first page or are distributed across different pages:

// Find the 10 most recent euro payments over €100.00.
const payments = mollieClient.payments.iterate()
  .filter(({ amount }) => amount.currency == 'EUR' && parseFloat(amount.value) > 100)
  .take(10);

Guides

For a deep dive in how our systems function, we refer to our excellent guides. These guides provide a complete overview of the Mollie API and cover specific topics dealing with a number of important aspects of the API.

API reference

This library is a wrapper around our Mollie API. Some more specific details are better explained in our API reference, and you can also get a better understanding of how the requests look under the hood.

Migrating

See the migration guide if you are migrating from an older version of the library.

Contributing

Want to help us make our API client even better? We take pull requests, sure. See CONTRIBUTING.md for development setup, our commit conventions, and the release process.

But how would you like to contribute to a technology oriented organization? Mollie is hiring developers and system engineers. Check out our vacancies or get in touch.