arazzo: 1.0.1
info:
  title: Paystack Charge and Refund a Transaction
  summary: Initialize and verify a transaction, then create a refund against it and fetch the refund status.
  description: >-
    A pay-then-refund lifecycle. A transaction is initialized and verified to a
    successful state, a refund is created against the verified reference, and the
    refund record is fetched to confirm its processing status. 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: acceptPaymentsApi
  url: ../openapi/paystack-accept-payments-openapi.yml
  type: openapi
- name: refundsApi
  url: ../openapi/paystack-refunds-disputes-openapi.yml
  type: openapi
workflows:
- workflowId: charge-and-refund-transaction
  summary: Collect a payment, then issue and track a refund against it.
  description: >-
    Initializes and verifies a transaction, creates a refund against the
    reference, and fetches the refund record to confirm its status.
  inputs:
    type: object
    required:
    - email
    - amount
    properties:
      email:
        type: string
        description: Customer's email address.
      amount:
        type: integer
        description: Transaction amount in the smallest currency unit.
      refundAmount:
        type: integer
        description: Amount to refund; omit to refund the full transaction amount.
      customer_note:
        type: string
        description: Reason for the refund shown to the customer.
  steps:
  - stepId: initializeTransaction
    description: Initialize the transaction that will later be refunded.
    operationId: transaction_initialize
    requestBody:
      contentType: application/json
      payload:
        email: $inputs.email
        amount: $inputs.amount
    successCriteria:
    - condition: $statusCode == 201
    outputs:
      reference: $response.body#/data/reference
  - stepId: verifyTransaction
    description: Verify the transaction reached a final state before refunding.
    operationId: transaction_verify
    parameters:
    - name: reference
      in: path
      value: $steps.initializeTransaction.outputs.reference
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      status: $response.body#/data/status
  - stepId: createRefund
    description: Create a refund against the verified transaction reference.
    operationId: refund_create
    requestBody:
      contentType: application/json
      payload:
        transaction: $steps.initializeTransaction.outputs.reference
        amount: $inputs.refundAmount
        customer_note: $inputs.customer_note
    successCriteria:
    - condition: $statusCode == 201
    outputs:
      refundId: $response.body#/data/id
      refundStatus: $response.body#/data/status
  - stepId: fetchRefund
    description: Fetch the refund record to confirm its current processing status.
    operationId: refund_fetch
    parameters:
    - name: id
      in: path
      value: $steps.createRefund.outputs.refundId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      refundStatus: $response.body#/data/status
  outputs:
    reference: $steps.initializeTransaction.outputs.reference
    refundId: $steps.createRefund.outputs.refundId
    refundStatus: $steps.fetchRefund.outputs.refundStatus