Square Basics

Working with Monetary Amounts

Understand how Square APIs work with money.

Tenders and money

Payments and refunds are represented as a set of tenders. A tender represents a discrete monetary exchange. Square represents this exchange as a money object with a specific currency in ISO 4217 format and an amount, where the amount is given in the smallest denomination of the given currency. For example, when the currency is USD, the amount is provided in cents.

Specifying monetary amounts

All monetary fields in Square APIs are represented by a Money object. For example:

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

The amount field is always in the smallest denomination of the currency indicated by currency_code. Businesses located in the United States or Canada can set monetary amounts as low as 1 cent. For example, the following structure sets a monetary amount of 50 cents USD:

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

Connect v1 versus Connect v2

In Connect v2, all monetary amounts are positive. Use the field name and data type to determine if the amount indicates a credit or debit against the Square account.

In Connect v1, monetary amounts may be positive or negative:

  • Monetary values are positive if they represent an increase in the amount of money an account receives (e.g., amounts related to collecting taxes and tips).
  • Monetary values are negative if they represent a decrease in the amount of money the merchant receives (e.g., amounts related to discounts and refunds).

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow