Multibanco Offline Algorithm
Overview
Welcome to the MULTIBANCO OFFLINE ALGORITHM documentation.
If you need to perform the integration from scratch, here is the description of the algorithm for generating offline references. For integration via this process, you will need an entity code (5 numeric digits) and a sub-entity code (3 numeric digits) assigned by ifthenpay to the merchant.
In this Multibanco reference format, it is not possible to set expiration dates.
If you do not have these entity and sub-entity codes, please contact ifthenpay.
Before implementation, please verify if an existing integration is already available for your platform, whether developed by Ifthenpay, the platform provider, or a third party.
You can check the list of available plugins and their corresponding e-commerce platforms here. You can also check the list of integrations with invoicing software here.
ifthenpay offers free technical support to all customers through the following channels:
- Email: suporte@ifthenpay.com
- Phone: 808 222 777 | +351 227 660 871
- Helpdesk: submit a ticket
- Site: www.ifthenpay.com
Explanation
If you need to calculate our Multibanco references, we offer a step-by-step guide on the reference generation algorithm.
In the Multibanco system, customers use three sets of digits to make a payment: the Entity, the Reference, and the Amount.
|
Entity: 11604 Reference: 999 123 490 Amount: 25,86 € |
Payment via Multibanco or HomebankingThis box should be printed on the sales document (usually in the bottom left corner) or, in the case of e-commerce, displayed/printed by the browser and, preferably, also sent by email with the order details.
The payment deadline can also be displayed, but by default, it is transparent to the system, which will accept payments at any date, even after the specified date.
Multibanco terminals also accept, by default, the same reference for payment more than once, so handling duplicate payments should be managed administratively.
- Entity: The entity code will always have 5 digits and will be provided by ifthenpay.
- Amount: Amount with a maximum of 8 digits (excluding the decimal separator) in the format 000 000,00.
For whole values, always display two decimal places (e.g., 25,00 rather than just 25).
The Euro symbol (€) may or may not be included before the amount.
- Reference: The reference is always composed of 9 digits (grouped in sets of 3 for easier readability), and in our system, it is structured as follows: SSSDDDDCC
SSS: Three digits that identify the sub-entity (the merchant). This code is assigned by ifthenpay.
DDDD: ID - Four digits that identify the document/order number to be paid or the customer number (depending on whether you prefer to associate the payment with a document or a customer). This ID must have exactly 4 digits. If the document/order number or customer number has more than 4 digits, use only the 4 rightmost digits. If it has fewer than 4 digits, pad the remaining digits with zeros to the left.
CC: Two control digits (check-digits). They are used by the terminal to validate whether the information is correct. Note: If the control digit has only one digit, it must be formatted to two digits by padding with a leading zero.
In the example above:
• 11604 is the entity code;
• 999 is the sub-entity code;
• 1234 is the ID – document/order number to be paid or your customer number;
• 90 are the control digits;
• 25,86 € is the amount to be paid.
Control Digits
To calculate Control Digit you need to:
- Concatenate into a string: the 5 digits of the entity + the 3 digits of the sub-entity + 4 digits of the ID + the 8 digits of the amount (without the decimal separator and padding with leading zeros to make 8 characters).
In our example, this would be: 11604999123400002586 - Perform the following operation:
result =
51 x 1º dígito +
73 x 2º dígito +
17 x 3º dígito +
89 x 4º dígito +
38 x 5º dígito +
62 x 6º dígito +
45 x 7º dígito +
53 x 8º dígito +
15 x 9º dígito +
50 x 10º dígito +
5 x 11º dígito +
49 x 12º dígito +
34 x 13º dígito +
81 x 14º dígito +
76 x 15º dígito +
27 x 16º dígito +
90 x 17º dígito +
9 x 18º dígito +
30 x 19º dígito +
3 x 20º dígito
In our example: result = 51x1 + 73x1 + 17x6 + 89x0 + 38x4 + 62x9 + 45x9 + 53x9 + 15x1 + 50x2 + 5x3 + 49x4 + 34x0 + 81x0 + 76x0 + 27x0 + 90x2 + 9x5 + 30x8 + 3x6 = 2627
- Perform the following operation:
final_result = 98 – (result mod 97), where mod represents the remainder of the integer division.
In our example: final_result = 98 – (2627 mod 97) = 98 – 8 = 90
The control digits would then be 90.
Note: If the control digit had only one digit (e.g., 5), it should be formatted to two digits by padding with a leading zero (e.g., 05).
Payment of References
Immediately after a reference is generated (which is done offline), it can be paid at Multibanco terminals (or HomeBanking, Telemultibanco, or MBSpot) using the option for Payment of Purchases/Services (in the same way as utility bills such as electricity, water, gas, and telecommunications).
Note that you do not need to send the generated references to any web service of ifthenpay or SIBS. They simply need to be correctly calculated to be immediately payable.
Additionally, Multibanco references can only be paid for the amount for which they were generated (the amount is part of the calculation for the check-digits).
Testing References
Although the calculation of Multibanco references is relatively simple, test its functionality with different values and IDs using our validation application (available at https://backoffice.ifthenpay.com) in our Backoffice. Also, ensure that you are using the entity and sub-entity assigned to by ifthenpay>.
Implementation Examples
You can download examples of how to implement this algorithm in various programming languages, as well as modules for major e-commerce platforms, from the following link.
List of Payments
One way to automate the processing of completed payments is by retrieving them via a web service.
If you need to list payments, you can use this API
Whenever possible, especially on online platforms, you should use the callback method described here