Tamara Order Status Refund

arazzo: 1.0.1
info:
  title: Tamara Order Status Refund
  summary: Read an order's status and refund it only when funds have been captured.
  description: >-
    Safely refunds a Tamara order by first reading its status and branching on the
    order lifecycle. A refund is only valid once funds have been captured, so the
    workflow refunds when the order is fully or partially captured and ends without
    calling refund otherwise. This prevents refund attempts against orders that are
    still merely authorised or already fully refunded. Every step spells out its
    request inline so the flow can be read and executed without opening the
    underlying OpenAPI descriptions.
  version: 1.0.0
sourceDescriptions:
- name: ordersApi
  url: ../openapi/tamara-orders-api-openapi.yml
  type: openapi
- name: paymentsApi
  url: ../openapi/tamara-payments-api-openapi.yml
  type: openapi
workflows:
- workflowId: order-status-refund
  summary: Refund a Tamara order only when its status shows funds were captured.
  description: >-
    Reads an order's status and issues a simplified refund only when the order is
    fully or partially captured.
  inputs:
    type: object
    required:
    - merchantToken
    - orderId
    - refundAmount
    - refundComment
    properties:
      merchantToken:
        type: string
        description: Tamara-issued merchant API bearer token.
      orderId:
        type: string
        description: The Tamara order_id (uuid) to inspect and refund.
      refundAmount:
        type: object
        description: Money object (amount + currency) to refund.
      refundComment:
        type: string
        description: Reason/comment recorded against the refund.
      merchantRefundId:
        type: string
        description: Optional merchant-side refund id for idempotency/reconciliation.
  steps:
  - stepId: getOrder
    description: >-
      Read the order so the workflow can branch on whether funds have been captured
      (fully_captured or partially_captured) before refunding.
    operationId: getOrderDetails
    parameters:
    - name: order_id
      in: path
      value: $inputs.orderId
    - name: Authorization
      in: header
      value: "Bearer $inputs.merchantToken"
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      orderStatus: $response.body#/status
      capturedAmount: $response.body#/captured_amount
    onSuccess:
    - name: fullyCaptured
      type: goto
      stepId: refund
      criteria:
      - context: $response.body
        condition: $.status == "fully_captured"
        type: jsonpath
    - name: partiallyCaptured
      type: goto
      stepId: refund
      criteria:
      - context: $response.body
        condition: $.status == "partially_captured"
        type: jsonpath
    - name: notRefundable
      type: end
      criteria:
      - context: $response.body
        condition: $.status != "fully_captured" && $.status != "partially_captured"
        type: jsonpath
  - stepId: refund
    description: >-
      Process a partial or full refund against the captured order using the modern
      simplified-refund surface (no capture ids required).
    operationId: simplifiedRefund
    parameters:
    - name: order_id
      in: path
      value: $inputs.orderId
    - name: Authorization
      in: header
      value: "Bearer $inputs.merchantToken"
    requestBody:
      contentType: application/json
      payload:
        total_amount: $inputs.refundAmount
        comment: $inputs.refundComment
        merchant_refund_id: $inputs.merchantRefundId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      refundId: $response.body#/refund_id
      refundStatus: $response.body#/status
      refundedAmount: $response.body#/refunded_amount
  outputs:
    orderId: $inputs.orderId
    orderStatus: $steps.getOrder.outputs.orderStatus
    refundId: $steps.refund.outputs.refundId
    refundStatus: $steps.refund.outputs.refundStatus