Square Connect API List Payments Endpoint not showing 'Description'

Question

In the example response for the List Payments endpoint in the Square Connect API Documentation, it shows 'Description' as a returned key, but the data I am receiving from Square does not show that key.

I have verified that the payments do have a Description attached to them (by downloading the transaction report from the Square Dashboard).

Answer 1

Thanks for identifying this inconsistency between the documentation and the API. The Payment object does not in fact have a description field.

However, the following fields included in a Payment object do contain merchant-specified notes about a payment (assuming the merchant provided them at the time of sale):

• The payment_note field of a Payment’s tender contains a merchant-specified note about the form of tender used for the payment. This is generally present only for Tender objects with a type of OTHER.

• The notes field of a PaymentItemization in a Payment contains a merchant-specified note about that particular item in the payment. Note that PaymentItemizations are only available from the Retrieve Payment endpoint (not List Payments).

The Description column of the transaction report provided by the merchant dashboard is simply a comma-separated list of the names of the items included in the payment, along with any notes for each item. The Connect API does not provide this list directly, but you can recreate it for a payment with the fields of the payment’s itemizations.