Valores monetários

Todo valor em dinheiro é um número inteiro, em centavos. Nunca número com vírgula ou ponto, nunca texto.

Os campos de dinheiro terminam em Cents (amountCents, feeCents, netAmountCents…), pra não haver dúvida. A moeda é sempre BRL.

Por que centavos

Computador erra conta com número quebrado: 0.1 + 0.2 dá 0.30000000000000004. Em dinheiro, esse erro vira centavo sobrando ou faltando. Com inteiro em centavos a conta é sempre exata.

Convertendo

De reais pra centavos (antes de mandar pra API): multiplique por 100 e arredonde.

const amountCents = Math.round(150.5 * 100); // 15050

O arredondamento não é opcional: 19.99 * 100 dá 1998.9999999999998, e sem Math.round você mandaria um valor errado (ou um número quebrado, que a API recusa).

Se o valor vem de um campo digitado, como "1.234,56", o caminho mais seguro é tirar tudo que não é dígito:

const amountCents = Number('1.234,56'.replace(/\D/g, '')); // 123456

(Vale quando o texto tem sempre duas casas depois da vírgula.)

De centavos pra reais (pra mostrar na tela): divida por 100 só na hora de exibir.

const text = (15050 / 100).toLocaleString('pt-BR', { style: 'currency', currency: 'BRL' }); // "R$ 150,50"

Boas práticas

• Guarde e some em centavos. Converta pra reais só pra mostrar.
• Ao dividir um valor (parcelas, rateio), divida em centavos e decida pra onde vai o centavo que sobra. R$ 100,00 em 3 partes são 3333 + 3333 + 3334, não três vezes 33.33.
• No banco de dados, use coluna de número inteiro.

Percentuais

Só os percentuais do split não são centavos: vão como número com até 2 casas decimais. percentage: 10.5 quer dizer 10,5 %.