Mollie API TypeScript SDK

1.5.2 · active · verified Sun Apr 19

This is the official TypeScript SDK for interacting with the Mollie Payments API, providing a type-safe and developer-friendly interface. It is currently at version 1.5.2 and maintains a rapid release cadence, with updates often published multiple times a week. The SDK is automatically generated using the Speakeasy CLI based on the Mollie OpenAPI specification, ensuring it stays up-to-date with the latest API changes. Key differentiators include full TypeScript support for robust development, explicit handling for authentication via API keys, organization access tokens, or OAuth, and built-in features like idempotency keys, custom User-Agent headers, pagination helpers, and automatic retry mechanisms. It supports both CommonJS and ES Modules runtimes for broad compatibility.

Common errors

```
Error: Unauthorized
```
cause The API request failed due to missing, invalid, or insufficient authentication credentials (API key, organization access token, or OAuth token).

fix Verify that your `security` configuration when initializing the `Client` is correct and that the associated environment variable (e.g., `CLIENT_ORGANIZATION_ACCESS_TOKEN`) holds a valid, active token with the necessary permissions.
```
TypeError: client.payments.create is not a function
```
cause Attempting to call an API method that does not exist on the current `Client` instance, often due to an outdated SDK version or a typo in the method name.

fix Update the `mollie-api-typescript` package to the latest version using `npm update mollie-api-typescript` or `yarn upgrade mollie-api-typescript`. Double-check the SDK documentation for the correct method names and casing.
```
Property 'storeCredentials' does not exist on type 'PaymentRequest'.
```
cause This TypeScript error indicates that a property (e.g., `storeCredentials`) you are trying to use in a request object is not defined in the SDK's type definitions for that version, likely because it's a new API feature.

fix Update `mollie-api-typescript` to the latest version. New API features and corresponding request/response properties are added as the SDK is generated from the most recent OpenAPI specification.
```
ReferenceError: process is not defined
```
cause The code is attempting to access `process.env` (a Node.js global) in a browser or other non-Node.js environment where `process` is not available.

fix When running in a browser environment, configure your build tools (e.g., Webpack, Rollup, Parcel, Vite) to provide a polyfill or substitute for `process.env`, or pass environment variables explicitly during the build process instead of relying on runtime access.

Warnings

breaking Breaking changes were introduced in v1.3.5 related to the settlements API. The `request.testmode` parameter was removed from `client.settlements.listPayments()`, `listCaptures()`, and `listRefunds()`, and the response structures (`response.Embedded.payments[]`, `captures[]`, `refunds[]`) were also changed.
Fix: Review the API documentation for the settlements endpoint and update your calls to remove the `testmode` parameter and adapt to the new response object structures. Regenerate types or update your code if you were relying on previous type definitions.
gotcha The SDK is automatically generated via Speakeasy CLI, meaning updates to the underlying Mollie OpenAPI specification can lead to new features, changes, or even breaking modifications being introduced in minor version bumps of the SDK. Developers should closely monitor release notes for changes, even when updating patch or minor versions.
Fix: Always review the SDK's `CHANGELOG.md` or release notes before updating, especially if you are using specific API endpoints that frequently evolve. Implement robust error handling and potentially API version pinning in critical production environments.
gotcha The SDK supports multiple authentication schemes: `apiKey` (HTTP Bearer for profile-specific access), `organizationAccessToken` (HTTP Bearer for organization-wide access), and `oAuth` (OAuth2 token). Misconfiguring or providing the wrong type of token can lead to authentication failures.
Fix: Ensure you are using the correct security scheme and providing the appropriate environment variable (e.g., `CLIENT_API_KEY` or `CLIENT_ORGANIZATION_ACCESS_TOKEN`) matching the type of access you require. Verify that the token has the necessary scopes for the API operations you are performing.
gotcha The SDK automatically handles pagination for list operations through async iterators (e.g., `for await (const page of result)`). If not used correctly, developers might only retrieve the first page of results or encounter unexpected behavior when iterating.
Fix: Always use the `for await...of` loop or explicitly handle the `nextPage()` method provided by the SDK's pagination helpers when dealing with list operations to ensure all available results are processed. Consult the SDK's usage examples for proper pagination patterns.

Install

npm install mollie-api-typescript npm
yarn add mollie-api-typescript yarn
pnpm add mollie-api-typescript pnpm

Imports

Client
wrong:
```
const { Client } = require('mollie-api-typescript');
```
correct:
```
import { Client } from 'mollie-api-typescript';
```
The primary entry point for interacting with the Mollie API. While CommonJS `require` is supported, ES Modules `import` is recommended for modern TypeScript/JavaScript development.
PaymentRequest
wrong:
```
import { PaymentRequest } from 'mollie-api-typescript';
```
correct:
```
import { components } from 'mollie-api-typescript';
```
Most type definitions, including request and response bodies like PaymentRequest, are typically nested under a 'components' or similar namespace within the SDK's generated types, rather than being top-level exports. You might need to explore the exact path depending on the SDK structure.
Balance
wrong:
```
import { Balance } from 'mollie-api-typescript';
```
correct:
```
import { components } from 'mollie-api-typescript';
```
Similar to PaymentRequest, complex types like Balance are usually found within nested namespaces in the generated types, not as direct named exports. Consult the SDK's type definitions for the exact path, e.g., 'components.schemas.Balance'.

Quickstart

This example initializes the Mollie client with an organization access token and fetches a paginated list of balances in EUR, demonstrating basic client setup and API interaction.

import { Client } from "mollie-api-typescript";

const client = new Client({
  testmode: false,
  security: {
    organizationAccessToken: process.env["CLIENT_ORGANIZATION_ACCESS_TOKEN"]
      ?? "",
  },
});

async function run() {
  try {
    const result = await client.balances.list({
      currency: "EUR",
      from: "bal_gVMhHKqSSRYJyPsuoPNFH",
      limit: 50,
      idempotencyKey: "123e4567-e89b-12d3-a456-426",
    });

    for await (const page of result) {
      console.log(page);
    }
  } catch (error) {
    console.error("Error fetching balances:", error);
  }
}

run();

view raw JSON →