Amounts

Summary

Amounts in Open Payments define monetary values using asset codes and asset scales. They provide a standardized way to represent money across different currencies and payment scenarios.

Amounts represent monetary values and are fundamental to every Open Payments operation. Whether you’re creating an incoming payment, requesting a quote, or tracking payment progress, every amount consists of three key components: a numerical value, an assetCode, and an assetScale. Understanding these components is crucial for building Open Payments applications.

Debit and receive amounts

Before learning about amount components, you should understand the difference between debit and receive amounts.

• Debit amount - The total amount that a sender will be charged, in their asset/currency, with the completion of an outgoing payment
• Receive amount - The amount that will be paid into the recipient’s account in their asset/currency

Values

The first component that makes up an amount is a numerical value.

To maximize precision and avoid rounding errors in financial calculations, Open Payments uses numerical data types without decimals to represent values. In the context of programming languages, this means that Open Payments uses unsigned 64-bit integers for monetary amounts instead of floating-point numbers.

An example of a value is the number 10000.

Asset codes

The second component of an amount is an assetCode.

Asset codes identify the type of currency or asset being used in a payment and should follow the ISO 4217 standard for currency representation.

An example of an ISO 4217 assetCode is USD, which represents the US Dollar.

Asset scales

The third component of an amount is an assetScale.

An asset scale tells you how many decimal places a currency uses. It’s like specifying whether you’re counting in dollars, cents, or smaller units.

Asset scales are numbers between 0 and 255 that indicate decimal precision.

In the case of USD with an assetScale of 2, the display amount of $100.00 is stored and represented as 10000 cents.

Thus, the conversion formula is:

$\frac{\text{value}}{10^{\text{assetScale}}} = \text{display amount}$

Using the preceding example, the formula looks like this:

$\frac{10000}{10^2} = \frac{10000}{100} = \$100.00$

Examples by currency

Currency	Asset Code	Asset Scale	Integer Amount (Value)	Actual Value
US Dollar	USD	2	10000	$100.00
Euro	EUR	2	2550	€25.50
British Pound	GBP	2	3250	£32.50
Japanese Yen	JPY	0	1000	¥1000
Mexican Peso	MXN	2	18500	$185.00
Jordanian Dinar	JOD	3	1000	د.ا1.000
South African Rand	ZAR	2	1500	R15.00

Amounts in Open Payments

Using the three necessary components of value, assetCode, and assetScale, $100 USD would be represented in Open Payments using the following structure:

{
  "value": "10000",
  "assetCode": "USD",
  "assetScale": 2
}

This consistent structure enables multi-currency payments, precise calculations, and seamless integration between different ASEs ? Account servicing entity .