Square · Schema

Square Payment

Represents a payment processed by the Square API, including credit cards, gift cards, digital wallets, ACH bank transfers, cash, and external payments.

RestaurantBookingsCatalogCheckoutCustomersDisputesEcommerceFinancial TechnologyGift CardsInventoryInvoicingLaborLocationsLoyaltyMerchantsOrdersPaymentsPoint of SaleRefundsRetailSubscriptionsTeamTerminalWebhooks

Properties

Name	Type	Description
id	string	A unique ID for the payment.
created_at	string	The timestamp of when the payment was created, in RFC 3339 format.
updated_at	string	The timestamp of when the payment was last updated, in RFC 3339 format.
amount_money	object	The amount processed for this payment, not including tip_money.
tip_money	object	The amount designated as a tip.
total_money	object	The total amount for the payment, including amount_money and tip_money.
app_fee_money	object	The amount the developer is taking as a fee for facilitating the payment on behalf of the seller.
approved_money	object	The amount of money approved for this payment.
processing_fee	array	The processing fees and fee adjustments assessed by Square for this payment.
refunded_money	object	The total amount of the payment refunded to date.
status	string	Indicates whether the payment is APPROVED, PENDING, COMPLETED, CANCELED, or FAILED.
delay_duration	string	The duration of time after the payment's creation when Square automatically applies the delay_action to the payment, in RFC 3339 duration format.
delay_action	string	The action to be applied to the payment when the delay_duration has elapsed. Current values include CANCEL and COMPLETE.
delayed_until	string	The read-only timestamp of when the delay_action is automatically applied, in RFC 3339 format.
source_type	string	The source type for this payment.
card_details	object	Details about a card payment. Only populated if the source_type is CARD.
cash_details	object	Details about a cash payment. Only populated if the source_type is CASH.
bank_account_details	object	Details about a bank account payment. Only populated if the source_type is BANK_ACCOUNT.
external_details	object	Details about an external payment. Only populated if the source_type is EXTERNAL.
wallet_details	object	Details about a wallet payment. Only populated if the source_type is WALLET.
buy_now_pay_later_details	object	Details about a Buy Now Pay Later payment. Only populated if the source_type is BUY_NOW_PAY_LATER.
square_account_details	object	Details about a Square Account payment. Only populated if the source_type is SQUARE_ACCOUNT.
location_id	string	The ID of the location associated with the payment.
order_id	string	The ID of the order associated with the payment.
reference_id	string	An optional ID that associates the payment with an entity in another system.
customer_id	string	The ID of the customer associated with the payment.
employee_id	string	An optional ID of the employee associated with taking the payment.
team_member_id	string	An optional ID of the TeamMember associated with taking the payment.
refund_ids	array	A list of refund IDs associated with the payment.
risk_evaluation	object	An assessment of the risk associated with the payment.
buyer_email_address	string	The buyer's email address.
billing_address	object	The buyer's billing address.
shipping_address	object	The buyer's shipping address.
note	string	An optional note to include when creating a payment.
statement_description_identifier	string	Additional payment information that gets added to the customer's card statement.
receipt_number	string	The payment's receipt number.
receipt_url	string	The URL for the payment's receipt.
version_token	string	Used for optimistic concurrency. This opaque token identifies a specific version of the Payment object.

View JSON Schema on GitHub

JSON Schema

