{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/cash-app/main/json-schema/cash-app-payment-schema.json",
  "title": "Payment",
  "description": "Describes the schema for a (read-only) payment object",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cash-app-recurring-payments-api-openapi.yml#/components/schemas/Payment",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique, permanent, Afterpay generated Order ID."
    },
    "token": {
      "type": "string",
      "description": "The token obtained from the checkout call"
    },
    "status": {
      "$ref": "#/$defs/PaymentStatus",
      "description": "represents the status of the order"
    },
    "created": {
      "type": "string",
      "description": " is the UTC timestamp of when the payment was completed."
    },
    "originalAmount": {
      "$ref": "#/$defs/Money"
    },
    "openToCaptureAmount": {
      "$ref": "#/$defs/Money"
    },
    "paymentState": {
      "$ref": "#/$defs/PaymentPaymentState",
      "description": "is the current state for capturing payments"
    },
    "merchantReference": {
      "type": "string",
      "description": "is the merchant's order id/reference that the payment corresponds to."
    },
    "refunds": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Refund"
      }
    },
    "orderDetails": {
      "$ref": "#/$defs/Order-Details"
    },
    "events": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Payment-Event"
      }
    }
  },
  "$defs": {
    "Consumer": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "format": "email"
        },
        "givenNames": {
          "type": "string",
          "description": "The consumer's first name"
        },
        "surname": {
          "type": "string",
          "description": "The consumer's last name"
        },
        "phoneNumber": {
          "type": "string"
        }
      },
      "required": [
        "email"
      ],
      "description": "The consumer data model is used for gathering essential user information. It captures details such as the individual's first name, represented by `givenNames`, and their last name, captured under `surname`. In addition, it stores the user's contact number under `phoneNumber` and their email address under `email`. These fields collectively provide contact and identification details for a user.",
      "title": "Consumer"
    },
    "Contact": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "line1": {
          "type": "string",
          "description": "First line of the address"
        },
        "line2": {
          "type": "string",
          "description": "Second line of the address "
        },
        "area1": {
          "type": "string",
          "description": "- AU: Suburb\n- NZ: Town or City\n- UK: Postal Town\n- US: City\n- Canada: City"
        },
        "area2": {
          "type": "string",
          "description": "- NZ: suburb\n- UK: village or local area."
        },
        "region": {
          "type": "string",
          "description": "- AU: State \n- NZ: Region\n- UK: County\n- US: State\n- CA: Province or Territory"
        },
        "postcode": {
          "type": "string"
        },
        "countryCode": {
          "$ref": "#/$defs/ContactCountryCode"
        },
        "phoneNumber": {
          "type": "string",
          "description": "The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123) format."
        }
      },
      "required": [
        "name",
        "line1",
        "area1",
        "region",
        "postcode",
        "countryCode"
      ],
      "description": "This data model is used for storing an individual's contact information. Mandatory fields such as **name**, **line1**, **area1**, **region**, **postcode**, and **countryCode** help in capturing vital information about a user's location. \n\nThe `line2` and `area2` fields provide additional space for extended addresses, while `phoneNumber` can be used to store the user's contact number.\n\n\n<Warning Title=\"Important Note\">\n  The `area1`, `area2` and `region` properties feature localized terminology based on country. Refer to the property descriptions for insights on each country's specific usage \n</Warning>\n",
      "title": "Contact"
    },
    "ContactCountryCode": {
      "type": "string",
      "enum": [
        "AU",
        "NZ",
        "US",
        "CA",
        "GB"
      ],
      "title": "ContactCountryCode"
    },
    "Discount": {
      "type": "object",
      "properties": {
        "displayName": {
          "type": "string"
        },
        "amount": {
          "$ref": "#/$defs/Money"
        }
      },
      "description": "Discount applied to an order",
      "title": "Discount"
    },
    "Item": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "sku": {
          "type": "string"
        },
        "pageUrl": {
          "type": "string"
        },
        "imageUrl": {
          "type": "string"
        },
        "quantity": {
          "type": "integer"
        },
        "price": {
          "$ref": "#/$defs/Money"
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "estimatedShipmentDate": {
          "type": "string",
          "format": "date"
        },
        "preorder": {
          "type": "boolean",
          "default": false
        }
      },
      "required": [
        "name",
        "quantity",
        "price"
      ],
      "description": "This data model is used to store crucial product details. The `price.amount` field represents the unit price of the individual item. The `quantity` field shows the number of units of the item. The `name` field denotes the name of the product, while `sku` holds the Stock Keeping Unit identifier. 100 is the maximum number of item objects in the items array.\n<Warning Title=\"Important Note\">\n  It is crucial that the `price.amount` represents the unit price of the individual item.\n  **Never** populate the `price.amount` by multiplying the quantity by the unit cost. Always enter the price for a single unit to maintain data accuracy.\n</Warning>\n",
      "title": "Item"
    },
    "Money": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "string",
          "description": "The amount as a string representation of a decimal number, rounded to 2 decimal places."
        },
        "currency": {
          "$ref": "#/$defs/MoneyCurrency"
        }
      },
      "required": [
        "amount",
        "currency"
      ],
      "description": "Object containing amount and currency",
      "title": "Money"
    },
    "MoneyCurrency": {
      "type": "string",
      "enum": [
        "AUD",
        "NZD",
        "USD",
        "CAD",
        "GBP"
      ],
      "title": "MoneyCurrency"
    },
    "Order-Details": {
      "type": "object",
      "properties": {
        "consumer": {
          "$ref": "#/$defs/Consumer"
        },
        "billing": {
          "$ref": "#/$defs/Contact"
        },
        "courier": {
          "$ref": "#/$defs/Shipping-Courier"
        },
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Item"
          }
        },
        "discounts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Discount"
          }
        },
        "taxAmount": {
          "$ref": "#/$defs/Money"
        },
        "shippingAmount": {
          "$ref": "#/$defs/Money"
        }
      },
      "description": "This comprehensive schema is designed to store an entire transaction's detail, covering crucial aspects like consumer information, billing and shipping details, courier particulars, item list, discounts, tax, and shipping amount.",
      "title": "Order-Details"
    },
    "Payment-Event": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "created": {
          "type": "string"
        },
        "expires": {
          "type": "string"
        },
        "type": {
          "$ref": "#/$defs/PaymentEventType"
        },
        "amount": {
          "$ref": "#/$defs/Money"
        },
        "paymentEventMerchantReference": {
          "type": "string"
        }
      },
      "description": "Each payment event has a unique ID, creation timestamp, and type (e.g., \"AUTH_APPROVED\", \"AUTH_DECLINED\"). For \"AUTH_APPROVED\" events, an expiration timestamp is provided. The \"payment event merchant reference\" field, which can be used for payment capture events",
      "title": "Payment-Event"
    },
    "PaymentEventType": {
      "type": "string",
      "enum": [
        "AUTH_APPROVED",
        "AUTH_DECLINED",
        "CAPTURED",
        "CAPTURE_DECLINED",
        "VOIDED",
        "EXPIRED"
      ],
      "title": "PaymentEventType"
    },
    "PaymentPaymentState": {
      "type": "string",
      "enum": [
        "AUTH_APPROVED",
        "AUTH_DECLINED",
        "PARTIALLY_CAPTURED",
        "CAPTURED",
        "CAPTURE_DECLINED",
        "VOIDED"
      ],
      "description": "is the current state for capturing payments",
      "title": "PaymentPaymentState"
    },
    "PaymentStatus": {
      "type": "string",
      "enum": [
        "APPROVED",
        "DECLINED"
      ],
      "description": "represents the status of the order",
      "title": "PaymentStatus"
    },
    "Refund": {
      "type": "object",
      "properties": {
        "requestId": {
          "type": "string",
          "description": "Unique ID required for safe retries. Max length 64 (varchar)."
        },
        "amount": {
          "$ref": "#/$defs/Money"
        },
        "merchantReference": {
          "type": "string",
          "description": "The merchant’s internal refund id/reference. This must be included along with the `requestId` to utilise idempotency. Max length 85 (varchar)."
        },
        "refundMerchantReference": {
          "type": "string",
          "description": "A unique reference for the individual refund event. Max length 128 (varchar)."
        },
        "refundId": {
          "type": "string",
          "description": "The unique, permanent, Afterpay-generated Refund ID."
        },
        "refundedAt": {
          "type": "string"
        }
      },
      "description": "To guarantee safe retries, the merchant should offer their refund ID or reference, aligning with their internal records\n\nUnique values for the `requestID`  and `merchantReference` are required to guarantee safe retries. It is recommended that the merchant generates a UUID for each unique refund request.\n\nThe `refundMerchantReference` is a unique reference that when provided, will appear in the daily settlement file as \"Payment Event Id\". In most cases, this would hold the same value as the `merchantReference`.\n",
      "title": "Refund"
    },
    "Shipping-Courier": {
      "type": "object",
      "properties": {
        "shippedAt": {
          "type": "string",
          "format": "date-time"
        },
        "name": {
          "type": "string"
        },
        "tracking": {
          "type": "string"
        },
        "priority": {
          "$ref": "#/$defs/ShippingCourierPriority"
        }
      },
      "description": "Essential information for tracking a shipment. The `shippedAt` key represents the date and time when the item was shipped. This value follows the [ISO 8601 standard format](https://www.iso.org/iso-8601-date-and-time-format.html) for date and time representations.\n\nThe `name` field indicates the courier service employed to handle the shipment (e.g. FEDEX, UPS). For orders that are picked up in-store (also known as Buy-Online-Pickup-Instore), please use \"INSTORE_PICKUP\" as the `name` field value.\n\nThe `tracking` key represents a unique tracking number provided by the courier service to monitor the shipment's progress. It's a valuable tool for customers and businesses to track and trace their packages.\n\nThe `priority` field tracks the shipping speed or service level associated with the delivery. ",
      "title": "Shipping-Courier"
    },
    "ShippingCourierPriority": {
      "type": "string",
      "enum": [
        "STANDARD",
        "EXPRESS"
      ],
      "title": "ShippingCourierPriority"
    }
  }
}