Square Data Model

Payments and refunds

To understand money movement in the Square data model, you will need to understand the data types used to model payments and refunds. This section will walk you through the Connect v2 concepts of transactions, tenders, money, and refunds.

Payments and refunds are modeled as elements of a transaction and 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 and 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.

Multiple tenders in a single transaction are differentiated based on their type and the associated tender details. The specifics of the tender details depends on the associated tender type. For example, the details for a cash tender are the total amount of cash provided and any change returned. But credit card tenders include information about the type of card used and how the card information was captured.

Payments

Individual tenders are not payments. Every transaction has a single payment modeled as a set of tenders. For example, consider the case where a customer visits one of the physical locations for Raphael's Puppy-Care Emporium and pays at the register with:

  • a gift card worth 30 USD.
  • 10 USD in cash they happen to have in their pocket.
  • 20 USD with a credit card.
Basic transaction

Even though it represents a single payment, the transaction object includes 3 distinct tenders.

A single payment may also have multiple tenders of the same type but different details. For example, if a customer pays for everything by spreading the total across 3 different cards, the transaction will have 3 distinct tenders even though they are all credit cards. Online payments typically have a single tender because the customer pays for the entire order at once. But in-person payments made through a point of sale can, and often do, have multiple tenders.

Refunds

Refunds are also built on tenders. Square models refunds as the full or partial repayment of one or more tender used in the transaction. Since transactions can have multiple payment tenders, they can also have multiple refunds. But each refund must be tied to a specific payment tender.

For example, if the customer mentioned previously decides to return one of the items for 5 USD in cash, the store can issue a cash refund and link it to the original cash tender of 10 USD.

Transaction refund

The amount and type of a refund is limited by the amount and type of the associated tender. The tender for an individual return must be the same type as the original transaction tender. And the amount of the refund cannot exceed the original tendered amount minus the amounts of any earlier refunds on that tender.

Prev
< Business entities and locations
Next
Customers and cards on file >

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