La mayoría de desarrolladores de pagos descubren eventualmente las monedas sin decimales de la peor manera -- a través de un error. Nosotros lo descubrimos cuando un pago de prueba de 5.000 XOF apareció como $0,05 en el panel. Ese único error nos enseñó más sobre el manejo de monedas que cualquier documentación jamás podría.
¿Qué son las monedas sin decimales?
La mayoría de monedas tienen subunidades. El dólar estadounidense tiene centavos: $50,00 son 5.000 centavos. Pero algunas monedas no tienen subunidades. 5.000 XOF son simplemente 5.000 XOF. No hay "céntimos de CFA" en uso diario. Cuando pasas 5000 a un proveedor de pagos para XOF, quieres decir 5.000 XOF, no 50,00 XOF.
Esta distinción rompe todo sistema de pagos que asuma "dividir por 100 para mostrar".
El conjunto completo de monedas sin decimales
0fee.dev mantiene un conjunto definitivo de 17 monedas sin decimales que cubre XOF, XAF, GNF, UGX, TZS, RWF, BIF, DJF, KMF (africanas), JPY, KRW, VND (asiáticas), y CLP, ISK, PYG, VUV, XPF (otras).
Precisión float-a-int: int(round(...))
El error más insidioso en el manejo de monedas es la precisión de punto flotante:
python# MAL: Conversión directa float-a-int
amount = 49.99
cents = int(amount * 100) # 4998! No 4999!
# BIEN: Redondear antes de truncar
amount = 49.99
cents = int(round(amount * 100)) # 4999El error de $0,05 (sesión 017)
Un pago de 5.000 XOF se mostraba como $0,05. La causa raíz: el monto estaba siendo dividido por 100 dos veces -- una al almacenar y otra al mostrar.
La gran purga de /100 (sesión 066)
La sesión 017 arregló el error inmediato de visualización, pero descubrimos en la sesión 066 que las divisiones erróneas por 100 se habían propagado por todo el código como un virus. La auditoría encontró divisiones incorrectas en almacenamiento de transacciones, gráficos del panel, cálculos de facturas, procesamiento de webhooks, cálculo de comisiones y exportación CSV.
Validación de entrada
La API valida montos según el tipo de moneda: las monedas sin decimales deben ser números enteros, las monedas estándar pueden tener máximo dos decimales. Una solicitud de 5000.50 XOF devuelve un error de validación claro en lugar de truncar silenciosamente.
Lecciones aprendidas
- Las monedas sin decimales no son casos límite. En África, son la norma. XOF y XAF solos cubren 14 países.
- El instinto de /100 es peligroso. En un sistema multidivisa, ese instinto debe ser reemplazado con una función consciente de la moneda.
- Atrápalo en el límite. Valida montos al ingerir por la API y normaliza inmediatamente.
- Audita regularmente. La purga de la sesión 066 encontró problemas que habían estado en producción durante semanas.
- Un conjunto, compartido en todas partes. El conjunto
ZERO_DECIMAL_CURRENCIESexiste idénticamente en Python y TypeScript.
Este artículo es parte de la serie "Cómo construimos 0fee.dev". 0fee.dev es un orquestador de pagos que cubre más de 53 proveedores en más de 200 países, construido por Juste Thales Gnimavo y Claude desde Abiyán sin ingenieros humanos. Sigue la serie para conocer la historia completa de la construcción.