As part of Mollie's efforts to improve the reliability and security of our systems, we are working on unifying our API resource identifiers under a new standard - payment and order identifiers are next in line.
What’s evolving?
Historically, our API identifiers consisted of 10 characters or less (excluding the prefix, example: tr_XYZXYZXYZX). Since the beginning of the year, we've been upgrading these legacy identifiers to a longer format, adding an additional 4 to 12 characters.
Newer resources - like Captures and Payment Links - were introduced using this extended format from the start. Refunds, an older resource, were recently updated to adopt the new format.
Next, this change will apply to our most critical resources: Payments (Create Payment -> Response -> ID) and Orders (Create Order -> Response -> ID).
What does this mean for you?
If you are using one of our prebuilt integrations, like WooCommerce, Shopify, or Magento 2, you should see no impact from this change. We reviewed these integrations and haven't identified any compatibility issues.
However, if you have a custom-built integration with Mollie and/or additional downstream integrations that handle these payment references (for example, ERP, order management, or accounting systems), please take a moment to review the following:
- Database storage: If you store these identifiers, ensure the field length isn't limited to just 10 characters. We recommend a field length of at least 40 characters or more for future-proofing.
- Custom validation: Make sure that any custom identifier validation you have can accommodate the longer format. We recommend that if you decide to validate the token format, you only check that the prefix matches your expectations and avoid validating the remainder of the token.
This update shouldn't disrupt payment processing, but incorrect handling of the new identifiers could lead to mismatches. You can find further information about the new standard here.
Prepare for a test transaction:
We will perform a single test transaction on each unique profile/user_agent/client_id combination using the new API identifiers on 5 June, starting at 2 am CET. Therefore we route the first transaction being made to use the new token format. All subsequent transactions will use the old standard again, until we start the roll-out on June 12th.
If any issues arise after this test, we’ll give you the choice to temporarily opt out from the change. We’ll email you a form regarding the opt-out on 6 June.
Troubleshooting
In case your systems unexpectedly do have issues handling the new token format, you can manage the transaction (ex. cancel/refund/capture) manually in your Mollie Dashboard by navigating to Orders/Sales, selecting the relevant transaction and performing the desired action there.
Note: We’re hosting a Q&A session on 2 June hosted on Discord. Additionally, you can ask any questions in this Discord channel.
Timelines:
- June 2nd: Q&A session - Join us on Discord
- June 5th: Single Test Transaction per unique profile/user-agent/client_id combination
- June 6th: Follow up email, with option to temporarily opt out from the new token change
- June 12th: Beginning of gradual roll-out of new token format (excl. opt outs)
- July 8th: 100% roll-out of new token format (excl. opt outs)
-
December 31st: End of opt-out period, migration of all remaining profiles.