Official Mollie API client for Node


17363.5.14 months ago3 years agoMinified + gzip package size for @mollie/api-client in KB


Mollie API client for Node.js


This is the README of the v2 Node client. If you are looking for the README of v1 you should look here.


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 iDEAL, Bancontact/Mister Cash, SOFORT Banking, Credit Card, SEPA Bank transfer, SEPA Direct debit, PayPal, Belfius Direct Net, paysafecard, Gift Cards, Giropay, EPS and Apple Pay 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.


  • Payments: are the heart of the Mollie API: this is where most implementations start off.
  • Methods: show all the payment methods activated on the website profile. Also allows you to integrate iDEAL's bank selection screen into your own payment flow.
  • Refunds: allow you to make refunds in relation to a payment.
  • Customers: allow you to manage your customer's details.
  • Orders: allows you to use Mollie for your order management. Pay after delivery payment methods, such as Klarna Pay later and Klarna Slice it, require orders and cannot be used with payments.
  • Mandates: allow you to charge a customer's credit card or bank account recurrently.
  • Subscriptions: allow you to schedule recurring payments to take place at regular intervals.

A note on use outside of Node.js

This is a JavaScript library, a language which is universal by nature. While it is theoretically possible to include this library into a website or mobile app, it is not recommended to do so.

In the typical setup, you will make calls to Mollie ‒ through one of our libraries ‒ from your server (e.g. a Node.js server). Your API key sits safely on this server, out of reach to the outside world.

If you include this library in a website or app, however, your API key will be shipped to users. With this key, users will be able to act on your behalf.

Getting started


Mollie API client requires Node 6.14.x or higher to be installed.


To use the Mollie API client, the following things are required:

  • Get yourself a free Mollie account. No sign up costs.
  • Login to your Dashboard to get your API keys (live and test mode).
  • Now you're ready to use the Mollie API client in test mode.
  • 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.


Using npm:

npm install @mollie/api-client --save

Or using yarn:

yarn add @mollie/api-client

This will add @mollie/api-client to your project's dependencies.

You may also git checkout or download all the files, and include the Mollie API client manually.

Check the releases page to know which versions are available.

How to receive payments

To successfully receive a payment, these steps should be implemented:

  1. Use the client to create a payment with the requested amount, description, redirectUrl and webhookUrl and optionally, a payment method. It is important to specify a unique redirectUrl where the customer is supposed to return to after the payment is completed.

  2. After the payment is completed, our platform will send a request to the provided webhookUrl to allow the payment details to be retrieved, so you know exactly when to start processing the customer's order.

  3. The customer returns, and should be satisfied to see that the order was paid and is now being processed.


To be able to receive data from the API, an app should authenticate with a bearer token, referred to as API keys.

We've already prepared this step by creating a test and live key for you in your Dashboard.

Making your first request

Import the client and set your API key


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

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

Using JavaScript modules:

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

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

Create a new payment

  amount: {
    value:    '10.00',
    currency: 'EUR'
  description: 'My first API payment',
  redirectUrl: 'https://yourwebshop.example.org/order/123456',
  webhookUrl:  'https://yourwebshop.example.org/webhook'
  .then(payment => {
    // Forward the customer to the payment.getCheckoutUrl()
  .catch(error => {
    // Handle the error

Retrieve a payment

  .then(payment => {
    // E.g. check if the payment.isPaid()
  .catch(error => {
    // Handle the error

That's it!


Fetching all objects of a resource can be convenient. At the same time, returning too many objects at once can be unpractical from a performance perspective. Doing so might be too much work for the Mollie API to generate, or for your website to process. The maximum number of objects returned is 250.

If you want to programmatically browse through a list of objects, use the nextPage and previousPage methods.

    limit: 15
  .then(payments => {
    // "payments" contains the first 15 payments

    return payments.nextPage();
  .then(payments => {
    // "payments" contains the next 15 payments

To retrieve a list of 15 payments, starting with { id: 'tr_8WhJKGmgBy' }, add the first payment ID with the from parameter.

    limit: 15,
    from: 'tr_8WhJKGmgBy'
  .then(payments => {
    console.log(`First payment on next page will be: ${payments.nextPageCursor}`);


To help you get the most out of this client, we've prepared reference documentation, tutorials and other examples that will help you learn and understand how to use this library.


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 such as query parameters and pagination are better explained in our API reference, and you can also get a better understanding of how the requests look under the hood.

Migrating from v1.x

The API client v2.0 was a major rewrite, with some breaking changes. While the basic functionality stayed the same and the method names did not change, some function signatures have changed.

See the migration guide for more information.


Want to help us make our API client even better? We take pull requests.

Working at Mollie

Mollie is always looking for new talent to join our teams. We’re looking for inquisitive minds with good ideas and strong opinions, and, most importantly, who know how to ship great products. Want to join the future of payments? Check out our vacancies.


New BSD (Berkeley Software Distribution) License. Copyright 2013-2019, Mollie B.V.

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.