Working with Monetary Amounts

Learn how the Square API model works with monetary amounts.

Link to section

Money

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.

Link to section

Specifying monetary amounts

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:

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

{
  "amount": 400, 
  "currency_code": "USD"
}

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

{
  "amount": 50,
  "currency_code": "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:

{
  "amount": 2,
  "currency_code": "JPY"
}

Link to section

Monetary amount limits

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.

Link to section

About the EXPECTED_INTEGER error code

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. For more information, see Payment Minimums.

Link to section

See also

• Common Data Types