Payments

Retrieves card payments processed through Square. Does not include cash or other non‑card tenders.

Table Specific Information

Select

The add-in uses the Square API to filter the results by the following columns and operators while the rest of the filter is executed client-side within the add-in.

Id supports the following operator: =.
CardLast4 supports the following operator: =.
CreatedAt supports the following operators: =, >=, <=, >, <.
LocationId supports the following operator: =.
TotalMoneyAmount supports the following operator: =.
UpdatedAt supports the following operators: =, >=, <=, >, <.
CardBrand supports the following operator: =.

Retrieve a single payment by providing a valid Id:

SELECT * FROM Payments WHERE Id = '5xNDT7Sd6qFHsLyKlugpZIqeV'

Filter by the creation date of a payment:

SELECT * FROM Payments WHERE CreatedAt > '2015-08-15'
SELECT * FROM Payments WHERE CreatedAt < '2015-08-15'

Insert

To create a payment, you must specify IdempotencyKey, SourceId, MoneyAmount, and MoneyCurrency.

INSERT INTO Payments (IdempotencyKey, SourceId, MoneyAmount, MoneyCurrency) VALUES ('390a7d22-49d6-4ff3-ae1e-755455d03b50', 'cnon:card-nonce-ok', 100, 'USD')

Update

A payment can be updated by providing the Id.

UPDATE payments SET IdempotencyKey = 'b741f5a5-c041-4bd6-9e79-dfefcf69c4b7', MoneyAmount = 200 , BuyerEmailAddress = '[email protected]' WHERE Id = '390a7d22-49d6-4ff3-ae1e-755455d03b50'

Columns


