Mollie Getting Started: Account, API Keys, First Payment (2026)

Getting started overview

Integrating with Mollie involves a sequence of steps designed to enable payment processing for online businesses. The process begins with account creation and verification, followed by obtaining API keys necessary for authenticating requests to the Mollie API. Developers then use these keys to send payment requests, manage transactions, and handle asynchronous events via webhooks. Mollie's API is RESTful, supporting various payment methods and enabling features such as recurring payments and payment links Mollie API reference introduction. The platform also provides SDKs for common programming languages to streamline integration.

This guide outlines the essential steps to get a basic Mollie integration operational, from setting up an account to executing a first test payment. It focuses on the core components required for a functional setup, enabling developers to quickly initiate payment flows.

Quick Reference Guide

Create an account and get keys

The initial step for any Mollie integration is creating a merchant account and configuring your business profile. This process establishes your entity within Mollie's system and enables access to the necessary API credentials.

1. Sign Up for a Mollie Account

Navigate to the Mollie sign-up page and complete the registration form. You will need to provide basic business information, including your company name, email address, and country of operation. Mollie requires verification of your business to comply with financial regulations, which may involve submitting identification documents and bank account details Mollie pricing and account information.

2. Complete Your Website Profile

After creating your account, log in to the Mollie Dashboard. Go to Settings > Website profiles. Here, you'll create or edit a website profile associated with your integration. This profile includes details such as your website URL, industry, and contact information. Activating a website profile is crucial, as it determines which payment methods are available and is linked to your API keys.

3. Retrieve API Keys

Mollie uses API keys for authenticating requests. There are two types of API keys: test API keys and live API keys. Test keys are used in the development and staging environments and do not process real money. Live keys are used for production environments and handle actual transactions.

1. From the Mollie Dashboard, navigate to Developers > API keys.
2. You will find both a Test API key (starting with test_) and a Live API key (starting with live_).
3. Copy the Test API key. This key will be used for your first request. Keep your live API key secure and never expose it in client-side code.

Mollie's API keys function as bearer tokens. When making an API request, you include the key in the Authorization header, formatted as Bearer test_YOUR_API_KEY or Bearer live_YOUR_API_KEY Mollie API authentication details. This method is a common practice for securing RESTful APIs, similar to how other payment gateways like Stripe handle API authentication Stripe API keys documentation.

Your first request

To confirm your setup is correct, you can make a simple API call to create a test payment. This example uses cURL, but you can adapt it to any HTTP client or a Mollie SDK.

Prerequisites

• Your Mollie Test API key.
• A command-line interface with cURL installed, or a programming language environment with a Mollie SDK installed.

Example: Create a Test Payment with cURL

This cURL command creates a payment for €10.00 using the iDEAL payment method. Replace test_YOUR_API_KEY with your actual Test API key.

curl -X POST \
  https://api.mollie.com/v2/payments \
  -H 'Authorization: Bearer test_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": {
      "currency": "EUR",
      "value": "10.00"
    },
    "description": "Order #12345",
    "redirectUrl": "https://example.com/return",
    "webhookUrl": "https://example.com/webhook",
    "method": "ideal"
  }'

Upon successful execution, the API will return a JSON object representing the created payment, including a _links.checkout.href URL. You can visit this URL in a browser to simulate completing the payment through Mollie's hosted payment page in test mode. The webhookUrl specifies where Mollie will send notifications about payment status changes, such as when the payment is completed or failed Mollie create payment API reference.

Example: Create a Test Payment with Node.js SDK

First, install the Mollie Node.js SDK:

npm install @mollie/api-client

Then, use the following code:

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

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

async function createTestPayment() {
  try {
    const payment = await mollieClient.payments.create({
      amount: {
        currency: 'EUR',
        value: '10.00',
      },
      description: 'Order #12345',
      redirectUrl: 'https://example.com/return',
      webhookUrl: 'https://example.com/webhook',
      method: 'ideal',
    });

    console.log('Payment created:', payment.id);
    console.log('Checkout URL:', payment._links.checkout.href);
  } catch (error) {
    console.error('Error creating payment:', error);
  }
}

createTestPayment();

