braintree · Schema

Braintree Transaction

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.

Properties

Name	Type	Description
id	string	Unique identifier for the transaction assigned by Braintree.
amount	string	The transaction amount as a decimal string in the transaction currency.
status	string	The current processing status of the transaction.
type	string	The type of transaction. 'sale' represents a charge and 'credit' represents a refund.
currency_iso_code	string	ISO 4217 three-letter currency code for the transaction.
order_id	string	Merchant-provided order identifier associated with this transaction for reconciliation.
merchant_account_id	string	Identifier of the Braintree merchant account used to process this transaction.
customer_id	string	Identifier of the customer in the Braintree Vault associated with this transaction, if applicable.
payment_method_token	string	Token of the vaulted payment method used for this transaction, if applicable.
payment_method_nonce	string	The one-time payment method nonce used for this transaction, if applicable.
processor_response_code	string	The processor-specific response code returned when the transaction was processed.
processor_response_text	string	Human-readable text description of the processor response code.
gateway_rejection_reason	string	The reason the Braintree gateway rejected the transaction, if applicable.
tax_amount	string	The tax amount included in the transaction total, as a decimal string.
shipping_amount	string	The shipping amount included in the transaction total, as a decimal string.
transaction_source	string	Indicates the origin of the transaction for network reporting requirements.
billing	object	Billing address associated with this transaction.
shipping	object	Shipping address associated with this transaction.
customer_details	object	Summary of the customer associated with this transaction.
credit_card_details	object	Masked credit or debit card details used in this transaction.
descriptor	object	Dynamic descriptor fields that appear on the customer's bank statement.
refund_ids	array	List of transaction identifiers for refund transactions created against this transaction.
refunded_transaction_id	string	For refund transactions, the identifier of the original transaction being refunded.
subscription_id	string	Identifier of the subscription that generated this transaction, if applicable.
line_items	array	Line items for Level 3 processing data, up to 249 items.
disbursement_details	object	Disbursement information for when the transaction funds were or will be sent to the merchant.
created_at	string	Timestamp when the transaction was created, in ISO 8601 format.
updated_at	string	Timestamp when the transaction was last updated, in ISO 8601 format.

View JSON Schema on GitHub

JSON Schema

{
  "$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."
        }
      }
    }
  }
}