Name	Type	ReadOnly	Description
Id [KEY]	String	True	Unique Square‑assigned identifier for the payment. Used for refunds, disputes, or reporting.
MoneyAmount	Int64	False	The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents.
MoneyCurrency	String	False	The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.
AppFeeMoneyAmount	Int64	False	The amount the developer is taking as a fee for facilitating the payment on behalf of the seller.
AppFeeMoneyCurrency	String	False	The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.
ApprovedMoneyAmount	Int64	True	The initial amount of money approved for this payment. The amount the developer is taking as a fee for facilitating the payment on behalf of the seller.
ApprovedMoneyCurrency	String	True	The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.
BankAccountOwnershipType	String	True	The ownership type of the bank account performing the transfer. The allowed values are INDIVIDUAL, COMPANY, ACCOUNT_TYPE_UNKNOWN.
ACHDetailsAccountNumberSuffix	String	True	The last few digits of the bank account number.
ACHDetailsAccountType	String	True	The type of bank account performing the transfer. The allowed values are CHECKING, SAVINGS, UNKNOWN.
ACHDetailsRoutingNumber	String	True	The routing number for the bank account.
BankName	String	True	The name of the bank associated with the bank account.
BankAccountCountry	String	True	The two-letter ISO code representing the country the bank account is located in.
BankAccountFingerprint	String	True	Uniquely identifies the bank account for this seller and can be used to determine if payments are from the same bank account.
BankAccountStatementDescription	String	True	The statement description as sent to the bank.
BankAccountTransferType	String	True	The type of bank transfer method. The allowed values are ACH, UNKNOWN.
BillingAddressLine1	String	False	The first line of the address.
BillingAddressLine2	String	False	The second line of the address, if any.
BillingAddressLine3	String	False	The third line of the address, if any.
BillingAddressAdministrativeDistrictLevel1	String	False	A civil entity within the address's country. In the US, this is the state.
BillingAddressAdministrativeDistrictLevel2	String	False	A civil entity within the address's administrative_district_level_1. In the US, this is the county.
BillingAddressAdministrativeDistrictLevel3	String	False	A civil entity within the address's administrative_district_level_2, if any.
BillingAddressCountry	String	False	The address's country, in ISO 3166-1-alpha-2 format.
BillingAddressFirstName	String	False	Optional first name when it's representing recipient.
BillingAddressLastName	String	False	Optional last name when it's representing recipient.
BillingAddressLocality	String	False	The city or town of the address.
BillingAddressPostalCode	String	False	The address's postal code.
BillingAddressSubLocality	String	False	A civil region within the address's locality, if any.
BillingAddressSubLocality2	String	False	A civil region within the address's sublocality, if any.
BillingAddressSubLocality3	String	False	A civil region within the address's sublocality_2, if any.
BuyerEmailAddress	String	False	The buyer's email address.
Capabilities	String	True	Actions that can be performed on this payment. For example, EDIT_AMOUNT_UP, EDIT_AMOUNT_DOWN, EDIT_TIP_AMOUNT_UP, or EDIT_TIP_AMOUNT_DOWN.
CardDetailsApplicationCryptogram	String	True	For EMV payments, the cryptogram generated for the payment.
CardDetailsApplicationIdentifier	String	True	For EMV payments, the application Id identifies the EMV application used for the payment.
CardDetailsApplicationName	String	True	For EMV payments, the human-readable name of the EMV application used for the payment.
CardDetailsAuthResultCode	String	True	The status code returned by the card issuer that describes the payment's authorization status.
CardDetailsAVSStatus	String	True	The status code returned from the Address Verification System (AVS) check. The allowed values are AVS_ACCEPTED, AVS_REJECTED, AVS_NOT_CHECKED.
CardId	String	True	Unique Id for this card. Generated by Square.
CardBillingAddressLine1	String	True	The first line of the address.
CardBillingAddressLine2	String	True	The second line of the address, if any.
CardBillingAddressLine3	String	True	The third line of the address, if any.
CardBillingAddressAdministrativeDistrictLevel1	String	True	A civil entity within the address's country. In the US, this is the state.
CardBillingAddressAdministrativeDistrictLevel2	String	True	A civil entity within the address's administrative_district_level_1. In the US, this is the county.
CardBillingAddressAdministrativeDistrictLevel3	String	True	A civil entity within the address's administrative_district_level_2, if any.
CardBillingAddressCountry	String	True	The address's country, in ISO 3166-1-alpha-2 format.
CardBillingAddressFirstName	String	True	Optional first name when it's representing recipient.
CardBillingAddressLastName	String	True	Optional last name when it's representing recipient.
CardBillingAddressLocality	String	True	The city or town of the address.
CardBillingAddressPostalCode	String	True	The address's postal code.
CardBillingAddressSubLocality	String	True	A civil region within the address's locality, if any.
CardBillingAddressSubLocality2	String	True	A civil region within the address's sublocality, if any.
CardBillingAddressSubLocality3	String	True	A civil region within the address's sublocality_2, if any.
CardBin	String	True	The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API returns this field.
CardType	String	True	The type of the card. The Card object includes this field only in response to Payments API calls. The allowed values are UNKNOWN_CARD_TYPE, CREDIT, DEBIT.
CardholderName	String	True	The name of the cardholder.
CardCustomerId	String	True	The Id of a customer created using the Customers API to be associated with the card.
CardEnabled	Boolean	True	Indicates whether or not a card can be used for payments.
CardExpiryMonth	Int64	True	The expiration month of the associated card as an integer between 1 and 12.
CardExpiryYear	Int64	True	The four-digit year of the card's expiration date.
CardFingerprint	String	True	Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
CardLast4	String	True	The last 4 digits of the card number.
CardPrepaidType	String	True	Indicates whether the Card is prepaid or not. The Card object includes this field only in response to Payments API calls The allowed values are UNKNOWN_PREPAID_TYPE, NOT_PREPAID, PREPAID.
CardReferenceId	String	True	An optional user-defined reference Id that associates this card with another entity in an external system.
CardVersion	Int64	True	Current version number of the card. Increments with each card update.
CardTimelineAuthorizedAt	Datetime	True	The timestamp when the payment was authorized, in RFC 3339 format.
CardTimelineCapturedAt	Datetime	True	The timestamp when the payment was captured, in RFC 3339 format.
CardTimelineVoidedAt	Datetime	True	The timestamp when the payment was voided, in RFC 3339 format.
CardCVVStatus	String	True	The status code returned from the Card Verification Value (CVV) check. The allowed values are CVV_ACCEPTED, CVV_REJECTED, CVV_NOT_CHECKED.
CardDeviceId	String	True	The Square-issued Id of the device.
CardDeviceInstallationId	String	True	The Square-issued installation Id for the device.
CardDeviceName	String	True	The name of the device set by the seller.
CardEntryMethod	String	True	The method used to enter the card's details for the payment. The allowed values are KEYED, SWIPED, EMV, ON_FILE, CONTACTLESS.
RefundRequiresCardPresence	Boolean	True	Whether the card must be physically present for the payment to be refunded. If set to true, the card must be present.
CardStatementDescription	String	True	The statement description sent to the card networks.
CardStatus	String	True	The card payment's current state. The allowed values are AUTHORIZED, CAPTURED, VOIDED, FAILED.
CardVerificationMethod	String	True	For EMV payments, the method used to verify the cardholder's identity. The allowed values are PIN, SIGNATURE, PIN_AND_SIGNATURE, ON_DEVICE, NONE.
CardVerificationResults	String	True	For EMV payments, the results of the cardholder verification. The allowed values are SUCCESS, FAILURE, UNKNOWN.
CashBuyerSupplierMoneyAmount	Int64	False	The amount of money, in the smallest denomination of the currency indicated by currency.
CashBuyerSupplierMoneyCurrency	String	False	The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.
CashChangeBackMoneyAmount	Int64	True	The amount of change due back to the buyer. This read-only field is calculated from the amount_money and buyer_supplied_money fields.
CashChangeBackMoneyCurrency	String	True	The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.
CreatedAt	Datetime	True	The timestamp of when the payment was created, in RFC 3339 format.
CustomerId	String	False	The Customer Id of the customer associated with the payment.
DelayAction	String	False	The action to be applied to the payment when the delay_duration has elapsed. The allowed values are CANCEL, COMPLETE.
DelayDuration	String	False	The duration of time after the payment's creation when Square automatically applies the delay_action to the payment.
DelayedUntil	Datetime	True	The timestamp of when the delay_action is automatically applied, in RFC 3339 format.
ExternalDetailsSource	String	False	A description of the external payment source. For example, 'Food Delivery Service'.
ExternalDetailsType	String	False	The type of external payment the seller received. The allowed values are CHECK, BANK_TRANSFER, OTHER_GIFT_CARD, CRYPTO, SQUARE_CASH, SOCIAL, EXTERNAL, EMONEY, CARD, STORED_BALANCE, OTHER.
ExternalDetailsSourceFeeMoneyAmount	Int64	False	The fees paid to the source. The amount_money minus this field is the net amount seller receives.
ExternalDetailsSourceFeeMoneyCurrency	String	False	The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.
ExternalDetailsSourceId	String	False	An Id to associate the payment to its originating source.
LocationId	String	False	The Id of the location associated with the payment.
Note	String	False	An optional note to include when creating a payment.
OrderId	String	False	The Id of the order associated with the payment.
ProcessingFee	String	True	The processing fees and fee adjustments assessed by Square for this payment.
ReceiptNumber	String	True	The payment's receipt number. The field is missing if a payment is canceled.
ReceiptURL	String	True	The URL for the payment's receipt. The field is only populated for COMPLETED payments.
ReferenceId	String	False	An optional Id that associates the payment with an entity in another system.
RefundIds	String	True	A list of refund_ids identifying refunds for the payment.
RefundedMoneyAmount	Int64	True	The total amount of the payment refunded to date.
RefundedMoneyCurrency	String	True	The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.
RiskEvaluationCreatedAt	Datetime	True	Provides information about the risk associated with the payment, as determined by Square.
RiskEvaluationLevel	String	True	The risk level associated with the payment. The allowed values are PENDING, NORMAL, MODERATE, HIGH.
ShippingAddressLine1	String	False	The first line of the address.
ShippingAddressLine2	String	False	The second line of the address, if any.
ShippingAddressLine3	String	False	The third line of the address, if any.
ShippingAddressAdministrativeDistrictLevel1	String	False	A civil entity within the address's country. In the US, this is the state.
ShippingAddressAdministrativeDistrictLevel2	String	False	A civil entity within the address's administrative_district_level_1. In the US, this is the county.
ShippingAddressAdministrativeDistrictLevel3	String	False	A civil entity within the address's administrative_district_level_2, if any.
ShippingAddressCountry	String	False	The address's country, in ISO 3166-1-alpha-2 format.
ShippingAddressFirstName	String	False	Optional first name when it's representing recipient.
ShippingAddressLastName	String	False	Optional last name when it's representing recipient.
ShippingAddressLocality	String	False	The city or town of the address.
ShippingAddressPostalCode	String	False	The address's postal code.
ShippingAddressSubLocality	String	False	A civil region within the address's locality, if any.
ShippingAddressSubLocality2	String	False	A civil region within the address's sublocality, if any.
ShippingAddressSubLocality3	String	False	A civil region within the address's sublocality_2, if any.
SourceType	String	True	The source type for this payment. The allowed values are CARD, BANK_ACCOUNT, CASH, EXTERNAL, WALLET, BUY_NOW_PAY_LATER, SQUARE_ACCOUNT.
StatementDescriptionIdentifier	String	False	Additional payment information that gets added to the customer's card statement as part of the statement description.
Status	String	True	Indicates whether the payment is APPROVED, PENDING, COMPLETED, CANCELED, or FAILED. The allowed values are APPROVED, PENDING, COMPLETED, CANCELED, FAILED.
TipMoneyAmount	Int64	False	The amount designated as a tip.
TipMoneyCurrency	String	False	The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.
TotalMoneyAmount	Int64	True	The total amount for the payment, including amount_money and tip_money.
TotalMoneyCurrency	String	True	The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.
UpdatedAt	Datetime	True	The timestamp of when the payment was last updated, in RFC 3339 format.
VersionToken	String	False	Used for optimistic concurrency. This opaque token identifies a specific version of the Payment object.
TeamMemberId	String	False	An optional Id of the TeamMember associated with taking the payment.
ApplicationDetailsApplicationId	String	True	The Square Id assigned to the application used to take the payment.
ApplicationDetailsSquareProduct	String	True	The Square product, such as Square Point of Sale (POS), Square Invoices, or Square Virtual Terminal.
BuyNowPayLaterDetailsBrand	String	True	The brand used for the Buy Now Pay Later payment. The brand can be AFTERPAY, CLEARPAY or UNKNOWN. The allowed values are AFTERPAY, CLEARPAY, UNKNOWN.
BuyNowAfterPayEmailAddress	String	True	Email address on the buyer's Afterpay account.
BuyNowClearPayEmailAddress	String	True	Email address on the buyer's Clearpay account.
CardBrand	String	True	The card's brand. The allowed values are OTHER_BRAND, VISA, MASTERCARD, AMERICAN_EXPRESS, DISCOVER, DISCOVER_DINERS, JCB, CHINA_UNIONPAY, SQUARE_GIFT_CARD, SQUARE_CAPITAL_CARD, INTERAC, EFTPOS, FELICA, EBT.
SquareAccountPaymentSourceToken	String	True	Unique identifier for the payment source used for this payment.
SquareAccountErrors	String	True	Information about errors encountered during the request.
WalletDetailsBrand	String	True	The brand used for the WALLET payment. The brand can be CASH_APP, PAYPAY, ALIPAY, RAKUTEN_PAY, AU_PAY, D_BARAI, MERPAY, WECHAT_PAY or UNKNOWN. The allowed values are CASH_APP, PAYPAY, ALIPAY, RAKUTEN_PAY, AU_PAY, D_BARAI, MERPAY, WECHAT_PAY, LIGHTNING, UNKNOWN.
WalletDetailsBuyerFullName	String	True	The name of the Cash App account holder.
WalletDetailsBuyerCountryCode	String	True	The country of the Cash App account holder, in ISO 3166-1-alpha-2 format.
WalletDetailsBuyerCashTag	String	True	$Cashtag of the Cash App account holder.
WalletDetailsStatus	String	True	The status of the WALLET payment. The status can be AUTHORIZED, CAPTURED, VOIDED, or FAILED. The allowed values are AUTHORIZED, CAPTURED, VOIDED, FAILED.
IsOfflinePayment	Boolean	True	Whether or not this payment was taken offline.
OfflineCreatedAt	Datetime	True	The client-side timestamp of when the offline payment was created, in RFC 3339 format. The range is determined using the offline_payment_details.client_created_at field for each Payment. If set, payments without a value set in offline_payment_details.client_created_at will not be returned. Default: The current time.
WalletDetailsErrors	String	True	Information about errors encountered during the wallet payment.
CardMerchantId	String	True	The ID of the merchant that stored this card.
CardCreatedAt	Datetime	True	The timestamp when the card was created, in RFC 3339 format.
CardDisabledAt	Datetime	True	The timestamp when the card was disabled, in RFC 3339 format.
CardIssuerAlert	String	True	An alert issued by the card issuer about the status of the card.
CardIssuerAlertAt	Datetime	True	The timestamp when the issuer alert was generated, in RFC 3339 format.
CardHsaFsa	Boolean	True	Indicates whether the card is a Health Savings Account (HSA) or Flexible Spending Account (FSA) card.
AppliedCardSurchargeDetails	String	True	Details about the card surcharge applied to this payment.
TerminalCheckoutId	String	True	An optional ID for a Terminal checkout that is associated with the payment.
BuyNowPayLaterDetailsErrors	String	True	Information about errors encountered during the Buy Now Pay Later payment.

Pseudocolumns

Pseudo column fields are used in the WHERE clause of SELECT statements (unless stated otherwise) and offer a more granular control over the tuples that are returned from the data source.


Name	Type	Description
IdempotencyKey	String	A unique string that identifies the request. Required for INSERT and UPDATE operations. Maximum 45 characters.
SourceId	String	The Id for the source of funds for this payment.
AutoComplete	Boolean	If set to true, this payment will be completed when possible. If set to false, this payment is held in an approved state until either explicitly completed (captured) or canceled (voided).
VerificationToken	String	An identifying token generated by payments.verifyBuyer(). Encapsulates customer device information and 3-D Secure challenge results to indicate that Square has verified the buyer identity.
AcceptPartialAuthorization	Boolean	If set to true and charging a Square Gift Card, a payment may be returned with an amount less than requested. Cannot be true when AutoComplete is true.
BuyerPhoneNumber	String	The buyer's phone number. Must start with + followed by the country code and contain 9-16 digits total.
CustomerDetailsCustomerInitiated	Boolean	Indicates whether the customer initiated the payment.
CustomerDetailsSellerKeyedIn	Boolean	Indicates whether the seller manually keyed in payment details for the customer.