Refund a customer's bank account (ACH) with no originating payment reference.

arazzo: 1.0.0
info:
  title: Run an unreferenced bank-transfer refund
  summary: Return funds to a customer's bank account (ACH) without referencing an
    originating payment.
  description: |
    Refunds money to a customer's bank account when there is no originating paymentId to link the refund to (e.g. a goodwill gesture or an out-of-band sale). Because the refund is unreferenced, you supply the customer's bank details and the refund amount directly rather than pointing at a prior payment. Unreferenced refunds are available only on certain merchant accounts.
    - POST /bank-transfer-refunds via operationId
      `bankTransferUnreferencedRefund`. No `channel` field; the `refundMethod` is
      type `ach` (or `secureToken`) and a customer contact method is typically
      supplied so the gateway can notify the recipient. Returns 201 with a
      top-level `refundId`.

    Agent gotchas: the refund id is returned at the top level as `refundId` (not nested); every request requires an `Idempotency-Key` header in UUID v4 format; and `refundMethod` is polymorphic - its `type` (ach / secureToken) selects the variant, so do not mix card fields into an ACH refund.
    To return funds to a card instead, use the run-unreferenced-card-refund workflow.
  version: 1.0.0
sourceDescriptions:
  - name: payroc-api
    url: /openapi.yaml
    type: openapi
workflows:
  - workflowId: run-unreferenced-bank-transfer-refund
    summary: Refund a customer's bank account (ACH) with no originating payment
      reference.
    description: |
      Runs a single unreferenced bank-transfer refund via POST /bank-transfer-refunds with a `refundMethod` of type `ach` (or `secureToken`).
    x-actors:
      - id: customer
        name: Customer
        type: human
        description: The person receiving the returned funds to their bank account.
      - id: merchant
        name: Merchant / integrator
        type: client
        description: Calls the Payroc API to issue the unreferenced refund on the
          customer's behalf.
      - id: payroc-gateway
        name: Payroc gateway
        type: api
        description: The Payroc API surface these steps call.
      - id: processor
        name: ACH network
        type: external-system
        description: Downstream ACH network that settles the returned funds; not
          directly callable.
    inputs:
      type: object
      required:
        - idempotencyKey
        - processingTerminalId
        - orderId
        - description
        - amount
        - currency
        - nameOnAccount
        - accountNumber
        - routingNumber
        - customerEmail
      properties:
        idempotencyKey:
          type: string
          description: Unique UUID v4 you generate per request, sent as the
            Idempotency-Key header.
          example: f32c9ad6-c97f-4998-9356-f3b6718b1b68
        processingTerminalId:
          type: string
          description: Unique identifier of the processing terminal that issues the refund.
          example: "1234001"
        orderId:
          type: string
          description: Unique identifier the merchant assigns to this refund transaction.
          example: OrderRef6543
        description:
          type: string
          description: Description of the refund.
          example: Refund for order OrderRef6543
        amount:
          type: integer
          description: Refund amount in the currency's lowest denomination (e.g. cents).
          example: 4999
        currency:
          type: string
          description: ISO 4217 currency code of the refund.
          example: USD
        nameOnAccount:
          type: string
          description: Name on the customer's bank account.
          example: Sarah Hazel Hopper
        accountNumber:
          type: string
          description: The customer's bank account number.
          example: "1234567890"
        routingNumber:
          type: string
          description: The routing number for the customer's bank account.
          example: "123456789"
        customerEmail:
          type: string
          description: Email used to notify the customer of the refund.
          example: sarah.hopper@example.com
    steps:
      - stepId: runBankRefund
        x-actor: merchant
        x-actor-to: payroc-gateway
        x-label: unreferenced refund request
        description: |
          Issues an unreferenced bank-transfer refund (POST /bank-transfer-refunds). There is no `channel` field; supply a `refundMethod` of type `ach` and a customer contact method so the gateway can notify the recipient.
        operationId: $sourceDescriptions.payroc-api.bankTransferUnreferencedRefund
        parameters:
          - name: Idempotency-Key
            in: header
            value: $inputs.idempotencyKey
        requestBody:
          contentType: application/json
          payload:
            processingTerminalId: $inputs.processingTerminalId
            order:
              orderId: $inputs.orderId
              description: $inputs.description
              amount: $inputs.amount
              currency: $inputs.currency
            customer:
              notificationLanguage: en
              contactMethods:
                - type: email
                  value: $inputs.customerEmail
            refundMethod:
              type: ach
              secCode: web
              accountType: checking
              nameOnAccount: $inputs.nameOnAccount
              accountNumber: $inputs.accountNumber
              routingNumber: $inputs.routingNumber
        successCriteria:
          - condition: $statusCode == 201
        outputs:
          refundId: $response.body#/refundId
    outputs:
      refundId: $steps.runBankRefund.outputs.refundId