{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://api-evangelist.github.io/braintree/schemas/transaction.json",
  "title": "Braintree Transaction",
  "description": "Represents a payment transaction processed through the Braintree gateway. A transaction captures the full lifecycle from authorization through settlement, refund, or void, and supports credit and debit cards, PayPal, Apple Pay, Google Pay, Venmo, ACH, and SEPA payment methods.",
  "type": "object",
  "required": ["id", "amount", "status", "type"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the transaction assigned by Braintree.",
      "minLength": 1
    },
    "amount": {
      "type": "string",
      "description": "The transaction amount as a decimal string in the transaction currency.",
      "pattern": "^\\d+\\.\\d{2}$",
      "example": "10.00"
    },
    "status": {
      "type": "string",
      "description": "The current processing status of the transaction.",
      "enum": [
        "authorization_expired",
        "authorized",
        "authorizing",
        "settlement_confirmed",
        "settlement_declined",
        "settlement_pending",
        "settled",
        "settling",
        "submitted_for_settlement",
        "voided",
        "processor_declined",
        "failed",
        "gateway_rejected"
      ]
    },
    "type": {
      "type": "string",
      "description": "The type of transaction. 'sale' represents a charge and 'credit' represents a refund.",
      "enum": ["sale", "credit"]
    },
    "currency_iso_code": {
      "type": "string",
      "description": "ISO 4217 three-letter currency code for the transaction.",
      "pattern": "^[A-Z]{3}$",
      "example": "USD"
    },
    "order_id": {
      "type": "string",
      "description": "Merchant-provided order identifier associated with this transaction for reconciliation.",
      "maxLength": 255
    },
    "merchant_account_id": {
      "type": "string",
      "description": "Identifier of the Braintree merchant account used to process this transaction."
    },
    "customer_id": {
      "type": "string",
      "description": "Identifier of the customer in the Braintree Vault associated with this transaction, if applicable.",
      "maxLength": 36
    },
    "payment_method_token": {
      "type": "string",
      "description": "Token of the vaulted payment method used for this transaction, if applicable."
    },
    "payment_method_nonce": {
      "type": "string",
      "description": "The one-time payment method nonce used for this transaction, if applicable."
    },
    "processor_response_code": {
      "type": "string",
      "description": "The processor-specific response code returned when the transaction was processed.",
      "pattern": "^\\d{4}$"
    },
    "processor_response_text": {
      "type": "string",
      "description": "Human-readable text description of the processor response code."
    },
    "gateway_rejection_reason": {
      "type": "string",
      "description": "The reason the Braintree gateway rejected the transaction, if applicable.",
      "enum": [
        "avs",
        "avs_and_cvv",
        "cvv",
        "duplicate",
        "fraud",
        "risk_threshold",
        "three_d_secure",
        "token_issuance",
        "application_incomplete"
      ]
    },
    "tax_amount": {
      "type": "string",
      "description": "The tax amount included in the transaction total, as a decimal string.",
      "pattern": "^\\d+\\.\\d{2}$"
    },
    "shipping_amount": {
      "type": "string",
      "description": "The shipping amount included in the transaction total, as a decimal string.",
      "pattern": "^\\d+\\.\\d{2}$"
    },
    "transaction_source": {
      "type": "string",
      "description": "Indicates the origin of the transaction for network reporting requirements.",
      "enum": ["recurring", "recurring_first", "unscheduled", "moto"]
    },
    "billing": {
      "$ref": "#/$defs/Address",
      "description": "Billing address associated with this transaction."
    },
    "shipping": {
      "$ref": "#/$defs/Address",
      "description": "Shipping address associated with this transaction."
    },
    "customer_details": {
      "$ref": "#/$defs/CustomerSummary",
      "description": "Summary of the customer associated with this transaction."
    },
    "credit_card_details": {
      "$ref": "#/$defs/CreditCardDetails",
      "description": "Masked credit or debit card details used in this transaction."
    },
    "descriptor": {
      "$ref": "#/$defs/Descriptor",
      "description": "Dynamic descriptor fields that appear on the customer's bank statement."
    },
    "refund_ids": {
      "type": "array",
      "description": "List of transaction identifiers for refund transactions created against this transaction.",
      "items": {
        "type": "string",
        "description": "Unique identifier of a refund transaction."
      }
    },
    "refunded_transaction_id": {
      "type": "string",
      "description": "For refund transactions, the identifier of the original transaction being refunded."
    },
    "subscription_id": {
      "type": "string",
      "description": "Identifier of the subscription that generated this transaction, if applicable."
    },
    "line_items": {
      "type": "array",
      "description": "Line items for Level 3 processing data, up to 249 items.",
      "maxItems": 249,
      "items": {
        "$ref": "#/$defs/LineItem"
      }
    },
    "disbursement_details": {
      "$ref": "#/$defs/DisbursementDetails",
      "description": "Disbursement information for when the transaction funds were or will be sent to the merchant."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp when the transaction was created, in ISO 8601 format."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp when the transaction was last updated, in ISO 8601 format."
    }
  },
  "$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}$"
        },
        "country_name": {
          "type": "string",
          "description": "Full country name.",
          "maxLength": 255
        }
      }
    },
    "CustomerSummary": {
      "type": "object",
      "description": "A summary of the customer associated with a transaction.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier of the customer in the Braintree Vault.",
          "maxLength": 36
        },
        "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.",
          "maxLength": 255
        },
        "phone": {
          "type": "string",
          "description": "Customer's phone number.",
          "maxLength": 255
        },
        "company": {
          "type": "string",
          "description": "Customer's company or organization name.",
          "maxLength": 255
        }
      }
    },
    "CreditCardDetails": {
      "type": "object",
      "description": "Masked credit or debit card details used in a transaction.",
      "properties": {
        "bin": {
          "type": "string",
          "description": "First six digits of the card number, identifying the issuing bank and card type.",
          "pattern": "^\\d{6}$"
        },
        "last_4": {
          "type": "string",
          "description": "Last four digits of the card number.",
          "pattern": "^\\d{4}$"
        },
        "card_type": {
          "type": "string",
          "description": "The card network or brand.",
          "enum": [
            "American Express",
            "Carte Blanche",
            "China UnionPay",
            "Diners Club",
            "Discover",
            "Elo",
            "JCB",
            "Laser",
            "Maestro",
            "MasterCard",
            "Solo",
            "Switch",
            "Visa",
            "Unknown"
          ]
        },
        "expiration_month": {
          "type": "string",
          "description": "Two-digit expiration month of the card.",
          "pattern": "^(0[1-9]|1[0-2])$"
        },
        "expiration_year": {
          "type": "string",
          "description": "Four-digit expiration year of the card.",
          "pattern": "^\\d{4}$"
        },
        "cardholder_name": {
          "type": "string",
          "description": "Name of the cardholder as it appears on the card.",
          "maxLength": 175
        },
        "country_of_issuance": {
          "type": "string",
          "description": "Two-letter ISO 3166-1 country code of the card-issuing country.",
          "pattern": "^[A-Z]{2}$"
        },
        "token": {
          "type": "string",
          "description": "Vault token for this card if it was stored during the transaction."
        }
      }
    },
    "Descriptor": {
      "type": "object",
      "description": "Dynamic descriptor fields that appear on the cardholder's bank or credit card statement.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Merchant name as it appears on the customer's statement. Maximum 22 characters.",
          "maxLength": 22
        },
        "phone": {
          "type": "string",
          "description": "Merchant phone number as it appears on the customer's statement. 10–14 digits.",
          "maxLength": 14,
          "pattern": "^\\d{10,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 single product or service line item included 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/refund).",
          "enum": ["debit", "credit"]
        },
        "quantity": {
          "type": "string",
          "description": "Quantity of the line item as a decimal string.",
          "pattern": "^\\d+\\.\\d{4}$",
          "example": "1.0000"
        },
        "unit_amount": {
          "type": "string",
          "description": "Unit price of the line item as a decimal string.",
          "pattern": "^\\d+\\.\\d{2}$",
          "example": "5.00"
        },
        "total_amount": {
          "type": "string",
          "description": "Total amount for this line item (quantity × unit_amount) as a decimal string.",
          "pattern": "^\\d+\\.\\d{2}$",
          "example": "5.00"
        },
        "unit_of_measure": {
          "type": "string",
          "description": "Unit of measure for the quantity, such as 'each', 'kg', or 'oz'.",
          "maxLength": 12
        },
        "commodity_code": {
          "type": "string",
          "description": "Commodity code identifying the type of goods for Level 3 processing.",
          "maxLength": 12
        },
        "tax_amount": {
          "type": "string",
          "description": "Tax amount for this line item as a decimal string.",
          "pattern": "^\\d+\\.\\d{2}$"
        },
        "discount_amount": {
          "type": "string",
          "description": "Discount amount applied to this line item as a decimal string.",
          "pattern": "^\\d+\\.\\d{2}$"
        },
        "product_code": {
          "type": "string",
          "description": "Merchant-defined product code or SKU for this line item.",
          "maxLength": 12
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL for the product page of this line item."
        }
      }
    },
    "DisbursementDetails": {
      "type": "object",
      "description": "Details about the disbursement of transaction funds to the merchant's bank account.",
      "properties": {
        "disbursement_date": {
          "type": "string",
          "format": "date",
          "description": "Date on which the funds were or will be disbursed to the merchant."
        },
        "settlement_amount": {
          "type": "string",
          "description": "Amount that was or will be disbursed, in the settlement currency.",
          "pattern": "^\\d+\\.\\d{2}$"
        },
        "settlement_currency_iso_code": {
          "type": "string",
          "description": "ISO 4217 currency code of the settlement currency.",
          "pattern": "^[A-Z]{3}$"
        },
        "funds_held": {
          "type": "boolean",
          "description": "If true, the funds are being held and not yet disbursed to the merchant."
        }
      }
    }
  }
}