openapi: 3.1.0
info:
  title: Wells Fargo ACH Payments API
  description: >-
    The Wells Fargo ACH Payments API enables commercial banking customers to
    initiate ACH credit and debit transactions, including same-day ACH, for
    payroll, vendor payments, and collections. The API integrates with Wells
    Fargo's intelligent payment routing that automatically selects the optimal
    payment rail including RTP, FedNow, and ACH for each transaction. OAuth 2.0
    client credentials flow is used for authentication. The API is available
    through the Wells Fargo Developer Portal at developer.wellsfargo.com.
  version: '2.0'
  contact:
    url: https://developer.wellsfargo.com/documentation/api-references/ach-payments/v2/ach-payments-api-ref-v2
servers:
  - url: https://api.wellsfargo.com
tags:
  - name: ACH Payments
    description: Initiate and manage ACH credit and debit transactions.
  - name: Payment Batches
    description: Batch ACH payment file management.
  - name: Payment Returns
    description: ACH return and NOC (Notification of Change) processing.
paths:
  /v2/ach/payments:
    post:
      operationId: initiateAchPayment
      summary: Initiate ACH Payment
      description: >-
        Initiates a single ACH credit or debit transaction. Supports standard
        ACH and same-day ACH processing. The intelligent routing engine may
        upgrade eligible transactions to RTP or FedNow for faster settlement.
      tags:
        - ACH Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AchPaymentRequest'
      security:
        - oauth2:
            - payments:write
      responses:
        '201':
          description: ACH payment initiated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AchPayment'
        '400':
          description: Bad request - validation error.
        '401':
          description: Unauthorized.
        '422':
          description: Unprocessable entity - business rule violation.
    get:
      operationId: listAchPayments
      summary: List ACH Payments
      description: >-
        Retrieves a list of ACH payments initiated by the authenticated
        customer, with optional filtering by date range, status, and payment type.
      tags:
        - ACH Payments
      parameters:
        - name: startDate
          in: query
          description: Filter by payment initiation start date (YYYY-MM-DD).
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          description: Filter by payment initiation end date (YYYY-MM-DD).
          schema:
            type: string
            format: date
        - name: status
          in: query
          description: Filter by payment status.
          schema:
            type: string
            enum: [PENDING, SUBMITTED, SETTLED, RETURNED, REJECTED]
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 100
        - name: pageToken
          in: query
          schema:
            type: string
      security:
        - oauth2:
            - payments:read
      responses:
        '200':
          description: ACH payment list returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AchPaymentListResponse'
        '401':
          description: Unauthorized.
  /v2/ach/payments/{paymentId}:
    get:
      operationId: getAchPayment
      summary: Get ACH Payment
      description: >-
        Retrieves the details and current status of a specific ACH payment
        by its payment ID, including settlement information and any return codes.
      tags:
        - ACH Payments
      parameters:
        - name: paymentId
          in: path
          description: The ACH payment identifier.
          required: true
          schema:
            type: string
      security:
        - oauth2:
            - payments:read
      responses:
        '200':
          description: ACH payment returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AchPayment'
        '401':
          description: Unauthorized.
        '404':
          description: Payment not found.
    delete:
      operationId: cancelAchPayment
      summary: Cancel ACH Payment
      description: >-
        Cancels a pending ACH payment that has not yet been submitted to
        the ACH network. Only payments in PENDING status can be cancelled.
      tags:
        - ACH Payments
      parameters:
        - name: paymentId
          in: path
          description: The ACH payment identifier.
          required: true
          schema:
            type: string
      security:
        - oauth2:
            - payments:write
      responses:
        '204':
          description: Payment cancelled successfully.
        '400':
          description: Bad request - payment cannot be cancelled in current status.
        '401':
          description: Unauthorized.
        '404':
          description: Payment not found.
  /v2/ach/batches:
    post:
      operationId: submitAchBatch
      summary: Submit ACH Batch
      description: >-
        Submits a batch ACH payment file (NACHA-formatted or JSON) containing
        multiple ACH transactions for processing in a single submission.
        Supports CTX, CCD, PPD, and WEB ACH transaction codes.
      tags:
        - Payment Batches
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AchBatchRequest'
      security:
        - oauth2:
            - payments:write
      responses:
        '201':
          description: Batch submitted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AchBatch'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
  /v2/ach/returns:
    get:
      operationId: listAchReturns
      summary: List ACH Returns
      description: >-
        Retrieves ACH returns and Notifications of Change (NOC) for the
        authenticated customer, including return reason codes, original
        transaction details, and resolution guidance.
      tags:
        - Payment Returns
      parameters:
        - name: startDate
          in: query
          description: Filter returns from this date.
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          description: Filter returns up to this date.
          schema:
            type: string
            format: date
        - name: returnType
          in: query
          description: Filter by return type (RETURN or NOC).
          schema:
            type: string
            enum: [RETURN, NOC]
      security:
        - oauth2:
            - payments:read
      responses:
        '200':
          description: ACH returns returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AchReturnListResponse'
        '401':
          description: Unauthorized.
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.wellsfargo.com/oauth2/token
          scopes:
            payments:read: Read payment information and status
            payments:write: Initiate and cancel payments
  schemas:
    AchPaymentRequest:
      type: object
      required:
        - debitAccountId
        - amount
        - currency
        - creditAccountNumber
        - creditRoutingNumber
        - transactionCode
      properties:
        debitAccountId:
          type: string
          description: Wells Fargo account ID to debit.
        amount:
          type: number
          format: double
          description: Payment amount.
        currency:
          type: string
          example: USD
        creditAccountNumber:
          type: string
          description: Receiver's account number.
        creditRoutingNumber:
          type: string
          description: Receiver's bank routing/transit number (9 digits).
        creditAccountType:
          type: string
          enum: [CHECKING, SAVINGS]
        transactionCode:
          type: string
          enum: [CCD, CTX, PPD, WEB]
          description: NACHA transaction code (CCD for corporate, PPD for consumer).
        receiverName:
          type: string
          description: Name of payment receiver.
        addendaInformation:
          type: string
          description: Optional payment addenda (up to 80 characters).
        sameDayAch:
          type: boolean
          description: Request same-day ACH processing.
          default: false
        effectiveDate:
          type: string
          format: date
          description: Requested settlement date.
    AchPayment:
      type: object
      properties:
        paymentId:
          type: string
        status:
          type: string
          enum: [PENDING, SUBMITTED, SETTLED, RETURNED, REJECTED, CANCELLED]
        debitAccountId:
          type: string
        amount:
          type: number
          format: double
        currency:
          type: string
        creditAccountNumber:
          type: string
        creditRoutingNumber:
          type: string
        transactionCode:
          type: string
        receiverName:
          type: string
        effectiveDate:
          type: string
          format: date
        settlementDate:
          type: string
          format: date
        createdAt:
          type: string
          format: date-time
        traceNumber:
          type: string
          description: NACHA trace number assigned at submission.
    AchPaymentListResponse:
      type: object
      properties:
        payments:
          type: array
          items:
            $ref: '#/components/schemas/AchPayment'
        nextPageToken:
          type: string
        totalCount:
          type: integer
    AchBatchRequest:
      type: object
      properties:
        companyName:
          type: string
        companyId:
          type: string
        effectiveDate:
          type: string
          format: date
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/AchPaymentRequest'
    AchBatch:
      type: object
      properties:
        batchId:
          type: string
        status:
          type: string
          enum: [RECEIVED, PROCESSING, SUBMITTED, COMPLETED, REJECTED]
        transactionCount:
          type: integer
        totalDebitAmount:
          type: number
          format: double
        totalCreditAmount:
          type: number
          format: double
        createdAt:
          type: string
          format: date-time
    AchReturnListResponse:
      type: object
      properties:
        returns:
          type: array
          items:
            type: object
            properties:
              returnId:
                type: string
              originalPaymentId:
                type: string
              returnType:
                type: string
                enum: [RETURN, NOC]
              returnCode:
                type: string
              returnReason:
                type: string
              returnDate:
                type: string
                format: date
              amount:
                type: number
                format: double