Dynamic Multibanco references in Drupal Commerce: Commerce ifthenpay 3.0 has arrived

In 2018 we released Commerce ifthenpay, the module that brought Multibanco references to Drupal Commerce. Seven years later, we are publishing version 3.0.0: the module's biggest evolution since then, with dynamic Multibanco references generated by the ifthenpay API, MB WAY payment retries and full support for Drupal 10 and 11.

The silent problem of locally generated references

A Multibanco reference has 9 digits, and the classic local generation algorithm reserves only 4 of them for the order number. It works perfectly up to order 9999. Beyond that, the number has to be compressed to fit, and this is where mathematics turns against the store.

Version 2.x mitigated the problem by spreading order numbers across 9000 possible combinations. It sounds like a lot, but the birthday paradox is relentless: around 112 simultaneously open references are enough for a 50% chance that two different orders share exactly the same reference. In a busy store, that means payments that can be matched to the wrong order, or never reconciled at all. Worst of all, the problem is invisible: everything seems to work, until the day a customer pays and their order stays "unpaid".

The solution: references generated by ifthenpay

Version 3.0.0 introduces a new mode on the Multibanco gateway: instead of computing the reference locally, the module requests it from the ifthenpay REST API, using the account's MB Key. The differences are structural:

  • The order number is sent in full (up to 25 characters): no truncation, no compression, no collisions;
  • Each transaction receives a unique identifier, and the payment confirmation is validated against it;
  • References can have an expiry date (from 1 day to 2 years), something impossible in local mode;
  • There is a sandbox environment to validate the integration without real transactions.

The local mode remains available for backwards compatibility, and open references generated the old way keep reconciling after the switch: stores migrate with no downtime window.

MB WAY: promise delivered, and then some

When we wrote about version 2.x, MB WAY was "future development". Version 3.0.0 closes the loop: besides push payments at checkout, customers can re-send the payment request from their order history without going through checkout again, and the store team can trigger a push directly from the backoffice. Fewer orders abandoned because a push expired on someone's phone.

Ready for Drupal's future

Version 3.0.0 supports Drupal 10 and Drupal 11, and Commerce 2.x and 3.x. The module now runs continuous integration on drupal.org, with more than 50 automated tests validating every change on both Drupal versions, and stable releases are covered by the community's security advisory policy.

If your store runs version 2.x, we recommend upgrading: the 2.x branch is no longer supported and does not include the protections against reference collisions.

composer require 'drupal/commerce_ifthenpay:^3.0'

Need help with payments in Drupal Commerce?

Bloomidea develops and maintains Commerce ifthenpay and has been building Drupal Commerce stores for the Portuguese market for more than a decade: Multibanco, MB WAY, cards, Stripe and PayPal, with ERP and logistics integrations. Talk to us about your project.

Ecommerce
Drupal