Learn how the Square API model works with monetary amounts.
Build Basics

Working with Monetary Amounts

Learn how the Square API model works with monetary amounts.

Payments and refunds represent discrete monetary exchanges. Square represents the exchange as a Money object with a specific currency in ISO 4217 format and a positive or negative amount.

In the Money object, the amount field indicates the amount in the base unit of the currency. The following table lists currencies and base units, with an example of each:

CurrencyBase unit
AUDCent (amount 100 in the Money object indicates $1.00)
CADCent (amount 100 in the Money object indicates $1.00)
JPYYen (amount 100 in the Money object indicates ¥ 100)
GBPPence (amount 100 in the Money object indicates £1.00)
USDCent (amount 100 in the Money object indicates $1.00)
EURCent (amount 100 in the Money object indicates 1.00 EUR)

For example, the following Money object represents 400 cents ($4.00 USD):

The following Money object represents an amount of $0.50 USD:

Currencies such as the Japanese Yen are known as zero-decimal currencies. That is, the smallest unit of the currency is ¥1 (1 JPY). For example, the following JSON represents an amount of ¥2:

The minimum payment amount you can specify in CreatePayment or UpdatePayment requests varies depending on the payment source. For more information, see Monetary amount limits.

When working with the Money object, applications might get an EXPECTED_INTEGER error code because the specified amount value is invalid. It indicates that Square was expecting information as an integer but was sent something else (for example, a string or a float). To resolve this error:

  • Make sure the amount value is specified in the smallest denomination of the currency used. For example, the smallest currency denomination for USD is cents.

  • Make sure the amount value is specified as a positive integer.

  • Make sure the amount value is greater than, or equal to, the valid minimum amount. Valid minimums are determined by the Location.country associated with the account:

    • The United States and Canada. amount values must be integers greater than or equal to 1.

    • Australia, Japan, and the United Kingdom. amount values must be integers greater than or equal to 100.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.