Mollie API Node.js SDK

You can install the Mollie Node.js API client using npm or yarn.

npm install @mollie/api-client

or

yarn add @mollie/api-client

When upgrading to v3.0.0, the primary change is the transition to a named factory function for client initialization.

CommonJS Initialization

Use createMollieClient from the package:

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

ESM/JavaScript Modules Initialization

import { createMollieClient, PaymentMethod } from '@mollie/api-client';

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

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

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

mollieClient.payments.create({
  amount: {
    currency: 'EUR',
    value: '10.00',
  },
  description: 'Order #478',
  method: PaymentMethod.ideal
});

To use the library, create a client instance using createMollieClient. You can use either ES Modules or CommonJS syntax. You must provide an apiKey for authentication.

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

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

The details property in PaymentData provides specialized information depending on the method used. Common detail structures include:

• CreditCardDetails: Includes cardHolder, cardNumber (last 4 digits), cardFingerprint, cardLabel, and failureReason for failed payments.
• IdealDetails: Includes consumerName, consumerAccount (IBAN), and consumerBic.
• PayPalDetails: Includes consumerName, consumerAccount (email), paypalReference, and sellerProtection status.
• BankTransferDetails: Includes bankName, bankAccount (IBAN), bankBic, and transferReference.
• BancontactDetails: Includes consumerName, consumerAccount, and qrCode for mobile scanning.

The PaymentData interface represents the core data object for a Mollie payment. It contains information about the payment's status, amount, method, and lifecycle timestamps.

Key properties include:

• mode: Indicates if the payment is live or test.
• status: The current state of the payment (e.g., authorized, paid, canceled).
• amount: An object containing the currency and value.
• method: The payment method used (e.g., ideal, creditcard, paypal).
• statusReason: Details about why a payment reached a specific status (primarily for point-of-sale).
• _links: A collection of URLs for interacting with the payment (e.g., checkout, dashboard, refunds).
• details: A polymorphic object containing method-specific information (e.g., CreditCardDetails, IdealDetails).

When fetching capture data, you can embed related resources using the embed query parameter. Use the CaptureEmbed enum to specify which resources to include.

Note: The CaptureInclude enum is deprecated. Use CaptureEmbed instead. Passing include to the Captures API has no effect.

// Use CaptureEmbed to include related resources like the payment
// Example usage in an API call (conceptual):
// client.captures.get('cap_123', { embed: CaptureEmbed.payment });

By default, the client throws an error if it detects a browser-like environment to prevent accidental credential exposure. If you have appropriate mitigations in place (such as using a short-lived, narrowly-scoped access token), you can bypass this check using the dangerouslyAllowBrowser: true option.

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

The Mollie API returns results in pages. To implement manual pagination, use the .page() method. This method returns a subset of objects and provides a nextPageCursor which is the ID of the first object on the next page. You can use this cursor in the from parameter of the subsequent call.

// 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.

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

Retrieve the current status of an existing payment using its ID with mollieClient.payments.get().

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

// Check payment.status.

Use mollieClient.payments.create() to initiate a new payment. You must provide the amount (with value and currency), a description, a redirectUrl (where the customer is sent after payment), and a webhookUrl (where Mollie sends status updates).

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().