payment.md

Payment

Represents a payment processed by the Square API.

Structure

Payment

Fields

Name	Type	Tags	Description
id	string | undefined	Optional	A unique ID for the payment. Constraints: Maximum Length: 192
createdAt	string | undefined	Optional	The timestamp of when the payment was created, in RFC 3339 format. Constraints: Maximum Length: 32
updatedAt	string | undefined	Optional	The timestamp of when the payment was last updated, in RFC 3339 format. Constraints: Maximum Length: 32
amountMoney	Money | undefined	Optional	Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
tipMoney	Money | undefined	Optional	Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
totalMoney	Money | undefined	Optional	Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
appFeeMoney	Money | undefined	Optional	Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
approvedMoney	Money | undefined	Optional	Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
processingFee	ProcessingFee[] | undefined	Optional	The processing fees and fee adjustments assessed by Square for this payment.
refundedMoney	Money | undefined	Optional	Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
status	string | undefined	Optional	Indicates whether the payment is APPROVED, PENDING, COMPLETED, CANCELED, or FAILED. Constraints: Maximum Length: 50
delayDuration	string | undefined	Optional	The duration of time after the payment's creation when Square automatically applies the delay_action to the payment. This automatic delay_action applies only to payments that do not reach a terminal state (COMPLETED, CANCELED, or FAILED) before the delay_duration time period. This field is specified as a time duration, in RFC 3339 format. Notes: This feature is only supported for card payments. Default: - Card-present payments: "PT36H" (36 hours) from the creation time. - Card-not-present payments: "P7D" (7 days) from the creation time.
delayAction	string | undefined	Optional	The action to be applied to the payment when the delay_duration has elapsed. Current values include CANCEL and COMPLETE.
delayedUntil	string | undefined	Optional	The read-only timestamp of when the delay_action is automatically applied, in RFC 3339 format. Note that this field is calculated by summing the payment's delay_duration and created_at fields. The created_at field is generated by Square and might not exactly match the time on your local machine.
sourceType	string | undefined	Optional	The source type for this payment. Current values include CARD, BANK_ACCOUNT, WALLET, BUY_NOW_PAY_LATER, CASH and EXTERNAL. For information about these payment source types, see Take Payments. Constraints: Maximum Length: 50
cardDetails	CardPaymentDetails | undefined	Optional	Reflects the current status of a card payment. Contains only non-confidential information.
cashDetails	CashPaymentDetails | undefined	Optional	Stores details about a cash payment. Contains only non-confidential information. For more information, see Take Cash Payments.
bankAccountDetails	BankAccountPaymentDetails | undefined	Optional	Additional details about BANK_ACCOUNT type payments.
externalDetails	ExternalPaymentDetails | undefined	Optional	Stores details about an external payment. Contains only non-confidential information. For more information, see Take External Payments.
walletDetails	DigitalWalletDetails | undefined	Optional	Additional details about WALLET type payments. Contains only non-confidential information.
buyNowPayLaterDetails	BuyNowPayLaterDetails | undefined	Optional	Additional details about a Buy Now Pay Later payment type.
locationId	string | undefined	Optional	The ID of the location associated with the payment. Constraints: Maximum Length: 50
orderId	string | undefined	Optional	The ID of the order associated with the payment. Constraints: Maximum Length: 192
referenceId	string | undefined	Optional	An optional ID that associates the payment with an entity in another system. Constraints: Maximum Length: 40
customerId	string | undefined	Optional	The ID of the customer associated with the payment. If the ID is not provided in the CreatePayment request that was used to create the Payment, Square may use information in the request (such as the billing and shipping address, email address, and payment source) to identify a matching customer profile in the Customer Directory. If found, the profile ID is used. If a profile is not found, the API attempts to create an instant profile. If the API cannot create an instant profile (either because the seller has disabled it or the seller's region prevents creating it), this field remains unset. Note that this process is asynchronous and it may take some time before a customer ID is added to the payment. Constraints: Maximum Length: 191
employeeId	string | undefined	Optional	Deprecated: Use Payment.team_member_id instead. An optional ID of the employee associated with taking the payment. Constraints: Maximum Length: 192
teamMemberId	string | undefined	Optional	An optional ID of the TeamMember associated with taking the payment. Constraints: Maximum Length: 192
refundIds	string[] | undefined	Optional	A list of refund_ids identifying refunds for the payment.
riskEvaluation	RiskEvaluation | undefined	Optional	Represents fraud risk information for the associated payment. When you take a payment through Square's Payments API (using the CreatePayment endpoint), Square evaluates it and assigns a risk level to the payment. Sellers can use this information to determine the course of action (for example, provide the goods/services or refund the payment).
buyerEmailAddress	string | undefined	Optional	The buyer's email address. Constraints: Maximum Length: 255
billingAddress	Address | undefined	Optional	Represents a postal address in a country. For more information, see Working with Addresses.
shippingAddress	Address | undefined	Optional	Represents a postal address in a country. For more information, see Working with Addresses.
note	string | undefined	Optional	An optional note to include when creating a payment. Constraints: Maximum Length: 500
statementDescriptionIdentifier	string | undefined	Optional	Additional payment information that gets added to the customer's card statement as part of the statement description. Note that the statement_description_identifier might get truncated on the statement description to fit the required information including the Square identifier (SQ *) and the name of the seller taking the payment.
capabilities	string[] | undefined	Optional	Actions that can be performed on this payment: - EDIT_AMOUNT_UP - The payment amount can be edited up. - EDIT_AMOUNT_DOWN - The payment amount can be edited down. - EDIT_TIP_AMOUNT_UP - The tip amount can be edited up. - EDIT_TIP_AMOUNT_DOWN - The tip amount can be edited down. - EDIT_DELAY_ACTION - The delay_action can be edited.
receiptNumber	string | undefined	Optional	The payment's receipt number. The field is missing if a payment is canceled. Constraints: Maximum Length: 4
receiptUrl	string | undefined	Optional	The URL for the payment's receipt. The field is only populated for COMPLETED payments. Constraints: Maximum Length: 255
deviceDetails	DeviceDetails | undefined	Optional	Details about the device that took the payment.
applicationDetails	ApplicationDetails | undefined	Optional	Details about the application that took the payment.
versionToken	string | undefined	Optional	Used for optimistic concurrency. This opaque token identifies a specific version of the Payment object.

Example (as JSON)

{
  "amount_money": null,
  "tip_money": null,
  "total_money": null,
  "app_fee_money": null,
  "approved_money": null,
  "refunded_money": null,
  "delay_action": null,
  "card_details": null,
  "cash_details": null,
  "bank_account_details": null,
  "external_details": null,
  "wallet_details": null,
  "buy_now_pay_later_details": null,
  "risk_evaluation": null,
  "billing_address": null,
  "shipping_address": null,
  "device_details": null,
  "application_details": null,
  "version_token": null
}