> ## 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.

# Execute interceptor

> Submits an acquirer request body to the interceptor identified by `ref`; Specter maps it to a decision and either forwards it (ALLOW) or returns a configured block or review response.



## OpenAPI

````yaml /products/specter/openapi.yaml post /api/interceptors/{ref}
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: 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/interceptors/{ref}:
    post:
      tags:
        - Interceptors
      summary: Execute interceptor
      description: >-
        Submits an acquirer request body to the interceptor identified by `ref`;
        Specter maps it to a decision and either forwards it (ALLOW) or returns
        a configured block or review response.
      operationId: interceptors_execute
      parameters:
        - description: The interceptor's reference
          in: path
          name: ref
          required: true
          schema:
            type: string
        - description: >-
            Payment type declared by the merchant. Controls the initial payment
            state on the decision.
          in: header
          name: payment-type
          required: false
          schema:
            example: authorization-and-capture
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
        description: Acquirer request body
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InterceptorDecisionResponse'
          description: >-
            Interceptor outcome. On ALLOW the merchant's request is forwarded
            and the destination's response is returned verbatim. On BLOCK/REVIEW
            the body is either the configured template response or, in
            `decision` mode, the decision result shown below.
          headers:
            x-specter-decision-id:
              description: UUID of the decision created for this interceptor call
              schema:
                format: uuid
                type: string
              style: simple
            x-specter-interceptor-id:
              description: >-
                UUID of the specific interceptor version that handled the
                request
              schema:
                format: uuid
                type: string
              style: simple
            x-specter-interceptor-version:
              description: Version number of the interceptor that handled the request
              schema:
                type: integer
              style: simple
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
          description: Interceptor not found
      callbacks: {}
      security:
        - bearerAuth: []
components:
  schemas:
    InterceptorDecisionResponse:
      allOf:
        - $ref: '#/components/schemas/DecisionResponse'
        - properties:
            payload:
              example:
                billing:
                  city: Milford
                  country: US
                  postal_code: '03055'
                credential:
                  pan:
                    expiry_month: 7
                    expiry_year: 2029
                    scheme: visa
                    value: '[REDACTED]'
                  type: pan
                customer:
                  id: cust_001
                device:
                  ip: 1.2.3.4
                transaction:
                  amount: 4900
                  currency: EUR
                  reference: ord_001
              description: >-
                Redacted copy of the decision request the interceptor built from
                the inbound body, captured at intercept time. The field mapping
                is applied first, so this is the mapped request rather than the
                raw body, and the ruleset context is omitted. Sensitive values
                are removed, not masked — no partial digits survive. PAN-like
                values (13–19 digits), IBAN-like values, targets mapped from a
                CVC/CVV source or flagged sensitive, and 3–4 digit numbers
                outside a known-safe path are all replaced with the literal
                string `[REDACTED]`. Short numbers at known-safe paths — expiry,
                postal code, amount, item quantity — are kept. Compare
                `masked_credential`, which does mask (`411111 •••••• 4242`).
              type:
                - object
                - 'null'
            payment_state:
              description: >-
                Current payment lifecycle state. Advances as lifecycle events
                are submitted via POST /api/events. "fraud_reported" is a legacy
                value no longer written — fraud is tracked by the fraud marker
                fields, independent of payment_state.
              enum:
                - authorized
                - captured
                - voided
                - fraud_reported
                - chargedback
                - failed
              type:
                - string
                - 'null'
            payment_type:
              description: >-
                Payment type declared by the merchant via the `payment-type`
                request header.
              enum:
                - unknown
                - authorization
                - authorization-and-capture
              type:
                - string
                - 'null'
          type: object
      description: >-
        Decision body returned by the interceptor runtime endpoint when it
        produces a decision (BLOCK or REVIEW in `decision` response mode).
        Identical to the standard decision result plus the interceptor-specific
        `payment_type`, `payment_state`, and `payload` fields.
      title: InterceptorDecisionResponse
    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
    NotFound:
      description: The requested resource does not exist.
      example:
        classifier: NOT_FOUND
        code: 404
        message: The requested resource does not exist
      properties:
        classifier:
          enum:
            - NOT_FOUND
          type: string
        code:
          enum:
            - 404
          type: integer
        message:
          type: string
      required:
        - classifier
        - code
        - message
      title: NotFound
      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'
        device_ip:
          example: 1.2.3.4
          type:
            - string
            - 'null'
        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
          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'
        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
    BackendResult:
      description: Outcome of a single backend rule that was executed.
      properties:
        backend:
          example: vdm
          type: string
        decision:
          enum:
            - ALLOW
            - BLOCK
            - REVIEW
          type:
            - string
            - 'null'
        error:
          example: timeout
          description: >-
            Error code when the backend did not produce a decision.
            "insufficient_context" means required context fields were missing
            and no call was made.
          type:
            - string
            - 'null'
        latency_ms:
          example: 42
          type: integer
        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
          type:
            - object
            - 'null'
        rule_id:
          example: r1
          type: string
      title: BackendResult
      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
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      description: >-
        HS256-signed JWT bearer token, obtained via the OAuth2
        client-credentials grant (see Authentication).
      scheme: bearer
      type: http

````