> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create decision

> Evaluate a payload and receive an `ALLOW`, `REVIEW`, or `BLOCK` decision. If an asynchronous backend rule is involved, the response is `PROVISIONAL` and updated later.

`context` selects the active ruleset, and the ruleset's bound [schema](/products/specter/concepts/schemas) defines the payload. The body below is the built-in `transaction` schema; a context bound to a custom schema takes that schema's fields in the same envelope. The payload validates against the schema before any rule runs — shape, required fields, and each field's type rule — and a failure returns `422` naming the path without echoing regulated values. Below PCI level `SAQ_D`, a payload carrying `pci-pan` or `pci-sad` fields rejects with `422`.




## OpenAPI

````yaml /products/specter/openapi.yaml post /api/decisions
openapi: 3.1.0
info:
  contact:
    email: support@hellgate.io
    name: Starfish GmbH & Co. KG
    url: https://hellgate.io/cpa/specter
  description: Composable decision engine and fraud prevention service.
  license:
    name: Hellgate API Terms
    url: https://hellgate.io/terms-and-conditions
  title: Specter API
  version: '1.0'
servers:
  - description: Managed instance of Specter
    url: https://{instance}.{env}.on-hellgate.cloud
    variables:
      instance:
        default: my-instance
        description: Your unique instance slug, provided during onboarding.
      env:
        default: eu1
        description: Deployment environment (currently eu1).
security: []
tags:
  - description: Evaluate transactions and retrieve decision results.
    name: Decisions
  - description: Close decisions that were flagged for manual review.
    name: Resolutions
  - description: Report payment lifecycle events for a prior decision.
    name: Lifecycle Events
  - description: Manage rulesets and their activation lifecycle.
    name: Rulesets
  - description: Register and version custom decision-payload schemas.
    name: Schemas
  - description: Configure interceptors and intercept live payment requests.
    name: Interceptors
  - description: Subscribe to decision and event notifications.
    name: Webhooks
  - description: Manage blocked field values.
    name: Blacklist
