Wells Fargo ACH Payments API

openapi: 3.1.0
info:
  title: Wells Fargo Account Transactions Accounts ACH Payments API
  description: The Wells Fargo Account Transactions API enables treasury management customers to search and retrieve transaction data from the current day through 180 days prior. The API supports ACH, Wire, and RTP/Instant Payment transactions with unique transaction IDs, intraday and previous day reporting, and pagination for high-volume transaction retrieval. Authentication uses OAuth 2.0 bearer tokens obtained through the Wells Fargo Developer Portal.
  version: '3.0'
  contact:
    url: https://developer.wellsfargo.com/documentation/api-references/account-transactions/v3/transaction-detail-api-ref-v3
servers:
- url: https://api.wellsfargo.com
tags:
- name: ACH Payments
  description: Initiate and manage ACH credit and debit transactions.
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.
components:
  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
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.wellsfargo.com/oauth2/token
          scopes:
            accounts:read: Read account information and balances
            transactions:read: Read transaction history and details