Mollie Knowledge Patch

Mollie Knowledge Patch

Use this skill when implementing, reviewing, or updating Mollie integrations, API response models, generated SDKs, terminal pairing flows, settlement logic, or Mollie Components types.

Keep enum handling open to every value documented here. Preserve the exact literal identifiers and status values described by this patch.

Reference index

Apply compatibility changes first

Retire deprecated Mollie Components types

The old ComponentType values for Card and Express components in the private-beta Mollie.js v2 are deprecated. Those component types are being renamed ahead of public release.

Treat the old Card and Express values as deprecated. Do not invent replacement names from this guidance; it does not provide the new names.

See sdk-and-components.md for the exact scope of the deprecation.

Update Draft Transfers requests

The Draft Transfers API is available again and is generally available.

For Draft Transfers integrations:

• use pending-review instead of awaiting-initiation;
• limit account-holder names to 70 characters;
• provide a valid debtor IBAN; and
• provide a valid creditor IBAN.

Apply all four requirements together when updating a request path. See transfers-and-settlements.md.

Expand closed API enums

Do not reject these values in parsers or closed enums:

The balance-transaction API was already returning application-fee and payment-fee even though they had been omitted from the documentation.

Read api-values-and-terminals.md for balance transactions, locales, and card fee regions. Read transfers-and-settlements.md for settlement subtotal methods.

Preserve special settlement identifiers

The id returned by the open-settlement convenience endpoint is the literal open.

The id returned by the next-settlement convenience endpoint is the literal next.

Neither value is a normal settlement identifier. Models and validators for these convenience endpoints must therefore preserve their respective literal value rather than require a normal settlement identifier.

See transfers-and-settlements.md.

Handle terminal pairing-code outcomes

Requesting a terminal pairing code returns 403 when the organization is ineligible.

Revoked and expired pairing codes are retained for one month.

After a pairing code is permanently deleted:

• fetching it returns 404; and
• list responses omit it.

Keep the one-month retained state distinct from permanent deletion when handling fetch and list results.

See api-values-and-terminals.md.

Account for API limits and usage visibility

Mollie is introducing API rate limits. Integrations should account for those limits.

Mollie is also introducing a Mollie Web App section that exposes usage visibility. Integrations should monitor their usage there.

Do not turn this guidance into a specific numeric limit; no numeric limit is provided here.

See api-values-and-terminals.md.

Generate payment-method operations

The profile ID path parameter no longer uses a union schema for operations that enable or disable payment methods and payment-method issuers.

This change allows all four operations to be generated in language SDKs.

When reviewing generated SDK coverage, include the enable and disable operations for both payment methods and payment-method issuers.

See sdk-and-components.md.

Review checklist

Request construction

• Draft Transfers use pending-review, not awaiting-initiation.
• Account-holder names do not exceed 70 characters.
• Debtor and creditor IBANs are valid.

Response parsing

• Balance-transaction type accepts both added fee values.
• Settlement cost and revenue subtotal method accepts refund and chargeback.
• Locale handling accepts en_BE and en_NL.
• Card fee-region handling accepts visa-credit-consumer-inter.
• Open and next settlement endpoints preserve open and next as their respective id values.

Terminal behavior

• An ineligible organization can receive 403 when requesting a pairing code.
• Revoked and expired codes remain retained for one month.
• Permanently deleted codes return 404 on fetch and disappear from lists.

SDK and web integration

• Generated SDKs include all four enable/disable operations for payment methods and payment-method issuers.
• Old Card and Express ComponentType values in private-beta Mollie.js v2 are treated as deprecated.
• Integrations account for Mollie API rate limits.
• Usage is monitored in the Mollie Web App section that exposes usage visibility.

Scope discipline

Use the exact values and behaviors above. Where this patch does not state a replacement name, numeric limit, or additional response behavior, leave that detail unspecified rather than deriving it from adjacent API behavior.

Open the topic reference before changing code in that area; the references separate request rules, response values, endpoint lifecycle behavior, and SDK or component changes.