paths:
  /api/decisions:
    post:
      tags:
        - Decisions
      summary: Create decision
      description: >
        Evaluate a payload and receive an `ALLOW`, `REVIEW`, or `BLOCK`
        decision. If an asynchronous backend rule is involved, the response is
        `PROVISIONAL` and updated later.


        `context` selects the active ruleset, and the ruleset's bound
        [schema](/products/specter/concepts/schemas) defines the payload. The
        body below is the built-in `transaction` schema; a context bound to a
        custom schema takes that schema's fields in the same envelope. The
        payload validates against the schema before any rule runs — shape,
        required fields, and each field's type rule — and a failure returns
        `422` naming the path without echoing regulated values. Below PCI level
        `SAQ_D`, a payload carrying `pci-pan` or `pci-sad` fields rejects with
        `422`.
      operationId: decisions_create
      parameters: []
      requestBody:
        content:
          application/json:
            examples:
              full:
                summary: Full payload
                value:
                  billing:
                    address1: 96 Powers Street
                    city: Milford
                    country: US
                    first_name: James
                    last_name: Smith
                    postal_code: '03055'
                    state: NH
                  context: checkout
                  credential:
                    pan:
                      cardholder_name: Sherlock Holmes
                      expiry_month: 12
                      expiry_year: 2031
                      value: '4111111111111111'
                    type: pan
                  customer:
                    id: cust_001
                    email: sherlock@example.com
                    first_name: Sherlock
                    last_name: Holmes
                  device:
                    fingerprint: fp_vdm_test
                    ip: 1.2.3.4
                    language: en-GB
                  items:
                    - categories:
                        - Accessories
                        - Smoking
                      name: Calabash Pipe
                      price: 4900
                      product_type: physical
                      quantity: 1
                      sku: PIPE-001
                  metadata:
                    campaign: spring_2026
                    channel: web
                  shipping:
                    carrier: DHL
                    method: STANDARD
                  transaction:
                    amount: 4900
                    currency: USD
                    reference: ord_001
              masked_pan:
                summary: Masked PAN
                value:
                  context: checkout
                  credential:
                    masked_pan:
                      expiry_month: 12
                      expiry_year: 2026
                      first_six: '411111'
                      last_four: '1111'
                    type: masked_pan
                  customer:
                    id: cust_123
                  device:
                    fingerprint: fp_abc123
                    ip: 1.2.3.4
                  transaction:
                    amount: 5000
                    currency: EUR
                    reference: txn_abc
              pan:
                summary: Full PAN
                value:
                  context: checkout
                  credential:
                    pan:
                      expiry_month: 7
                      expiry_year: 2029
                      value: '4111111111111111'
                    type: pan
                  customer:
                    id: cust_001
                  device:
                    fingerprint: fp_abc123
                    ip: 1.2.3.4
                  transaction:
                    amount: 4900
                    currency: EUR
                    reference: ord_001
              sepa:
                summary: SEPA direct debit
                value:
                  context: checkout
                  credential:
                    sepa:
                      iban: DE89370400440532013000
                      owner_name: John Doe
                    type: sepa
                  customer:
                    id: cust_001
                  transaction:
                    amount: 1800
                    currency: EUR
                    reference: txn_001
            schema:
              $ref: '#/components/schemas/DecisionRequest'
        description: Decision request
        required: true
      responses:
        '201':
          content:
            application/json:
              examples:
                allow:
                  summary: ALLOW — no rules matched
                  value:
                    id: 9f1c8e2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b
                    backend_results: []
                    context: checkout
                    credential_fingerprint: crd_4ba2188f9c1e
                    credential_type: pan
                    decision: ALLOW
                    evaluated_at: '2026-06-02T12:00:00Z'
                    events: []
                    has_backend_error: false
                    latency_us: 4250
                    masked_credential: 411111 •••••• 1111
                    resolution: null
                    ruleset_id: 1f2e3d4c-5b6a-4978-8c0d-1e2f3a4b5c6d
                    ruleset_version: 3
                    source: RULE_ENGINE
                    triggered_rules: []
                block:
                  summary: BLOCK — terminating rule matched
                  value:
                    id: a3f9c7d1-2e4b-4a6c-8f0d-9b1a3c5e7d2f
                    backend_results: []
                    context: checkout
                    credential_fingerprint: crd_4ba2188f9c1e
                    credential_type: pan
                    decision: BLOCK
                    evaluated_at: '2026-06-02T12:00:00Z'
                    events: []
                    has_backend_error: false
                    latency_us: 3800
                    masked_credential: 411111 •••••• 1111
                    resolution: null
                    ruleset_id: 1f2e3d4c-5b6a-4978-8c0d-1e2f3a4b5c6d
                    ruleset_version: 3
                    source: RULE_ENGINE
                    triggered_rules:
                      - action: BLOCK
                        name: Block USD
                        rule_id: r1
                review:
                  summary: REVIEW — flagged for manual review
                  value:
                    id: 7c2b1a90-8d7e-4f6c-9b5a-3e2d1c0b9a8f
                    backend_results: []
                    context: checkout
                    credential_fingerprint: crd_4ba2188f9c1e
                    credential_type: pan
                    decision: REVIEW
                    evaluated_at: '2026-06-02T12:00:00Z'
                    events: []
                    has_backend_error: false
                    latency_us: 5100
                    masked_credential: 411111 •••••• 1111
                    resolution: null
                    ruleset_id: 1f2e3d4c-5b6a-4978-8c0d-1e2f3a4b5c6d
                    ruleset_version: 3
                    source: RULE_ENGINE
                    triggered_rules:
                      - action: REVIEW
                        name: Review high EUR amount
                        rule_id: r3
              schema:
                $ref: '#/components/schemas/DecisionResponse'
          description: Decision result
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrors'
          description: >-
            Validation errors — the payload validates against the (schema,
            version) bound by the context's active ruleset before any rule
            evaluates. Entries name the offending field path and violated
            constraint; offending values of pii / pci-pan / pci-sad scoped
            fields are never echoed.
      callbacks: {}
      security:
        - bearerAuth: []
