Handling Monetary Values in Our System

To ensure accuracy and consistency in all financial transactions, our system adopts a specific approach for representing monetary values: all values are treated as integers, where each unit represents the smallest currency sub-unit (the centavo for Brazilian Real).

For Brazilian Real (BRL), this means:

1 unit in the system = R$0.01 (one centavo)

100 units in the system = R$1.00 (one real)

Practical Examples

To illustrate how this conversion works in practice, see the table below:

Integer Value in System	Representation in BRL	Note
`1`	R$0.01	One centavo
`10`	R$0.10	Ten centavos
`55`	R$0.55	Fifty-five centavos
`100`	R$1.00	One real
`185`	R$1.85	One real and eighty-five centavos
`1234`	R$12.34	Twelve reais and thirty-four centavos
`10000`	R$100.00	One hundred reais
`150075`	R$1,500.75	One thousand five hundred reais and seventy-five centavos
`1000000`	R$10,000.00	Ten thousand reais

When sending or receiving monetary values through our API, always use this integer representation. Similarly, when displaying these values to the end-user, remember to format them correctly for Brazilian Real by dividing the integer value by 100 and applying appropriate currency formatting (e.g., two decimal places, using "R$" symbol for BRL).

Why We Use This Approach (Benefits)

Working with monetary values as integers (representing centavos or cents) is a recommended practice in software engineering for several important reasons:

Absolute Precision (Avoids Floating-Point Errors):
Computers can struggle to represent decimal fractions exactly using floating-point data types (like float or double). This can lead to small rounding errors that, over many transactions, can accumulate and cause significant financial discrepancies. Using integers completely eliminates this problem, as all operations are exact.

Simplicity in Mathematical Operations:
Integer arithmetic is inherently simpler and often more performant than floating-point arithmetic. Operations like addition, subtraction, and multiplication are straightforward and don't carry the risk of precision loss.

Consistency Across Systems:
It ensures that different parts of the system, or even different systems that integrate, interpret monetary values in the same way, preventing conversion or interpretation errors.

Ease of Storage and Indexing:
Databases handle integer data types very well. They are efficient for storing, indexing, and querying, which is crucial for financial systems.

Explicit Control Over Rounding:
By dealing with the smallest currency unit (like centavos), you have full control over how and when rounding should be applied, especially when converting the value for display or performing calculations involving complex divisions (such as interest or fee distribution).

Industry Standard:
Many financial institutions and payment platforms (like payment gateways) adopt this practice, which facilitates integration and interoperability.

Adopting this convention ensures that our financial system is robust, accurate, and reliable. If you have any questions about how to handle these values, please contact our support team.

Converting to Decimal for Display or Other Purposes

While our system stores and processes all monetary values as integers (representing centavos), you'll often need to convert this integer back into a decimal format for display to users, for reporting, or before sending to a third-party system that expects a decimal.

The conversion is straightforward: divide the integer amount by 100.

Here are some examples in common programming languages:

JavaScript

You can put other components inside Accordions.

Python

Java

Handling Monetary Values in Our System

Practical Examples#

Why We Use This Approach (Benefits)#

Converting to Decimal for Display or Other Purposes#

Practical Examples

Why We Use This Approach (Benefits)

Converting to Decimal for Display or Other Purposes