{
  "$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"
  ]
}