Square Payment is a JSON Structure definition published by Square, describing 38 properties, of which 1 is required. It conforms to the https://json-structure.org/meta/core/v0/# meta-schema.
{
"$schema": "https://json-structure.org/meta/core/v0/#",
"$id": "https://raw.githubusercontent.com/api-evangelist/square/refs/heads/main/json-structure/payment-structure.json",
"name": "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": {
"description": "A unique ID for the payment.",
"maxLength": 192,
"readOnly": true,
"type": "string"
},
"created_at": {
"description": "The timestamp of when the payment was created, in RFC 3339 format.",
"readOnly": true,
"type": "datetime"
},
"updated_at": {
"description": "The timestamp of when the payment was last updated, in RFC 3339 format.",
"readOnly": true,
"type": "datetime"
},
"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": {
"items": {
"properties": {
"effective_at": {
"description": "The timestamp of when the fee takes effect.",
"type": "datetime"
},
"type": {
"description": "The type of fee assessed or adjusted.",
"type": "string"
},
"amount_money": {
"$ref": "money.json",
"description": "The fee amount."
}
},
"type": "object"
},
"description": "The processing fees and fee adjustments assessed by Square for this payment.",
"readOnly": true,
"type": "array"
},
"refunded_money": {
"$ref": "money.json",
"description": "The total amount of the payment refunded to date.",
"readOnly": true
},
"status": {
"description": "Indicates whether the payment is APPROVED, PENDING, COMPLETED, CANCELED, or FAILED.",
"enum": [
"APPROVED",
"PENDING",
"COMPLETED",
"CANCELED",
"FAILED"
],
"readOnly": true,
"type": "string"
},
"delay_duration": {
"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,
"type": "string"
},
"delay_action": {
"description": "The action to be applied to the payment when the delay_duration has elapsed. Current values include CANCEL and COMPLETE.",
"enum": [
"CANCEL",
"COMPLETE"
],
"type": "string"
},
"delayed_until": {
"description": "The read-only timestamp of when the delay_action is automatically applied, in RFC 3339 format.",
"readOnly": true,
"type": "datetime"
},
"source_type": {
"description": "The source type for this payment.",
"enum": [
"CARD",
"BANK_ACCOUNT",
"WALLET",
"BUY_NOW_PAY_LATER",
"SQUARE_ACCOUNT",
"CASH",
"EXTERNAL"
],
"readOnly": true,
"type": "string"
},
"card_details": {
"description": "Details about a card payment. Only populated if the source_type is CARD.",
"readOnly": true,
"type": "object"
},
"cash_details": {
"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."
}
},
"type": "object"
},
"bank_account_details": {
"description": "Details about a bank account payment. Only populated if the source_type is BANK_ACCOUNT.",
"readOnly": true,
"type": "object"
},
"external_details": {
"description": "Details about an external payment. Only populated if the source_type is EXTERNAL.",
"readOnly": true,
"type": "object"
},
"wallet_details": {
"description": "Details about a wallet payment. Only populated if the source_type is WALLET.",
"readOnly": true,
"type": "object"
},
"buy_now_pay_later_details": {
"description": "Details about a Buy Now Pay Later payment. Only populated if the source_type is BUY_NOW_PAY_LATER.",
"readOnly": true,
"type": "object"
},
"square_account_details": {
"description": "Details about a Square Account payment. Only populated if the source_type is SQUARE_ACCOUNT.",
"readOnly": true,
"type": "object"
},
"location_id": {
"description": "The ID of the location associated with the payment.",
"maxLength": 50,
"readOnly": true,
"type": "string"
},
"order_id": {
"description": "The ID of the order associated with the payment.",
"maxLength": 192,
"readOnly": true,
"type": "string"
},
"reference_id": {
"description": "An optional ID that associates the payment with an entity in another system.",
"maxLength": 40,
"type": "string"
},
"customer_id": {
"description": "The ID of the customer associated with the payment.",
"type": "string"
},
"employee_id": {
"description": "An optional ID of the employee associated with taking the payment.",
"readOnly": true,
"type": "string"
},
"team_member_id": {
"description": "An optional ID of the TeamMember associated with taking the payment.",
"readOnly": true,
"type": "string"
},
"refund_ids": {
"items": {
"type": "string"
},
"description": "A list of refund IDs associated with the payment.",
"readOnly": true,
"type": "array"
},
"risk_evaluation": {
"description": "An assessment of the risk associated with the payment.",
"properties": {
"created_at": {
"description": "The timestamp when the risk evaluation was created.",
"type": "datetime"
},
"risk_level": {
"description": "The risk level associated with the payment.",
"enum": [
"PENDING",
"NORMAL",
"MODERATE",
"HIGH"
],
"type": "string"
}
},
"readOnly": true,
"type": "object"
},
"buyer_email_address": {
"description": "The buyer's email address.",
"type": "string"
},
"billing_address": {
"description": "The buyer's billing address.",
"type": "object"
},
"shipping_address": {
"description": "The buyer's shipping address.",
"type": "object"
},
"note": {
"description": "An optional note to include when creating a payment.",
"maxLength": 500,
"type": "string"
},
"statement_description_identifier": {
"description": "Additional payment information that gets added to the customer's card statement.",
"maxLength": 20,
"type": "string"
},
"receipt_number": {
"description": "The payment's receipt number.",
"maxLength": 4,
"readOnly": true,
"type": "string"
},
"receipt_url": {
"description": "The URL for the payment's receipt.",
"readOnly": true,
"type": "uri"
},
"version_token": {
"description": "Used for optimistic concurrency. This opaque token identifies a specific version of the Payment object.",
"type": "string"
}
},
"required": [
"amount_money"
]
}