gru_emoney_token-factory/api/packages/openapi/v1/paths/triggers.yaml

paths:
  /triggers:
    get:
      summary: List triggers
      description: List payment rail triggers with filtering
      operationId: listTriggers
      tags:
        - Triggers
      security:
        - oauth2:
            - triggers:read
      parameters:
        - name: state
          in: query
          schema:
            $ref: '../components/schemas.yaml#/components/schemas/TriggerState'
          description: Filter by trigger state
        - name: rail
          in: query
          schema:
            $ref: '../components/schemas.yaml#/components/schemas/Rail'
          description: Filter by payment rail
        - name: msgType
          in: query
          schema:
            type: string
            pattern: '^[a-z]+\\.[0-9]{3}$'
          description: Filter by ISO-20022 message type
        - name: instructionId
          in: query
          schema:
            type: string
            pattern: '^[a-fA-F0-9]{64}$'
          description: Filter by instruction ID
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: List of triggers
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '../components/schemas.yaml#/components/schemas/Trigger'
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer

  /triggers/{triggerId}:
    get:
      summary: Get trigger
      description: Get trigger details by ID
      operationId: getTrigger
      tags:
        - Triggers
      security:
        - oauth2:
            - triggers:read
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/TriggerId'
      responses:
        '200':
          description: Trigger details
          content:
            application/json:
              schema:
                $ref: '../components/schemas.yaml#/components/schemas/Trigger'
        '404':
          $ref: '../openapi.yaml#/components/responses/NotFound'

  /triggers/{triggerId}/validate-and-lock:
    post:
      summary: Validate and lock trigger
      description: Orchestrator step - validate trigger and lock funds
      operationId: validateAndLockTrigger
      tags:
        - Triggers
      security:
        - oauth2:
            - triggers:write
      x-roles:
        - POLICY_OPERATOR
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/TriggerId'
      responses:
        '200':
          description: Trigger validated and locked
          content:
            application/json:
              schema:
                $ref: '../components/schemas.yaml#/components/schemas/Trigger'
        '400':
          $ref: '../openapi.yaml#/components/responses/BadRequest'
        '409':
          $ref: '../openapi.yaml#/components/responses/Conflict'

  /triggers/{triggerId}/mark-submitted:
    post:
      summary: Mark trigger as submitted
      description: Mark trigger as submitted to rail (includes railTxRef)
      operationId: markTriggerSubmitted
      tags:
        - Triggers
      security:
        - oauth2:
            - triggers:write
      x-roles:
        - POLICY_OPERATOR
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/TriggerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - railTxRef
              properties:
                railTxRef:
                  type: string
                  description: Rail transaction reference
      responses:
        '200':
          description: Trigger marked as submitted
          content:
            application/json:
              schema:
                $ref: '../components/schemas.yaml#/components/schemas/Trigger'

  /triggers/{triggerId}/confirm-settled:
    post:
      summary: Confirm trigger settled
      description: Confirm trigger has settled on the rail
      operationId: confirmTriggerSettled
      tags:
        - Triggers
      security:
        - oauth2:
            - triggers:write
      x-roles:
        - POLICY_OPERATOR
      x-idempotency: true
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/TriggerId'
        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Trigger confirmed as settled
          content:
            application/json:
              schema:
                $ref: '../components/schemas.yaml#/components/schemas/Trigger'

  /triggers/{triggerId}/confirm-rejected:
    post:
      summary: Confirm trigger rejected
      description: Confirm trigger was rejected on the rail
      operationId: confirmTriggerRejected
      tags:
        - Triggers
      security:
        - oauth2:
            - triggers:write
      x-roles:
        - POLICY_OPERATOR
      x-idempotency: true
      parameters:
        - $ref: '../components/parameters.yaml#/components/parameters/TriggerId'
        - $ref: '../components/parameters.yaml#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: Rejection reason
      responses:
        '200':
          description: Trigger confirmed as rejected
          content:
            application/json:
              schema:
                $ref: '../components/schemas.yaml#/components/schemas/Trigger'