List, retrieve, then reverse (cancel) a card refund.

arazzo: 1.0.0
info:
  title: Reverse a refund
  summary: Find a card refund, retrieve it, then cancel (reverse) it while it is
    in an open batch.
  description: |
    Cancel an existing card refund (created via a referenced or unreferenced refund) while it is still in an open batch, so no funds are returned to the cardholder. Read-then-act: list refunds with filters, take a result, retrieve it to confirm the action is permitted, then reverse it.
    Agent gotchas captured by this workflow:
      - List responses are paginated: refunds live in the `data` array alongside
        `count`, `hasMore`, and `limit`. To act on a result, reach into
        `data/0/refundId` - not a top-level field. On a single retrieved refund,
        `refundId` IS top-level.
      - `reverseRefund` cancels the refund while it is in an open batch, removing
        it so no funds are returned - after a reverse, `transactionResult.status`
        is `reversal`.
      - The list/retrieve operations are GET (200). reverse is POST (200, not
        201) and requires a unique `Idempotency-Key` header in UUID v4 format.

    To change a refund's status or customer details instead of canceling it, use the adjust-a-refund workflow. To reverse a bank-transfer refund, use the reverse-a-bank-transfer-refund workflow.
  version: 1.0.0
sourceDescriptions:
  - name: payroc-api
    url: /openapi.yaml
    type: openapi
workflows:
  - workflowId: reverse-a-refund
    x-actors:
      - id: merchant
        name: Merchant / integrator
        type: client
        description: Calls the Payroc API to find, inspect, and reverse the refund.
      - id: payroc-gateway
        name: Payroc gateway
        type: api
        description: The Payroc API surface these steps call.
    summary: List, retrieve, then reverse (cancel) a card refund.
    description: |
      Find the card refund (listRefunds -> getRefund), confirm from the retrieved refund's `transactionResult.status` that it is still reversible, then reverse it (reverseRefund). The list and retrieve steps are optional when you already hold the refundId.
    inputs:
      type: object
      required:
        - processingTerminalId
        - idempotencyKey
      properties:
        processingTerminalId:
          type: string
          description: Processing terminal to filter the refund list by.
          example: "1234001"
        orderId:
          type: string
          description: Filter refunds by the order identifier the merchant assigned.
          example: OrderRef6543
        status:
          type: string
          description: |
            Filter the list by refund status. Only a refund in an open batch can be reversed.
          example: ready
        dateFrom:
          type: string
          format: date-time
          description: Return refunds processed on or after this ISO 8601 timestamp.
          example: 2024-07-01T15:30:00Z
        limit:
          type: integer
          description: Maximum number of refunds to return per page.
          example: 2
        idempotencyKey:
          type: string
          description: |
            Unique UUID v4 you generate for the reverse request, sent as the `Idempotency-Key` header.
          example: f32c9ad6-c97f-4998-9356-f3b6718b1b68
    steps:
      - stepId: listRefunds
        x-actor: merchant
        x-actor-to: payroc-gateway
        x-label: refund search
        description: |
          OPTIONAL — list card refunds filtered by terminal, order, status, and date. The response is paginated - refunds are in the `data` array. This step extracts the first refund's `refundId` for the follow-on steps.
        operationId: listRefunds
        parameters:
          - name: processingTerminalId
            in: query
            value: $inputs.processingTerminalId
          - name: orderId
            in: query
            value: $inputs.orderId
          - name: status
            in: query
            value: $inputs.status
          - name: dateFrom
            in: query
            value: $inputs.dateFrom
          - name: limit
            in: query
            value: $inputs.limit
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          firstRefundId: $response.body#/data/0/refundId
          hasMore: $response.body#/hasMore
      - stepId: getRefund
        x-actor: merchant
        x-actor-to: payroc-gateway
        x-label: refund lookup
        description: |
          OPTIONAL — retrieve the full detail of the first card refund from the list. Inspect `supportedOperations` and `transactionResult.status` to confirm the refund can be reversed before acting.
        operationId: getRefund
        parameters:
          - name: refundId
            in: path
            value: $steps.listRefunds.outputs.firstRefundId
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          refundId: $response.body#/refundId
          status: $response.body#/transactionResult/status
          supportedOperations: $response.body#/supportedOperations
      - stepId: reverseRefund
        x-actor: merchant
        x-actor-to: payroc-gateway
        x-label: reversal request
        description: |
          Cancel the card refund while it is in an open batch using the `refundId` from getRefund; no funds are returned to the cardholder. Requires a unique `Idempotency-Key` header. Returns 200 with `transactionResult.status` == `reversal`.
        operationId: reverseRefund
        parameters:
          - name: Idempotency-Key
            in: header
            value: $inputs.idempotencyKey
          - name: refundId
            in: path
            value: $steps.getRefund.outputs.refundId
        successCriteria:
          - condition: $statusCode == 200
          - condition: $response.body#/transactionResult/status == 'reversal'
        outputs:
          refundId: $response.body#/refundId
          status: $response.body#/transactionResult/status
    outputs:
      refundId: $steps.reverseRefund.outputs.refundId
      status: $steps.reverseRefund.outputs.status