Transaction

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/griffnode-com/json-schema/griffnode-com-transaction-schema.json",
  "title": "Transaction",
  "description": "The canonical, curated public view of a transaction (same shape from create, get and list). Internal fields (capability tokens, client_ip, address_index, derivation/db internals) are deliberately NOT exposed.\n",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/griffnode-com-api-openapi.yml#/components/schemas/Transaction",
  "type": "object",
  "required": [
    "transaction_id",
    "status",
    "crypto",
    "amount_fiat",
    "amount_usd",
    "currency_fiat",
    "created_at",
    "expires_at"
  ],
  "properties": {
    "transaction_id": {
      "type": "string"
    },
    "status": {
      "$ref": "#/$defs/TransactionStatus"
    },
    "exception": {
      "$ref": "#/$defs/TransactionException"
    },
    "type": {
      "type": "string",
      "enum": [
        "basic",
        "detailed"
      ]
    },
    "crypto": {
      "$ref": "#/$defs/CryptoSymbol"
    },
    "deposit_address": {
      "type": "string"
    },
    "amount_crypto": {
      "type": "number"
    },
    "amount_fiat": {
      "type": "number"
    },
    "amount_usd": {
      "type": "number"
    },
    "amount_paid": {
      "type": "number"
    },
    "amount_remaining": {
      "type": "number"
    },
    "currency_fiat": {
      "$ref": "#/$defs/FiatCurrency"
    },
    "fiat_to_usd_rate": {
      "type": "number"
    },
    "exchange_rate": {
      "type": "number",
      "description": "USD per unit of crypto, locked at creation."
    },
    "confirmations_required": {
      "type": "integer"
    },
    "payment_url": {
      "type": "string",
      "format": "uri"
    },
    "order_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "customer_email": {
      "type": [
        "string",
        "null"
      ]
    },
    "items": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/LineItem"
      }
    },
    "payments": {
      "type": "array",
      "description": "On-chain payments detected toward this transaction.",
      "items": {
        "$ref": "#/$defs/PaymentSplit"
      }
    },
    "metadata": {
      "$ref": "#/$defs/Metadata"
    },
    "success_url": {
      "type": [
        "string",
        "null"
      ]
    },
    "cancel_url": {
      "type": [
        "string",
        "null"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "test": {
      "type": "boolean",
      "description": "Present and true only on a test-mode transaction (sk_test_ key, TTX- id)."
    }
  },
  "$defs": {
    "CryptoSymbol": {
      "type": "string",
      "description": "Supported coin/token symbol. /cryptos/list is authoritative at runtime.",
      "enum": [
        "BTC",
        "LTC",
        "DOGE",
        "DASH",
        "ETH",
        "USDT",
        "USDC",
        "EURC",
        "DAI",
        "WBTC",
        "WETH",
        "SHIB",
        "PEPE",
        "LINK",
        "UNI",
        "LEO"
      ]
    },
    "FiatCurrency": {
      "type": "string",
      "enum": [
        "USD",
        "PLN",
        "EUR",
        "GBP"
      ],
      "default": "USD"
    },
    "LineItem": {
      "type": "object",
      "required": [
        "name",
        "price"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "quantity": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        },
        "price": {
          "type": "number"
        }
      }
    },
    "Metadata": {
      "type": [
        "object",
        "null"
      ],
      "description": "Free-form key/value (≤20 keys, string values ≤500 chars, ≤4 KB total).",
      "additionalProperties": {
        "type": "string"
      }
    },
    "PaymentSplit": {
      "type": "object",
      "description": "One on-chain payment toward the transaction.",
      "properties": {
        "txid": {
          "type": "string",
          "description": "On-chain transaction hash (blockchain id, NOT the GriffNode transaction_id)."
        },
        "amount_crypto": {
          "type": "number"
        },
        "confirmations": {
          "type": "integer"
        },
        "status": {
          "type": "string"
        },
        "detected_at": {
          "type": "string",
          "format": "date-time"
        },
        "confirmed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      }
    },
    "TransactionException": {
      "type": "string",
      "description": "Present only when the payment waits for the merchant's decision. paid_late: coins arrived within 6h after the window closed (status stays expired; complete it with Mark as paid in the dashboard, which also sends payment.completed). needs_review: ETH/ERC-20 deposit address balance dropped while open, payment unknown (status pending).\n",
      "enum": [
        "paid_late",
        "needs_review"
      ]
    },
    "TransactionStatus": {
      "type": "string",
      "description": "Public transaction status (internal sub-states are mapped to these).",
      "enum": [
        "pending",
        "awaiting_confirmation",
        "completed",
        "partial",
        "expired",
        "failed"
      ]
    }
  }
}