openapi: 3.0.3
info:
  title: Truist Commercial Account Transactions API
  description: >-
    Enables programmatic retrieval of commercial account transaction data including
    ACH credits and debits, wire transfers, checks, and other payment types. Supports
    ERP integrations, cash flow reconciliation, and automated accounting workflows.
  version: 1.0.0
  contact:
    url: https://developer.truist.com/
  termsOfService: https://www.truist.com/about-truist/terms-conditions
servers:
  - url: https://api.truist.com/v1
    description: Production
tags:
  - name: Commercial Transactions
    description: Commercial account transaction operations
paths:
  /commercial/accounts/{accountId}/transactions:
    get:
      operationId: listCommercialTransactions
      summary: List Commercial Account Transactions
      description: Retrieve commercial account transactions including ACH, wires, and checks with optional filtering by date range and transaction type.
      tags:
        - Commercial Transactions
      security:
        - OAuth2: [commercial.transactions:read]
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
          description: Unique account identifier
        - name: fromDate
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Start date for transaction retrieval (YYYY-MM-DD)
        - name: toDate
          in: query
          required: false
          schema:
            type: string
            format: date
          description: End date for transaction retrieval (YYYY-MM-DD)
        - name: transactionType
          in: query
          required: false
          schema:
            type: string
            enum: [ACH, WIRE, CHECK, BOOK_TRANSFER, FEE, INTEREST, ALL]
          description: Filter by transaction type
        - name: debitCreditIndicator
          in: query
          required: false
          schema:
            type: string
            enum: [DEBIT, CREDIT]
          description: Filter by debit or credit
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
            maximum: 500
          description: Maximum number of transactions to return
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Pagination offset
      responses:
        '200':
          description: Commercial transactions retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommercialTransactionListResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Account not found
  /commercial/accounts/{accountId}/transactions/{transactionId}:
    get:
      operationId: getCommercialTransaction
      summary: Get Commercial Transaction
      description: Retrieve details for a specific commercial account transaction.
      tags:
        - Commercial Transactions
      security:
        - OAuth2: [commercial.transactions:read]
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
          description: Unique account identifier
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
          description: Unique transaction identifier
      responses:
        '200':
          description: Commercial transaction retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommercialTransaction'
        '401':
          description: Unauthorized
        '404':
          description: Transaction not found
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.truist.com/oauth2/token
          scopes:
            commercial.transactions:read: Read access to commercial transaction data
  schemas:
    CommercialTransactionListResponse:
      type: object
      properties:
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/CommercialTransaction'
        totalCount:
          type: integer
        pageSize:
          type: integer
        offset:
          type: integer
    CommercialTransaction:
      type: object
      properties:
        transactionId:
          type: string
          description: Unique transaction identifier
        accountId:
          type: string
          description: Associated account identifier
        transactionDate:
          type: string
          format: date
          description: Transaction value date
        postedDate:
          type: string
          format: date
          description: Date transaction was posted to account
        amount:
          type: number
          format: double
          description: Transaction amount (positive for credits, negative for debits)
        currency:
          type: string
          default: USD
        debitCreditIndicator:
          type: string
          enum: [DEBIT, CREDIT]
        transactionType:
          type: string
          enum: [ACH, WIRE, CHECK, BOOK_TRANSFER, FEE, INTEREST]
          description: Payment type
        bankReferenceNumber:
          type: string
          description: Bank-assigned reference number
        customerReferenceNumber:
          type: string
          description: Customer-provided reference number
        description:
          type: string
          description: Transaction narrative description
        originatorName:
          type: string
          description: Originating party name (ACH/wire)
        receiverName:
          type: string
          description: Receiving party name
        checkNumber:
          type: string
          description: Check number if applicable
        achTraceNumber:
          type: string
          description: ACH trace number
        wireReferenceNumber:
          type: string
          description: Wire transfer reference number
        runningBalance:
          type: number
          format: double
          description: Ledger balance after transaction