RecurringPaymentRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/cash-app/main/json-schema/cash-app-recurring-payment-request-schema.json",
  "title": "RecurringPaymentRequest",
  "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/RecurringPaymentRequest",
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "format": "uuid",
      "description": "A unique identifier for the request, used for idempotency"
    },
    "paymentMethod": {
      "$ref": "#/$defs/RecurringPaymentRequestPaymentMethod"
    },
    "amount": {
      "$ref": "#/$defs/Money",
      "description": "The total amount of the payment"
    },
    "consumer": {
      "$ref": "#/$defs/Consumer"
    },
    "billing": {
      "$ref": "#/$defs/Contact"
    },
    "shipping": {
      "$ref": "#/$defs/Contact"
    },
    "courier": {
      "$ref": "#/$defs/Shipping-Courier"
    },
    "items": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Item"
      }
    },
    "discounts": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Discount"
      }
    },
    "description": {
      "type": "string"
    },
    "merchant": {
      "$ref": "#/$defs/RecurringPaymentRequestMerchant"
    },
    "merchantReference": {
      "type": "string",
      "description": "The reference/order ID in the merchant's system"
    },
    "shippingAmount": {
      "$ref": "#/$defs/Money",
      "description": "The shipping cost amount"
    },
    "taxAmount": {
      "$ref": "#/$defs/Money",
      "description": "The tax amount"
    },
    "custom": {
      "type": "object",
      "additionalProperties": {
        "description": "Any type"
      },
      "description": "Custom key-value pairs for merchant use"
    },
    "paymentScheduleChecksum": {
      "type": "string",
      "description": "Payment schedule validation checksum"
    },
    "enrichments": {
      "$ref": "#/$defs/RecurringPaymentRequestEnrichments"
    }
  },
  "required": [
    "requestId",
    "paymentMethod",
    "amount"
  ],
  "$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"
    },
    "RecurringPaymentRequestEnrichments": {
      "type": "object",
      "properties": {
        "initiation": {
          "$ref": "#/$defs/RecurringPaymentRequestEnrichmentsInitiation",
          "description": "Describes who initiated the transaction"
        }
      },
      "title": "RecurringPaymentRequestEnrichments"
    },
    "RecurringPaymentRequestEnrichmentsInitiation": {
      "type": "object",
      "properties": {
        "actor": {
          "$ref": "#/$defs/RecurringPaymentRequestEnrichmentsInitiationActor",
          "description": "The actor initiating the transaction. Use MERCHANT when the customer is not present."
        }
      },
      "description": "Describes who initiated the transaction",
      "title": "RecurringPaymentRequestEnrichmentsInitiation"
    },
    "RecurringPaymentRequestEnrichmentsInitiationActor": {
      "type": "string",
      "enum": [
        "CUSTOMER",
        "MERCHANT"
      ],
      "description": "The actor initiating the transaction. Use MERCHANT when the customer is not present.",
      "title": "RecurringPaymentRequestEnrichmentsInitiationActor"
    },
    "RecurringPaymentRequestMerchant": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The merchant name to display"
        }
      },
      "title": "RecurringPaymentRequestMerchant"
    },
    "RecurringPaymentRequestPaymentMethod": {
      "type": "object",
      "properties": {
        "token": {
          "type": "string",
          "description": "The billing agreement token"
        },
        "type": {
          "$ref": "#/$defs/RecurringPaymentRequestPaymentMethodType",
          "description": "The payment method type"
        }
      },
      "required": [
        "token",
        "type"
      ],
      "title": "RecurringPaymentRequestPaymentMethod"
    },
    "RecurringPaymentRequestPaymentMethodType": {
      "type": "string",
      "enum": [
        "BILLING_AGREEMENT"
      ],
      "description": "The payment method type",
      "title": "RecurringPaymentRequestPaymentMethodType"
    },
    "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"
    }
  }
}