CheckoutListResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/depixapp-com/json-schema/depixapp-com-checkout-list-response-schema.json",
  "title": "CheckoutListResponse",
  "description": "Paginated checkout list with aggregate stats.",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/depixapp-com-openapi.yml#/components/schemas/CheckoutListResponse",
  "type": "object",
  "required": [
    "checkouts",
    "stats",
    "limit",
    "offset"
  ],
  "additionalProperties": false,
  "properties": {
    "checkouts": {
      "type": "array",
      "description": "Checkout rows, newest first.",
      "items": {
        "type": "object",
        "description": "Checkout list item.",
        "required": [
          "id",
          "status",
          "amount",
          "description",
          "created_at",
          "expires_at",
          "is_live",
          "processing_at",
          "approved_at",
          "metadata",
          "product_name",
          "rejection_reasons"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "Checkout id (chk_*)."
          },
          "status": {
            "$ref": "#/$defs/CheckoutStatus"
          },
          "amount": {
            "type": "integer",
            "description": "Charge amount in cents."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Checkout description."
          },
          "created_at": {
            "type": "string",
            "description": "Creation timestamp (RFC 3339 UTC)."
          },
          "expires_at": {
            "type": "string",
            "description": "QR expiry timestamp (RFC 3339 UTC)."
          },
          "is_live": {
            "type": "integer",
            "description": "1 = live, 0 = sandbox (raw SQLite boolean).",
            "enum": [
              0,
              1
            ]
          },
          "processing_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the checkout entered processing (null if never)."
          },
          "approved_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "When the checkout was approved (null if never)."
          },
          "metadata": {
            "type": [
              "string",
              "null"
            ],
            "description": "Merchant metadata as the raw stored JSON string (not parsed on the list endpoint)."
          },
          "product_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Name of the linked product (null for generic checkouts)."
          },
          "payment_method": {
            "$ref": "#/$defs/PaymentMethod",
            "description": "The rail this checkout was created on."
          },
          "depix_discount_pct": {
            "type": [
              "integer",
              "null"
            ],
            "description": "depix rail only: the discount percentage applied to this checkout (0–90). Null on the pix rail."
          },
          "depix_due_cents": {
            "type": [
              "integer",
              "null"
            ],
            "description": "depix rail only: the discounted, uniqueness-adjusted amount in cents that had to arrive (and did, once settled — attribution is exact-match). This, not `amount` (the face value), is what the merchant received. Null on the pix rail."
          },
          "rejection_reasons": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Provider reasons for a refunded/held payment on the underlying deposit — e.g. PAYER_MISMATCH, PAST_DAILY_LIMIT, BLOCKED_USER, HIGH_VELOCITY. Empty array when the payment was not refused. New reason codes may appear; display unknown codes as-is."
          },
          "payer_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Name the provider reports for whoever paid, off the underlying deposit. Null while the sale is unpaid, on the depix rail (no Pix payer to name), and on any sale the provider settled without one."
          },
          "blockchain_tx_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Liquid txid that settled this sale, on either rail. Null until the money lands — and for a short while after, on the pix rail, when the provider reports the txid in a later callback than the one that completed the sale."
          },
          "delay_until": {
            "type": [
              "string",
              "null"
            ],
            "description": "When this sale's money is released, if it is being held. Same RFC 3339 UTC instant as every other timestamp here (`\"2026-08-13T12:03:00.000Z\"`). Non-null only once the provider has answered with a date, so a sale that is held right now still reads null for a while; it also stays set after the money lands, so it is a hold RECORD, not a live flag. Pair it with `status`: a sale still waiting sits in `processing`. Never a reason — what triggered the hold is not published."
          },
          "vault_hours": {
            "type": [
              "integer",
              "null"
            ],
            "description": "How many hours this sale was booked to wait when it was created. `0` means the hold policy looked at it and imposed no wait. **Null is not zero**: it means no hold decision was recorded against this sale at all — a sandbox checkout (no paired deposit exists), a row created before the mechanism shipped, or one created while the mechanism was switched off. Today the vast majority of rows read null. Use it as an answer to WHETHER, never to WHEN: the real wait starts when the payer pays, not when the sale was created, so `created_at + vault_hours` lands EARLY and must not be presented as a release date. `delay_until` is the only date."
          }
        }
      }
    },
    "stats": {
      "type": "object",
      "description": "Aggregates over the CURRENT FILTER (not just the current page).",
      "required": [
        "total",
        "pending",
        "completed",
        "completed_amount"
      ],
      "additionalProperties": false,
      "properties": {
        "total": {
          "type": "integer",
          "description": "Total checkouts matching the filter."
        },
        "pending": {
          "type": "integer",
          "description": "Checkouts currently pending."
        },
        "completed": {
          "type": "integer",
          "description": "Checkouts completed."
        },
        "completed_amount": {
          "type": "integer",
          "description": "Sum of completed amounts in cents."
        }
      }
    },
    "limit": {
      "type": "integer",
      "description": "Applied page size (1–100)."
    },
    "offset": {
      "type": "integer",
      "description": "Applied offset."
    }
  },
  "$defs": {
    "CheckoutStatus": {
      "type": "string",
      "description": "Checkout lifecycle status — the enum below is the complete, closed set. `completed` is the terminal SUCCESS state. Terminal states (safe to stop polling): completed, expired, cancelled.",
      "enum": [
        "pending",
        "processing",
        "approved",
        "completed",
        "expired",
        "cancelled"
      ],
      "oneOf": [
        {
          "const": "pending",
          "description": "Awaiting payment; the PIX QR is active until expires_at."
        },
        {
          "const": "processing",
          "description": "PIX paid; settlement in progress."
        },
        {
          "const": "approved",
          "description": "Payment approved by the provider; DePix on the way to the merchant."
        },
        {
          "const": "completed",
          "description": "TERMINAL — success: DePix delivered to the merchant.",
          "x-terminal": true
        },
        {
          "const": "expired",
          "description": "TERMINAL — QR expired unpaid.",
          "x-terminal": true
        },
        {
          "const": "cancelled",
          "description": "TERMINAL — cancelled upstream by the provider (refund/error).",
          "x-terminal": true
        }
      ]
    },
    "PaymentMethod": {
      "type": "string",
      "enum": [
        "pix",
        "depix"
      ],
      "description": "Which rail settles the checkout. `pix` (default): the payer pays a PIX QR and the provider delivers DePix to the merchant. `depix`: the payer sends DePix wallet-to-wallet on Liquid to an address dedicated to this merchant, and settlement is observed on-chain — no PIX QR exists on this rail."
    }
  }
}