TransactionRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/braintree/json-schema/braintree-transaction-request-schema.json",
  "title": "TransactionRequest",
  "description": "Request body for creating a new payment transaction. Either payment_method_nonce, payment_method_token, or customer_id is required.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/braintree-transactions-api-openapi.yml#/components/schemas/TransactionRequest",
  "type": "object",
  "properties": {
    "amount": {
      "type": "string",
      "description": "The billing amount for the transaction as a decimal string. Must be greater than 0 and match the currency decimal format."
    },
    "payment_method_nonce": {
      "type": "string",
      "description": "A one-time-use reference to payment information collected by the Braintree client SDK. Consumed upon transaction creation."
    },
    "payment_method_token": {
      "type": "string",
      "description": "The token of a vaulted payment method to charge for this transaction."
    },
    "customer_id": {
      "type": "string",
      "description": "The identifier of a customer whose default vaulted payment method will be used for this transaction.",
      "maxLength": 36
    },
    "order_id": {
      "type": "string",
      "description": "A merchant-defined order identifier associated with this transaction for reconciliation.",
      "maxLength": 255
    },
    "merchant_account_id": {
      "type": "string",
      "description": "The identifier of the merchant account to process this transaction. If omitted, the default merchant account is used."
    },
    "device_data": {
      "type": "string",
      "description": "Customer device data string collected by the Braintree data collector for fraud prevention analysis."
    },
    "descriptor": {
      "$ref": "#/$defs/Descriptor"
    },
    "billing": {
      "$ref": "#/$defs/Address"
    },
    "shipping": {
      "$ref": "#/$defs/Address"
    },
    "options": {
      "$ref": "#/$defs/TransactionOptions"
    },
    "tax_amount": {
      "type": "string",
      "description": "The tax amount included in the transaction total for Level 2 and Level 3 processing."
    },
    "shipping_amount": {
      "type": "string",
      "description": "The shipping amount included in the transaction total for Level 3 processing."
    },
    "customer": {
      "$ref": "#/$defs/CustomerRequest"
    },
    "line_items": {
      "type": "array",
      "description": "Line items for Level 3 processing. Up to 249 line items may be included.",
      "maxItems": 249,
      "items": {
        "$ref": "#/$defs/LineItem"
      }
    },
    "transaction_source": {
      "type": "string",
      "description": "Indicates the origin of this transaction for network reporting.",
      "enum": [
        "recurring",
        "recurring_first",
        "unscheduled",
        "moto"
      ]
    }
  },
  "$defs": {
    "Address": {
      "type": "object",
      "description": "A billing or shipping address associated with a transaction or customer.",
      "properties": {
        "first_name": {
          "type": "string",
          "description": "First name of the address holder.",
          "maxLength": 255
        },
        "last_name": {
          "type": "string",
          "description": "Last name of the address holder.",
          "maxLength": 255
        },
        "company": {
          "type": "string",
          "description": "Company or organization name at this address.",
          "maxLength": 255
        },
        "street_address": {
          "type": "string",
          "description": "Primary street address line.",
          "maxLength": 255
        },
        "extended_address": {
          "type": "string",
          "description": "Secondary address line such as apartment or suite number.",
          "maxLength": 255
        },
        "locality": {
          "type": "string",
          "description": "City or locality of the address.",
          "maxLength": 255
        },
        "region": {
          "type": "string",
          "description": "State, province, or region code of the address.",
          "maxLength": 255
        },
        "postal_code": {
          "type": "string",
          "description": "Postal or ZIP code of the address.",
          "maxLength": 9
        },
        "country_code_alpha2": {
          "type": "string",
          "description": "Two-letter ISO 3166-1 alpha-2 country code.",
          "pattern": "^[A-Z]{2}$"
        }
      }
    },
    "CustomerRequest": {
      "type": "object",
      "description": "Request body for creating or updating a customer record in the Braintree Vault. All fields are optional.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Custom customer identifier. If omitted, Braintree generates a unique ID. Alphanumeric, hyphens, and underscores only.",
          "maxLength": 36,
          "pattern": "^[a-zA-Z0-9_-]+$"
        },
        "first_name": {
          "type": "string",
          "description": "Customer's first name.",
          "maxLength": 255
        },
        "last_name": {
          "type": "string",
          "description": "Customer's last name.",
          "maxLength": 255
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Customer's email address. ASCII characters only.",
          "maxLength": 255
        },
        "phone": {
          "type": "string",
          "description": "Customer's phone number.",
          "maxLength": 255
        },
        "company": {
          "type": "string",
          "description": "Customer's company or organization name.",
          "maxLength": 255
        },
        "website": {
          "type": "string",
          "format": "uri",
          "description": "Customer's website URL. Must be a well-formed URL.",
          "maxLength": 255
        },
        "fax": {
          "type": "string",
          "description": "Customer's fax number.",
          "maxLength": 255
        },
        "payment_method_nonce": {
          "type": "string",
          "description": "A one-time nonce representing a payment method to vault for the customer at creation time."
        },
        "custom_fields": {
          "type": "object",
          "description": "Custom key-value pairs. Keys must be pre-configured in the Braintree Control Panel.",
          "additionalProperties": {
            "type": "string"
          }
        }
      }
    },
    "Descriptor": {
      "type": "object",
      "description": "Dynamic descriptor fields that appear on the customer's bank or credit card statement to identify the merchant and transaction.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Merchant name as it appears on the customer's statement. Maximum 22 characters total; name and phone combined must be 22 characters or less with an asterisk separator.",
          "maxLength": 22
        },
        "phone": {
          "type": "string",
          "description": "Merchant phone number as it appears on the customer's statement. Must be 10–14 digits.",
          "maxLength": 14
        },
        "url": {
          "type": "string",
          "description": "Merchant URL as it appears on the customer's statement. Maximum 13 characters.",
          "maxLength": 13
        }
      }
    },
    "LineItem": {
      "type": "object",
      "description": "A line item representing a single product or service in a transaction, used for Level 3 processing data.",
      "required": [
        "name",
        "quantity",
        "unit_amount",
        "total_amount",
        "kind"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Name or description of the product or service.",
          "maxLength": 127
        },
        "description": {
          "type": "string",
          "description": "Additional description of the line item.",
          "maxLength": 127
        },
        "kind": {
          "type": "string",
          "description": "Whether this item is a debit (charge) or credit (discount).",
          "enum": [
            "debit",
            "credit"
          ]
        },
        "quantity": {
          "type": "string",
          "description": "Quantity of the line item as a decimal string."
        },
        "unit_amount": {
          "type": "string",
          "description": "Unit price of the line item as a decimal string."
        },
        "total_amount": {
          "type": "string",
          "description": "Total amount for this line item (quantity * unit_amount) as a decimal."
        },
        "unit_of_measure": {
          "type": "string",
          "description": "Unit of measure for the quantity, such as \"each\" or \"kg\".",
          "maxLength": 12
        },
        "commodity_code": {
          "type": "string",
          "description": "Commodity code for Level 3 processing.",
          "maxLength": 12
        },
        "tax_amount": {
          "type": "string",
          "description": "Tax amount for this line item as a decimal string."
        }
      }
    },
    "TransactionOptions": {
      "type": "object",
      "description": "Configuration options that modify transaction processing behavior.",
      "properties": {
        "submit_for_settlement": {
          "type": "boolean",
          "description": "If true, the transaction is automatically submitted for settlement after authorization. Defaults to false.",
          "default": false
        },
        "store_in_vault": {
          "type": "boolean",
          "description": "If true, the payment method is stored in the Braintree Vault after the transaction is created.",
          "default": false
        },
        "store_in_vault_on_success": {
          "type": "boolean",
          "description": "If true, the payment method is stored in the Vault only if the transaction is successfully authorized.",
          "default": false
        },
        "skip_avs": {
          "type": "boolean",
          "description": "Skip the address verification check for this transaction.",
          "default": false
        },
        "skip_cvv": {
          "type": "boolean",
          "description": "Skip the CVV verification check for this transaction.",
          "default": false
        },
        "hold_in_escrow": {
          "type": "boolean",
          "description": "If true, funds are held in escrow rather than disbursed immediately. Applicable to Braintree Marketplace transactions only.",
          "default": false
        }
      }
    }
  }
}