arazzo: 1.0.1
info:
  title: Flutterwave Settlement Reconciliation Refund
  summary: Retrieve a settlement, confirm a charge within it succeeded, then refund the charge and verify the refund.
  description: >-
    A finance reconciliation flow that ties settlements back to refunds. The
    workflow retrieves a settlement record, retrieves a specific charge that
    rolled up into that settlement and confirms it succeeded, then issues a
    refund against that charge and retrieves the refund to verify its status.
    Branching on the refund status lets the finance team record whether the
    reversal completed. Every step spells out its request inline so the flow can
    be read and executed without opening the underlying OpenAPI description.
  version: 1.0.0
sourceDescriptions:
- name: settlementsApi
  url: ../openapi/flutterwave-settlements-api-openapi.yml
  type: openapi
- name: paymentsApi
  url: ../openapi/flutterwave-payments-api-openapi.yml
  type: openapi
workflows:
- workflowId: settlement-reconciliation-refund
  summary: Inspect a settlement, verify a settled charge, and refund it with verification.
  description: >-
    Retrieves the settlement, verifies the target charge succeeded, creates a
    refund against it, then branches on the verified refund status.
  inputs:
    type: object
    required:
    - accessToken
    - settlementId
    - chargeId
    - amount
    properties:
      accessToken:
        type: string
        description: OAuth2 client-credentials bearer token for the Authorization header.
      settlementId:
        type: string
        description: Identifier of the settlement being reconciled.
      chargeId:
        type: string
        description: Identifier of the charge within the settlement to refund.
      amount:
        type: number
        description: Amount to refund in the major currency unit.
      reason:
        type: string
        description: Optional human-readable reason for the refund.
  steps:
  - stepId: getSettlement
    description: Retrieve the settlement record being reconciled.
    operationId: getSettlement
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: id
      in: path
      value: $inputs.settlementId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      netAmount: $response.body#/net_amount
      settlementStatus: $response.body#/status
  - stepId: verifyCharge
    description: Retrieve the charge and confirm it succeeded before refunding.
    operationId: getCharge
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: id
      in: path
      value: $inputs.chargeId
    successCriteria:
    - condition: $statusCode == 200
    - context: $response.body
      condition: $.status == "succeeded"
      type: jsonpath
    outputs:
      chargeStatus: $response.body#/status
  - stepId: createRefund
    description: Issue a refund against the verified charge.
    operationId: createRefund
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    requestBody:
      contentType: application/json
      payload:
        charge_id: $inputs.chargeId
        amount: $inputs.amount
        reason: $inputs.reason
    successCriteria:
    - condition: $statusCode == 201
    outputs:
      refundId: $response.body#/id
  - stepId: verifyRefund
    description: Retrieve the refund to confirm its final status.
    operationId: getRefund
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: id
      in: path
      value: $steps.createRefund.outputs.refundId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      refundStatus: $response.body#/status
    onSuccess:
    - name: refundSucceeded
      type: end
      criteria:
      - context: $response.body
        condition: $.status == "succeeded"
        type: jsonpath
    - name: refundFailed
      type: end
      criteria:
      - context: $response.body
        condition: $.status == "failed"
        type: jsonpath
  outputs:
    netAmount: $steps.getSettlement.outputs.netAmount
    refundId: $steps.createRefund.outputs.refundId
    refundStatus: $steps.verifyRefund.outputs.refundStatus