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:

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"
}

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

• Working with Dates
• Working with Addresses