{
  "$id": "https://github.com/api-evangelist/square/blob/main/json-schema/payment.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Square Payment",
  "description": "Represents a payment processed by the Square API, including credit cards, gift cards, digital wallets, ACH bank transfers, cash, and external payments.",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "A unique ID for the payment.",
      "maxLength": 192,
      "readOnly": true
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "The timestamp of when the payment was created, in RFC 3339 format.",
      "readOnly": true
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "The timestamp of when the payment was last updated, in RFC 3339 format.",
      "readOnly": true
    },
    "amount_money": {
      "$ref": "money.json",
      "description": "The amount processed for this payment, not including tip_money."
    },
    "tip_money": {
      "$ref": "money.json",
      "description": "The amount designated as a tip."
    },
    "total_money": {
      "$ref": "money.json",
      "description": "The total amount for the payment, including amount_money and tip_money.",
      "readOnly": true
    },
    "app_fee_money": {
      "$ref": "money.json",
      "description": "The amount the developer is taking as a fee for facilitating the payment on behalf of the seller."
    },
    "approved_money": {
      "$ref": "money.json",
      "description": "The amount of money approved for this payment."
    },
    "processing_fee": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "effective_at": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp of when the fee takes effect."
          },
          "type": {
            "type": "string",
            "description": "The type of fee assessed or adjusted."
          },
          "amount_money": {
            "$ref": "money.json",
            "description": "The fee amount."
          }
        }
      },
      "description": "The processing fees and fee adjustments assessed by Square for this payment.",
      "readOnly": true
    },
    "refunded_money": {
      "$ref": "money.json",
      "description": "The total amount of the payment refunded to date.",
      "readOnly": true
    },
    "status": {
      "type": "string",
      "description": "Indicates whether the payment is APPROVED, PENDING, COMPLETED, CANCELED, or FAILED.",
      "enum": ["APPROVED", "PENDING", "COMPLETED", "CANCELED", "FAILED"],
      "readOnly": true
    },
    "delay_duration": {
      "type": "string",
      "description": "The duration of time after the payment's creation when Square automatically applies the delay_action to the payment, in RFC 3339 duration format.",
      "readOnly": true
    },
    "delay_action": {
      "type": "string",
      "description": "The action to be applied to the payment when the delay_duration has elapsed. Current values include CANCEL and COMPLETE.",
      "enum": ["CANCEL", "COMPLETE"]
    },
    "delayed_until": {
      "type": "string",
      "format": "date-time",
      "description": "The read-only timestamp of when the delay_action is automatically applied, in RFC 3339 format.",
      "readOnly": true
    },
    "source_type": {
      "type": "string",
      "description": "The source type for this payment.",
      "enum": ["CARD", "BANK_ACCOUNT", "WALLET", "BUY_NOW_PAY_LATER", "SQUARE_ACCOUNT", "CASH", "EXTERNAL"],
      "readOnly": true
    },
    "card_details": {
      "type": "object",
      "description": "Details about a card payment. Only populated if the source_type is CARD.",
      "readOnly": true
    },
    "cash_details": {
      "type": "object",
      "description": "Details about a cash payment. Only populated if the source_type is CASH.",
      "properties": {
        "buyer_supplied_money": {
          "$ref": "money.json",
          "description": "The amount of cash provided by the buyer."
        },
        "change_back_money": {
          "$ref": "money.json",
          "description": "The amount of change returned to the buyer."
        }
      }
    },
    "bank_account_details": {
      "type": "object",
      "description": "Details about a bank account payment. Only populated if the source_type is BANK_ACCOUNT.",
      "readOnly": true
    },
    "external_details": {
      "type": "object",
      "description": "Details about an external payment. Only populated if the source_type is EXTERNAL.",
      "readOnly": true
    },
    "wallet_details": {
      "type": "object",
      "description": "Details about a wallet payment. Only populated if the source_type is WALLET.",
      "readOnly": true
    },
    "buy_now_pay_later_details": {
      "type": "object",
      "description": "Details about a Buy Now Pay Later payment. Only populated if the source_type is BUY_NOW_PAY_LATER.",
      "readOnly": true
    },
    "square_account_details": {
      "type": "object",
      "description": "Details about a Square Account payment. Only populated if the source_type is SQUARE_ACCOUNT.",
      "readOnly": true
    },
    "location_id": {
      "type": "string",
      "description": "The ID of the location associated with the payment.",
      "maxLength": 50,
      "readOnly": true
    },
    "order_id": {
      "type": "string",
      "description": "The ID of the order associated with the payment.",
      "maxLength": 192,
      "readOnly": true
    },
    "reference_id": {
      "type": "string",
      "description": "An optional ID that associates the payment with an entity in another system.",
      "maxLength": 40
    },
    "customer_id": {
      "type": "string",
      "description": "The ID of the customer associated with the payment."
    },
    "employee_id": {
      "type": "string",
      "description": "An optional ID of the employee associated with taking the payment.",
      "readOnly": true
    },
    "team_member_id": {
      "type": "string",
      "description": "An optional ID of the TeamMember associated with taking the payment.",
      "readOnly": true
    },
    "refund_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "A list of refund IDs associated with the payment.",
      "readOnly": true
    },
    "risk_evaluation": {
      "type": "object",
      "description": "An assessment of the risk associated with the payment.",
      "properties": {
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "The timestamp when the risk evaluation was created."
        },
        "risk_level": {
          "type": "string",
          "description": "The risk level associated with the payment.",
          "enum": ["PENDING", "NORMAL", "MODERATE", "HIGH"]
        }
      },
      "readOnly": true
    },
    "buyer_email_address": {
      "type": "string",
      "format": "email",
      "description": "The buyer's email address."
    },
    "billing_address": {
      "type": "object",
      "description": "The buyer's billing address."
    },
    "shipping_address": {
      "type": "object",
      "description": "The buyer's shipping address."
    },
    "note": {
      "type": "string",
      "description": "An optional note to include when creating a payment.",
      "maxLength": 500
    },
    "statement_description_identifier": {
      "type": "string",
      "description": "Additional payment information that gets added to the customer's card statement.",
      "maxLength": 20
    },
    "receipt_number": {
      "type": "string",
      "description": "The payment's receipt number.",
      "maxLength": 4,
      "readOnly": true
    },
    "receipt_url": {
      "type": "string",
      "format": "uri",
      "description": "The URL for the payment's receipt.",
      "readOnly": true
    },
    "version_token": {
      "type": "string",
      "description": "Used for optimistic concurrency. This opaque token identifies a specific version of the Payment object."
    }
  },
  "required": ["amount_money"]
}