Affirm Transaction Structure

{
  "$schema": "https://json-structure.org/meta/core/v0/#",
  "$id": "https://raw.githubusercontent.com/api-evangelist/affirm/refs/heads/main/json-structure/affirm-transaction-structure.json",
  "name": "Affirm Transaction",
  "description": "Represents an Affirm payment transaction, capturing the full lifecycle from authorization through capture, refund, and void. Transactions are created by exchanging a checkout token via the Transactions API after a customer completes the Affirm checkout flow.",
  "type": "object",
  "required": [
    "id",
    "status",
    "amount",
    "currency",
    "created"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "A unique identifier representing the transaction, assigned by Affirm upon authorization."
    },
    "checkout_id": {
      "type": "string",
      "description": "A unique identifier referencing the Checkout object that originated this transaction."
    },
    "order_id": {
      "type": "string",
      "description": "Identifies the order within the merchant's order management system, used for reconciliation."
    },
    "status": {
      "type": "string",
      "description": "Current lifecycle state of the transaction.",
      "enum": [
        "authorized",
        "captured",
        "voided",
        "refunded",
        "partially_refunded"
      ]
    },
    "amount": {
      "type": "int32",
      "description": "The original amount financed to the customer, expressed in the smallest currency unit (e.g., cents for USD).",
      "minimum": 0
    },
    "amount_refunded": {
      "type": "int32",
      "description": "The cumulative amount refunded to the customer from this transaction, in the smallest currency unit.",
      "minimum": 0
    },
    "currency": {
      "type": "string",
      "description": "The ISO 4217 currency code for this transaction.",
      "pattern": "^[A-Z]{3}$",
      "examples": [
        "USD",
        "CAD",
        "GBP"
      ]
    },
    "created": {
      "type": "datetime",
      "description": "The timestamp when the transaction was created, in RFC 3339 format."
    },
    "authorization_expiration": {
      "type": "datetime",
      "description": "The timestamp after which the transaction authorization expires and can no longer be captured, in RFC 3339 format."
    },
    "provider_id": {
      "type": "int32",
      "description": "A unique identifier of the financing provider for this transaction."
    },
    "remove_tax": {
      "type": "boolean",
      "description": "Indicates whether tax was paid by the financing provider. Applicable to Affirm Connect integrations only."
    },
    "events": {
      "type": "array",
      "description": "Array of TransactionEvent objects documenting the full history of actions taken on this transaction.",
      "items": {
        "$ref": "#/$defs/TransactionEvent"
      }
    },
    "token": {
      "type": "string",
      "description": "A JWT signing the JSON response body. When PII is included in the response, this token is also encrypted."
    }
  },
  "definitions": {
    "TransactionEvent": {
      "type": "object",
      "description": "A single event in the lifecycle of a transaction documenting an action such as authorization, capture, refund, or void.",
      "required": [
        "id",
        "type",
        "amount",
        "currency",
        "created"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "A unique identifier for this transaction event."
        },
        "type": {
          "type": "string",
          "description": "The type of action represented by this event.",
          "enum": [
            "auth",
            "capture",
            "refund",
            "void",
            "update"
          ]
        },
        "amount": {
          "type": "int32",
          "description": "The monetary amount associated with this event in the smallest currency unit.",
          "minimum": 0
        },
        "currency": {
          "type": "string",
          "description": "The ISO 4217 currency code for this event.",
          "pattern": "^[A-Z]{3}$"
        },
        "fee": {
          "type": "int32",
          "description": "The Affirm transaction fee charged for this event, in the smallest currency unit.",
          "minimum": 0
        },
        "created": {
          "type": "datetime",
          "description": "The timestamp when this event was created, in RFC 3339 format."
        },
        "reference_id": {
          "type": "string",
          "description": "An external reference identifier for this event, such as a merchant capture or refund reference."
        },
        "metadata": {
          "type": "object",
          "description": "Arbitrary key-value metadata associated with this event.",
          "additionalProperties": {
            "type": "string"
          }
        }
      },
      "name": "TransactionEvent"
    },
    "SettlementEvent": {
      "type": "object",
      "description": "A disbursement line item from Affirm to the merchant, associated with a specific transaction event.",
      "required": [
        "id",
        "transaction_id",
        "amount",
        "currency",
        "created"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "A unique identifier for this settlement event."
        },
        "transaction_id": {
          "type": "string",
          "description": "The identifier of the transaction this settlement event is associated with."
        },
        "transaction_event_id": {
          "type": "string",
          "description": "The identifier of the specific transaction event that triggered this settlement."
        },
        "amount": {
          "type": "int32",
          "description": "The net disbursement amount in the smallest currency unit."
        },
        "currency": {
          "type": "string",
          "description": "The ISO 4217 currency code for this settlement.",
          "pattern": "^[A-Z]{3}$"
        },
        "created": {
          "type": "datetime",
          "description": "Timestamp when this settlement event was created, in RFC 3339 format."
        },
        "type": {
          "type": "string",
          "description": "The type of settlement event, corresponding to the originating transaction action.",
          "enum": [
            "capture",
            "refund",
            "void"
          ]
        }
      },
      "name": "SettlementEvent"
    }
  }
}