{"id":11353,"library":"mollie-api-typescript","title":"Mollie API TypeScript SDK","description":"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.","status":"active","version":"1.5.2","language":"javascript","source_language":"en","source_url":"https://github.com/mollie/mollie-api-typescript","tags":["javascript","typescript"],"install":[{"cmd":"npm install mollie-api-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add mollie-api-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add mollie-api-typescript","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { Client } = require('mollie-api-typescript');","symbol":"Client","correct":"import { Client } from 'mollie-api-typescript';"},{"note":"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.","wrong":"import { PaymentRequest } from 'mollie-api-typescript';","symbol":"PaymentRequest","correct":"import { components } from 'mollie-api-typescript';"},{"note":"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'.","wrong":"import { Balance } from 'mollie-api-typescript';","symbol":"Balance","correct":"import { components } from 'mollie-api-typescript';"}],"quickstart":{"code":"import { Client } from \"mollie-api-typescript\";\n\nconst client = new Client({\n  testmode: false,\n  security: {\n    organizationAccessToken: process.env[\"CLIENT_ORGANIZATION_ACCESS_TOKEN\"]\n      ?? \"\",\n  },\n});\n\nasync function run() {\n  try {\n    const result = await client.balances.list({\n      currency: \"EUR\",\n      from: \"bal_gVMhHKqSSRYJyPsuoPNFH\",\n      limit: 50,\n      idempotencyKey: \"123e4567-e89b-12d3-a456-426\",\n    });\n\n    for await (const page of result) {\n      console.log(page);\n    }\n  } catch (error) {\n    console.error(\"Error fetching balances:\", error);\n  }\n}\n\nrun();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.3.5"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The API request failed due to missing, invalid, or insufficient authentication credentials (API key, organization access token, or OAuth token).","error":"Error: Unauthorized"},{"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.","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.","error":"TypeError: client.payments.create is not a function"},{"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.","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.","error":"Property 'storeCredentials' does not exist on type 'PaymentRequest'."},{"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.","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.","error":"ReferenceError: process is not defined"}],"ecosystem":"npm"}