This Node.js example performs the same action as the cURL command. The SDK abstracts the HTTP request details, providing a more programmatic interface for interacting with the Mollie API Mollie Node.js SDK documentation.

Common next steps

After successfully making your first test payment, several next steps are typically involved in building a complete Mollie integration:

1. Implement Webhook Handling

Mollie uses webhooks to notify your application of asynchronous events, such as payment status changes (e.g., from open to paid, failed, or canceled). It's critical to implement a robust webhook endpoint that can receive and process these notifications. Your webhook endpoint should:

• Be publicly accessible.
• Return a 200 OK HTTP status code to acknowledge receipt.
• Verify the authenticity of the webhook by checking the X-Mollie-Signature header or by fetching the payment status directly from Mollie using the id provided in the webhook payload Mollie webhook guide.

For security, it's recommended to fetch the payment object using the provided ID rather than relying solely on the data in the webhook payload, as webhook data can be spoofed. This practice ensures data integrity, a principle also highlighted in general webhook security guidelines Twilio webhook security guide.

2. Integrate Payment Methods

Mollie supports a wide range of payment methods. You can enable and configure these in your Mollie Dashboard under Settings > Payment methods. To offer specific payment methods to your customers, you can either:

• Redirect customers to Mollie's hosted checkout page (as shown in the first request example).
• Build a custom checkout flow using the Mollie API to list available methods and create payments specific to each method Mollie get all methods API.

3. Handle Refunds and Chargebacks

As part of a complete payment integration, you will need to manage refunds and potentially handle chargebacks. The Mollie API provides endpoints for initiating refunds on processed payments Mollie create refund API. Understanding Mollie's policies and procedures for chargebacks is also important for mitigating risks and managing disputes.

4. Go Live

Once your integration is thoroughly tested with test API keys and you are confident in its functionality, you can switch to your Live API key. Before going live, ensure your Mollie account is fully verified and all required business information is submitted and approved. This typically involves a final review by Mollie to ensure compliance with financial regulations.

Troubleshooting the first call

When making your first API call to Mollie, you might encounter issues. Here are common problems and their solutions:

1. Invalid API Key

Symptom: API returns an authentication error (e.g., 401 Unauthorized or 403 Forbidden).

Solution:

• Check the key: Ensure you are using the correct test_ API key for your test environment. Double-check for typos or leading/trailing spaces.
• Bearer token format: Verify the Authorization header is correctly formatted as Bearer YOUR_API_KEY.
• Key type: Make sure you're not accidentally using a live_ API key in the test environment, or vice-versa, as they are distinct.

2. Incorrect Request Body or Headers

Symptom: API returns a 422 Unprocessable Entity or other client-side error with a message about invalid parameters.

Solution:

• Content-Type: Ensure the Content-Type header is set to application/json for requests with a JSON body.
• JSON format: Validate your JSON payload for syntax errors (e.g., missing commas, incorrect quotes). Online JSON validators can be helpful.
• Required fields: Check the Mollie API reference for the specific endpoint you are calling Mollie API reference to ensure all mandatory fields (e.g., amount, description, redirectUrl) are present and correctly formatted.

3. Network Issues or SSL Errors

Symptom: Request fails to reach Mollie's servers, or you receive an SSL certificate error.

Solution:

• Connectivity: Verify your internet connection.
• Firewall/Proxy: If you are behind a corporate firewall or proxy, ensure it allows outgoing HTTPS connections to api.mollie.com.
• SSL Certificates: Ensure your system's root certificates are up-to-date. This is less common but can cause issues with secure connections.

4. Unexpected Payment Status

Symptom: A payment is created, but its status doesn't change as expected after simulation.

Solution:

• Webhook URL: Confirm your webhookUrl is correct and publicly accessible. Test your webhook endpoint using a tool like ngrok during development.
• Webhook processing: Ensure your webhook endpoint correctly processes the incoming Mollie notification and fetches the payment status.
• Test payment simulation: For payments created in test mode, you must manually visit the _links.checkout.href URL and simulate the payment flow to change its status.

Mollie provides detailed error messages in its API responses. Always inspect the status code and the detail field in the JSON response for specific guidance on what went wrong Mollie error handling guide. Consulting the official Mollie documentation for the specific API endpoint you are using can provide further clarity on expected parameters and error codes.