Skip to main content

Amounts are integer strings

Every amount is an integer number of the currency’s minor unit (cents, pence, kobo), sent and returned as a string:
That’s US$1,250.00. Strings, not numbers, because JSON numbers lose precision above 253 in many languages, and an amount is the last place to find that out. Never parse an amount as a float. In Python, use int or Decimal:
To send £25.50, send "2550".

Currencies

Currencies are ISO 4217 codes, upper case. All the currencies you can hold have two decimal places: Recipients can be paid in other currencies too: destination requirements lists every corridor.

Balances

An account has three balances, all in its own currency: When you send a payment, the amount leaves available immediately and shows in pending until the payment completes or fails.

Exchange rates

When money changes currency, Talescria quotes both sides as integers: what leaves (amountFromMinorUnits) and what arrives (amountToMinorUnits). Those two amounts are the agreement. The rate (rateMicro, the rate × 1,000,000) is for showing people; multiplying one amount by it won’t reliably give you the other.

Timestamps

Timestamps such as createdAt, expiresAt and dueAt are milliseconds since the Unix epoch, in UTC. Calendar dates, such as a recurring series’ startDate, are YYYY-MM-DD.