arazzo: 1.0.1
info:
  title: dLocal Refund Payment and Confirm
  summary: Confirm a payment is PAID, issue a refund against it, then verify the refund status.
  description: >-
    Safely refunds a settled payment. The workflow first retrieves the payment
    to confirm it is in the PAID state, then creates a refund against it (full
    or partial depending on whether an amount is supplied), and finally polls
    the refund status endpoint to confirm settlement. 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: paymentsApi
  url: ../openapi/d-local-payments-api-openapi.yml
  type: openapi
- name: refundsApi
  url: ../openapi/d-local-refunds-api-openapi.yml
  type: openapi
workflows:
- workflowId: refund-payment-and-confirm
  summary: Verify a payment is PAID, refund it, and confirm the refund settled.
  description: >-
    Retrieves the payment to confirm it is PAID, creates a refund against it,
    and polls the refund status endpoint to confirm the refund resolved.
  inputs:
    type: object
    required:
    - paymentId
    properties:
      paymentId:
        type: string
        description: Identifier of the payment to refund.
      amount:
        type: number
        description: Amount to refund. Omit to refund the full payment.
      currency:
        type: string
        description: ISO-4217 currency code of the refund.
      notificationUrl:
        type: string
        description: URL to receive asynchronous refund notifications.
      description:
        type: string
        description: Free-text description of the refund reason.
  steps:
  - stepId: confirmPaymentPaid
    description: >-
      Retrieve the payment and confirm it is in the PAID state before issuing a
      refund.
    operationId: retrievePayment
    parameters:
    - name: payment_id
      in: path
      value: $inputs.paymentId
    successCriteria:
    - condition: $statusCode == 200
    - context: $response.body
      condition: $.status == "PAID"
      type: jsonpath
    outputs:
      status: $response.body#/status
      paidAmount: $response.body#/amount
  - stepId: createRefund
    description: >-
      Initiate a refund for the confirmed payment. When no amount is supplied
      the full payment is refunded.
    operationId: createRefund
    requestBody:
      contentType: application/json
      payload:
        payment_id: $inputs.paymentId
        amount: $inputs.amount
        currency: $inputs.currency
        notification_url: $inputs.notificationUrl
        description: $inputs.description
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      refundId: $response.body#/id
      status: $response.body#/status
  - stepId: confirmRefundStatus
    description: >-
      Retrieve the refund status to confirm whether the refund succeeded or
      remains pending.
    operationId: retrieveRefundStatus
    parameters:
    - name: refund_id
      in: path
      value: $steps.createRefund.outputs.refundId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      finalStatus: $response.body#/status
  outputs:
    refundId: $steps.createRefund.outputs.refundId
    finalStatus: $steps.confirmRefundStatus.outputs.finalStatus