components:
  schemas:
    DecisionRequest:
      example:
        billing:
          address1: 96 Powers Street
          city: Milford
          country: US
          first_name: James
          last_name: Smith
          postal_code: '03055'
          state: NH
        context: checkout
        credential:
          pan:
            expiry_month: 7
            expiry_year: 2029
            value: '4111111111111111'
          type: pan
        customer:
          id: cust_001
          first_name: Sherlock
          last_name: Holmes
        device:
          fingerprint: fp_abc123
          ip: 1.2.3.4
          language: en-GB
        items:
          - name: Calabash Pipe
            price: 2500
            product_type: physical
            quantity: 1
            sku: PIPE-001
        metadata:
          channel: web
        shipping:
          carrier: DHL
          method: STANDARD
        transaction:
          amount: 4900
          currency: EUR
          reference: ord_001
      properties:
        airline:
          $ref: '#/components/schemas/Airline'
        billing:
          description: Billing address for the transaction
          properties:
            address1:
              example: 96 Powers Street
              type: string
              x-data-classification: pii
            address2:
              type: string
              x-data-classification: pii
            city:
              example: Milford
              type: string
              x-data-classification: pii
            country:
              example: US
              type: string
              x-data-classification: pii
            email:
              example: test@example.com
              type: string
              x-data-classification: pii
            first_name:
              example: James
              type: string
              x-data-classification: pii
            last_name:
              example: Smith
              type: string
              x-data-classification: pii
            phone:
              description: E.164 format
              example: '+17606160717'
              type: string
              x-data-classification: pii
            postal_code:
              example: '03055'
              type: string
              x-data-classification: pii
            state:
              example: NH
              type: string
              x-data-classification: pii
          type: object
        context:
          description: Ruleset context key. Defaults to "default" if omitted.
          example: checkout
          type: string
        credential:
          $ref: '#/components/schemas/Credential'
        customer:
          properties:
            id:
              description: Stable merchant-assigned customer identifier
              example: cust_001
              minLength: 1
              type: string
              x-data-classification: pii
            date_of_birth:
              description: ISO 8601 date
              example: '1854-01-06'
              type: string
              x-data-classification: pii
            email:
              example: sherlock.holmes@example.com
              type: string
              x-data-classification: pii
            first_name:
              example: Sherlock
              type: string
              x-data-classification: pii
            last_name:
              example: Holmes
              type: string
              x-data-classification: pii
            name:
              example: Sherlock Holmes
              type: string
              x-data-classification: pii
            phone:
              description: E.164 format
              example: '+442031234321'
              type: string
              x-data-classification: pii
            registration_time:
              description: ISO 8601 datetime
              example: '2024-01-15T10:00:00Z'
              type: string
          required:
            - id
          type: object
        device:
          properties:
            fingerprint:
              example: fp_abc123
              type: string
              x-data-classification: pii
            ip:
              example: 1.2.3.4
              type: string
              x-data-classification: pii
            language:
              example: en-GB
              type: string
            session_id:
              type: string
            user_agent:
              type: string
          type: object
        items:
          description: Cart / order line items
          items:
            $ref: '#/components/schemas/Item'
          type: array
        metadata:
          additionalProperties:
            type: string
          description: >-
            Flat key-value pairs stored alongside the decision. Available to
            rules as `$.metadata.*` and forwarded to backends, so treat it as
            data you share with your backend providers.
          example:
            campaign: spring_2026
            channel: web
          type: object
        shipping:
          description: Shipping address for the transaction
          properties:
            address1:
              example: 96 Powers Street
              type: string
              x-data-classification: pii
            address2:
              type: string
              x-data-classification: pii
            address3:
              type: string
              x-data-classification: pii
            carrier:
              example: DHL
              type: string
            city:
              example: Milford
              type: string
              x-data-classification: pii
            country:
              example: US
              type: string
              x-data-classification: pii
            destination_code:
              type: string
            destination_types:
              items:
                type: string
              type: array
            first_name:
              example: James
              type: string
              x-data-classification: pii
            last_name:
              example: Smith
              type: string
              x-data-classification: pii
            method:
              type: string
            middle_name:
              type: string
              x-data-classification: pii
            phone:
              description: E.164 format
              example: '+17606160717'
              type: string
              x-data-classification: pii
            postal_code:
              example: '03055'
              type: string
              x-data-classification: pii
            state:
              example: NH
              type: string
              x-data-classification: pii
          type: object
        transaction:
          properties:
            amount:
              description: Amount in minor currency units
              example: 4900
              minimum: 0
              type: integer
            currency:
              description: ISO 4217 currency code
              example: EUR
              type: string
            reference:
              description: Merchant order or transaction reference
              example: ord_001
              minLength: 1
              type: string
          required:
            - reference
            - amount
            - currency
          type: object
      required:
        - credential
        - customer
        - transaction
      title: DecisionRequest
      type: object
    DecisionResponse:
      description: Result of evaluating a transaction against the active ruleset.
      properties:
        id:
          example: 1e7b9c0a-2d43-4f6a-8d29-c4a1f2d05b3e
          description: Unique decision identifier
          format: uuid
          type: string
        amount:
          example: 5000
          type:
            - integer
            - 'null'
        backend_results:
          description: One entry per backend rule that was executed.
          items:
            $ref: '#/components/schemas/BackendResult'
          type: array
        context:
          example: checkout
          type: string
        credential_fingerprint:
          description: Deterministic HMAC-SHA256 payment credential identifier
          example: crd_4ba218...
          type: string
        credential_type:
          description: Type of credential supplied in the request
          enum:
            - pan
            - masked_pan
            - sepa
            - paypal
          type:
            - string
            - 'null'
        currency:
          example: USD
          type:
            - string
            - 'null'
        customer_id:
          example: customer-123
          type:
            - string
            - 'null'
        decision:
          description: >-
            BLOCK terminates on first match. REVIEW accumulates. ALLOW is the
            default when no rules match.
          enum:
            - ALLOW
            - BLOCK
            - REVIEW
            - PROVISIONAL
          type: string
        device_fingerprint:
          example: fp-9c1e4b7a
          type:
            - string
            - 'null'
          x-data-classification: pii
        device_ip:
          example: 1.2.3.4
          type:
            - string
            - 'null'
          x-data-classification: pii
        evaluated_at:
          example: '2026-06-01T10:00:00Z'
          format: date-time
          type: string
        events:
          description: Always empty on a freshly evaluated decision.
          items:
            properties:
              id:
                format: uuid
                type: string
              occurred_at:
                example: '2026-06-01T10:04:00Z'
                format: date-time
                type: string
              processed_at:
                example: '2026-06-01T10:04:02Z'
                format: date-time
                type: string
              type:
                enum:
                  - authorization
                  - capture
                  - refund
                  - void
                  - chargeback
                  - fraud_report
                  - failed
                type: string
            type: object
          type: array
        has_backend_error:
          example: false
          description: >-
            True if any backend_results entry carries a non-nil error (e.g.
            "backend_capability_disabled").
          type: boolean
        integration:
          example: interceptor
          description: Integration type that originated this decision (e.g. 'interceptor')
          type:
            - string
            - 'null'
        interceptor_id:
          example: null
          description: ID of the interceptor that originated this decision
          format: uuid
          type:
            - string
            - 'null'
        latency_us:
          example: 4250
          type: integer
        masked_credential:
          description: >-
            Display-safe masked representation, e.g. '411111 •••••• 4242' for
            cards or 's•••@example.com' for PayPal. Identifies nobody on its
            own, so it carries no classification marker and is not subject to
            retention.
          example: 411111 •••••• 4242
          type:
            - string
            - 'null'
        metadata:
          example:
            order_ref: X36Q9C
          additionalProperties:
            type: string
          description: Merchant-supplied key-value pairs stored with the decision.
          type:
            - object
            - 'null'
        resolution:
          description: Always null on a freshly evaluated decision.
          properties:
            action:
              enum:
                - ACCEPTED
                - REJECTED
              type: string
            resolved_at:
              example: '2026-06-01T11:30:00Z'
              format: date-time
              type: string
          type:
            - object
            - 'null'
        ruleset_id:
          example: 6c1f4e8b-9a2d-4c7e-b5f3-8d1a6e9c4b2f
          format: uuid
          type:
            - string
            - 'null'
        ruleset_version:
          example: 7
          type:
            - integer
            - 'null'
        schema:
          $ref: '#/components/schemas/SchemaBinding'
          description: >-
            The (schema, version) the decision was evaluated against — the
            resolved ruleset's binding.
        source:
          description: >-
            RULE_ENGINE — condition rules only. BACKEND — backend rule(s) only.
            COMBINED — both.
          enum:
            - RULE_ENGINE
            - BACKEND
            - COMBINED
          type: string
        transaction_reference:
          example: X36Q9C
          type:
            - string
            - 'null'
        triggered_rules:
          items:
            $ref: '#/components/schemas/TriggeredRule'
          type: array
      title: DecisionResponse
      type: object
    Unauthorized:
      description: No valid authentication was provided.
      example:
        classifier: UNAUTHORIZED
        code: 401
        message: No valid means of authentication was provided
      properties:
        classifier:
          enum:
            - UNAUTHORIZED
          type: string
        code:
          enum:
            - 401
          type: integer
        message:
          type: string
      required:
        - classifier
        - code
        - message
      title: Unauthorized
      type: object
    Forbidden:
      description: The token lacks the scope required for this operation.
      example:
        classifier: FORBIDDEN
        code: 403
        message: Not allowed to access this resource or feature
      properties:
        classifier:
          enum:
            - FORBIDDEN
          type: string
        code:
          enum:
            - 403
          type: integer
        message:
          type: string
      required:
        - classifier
        - code
        - message
      title: Forbidden
      type: object
    ValidationErrors:
      description: Response shape for request validation failures
      example:
        classifier: VALIDATION_ERROR
        code: 422
        validation_errors:
          - message: must be a positive integer
            path: limit
      properties:
        classifier:
          example: VALIDATION_ERROR
          type: string
        code:
          example: 422
          type: integer
        validation_errors:
          items:
            properties:
              message:
                example: must be a positive integer
                type: string
              path:
                example: limit
                type: string
            type: object
          type: array
      required:
        - classifier
        - code
        - validation_errors
      title: ValidationErrors
      type: object
    Airline:
      description: Airline / travel industry data. Present only for airline transactions.
      properties:
        booking_code:
          description: PNR / booking reference
          example: X36Q9C
          type: string
        issuing_carrier:
          description: IATA carrier code
          example: LH
          type: string
        legs:
          items:
            properties:
              arrival_airport:
                example: JFK
                description: IATA airport code
                type: string
              arrival_at:
                example: '2026-07-01T15:30:00Z'
                description: ISO 8601 datetime
                type: string
              carrier_code:
                example: BA
                description: IATA carrier code
                type: string
              departure_airport:
                example: LHR
                description: IATA airport code
                type: string
              departure_at:
                example: '2026-07-01T12:05:00Z'
                description: ISO 8601 datetime
                type: string
              fare_amount:
                example: 48500
                description: Fare in minor currency units
                type: integer
              flight_class:
                example: 'Y'
                description: Booking class (e.g. Y, J, F)
                type: string
              flight_number:
                example: '117'
                type: string
              route_type:
                enum:
                  - one_way
                  - round_trip
                  - multi_city
                type: string
              stop_over:
                example: false
                type: boolean
            type: object
          type: array
        passengers:
          items:
            properties:
              country_code:
                example: US
                description: ISO 3166-1 alpha-2
                type: string
                x-data-classification: pii
              date_of_birth:
                example: '1985-04-12'
                description: ISO 8601 date
                type: string
                x-data-classification: pii
              email:
                example: james.smith@example.com
                type: string
                x-data-classification: pii
              first_name:
                example: James
                type: string
                x-data-classification: pii
              frequent_flyer_number:
                example: BA47210983
                type: string
                x-data-classification: pii
              last_name:
                example: Smith
                type: string
                x-data-classification: pii
              phone:
                example: '+16035550117'
                type: string
                x-data-classification: pii
              ticket_number:
                example: '1252310889087'
                type: string
            type: object
          type: array
        restricted_ticket:
          example: false
          description: Whether the ticket is non-refundable
          type: boolean
        ticket_number:
          example: 220-1234567890
          type: string
        travel_agency_code:
          example: '45812976'
          description: Travel agency IATA code
          type: string
        travel_agency_name:
          example: Example Travel
          type: string
      title: Airline
      type: object
    Credential:
      description: >-
        Payment credential the decision is made about. `type` selects the
        variant; the sibling object of the same name carries the credential
        data. Send exactly one variant.
      discriminator:
        mapping:
          masked_pan:
            $ref: '#/components/schemas/MaskedPanCredential'
          pan:
            $ref: '#/components/schemas/PanCredential'
          paypal:
            $ref: '#/components/schemas/PaypalCredential'
          sepa:
            $ref: '#/components/schemas/SepaCredential'
        propertyName: type
      oneOf:
        - $ref: '#/components/schemas/PanCredential'
        - $ref: '#/components/schemas/MaskedPanCredential'
        - $ref: '#/components/schemas/SepaCredential'
        - $ref: '#/components/schemas/PaypalCredential'
      title: Credential
    Item:
      description: >-
        A cart / order line item. At least one of `name` or `sku` is required; a
        line item carrying neither rejects with 422.
      example:
        categories:
          - Accessories
          - Smoking
        name: Calabash Pipe
        price: 2500
        product_type: physical
        quantity: 1
        sku: PIPE-001
      properties:
        categories:
          description: Product category hierarchy
          example:
            - Accessories
            - Smoking
          items:
            type: string
          type: array
        discount_amount:
          description: Discount on this line item in minor currency units
          example: 0
          type: integer
        name:
          description: Product name
          example: Calabash Pipe
          type: string
        price:
          description: Unit price in minor currency units
          example: 2500
          type: integer
        product_type:
          description: Product type — critical fraud signal
          enum:
            - physical
            - digital
            - service
          example: physical
          type: string
        product_url:
          description: URL to the product page
          example: https://shop.example.com/pipe-001
          type: string
        quantity:
          description: Quantity ordered
          example: 1
          type: integer
        sku:
          description: Product SKU
          example: PIPE-001
          type: string
        tax_amount:
          description: Tax on this line item in minor currency units
          example: 0
          type: integer
        upc:
          example: '012345678905'
          description: Universal Product Code
          type: string
      anyOf:
        - required:
            - name
        - required:
            - sku
      title: Item
      type: object
    BackendResult:
      description: Outcome of a single backend rule that was executed.
      properties:
        backend:
          example: vdm
          type: string
        backend_reference:
          example: dec-xyz
          description: >-
            The backend's own reference for this evaluation, mirrored from the
            response body so it stays addressable when the raw body is not
            served — it survives the body's retention window. Null when the
            backend supplied none.
          type:
            - string
            - 'null'
        decision:
          enum:
            - ALLOW
            - BLOCK
            - REVIEW
          type:
            - string
            - 'null'
        error:
          example: timeout
          description: >-
            Error code when the backend did not produce a decision.
            `insufficient_context` — required context fields were missing and no
            call was made. `guard_not_met` — the rule's `condition` was false or
            unevaluable and the call was skipped. `backend_capability_disabled`
            — the Link backend capability is off for this instance.
            `backend_disabled` — the Link backend is disabled and rejected the
            call. `not_simulated` — simulation only, no call made.
          type:
            - string
            - 'null'
        latency_ms:
          example: 42
          description: >-
            Round-trip latency of the call. Null where no call was made and none
            was attributed — a simulated backend rule renders "not_simulated"
            with no latency.
          type:
            - integer
            - 'null'
        link_execution_id:
          example: 3f8b2d16-71c4-4d29-a5e2-6b9c0d4f7a21
          description: >-
            Execution ID from the Link integration. Present only for Link-backed
            backends.
          type:
            - string
            - 'null'
        link_timing:
          description: >-
            Server-Timing breakdown in milliseconds, parsed from the backend
            response. Present only for Link-backed backends.
          properties:
            external:
              example: 120.5
              type: number
            internal:
              example: 8.2
              type: number
            total:
              example: 128.7
              type: number
          type:
            - object
            - 'null'
        live:
          example: true
          description: Whether the backend ran live (true) or in shadow mode (false).
          type: boolean
        missing_fields:
          example:
            - device.ip
            - billing.postal_code
          description: >-
            Dot-notation paths of required context fields that were absent.
            Populated only when error is "insufficient_context".
          items:
            type: string
          type:
            - array
            - 'null'
        raw_response:
          example:
            status: ACCEPTED
            id: dec-xyz
          description: >-
            The backend's own response body, scrubbed of values recognised as
            credentials. Null once any configured retention window has passed —
            the shape is the backend's, so no classification marker resolves a
            scope inside it and the whole body goes on the strictest configured
            window.
          type:
            - object
            - 'null'
        rule_id:
          example: r1
          type: string
      title: BackendResult
      type: object
    SchemaBinding:
      description: >-
        A ruleset's declared (schema, version) pair. name references a registry
        entry; version is required for custom schemas and absent for built-ins,
        whose version is implicit and advances only via Specter releases. Set at
        ruleset creation and immutable for the life of that ruleset version —
        rebinding a context means publishing a new ruleset version with the new
        binding and activating it. Rulesets that predate the registry surface
        the launch-backfilled transaction binding.
      properties:
        name:
          example: transaction
          type: string
        version:
          description: Registry version for custom schemas. Absent for built-in schemas.
          example: 1
          type:
            - integer
            - 'null'
      required:
        - name
      title: SchemaBinding
      type: object
    TriggeredRule:
      properties:
        action:
          enum:
            - BLOCK
            - REVIEW
          example: BLOCK
          type:
            - string
            - 'null'
        name:
          example: Block USD
          type:
            - string
            - 'null'
        rule_id:
          example: r1
          type: string
        type:
          enum:
            - condition
            - blacklist
            - backend
            - backend_group
          example: condition
          type: string
      title: TriggeredRule
      type: object
    MaskedPanCredential:
      description: Masked PAN credential — the truncated form, carrying no full PAN.
      properties:
        masked_pan:
          description: >-
            Carries seven optional BIN attributes (bin, schemes, type, segment,
            currency_code, issuer_name, issuer_country_code) — caller-composed
            issuance metadata named verbatim after Guardian's metadata-inquiry
            response. Specter never fetches, derives or cross-checks them; all
            seven are any-scoped, never required, and available on every
            instance tier.
          properties:
            bin:
              description: >-
                BIN prefix, caller-supplied — Specter performs no derivation
                from first_six and no consistency check.
              example: '411111'
              type: string
            currency_code:
              description: Card default currency, ISO 4217 (3-letter uppercase strict).
              example: EUR
              type: string
            expiry_month:
              example: 7
              maximum: 12
              minimum: 1
              type: integer
            expiry_year:
              description: Four-digit expiry year
              example: 2029
              type: integer
            first_six:
              description: >-
                First 6 digits of the PAN (BIN/IIN). Exactly six — an 8-digit
                prefix rejects with 422.
              example: '411111'
              maxLength: 6
              minLength: 6
              type: string
              x-data-classification: pii
            issuer_country_code:
              description: >-
                Issuer country, ISO 3166-1 alpha-2 — 2-letter uppercase strict;
                lowercase, 3-letter and numeric forms reject.
              example: US
              type: string
            issuer_name:
              description: >-
                Issuing-bank name, free string — no canonicalization, no
                consistency check.
              example: Example Bank N.A.
              type: string
            last_four:
              description: Last 4 digits of the PAN
              example: '1111'
              maxLength: 4
              minLength: 4
              type: string
              x-data-classification: pii
            schemes:
              description: >-
                Card scheme(s); co-branded cards carry several. Elements
                validate case-sensitively against the Guardian-aligned closed
                enum; an empty array is permitted (rules over it abstain). Rules
                take membership via `in` — comparing a string operand against
                this array rejects at submission.
              example:
                - visa
                - cartes bancaires
              items:
                enum:
                  - visa
                  - mastercard
                  - american express
                  - discover
                  - diners club
                  - jcb
                  - unionpay
                  - cartes bancaires
                  - airplus
                type: string
              type: array
            segment:
              description: Card segment.
              enum:
                - consumer
                - commercial
              type: string
            type:
              description: Funding type.
              enum:
                - credit
                - debit
                - prepaid
                - charge
                - deferred
                - unknown
              type: string
          required:
            - first_six
            - last_four
          type: object
        type:
          const: masked_pan
          description: Credential type
          type: string
      required:
        - type
        - masked_pan
      title: Masked PAN
      type: object
    PanCredential:
      description: >-
        Full PAN credential. The enclosing structure stays PCI-PAN-gated by its
        pan-typed `value` field regardless of which sub-fields are populated.
      properties:
        pan:
          description: >-
            Carries seven optional BIN attributes (bin, schemes, type, segment,
            currency_code, issuer_name, issuer_country_code) — caller-composed
            issuance metadata named verbatim after Guardian's metadata-inquiry
            response. Specter never fetches, derives or cross-checks them; all
            seven are any-scoped, never required, and available on every
            instance tier. Nothing is reconciled against `value`.
          properties:
            bin:
              description: >-
                BIN prefix, caller-supplied — Specter performs no derivation
                from value and no consistency check.
              example: '411111'
              type: string
            cardholder_name:
              description: Name as printed on the card
              example: Sherlock Holmes
              type: string
              x-data-classification: pii
            currency_code:
              description: Card default currency, ISO 4217 (3-letter uppercase strict).
              example: EUR
              type: string
            expiry_month:
              example: 7
              maximum: 12
              minimum: 1
              type: integer
            expiry_year:
              description: Four-digit expiry year
              example: 2029
              type: integer
            issuer_country_code:
              description: >-
                Issuer country, ISO 3166-1 alpha-2 — 2-letter uppercase strict;
                lowercase, 3-letter and numeric forms reject.
              example: US
              type: string
            issuer_name:
              description: >-
                Issuing-bank name, free string — no canonicalization, no
                consistency check.
              example: Example Bank N.A.
              type: string
            schemes:
              description: >-
                Card scheme(s); co-branded cards carry several. Elements
                validate case-sensitively against the Guardian-aligned closed
                enum; an empty array is permitted (rules over it abstain). Rules
                take membership via `in` — comparing a string operand against
                this array rejects at submission.
              example:
                - visa
                - cartes bancaires
              items:
                enum:
                  - visa
                  - mastercard
                  - american express
                  - discover
                  - diners club
                  - jcb
                  - unionpay
                  - cartes bancaires
                  - airplus
                type: string
              type: array
            segment:
              description: Card segment.
              enum:
                - consumer
                - commercial
              type: string
            type:
              description: Funding type.
              enum:
                - credit
                - debit
                - prepaid
                - charge
                - deferred
                - unknown
              type: string
            value:
              description: >-
                Full PAN — never persisted, only the HMAC-SHA256 fingerprint is
                stored
              example: '4111111111111111'
              type: string
              x-data-classification: pci-pan
          required:
            - value
            - expiry_month
            - expiry_year
          type: object
        type:
          const: pan
          description: Credential type
          type: string
      required:
        - type
        - pan
      title: Full PAN
      type: object
    PaypalCredential:
      description: PayPal credential.
      properties:
        paypal:
          description: >-
            All five fields are optional — they become available at different
            stages of the PayPal flow, so send whichever you have captured. All
            are caller-injected from the merchant's PayPal flow (e.g.
            Cybersource PayPal Express Checkout); Specter performs no PayPal
            lookup. Enum values are canonical lowercase snake_case.
          properties:
            address_status:
              description: PayPal address verification status (source field addressStatus)
              enum:
                - none
                - confirmed
                - unconfirmed
              example: confirmed
              type: string
            email:
              description: >-
                PayPal account email (source field paypalCustomerEmail). Never
                persisted raw; only a masked form appears in the decision log.
              example: sherlock.holmes@example.com
              type: string
              x-data-classification: pii
            payer_id:
              description: >-
                PayPal payer ID / account number (source field paypalPayerId).
                Source of the credential fingerprint, so a decision without it
                has no credential_fingerprint and does not participate in
                velocity counting or blacklist entries keyed on that path.
              example: 7E7MGXCWTTKK2
              minLength: 1
              type: string
              x-data-classification: pii
            payer_status:
              description: PayPal account verification status (source field payerStatus)
              enum:
                - verified
                - unverified
              example: verified
              type: string
            protection_eligibility:
              description: >-
                Seller protection eligibility (source field
                protectionEligibility). Returned by PayPal only after
                authorization, so a pre-authorization decision usually cannot
                carry it.
              enum:
                - eligible
                - partially_eligible
                - ineligible
              example: eligible
              type: string
          type: object
        type:
          const: paypal
          description: Credential type
          type: string
      required:
        - type
        - paypal
      title: PayPal
      type: object
    SepaCredential:
      description: SEPA direct debit credential.
      properties:
        sepa:
          description: Bank account identified by IBAN.
          properties:
            iban:
              description: Account IBAN — never persisted, only the fingerprint is stored
              example: DE89370400440532013000
              type: string
              x-data-classification: pii
            owner_name:
              description: Account holder name
              example: John Doe
              type: string
              x-data-classification: pii
          required:
            - iban
            - owner_name
          type: object
        type:
          const: sepa
          description: Credential type
          type: string
      required:
        - type
        - sepa
      title: SEPA Direct Debit
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      description: >-
        HS256-signed JWT bearer token, obtained via the OAuth2
        client-credentials grant (see Authentication).
      scheme: bearer
      type: http

````