{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/breezecash/json-schema/breezecash-create-gateway-payment-request-schema.json",
  "title": "CreateGatewayPaymentRequest",
  "description": "Server-to-server payment details",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/breezecash-breeze-api-openapi.yml#/components/schemas/CreateGatewayPaymentRequest",
  "type": "object",
  "properties": {
    "amount": {
      "type": "integer",
      "description": "All-in total charged to the customer, in minor units (e.g. `1000` = $10.00). Includes `taxDetails.amount` when tax is supplied.",
      "minimum": 1
    },
    "currency": {
      "type": "string",
      "description": "ISO 4217 currency code.",
      "enum": [
        "USD",
        "AUD",
        "CAD",
        "CHF",
        "DKK",
        "EUR",
        "GBP",
        "HKD",
        "JPY",
        "NOK",
        "NZD",
        "PLN",
        "SEK",
        "SGD",
        "TWD",
        "KRW"
      ]
    },
    "clientReferenceId": {
      "type": "string",
      "description": "Merchant-provided dedup key. Used to safely retry requests without double-charging.",
      "maxLength": 100,
      "pattern": "^[\\w-]+$"
    },
    "description": {
      "type": "string",
      "description": "Description of what the customer purchased. Direct Payment has no line items, so this is how product information reaches the receipt and the Breeze dashboard.",
      "maxLength": 280
    },
    "customer": {
      "description": "Customer identification. Provide one of the three variants below.",
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "Existing Breeze customer identifier (`cus_*`)."
            },
            "email": {
              "type": "string",
              "description": "Cardholder email. Required when neither `id` nor `referenceId` is provided.",
              "format": "email"
            },
            "firstName": {
              "type": "string",
              "description": "Required when neither `id` nor `referenceId` is provided. Must be supplied together with `lastName`.",
              "minLength": 1,
              "maxLength": 100
            },
            "lastName": {
              "type": "string",
              "description": "Required when neither `id` nor `referenceId` is provided. Must be supplied together with `firstName`.",
              "minLength": 1,
              "maxLength": 100
            },
            "phone": {
              "type": "object",
              "description": "Phone number broken into country code and subscriber number. Must appear in a pair.",
              "properties": {
                "countryCode": {
                  "type": "string",
                  "description": "ITU dialing prefix without the leading '+', e.g. '1', '44'."
                },
                "number": {
                  "type": "string",
                  "description": "Subscriber number without country code or formatting."
                }
              },
              "required": [
                "countryCode",
                "number"
              ],
              "additionalProperties": false
            },
            "address": {
              "type": "object",
              "description": "Billing address. Improves fraud scoring.",
              "properties": {
                "line1": {
                  "type": "string"
                },
                "line2": {
                  "type": "string"
                },
                "city": {
                  "type": "string"
                },
                "state": {
                  "type": "string"
                },
                "postalCode": {
                  "type": "string"
                },
                "country": {
                  "type": "string",
                  "description": "ISO 3166-1 alpha-2 country code.",
                  "pattern": "^[A-Z]{2}$"
                }
              },
              "additionalProperties": false
            },
            "merchantTrustSignal": {
              "type": "object",
              "description": "Gameplay-derived trust signal for the customer. Stored on the customer record and used in risk evaluation.",
              "properties": {
                "playerId": {
                  "type": "string",
                  "description": "Your identifier for the player this signal refers to.",
                  "maxLength": 255
                },
                "hoursPlayed": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Total hours the player has played. Non-negative integer. Send `null` to clear a previously stored value; omit to keep the stored value.",
                  "minimum": 0
                },
                "playerLevel": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "The player's current level. Non-negative integer. Send `null` to clear a previously stored value; omit to keep the stored value.",
                  "minimum": 0
                },
                "trustStatus": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Your trust verdict for the player. Send `null` to clear a previously stored status; omit to keep the stored value.",
                  "enum": [
                    "GOOD",
                    "BAD",
                    null
                  ]
                }
              },
              "required": [
                "playerId"
              ],
              "additionalProperties": false
            }
          },
          "additionalProperties": false,
          "allOf": [
            {
              "type": "object",
              "properties": {},
              "additionalProperties": false,
              "anyOf": [
                {
                  "required": [
                    "id"
                  ]
                },
                {
                  "required": [
                    "referenceId"
                  ]
                }
              ]
            },
            {
              "type": "object",
              "properties": {},
              "additionalProperties": false,
              "anyOf": [
                {
                  "required": [
                    "id"
                  ]
                },
                {
                  "required": [
                    "referenceId"
                  ]
                }
              ]
            }
          ],
          "title": "By Breeze customer ID",
          "description": "Use this when the customer already exists in Breeze. Other fields are treated as updates if supplied. Card authorization needs the customer's `firstName`, `lastName`, and `billingEmail`: if the stored customer is missing any of them, supply them here.",
          "required": [
            "id"
          ]
        },
        {
          "type": "object",
          "properties": {
            "referenceId": {
              "type": "string",
              "description": "Merchant-side customer key. If provided, Breeze creates or retrieves a `cus_*`."
            },
            "email": {
              "type": "string",
              "description": "Cardholder email. Required when neither `id` nor `referenceId` is provided.",
              "format": "email"
            },
            "firstName": {
              "type": "string",
              "description": "Required when neither `id` nor `referenceId` is provided. Must be supplied together with `lastName`.",
              "minLength": 1,
              "maxLength": 100
            },
            "lastName": {
              "type": "string",
              "description": "Required when neither `id` nor `referenceId` is provided. Must be supplied together with `firstName`.",
              "minLength": 1,
              "maxLength": 100
            },
            "phone": {
              "type": "object",
              "description": "Phone number broken into country code and subscriber number. Must appear in a pair.",
              "properties": {
                "countryCode": {
                  "type": "string",
                  "description": "ITU dialing prefix without the leading '+', e.g. '1', '44'."
                },
                "number": {
                  "type": "string",
                  "description": "Subscriber number without country code or formatting."
                }
              },
              "required": [
                "countryCode",
                "number"
              ],
              "additionalProperties": false
            },
            "address": {
              "type": "object",
              "description": "Billing address. Improves fraud scoring.",
              "properties": {
                "line1": {
                  "type": "string"
                },
                "line2": {
                  "type": "string"
                },
                "city": {
                  "type": "string"
                },
                "state": {
                  "type": "string"
                },
                "postalCode": {
                  "type": "string"
                },
                "country": {
                  "type": "string",
                  "description": "ISO 3166-1 alpha-2 country code.",
                  "pattern": "^[A-Z]{2}$"
                }
              },
              "additionalProperties": false
            },
            "merchantTrustSignal": {
              "type": "object",
              "description": "Gameplay-derived trust signal for the customer. Stored on the customer record and used in risk evaluation.",
              "properties": {
                "playerId": {
                  "type": "string",
                  "description": "Your identifier for the player this signal refers to.",
                  "maxLength": 255
                },
                "hoursPlayed": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Total hours the player has played. Non-negative integer. Send `null` to clear a previously stored value; omit to keep the stored value.",
                  "minimum": 0
                },
                "playerLevel": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "The player's current level. Non-negative integer. Send `null` to clear a previously stored value; omit to keep the stored value.",
                  "minimum": 0
                },
                "trustStatus": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Your trust verdict for the player. Send `null` to clear a previously stored status; omit to keep the stored value.",
                  "enum": [
                    "GOOD",
                    "BAD",
                    null
                  ]
                }
              },
              "required": [
                "playerId"
              ],
              "additionalProperties": false
            }
          },
          "additionalProperties": false,
          "allOf": [
            {
              "type": "object",
              "properties": {},
              "additionalProperties": false,
              "anyOf": [
                {
                  "required": [
                    "id"
                  ]
                },
                {
                  "required": [
                    "referenceId"
                  ]
                }
              ]
            },
            {
              "type": "object",
              "properties": {},
              "additionalProperties": false,
              "anyOf": [
                {
                  "required": [
                    "id"
                  ]
                },
                {
                  "required": [
                    "referenceId"
                  ]
                }
              ]
            }
          ],
          "title": "By merchant reference ID",
          "description": "Merchant-side customer key. If provided, Breeze creates or retrieves a `cus_*`.",
          "required": [
            "referenceId"
          ]
        },
        {
          "type": "object",
          "properties": {
            "email": {
              "type": "string",
              "description": "Cardholder email. Required when neither `id` nor `referenceId` is provided.",
              "format": "email"
            },
            "firstName": {
              "type": "string",
              "description": "Required when neither `id` nor `referenceId` is provided. Must be supplied together with `lastName`.",
              "minLength": 1,
              "maxLength": 100
            },
            "lastName": {
              "type": "string",
              "description": "Required when neither `id` nor `referenceId` is provided. Must be supplied together with `firstName`.",
              "minLength": 1,
              "maxLength": 100
            },
            "phone": {
              "type": "object",
              "description": "Phone number broken into country code and subscriber number. Must appear in a pair.",
              "properties": {
                "countryCode": {
                  "type": "string",
                  "description": "ITU dialing prefix without the leading '+', e.g. '1', '44'."
                },
                "number": {
                  "type": "string",
                  "description": "Subscriber number without country code or formatting."
                }
              },
              "required": [
                "countryCode",
                "number"
              ],
              "additionalProperties": false
            },
            "address": {
              "type": "object",
              "description": "Billing address. Improves fraud scoring.",
              "properties": {
                "line1": {
                  "type": "string"
                },
                "line2": {
                  "type": "string"
                },
                "city": {
                  "type": "string"
                },
                "state": {
                  "type": "string"
                },
                "postalCode": {
                  "type": "string"
                },
                "country": {
                  "type": "string",
                  "description": "ISO 3166-1 alpha-2 country code.",
                  "pattern": "^[A-Z]{2}$"
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false,
          "allOf": [
            {
              "type": "object",
              "properties": {},
              "additionalProperties": false,
              "anyOf": [
                {
                  "required": [
                    "id"
                  ]
                },
                {
                  "required": [
                    "referenceId"
                  ]
                }
              ]
            },
            {
              "type": "object",
              "properties": {},
              "additionalProperties": false,
              "anyOf": [
                {
                  "required": [
                    "id"
                  ]
                },
                {
                  "required": [
                    "referenceId"
                  ]
                }
              ]
            }
          ],
          "title": "Anonymous shopper",
          "description": "One-off shopper without `id` or `referenceId`. `email`, `firstName`, and `lastName` are all required. Not allowed when `paymentMethod.storeFutureUsage` is set.",
          "required": [
            "email",
            "firstName",
            "lastName"
          ]
        }
      ]
    },
    "paymentMethod": {
      "description": "Payment credentials. Pick the variant that matches your integration.",
      "oneOf": [
        {
          "type": "object",
          "description": "Submit a raw PAN. CVV is required for customer-initiated transactions.",
          "properties": {
            "type": {
              "const": "RAW_PAN"
            },
            "card": {
              "type": "object",
              "properties": {
                "number": {
                  "type": "string",
                  "description": "PAN (RAW_PAN), DPAN (Apple Pay / Google Pay CRYPTOGRAM_3DS), FPAN (Google Pay PAN_ONLY), or network token.",
                  "pattern": "^\\d{12,19}$"
                },
                "expiryMonth": {
                  "type": "string",
                  "description": "2-digit month (`01`–`12`).",
                  "pattern": "^(0[1-9]|1[0-2])$"
                },
                "expiryYear": {
                  "type": "string",
                  "description": "4-digit year (e.g. `2028`).",
                  "pattern": "^2\\d{3}$"
                },
                "scheme": {
                  "type": "string",
                  "description": "Card scheme.",
                  "enum": [
                    "VISA",
                    "MASTERCARD",
                    "AMEX",
                    "DISCOVER",
                    "DINERS",
                    "JCB",
                    "CARTES_BANCAIRES"
                  ]
                },
                "issuer": {
                  "type": "string",
                  "description": "Issuing bank."
                },
                "issuerCountry": {
                  "type": "string",
                  "description": "ISO 3166-1 alpha-2 country of the issuer."
                },
                "cvv": {
                  "type": "string",
                  "description": "Card CVV/CVC (3 or 4 digits). Required for customer-initiated transactions.",
                  "pattern": "^\\d{3,4}$"
                }
              },
              "required": [
                "number",
                "expiryMonth",
                "expiryYear"
              ],
              "additionalProperties": false
            },
            "storeFutureUsage": {
              "type": "string",
              "description": "Opt-in to saving this card against the customer for future reuse. Requires `customer.id` or `customer.referenceId`.",
              "enum": [
                "on_session",
                "off_session"
              ]
            }
          },
          "required": [
            "type",
            "card"
          ],
          "additionalProperties": false,
          "title": "RAW_PAN"
        },
        {
          "type": "object",
          "description": "Submit a decrypted Apple Pay token (DPAN + TAVV cryptogram). Cryptogram is required for customer-initiated transactions.",
          "properties": {
            "type": {
              "const": "DECRYPTED_APPLE_PAY"
            },
            "card": {
              "type": "object",
              "properties": {
                "number": {
                  "type": "string",
                  "description": "PAN (RAW_PAN), DPAN (Apple Pay / Google Pay CRYPTOGRAM_3DS), FPAN (Google Pay PAN_ONLY), or network token.",
                  "pattern": "^\\d{12,19}$"
                },
                "expiryMonth": {
                  "type": "string",
                  "description": "2-digit month (`01`–`12`).",
                  "pattern": "^(0[1-9]|1[0-2])$"
                },
                "expiryYear": {
                  "type": "string",
                  "description": "4-digit year (e.g. `2028`).",
                  "pattern": "^2\\d{3}$"
                },
                "scheme": {
                  "type": "string",
                  "description": "Card scheme.",
                  "enum": [
                    "VISA",
                    "MASTERCARD",
                    "AMEX",
                    "DISCOVER",
                    "DINERS",
                    "JCB",
                    "CARTES_BANCAIRES"
                  ]
                },
                "issuer": {
                  "type": "string",
                  "description": "Issuing bank."
                },
                "issuerCountry": {
                  "type": "string",
                  "description": "ISO 3166-1 alpha-2 country of the issuer."
                }
              },
              "required": [
                "number",
                "expiryMonth",
                "expiryYear"
              ],
              "additionalProperties": false
            },
            "network": {
              "type": "object",
              "properties": {
                "eci": {
                  "type": "string",
                  "description": "ECI indicator (e.g. `05` for Visa, `02` for Mastercard).",
                  "pattern": "^\\d{2}$"
                },
                "cryptogram": {
                  "type": "string",
                  "description": "Base64-encoded cryptogram (TAVV for Apple Pay, CAVV for Google Pay). Required for customer-initiated transactions."
                }
              },
              "additionalProperties": false
            },
            "storeFutureUsage": {
              "type": "string",
              "description": "Opt-in to saving this card against the customer for future reuse. Requires `customer.id` or `customer.referenceId`.",
              "enum": [
                "on_session",
                "off_session"
              ]
            }
          },
          "required": [
            "type",
            "card"
          ],
          "additionalProperties": false,
          "title": "DECRYPTED_APPLE_PAY"
        },
        {
          "type": "object",
          "description": "Submit a decrypted Google Pay token with `tokenType: PAN_ONLY` — underlying value is an FPAN; no cryptogram.",
          "properties": {
            "type": {
              "const": "DECRYPTED_GOOGLE_PAY"
            },
            "card": {
              "type": "object",
              "properties": {
                "number": {
                  "type": "string",
                  "description": "PAN (RAW_PAN), DPAN (Apple Pay / Google Pay CRYPTOGRAM_3DS), FPAN (Google Pay PAN_ONLY), or network token.",
                  "pattern": "^\\d{12,19}$"
                },
                "expiryMonth": {
                  "type": "string",
                  "description": "2-digit month (`01`–`12`).",
                  "pattern": "^(0[1-9]|1[0-2])$"
                },
                "expiryYear": {
                  "type": "string",
                  "description": "4-digit year (e.g. `2028`).",
                  "pattern": "^2\\d{3}$"
                },
                "scheme": {
                  "type": "string",
                  "description": "Card scheme.",
                  "enum": [
                    "VISA",
                    "MASTERCARD",
                    "AMEX",
                    "DISCOVER",
                    "DINERS",
                    "JCB",
                    "CARTES_BANCAIRES"
                  ]
                },
                "issuer": {
                  "type": "string",
                  "description": "Issuing bank."
                },
                "issuerCountry": {
                  "type": "string",
                  "description": "ISO 3166-1 alpha-2 country of the issuer."
                }
              },
              "required": [
                "number",
                "expiryMonth",
                "expiryYear"
              ],
              "additionalProperties": false
            },
            "network": {
              "type": "object",
              "properties": {
                "tokenType": {
                  "description": "Google Pay token type — `PAN_ONLY` (underlying FPAN) or `CRYPTOGRAM_3DS` (underlying DPAN).",
                  "const": "PAN_ONLY"
                }
              },
              "required": [
                "tokenType"
              ],
              "additionalProperties": false
            },
            "storeFutureUsage": {
              "type": "string",
              "description": "Opt-in to saving this card against the customer for future reuse. Requires `customer.id` or `customer.referenceId`.",
              "enum": [
                "on_session",
                "off_session"
              ]
            }
          },
          "required": [
            "type",
            "card",
            "network"
          ],
          "additionalProperties": false,
          "title": "DECRYPTED_GOOGLE_PAY (PAN_ONLY)"
        },
        {
          "type": "object",
          "description": "Submit a decrypted Google Pay token with `tokenType: CRYPTOGRAM_3DS` — underlying value is a DPAN. Cryptogram is required for customer-initiated transactions.",
          "properties": {
            "type": {
              "const": "DECRYPTED_GOOGLE_PAY"
            },
            "card": {
              "type": "object",
              "properties": {
                "number": {
                  "type": "string",
                  "description": "PAN (RAW_PAN), DPAN (Apple Pay / Google Pay CRYPTOGRAM_3DS), FPAN (Google Pay PAN_ONLY), or network token.",
                  "pattern": "^\\d{12,19}$"
                },
                "expiryMonth": {
                  "type": "string",
                  "description": "2-digit month (`01`–`12`).",
                  "pattern": "^(0[1-9]|1[0-2])$"
                },
                "expiryYear": {
                  "type": "string",
                  "description": "4-digit year (e.g. `2028`).",
                  "pattern": "^2\\d{3}$"
                },
                "scheme": {
                  "type": "string",
                  "description": "Card scheme.",
                  "enum": [
                    "VISA",
                    "MASTERCARD",
                    "AMEX",
                    "DISCOVER",
                    "DINERS",
                    "JCB",
                    "CARTES_BANCAIRES"
                  ]
                },
                "issuer": {
                  "type": "string",
                  "description": "Issuing bank."
                },
                "issuerCountry": {
                  "type": "string",
                  "description": "ISO 3166-1 alpha-2 country of the issuer."
                }
              },
              "required": [
                "number",
                "expiryMonth",
                "expiryYear"
              ],
              "additionalProperties": false
            },
            "network": {
              "type": "object",
              "properties": {
                "tokenType": {
                  "description": "Google Pay token type — `PAN_ONLY` (underlying FPAN) or `CRYPTOGRAM_3DS` (underlying DPAN).",
                  "const": "CRYPTOGRAM_3DS"
                },
                "eci": {
                  "type": "string",
                  "description": "ECI indicator (e.g. `05` for Visa, `02` for Mastercard).",
                  "pattern": "^\\d{2}$"
                },
                "cryptogram": {
                  "type": "string",
                  "description": "Base64-encoded cryptogram (TAVV for Apple Pay, CAVV for Google Pay). Required for customer-initiated transactions."
                }
              },
              "required": [
                "tokenType"
              ],
              "additionalProperties": false
            },
            "storeFutureUsage": {
              "type": "string",
              "description": "Opt-in to saving this card against the customer for future reuse. Requires `customer.id` or `customer.referenceId`.",
              "enum": [
                "on_session",
                "off_session"
              ]
            }
          },
          "required": [
            "type",
            "card",
            "network"
          ],
          "additionalProperties": false,
          "title": "DECRYPTED_GOOGLE_PAY (CRYPTOGRAM_3DS)"
        },
        {
          "type": "object",
          "description": "Submit a merchant-provisioned network token (BYOT). `scheme` is required and must be Visa or Mastercard for customer-initiated transactions; cryptogram is required for customer-initiated transactions.",
          "properties": {
            "type": {
              "const": "NETWORK_TOKEN"
            },
            "card": {
              "type": "object",
              "properties": {
                "number": {
                  "type": "string",
                  "description": "PAN (RAW_PAN), DPAN (Apple Pay / Google Pay CRYPTOGRAM_3DS), FPAN (Google Pay PAN_ONLY), or network token.",
                  "pattern": "^\\d{12,19}$"
                },
                "expiryMonth": {
                  "type": "string",
                  "description": "2-digit month (`01`–`12`).",
                  "pattern": "^(0[1-9]|1[0-2])$"
                },
                "expiryYear": {
                  "type": "string",
                  "description": "4-digit year (e.g. `2028`).",
                  "pattern": "^2\\d{3}$"
                },
                "issuer": {
                  "type": "string",
                  "description": "Issuing bank."
                },
                "issuerCountry": {
                  "type": "string",
                  "description": "ISO 3166-1 alpha-2 country of the issuer."
                },
                "scheme": {
                  "type": "string",
                  "description": "Card scheme. Required and limited to `VISA` or `MASTERCARD` for customer-initiated network token payments; unconstrained for merchant-initiated.",
                  "oneOf": [
                    {
                      "type": "string",
                      "enum": [
                        "VISA",
                        "MASTERCARD",
                        "AMEX",
                        "DISCOVER",
                        "DINERS",
                        "JCB",
                        "CARTES_BANCAIRES"
                      ]
                    },
                    {
                      "type": "string",
                      "enum": [
                        "VISA",
                        "MASTERCARD"
                      ]
                    }
                  ]
                }
              },
              "required": [
                "number",
                "expiryMonth",
                "expiryYear"
              ],
              "additionalProperties": false
            },
            "network": {
              "type": "object",
              "properties": {
                "eci": {
                  "type": "string",
                  "description": "ECI indicator (e.g. `05` for Visa, `02` for Mastercard).",
                  "pattern": "^\\d{2}$"
                },
                "cryptogram": {
                  "type": "string",
                  "description": "Base64-encoded cryptogram (TAVV for Apple Pay, CAVV for Google Pay). Required for customer-initiated transactions."
                }
              },
              "additionalProperties": false
            },
            "storeFutureUsage": {
              "type": "string",
              "description": "Opt-in to saving this card against the customer for future reuse. Requires `customer.id` or `customer.referenceId`.",
              "enum": [
                "on_session",
                "off_session"
              ]
            }
          },
          "required": [
            "type",
            "card"
          ],
          "additionalProperties": false,
          "title": "NETWORK_TOKEN"
        },
        {
          "type": "object",
          "description": "Re-use a payment method previously stored on a Breeze customer via `storeFutureUsage`.",
          "properties": {
            "type": {
              "const": "SAVED_CARD"
            },
            "card": {
              "type": "object",
              "properties": {
                "savedPaymentMethodId": {
                  "type": "string",
                  "description": "Saved payment method identifier (`spm_*`) previously stored on a Breeze customer."
                }
              },
              "required": [
                "savedPaymentMethodId"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "type",
            "card"
          ],
          "additionalProperties": false,
          "title": "SAVED_CARD"
        }
      ]
    },
    "transactionContext": {
      "type": "object",
      "description": "Required for Merchant-Initiated Transactions (MIT). Optional for standard Customer-Initiated Transactions (CIT).",
      "properties": {
        "initiator": {
          "type": "string",
          "description": "`CUSTOMER` for customer-initiated transactions (CIT); `MERCHANT` for merchant-initiated transactions (MIT).",
          "enum": [
            "CUSTOMER",
            "MERCHANT"
          ]
        },
        "mitType": {
          "type": "string",
          "description": "Type of merchant-initiated transaction. Required when `initiator` is `MERCHANT`.",
          "enum": [
            "SUBSCRIPTION",
            "INSTALLMENT",
            "UNSCHEDULED"
          ]
        },
        "originalTransaction": {
          "type": "object",
          "description": "References the original customer-initiated transaction. Optional for MIT, but strongly recommended when available — improves authorization rates and supports dispute defense.",
          "properties": {
            "schemeTransactionId": {
              "type": "string",
              "description": "Scheme transaction ID returned by the card network on the original CIT."
            }
          },
          "required": [
            "schemeTransactionId"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "initiator"
      ],
      "additionalProperties": false
    },
    "threeDs": {
      "description": "3DS authentication results. Required for customer-initiated transactions on `RAW_PAN`, `NETWORK_TOKEN`, and `DECRYPTED_GOOGLE_PAY` `PAN_ONLY`; optional otherwise. Merchant-initiated (MIT) transactions skip 3DS.",
      "oneOf": [
        {
          "type": "object",
          "description": "Merchant-provided 3DS — merchant performs 3DS on their own infrastructure and submits the authentication artefacts.",
          "properties": {
            "mode": {
              "const": "MERCHANT_PROVIDED"
            },
            "version": {
              "type": "string",
              "description": "3DS protocol version, e.g. `2.2.0`."
            },
            "eci": {
              "type": "string",
              "description": "ECI indicator (e.g. `05` for Visa, `02` for Mastercard).",
              "pattern": "^\\d{2}$"
            },
            "authenticationValue": {
              "type": "string",
              "description": "Issuer-returned authentication value (CAVV / AAV)."
            },
            "dsTransactionId": {
              "type": "string",
              "description": "Directory server transaction ID.",
              "minLength": 1,
              "maxLength": 128
            }
          },
          "required": [
            "mode"
          ],
          "additionalProperties": false,
          "title": "MERCHANT_PROVIDED"
        },
        {
          "type": "object",
          "description": "Breeze-hosted 3DS — Breeze handles the 3DS challenge. The payment response will return `status: ACTION_REQUIRED` with a `nextAction.redirectUrl` that you send the shopper to.",
          "properties": {
            "mode": {
              "const": "BREEZE_HOSTED"
            },
            "successReturnUrl": {
              "type": "string",
              "description": "Shopper is redirected here after a successful 3DS challenge.",
              "format": "uri"
            },
            "failReturnUrl": {
              "type": "string",
              "description": "Shopper is redirected here on 3DS failure or abandonment.",
              "format": "uri"
            }
          },
          "required": [
            "mode",
            "successReturnUrl",
            "failReturnUrl"
          ],
          "additionalProperties": false,
          "title": "BREEZE_HOSTED"
        }
      ]
    },
    "risk": {
      "type": "object",
      "description": "Risk signals used for fraud scoring. `sessionId` is required for CIT and omitted for MIT.",
      "properties": {
        "sessionId": {
          "type": "string",
          "description": "Session ID generated by the Breeze Risk SDK. Required for CIT; omitted for MIT (`transactionContext.initiator = MERCHANT`)."
        },
        "ipAddress": {
          "type": "string",
          "description": "Shopper IP address (IPv4 or IPv6).",
          "oneOf": [
            {
              "format": "ipv4"
            },
            {
              "format": "ipv6"
            }
          ]
        },
        "userAgent": {
          "type": "string",
          "description": "Shopper browser User-Agent string."
        },
        "userAgentClientHint": {
          "type": "string",
          "description": "`Sec-CH-UA` client hint string."
        },
        "acceptHeader": {
          "type": "string",
          "description": "Shopper `Accept` header."
        },
        "language": {
          "type": "string",
          "description": "Shopper browser language."
        },
        "timezone": {
          "type": "string",
          "description": "Timezone offset from UTC in minutes (e.g. `-480` for UTC+8).",
          "pattern": "^-?\\d{1,4}$"
        },
        "screenWidth": {
          "type": "integer",
          "description": "Shopper screen width in pixels.",
          "minimum": 0
        },
        "screenHeight": {
          "type": "integer",
          "description": "Shopper screen height in pixels.",
          "minimum": 0
        },
        "colorDepth": {
          "type": "integer",
          "description": "Shopper screen color depth.",
          "minimum": 0
        },
        "javaEnabled": {
          "type": "boolean",
          "description": "Whether the shopper browser has Java enabled."
        },
        "javascriptEnabled": {
          "type": "boolean",
          "description": "Whether the shopper browser has JavaScript enabled."
        },
        "timestamp": {
          "type": "integer",
          "description": "Client-side Unix timestamp in milliseconds when the signals were captured.",
          "minimum": 0
        }
      },
      "additionalProperties": false
    },
    "taxDetails": {
      "type": "object",
      "description": "Merchant-calculated tax included in the all-in customer charge in `amount`. Send the calculated tax as `taxDetails.amount` and its jurisdiction in `taxDetails.location`.",
      "properties": {
        "amount": {
          "type": "integer",
          "description": "Merchant-calculated tax amount, in minor units. Include this value in the top-level `amount`; use `0` when no tax is due. Must satisfy `0 ≤ taxDetails.amount < amount`.",
          "minimum": 0
        },
        "mode": {
          "description": "`merchant_calculated` — merchant computes tax; Breeze remits + files as Merchant of Record.",
          "const": "merchant_calculated"
        },
        "location": {
          "type": "object",
          "description": "Tax jurisdiction nested under `taxDetails`.",
          "properties": {
            "country": {
              "type": "string",
              "description": "ISO 3166-1 alpha-2 country code.",
              "pattern": "^[A-Z]{2}$"
            },
            "postalCode": {
              "type": "string",
              "description": "Postal code used for tax jurisdiction resolution. Required for US and CA; optional for other countries.",
              "minLength": 1
            }
          },
          "required": [
            "country"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "amount",
        "mode",
        "location"
      ],
      "additionalProperties": false
    },
    "metadata": {
      "type": "object",
      "description": "Arbitrary key-value pairs. Max 50 keys, string values only.",
      "properties": {},
      "additionalProperties": false
    }
  },
  "required": [
    "amount",
    "currency",
    "clientReferenceId",
    "customer",
    "paymentMethod"
  ],
  "additionalProperties": false
}