openapi: 3.1.0
info:
  title: Bank of America Accounts Payments API
  description: Bank of America provides developer APIs for banking services including payments, account management, and treasury services. The APIs enable corporate clients and fintech partners to integrate banking operations.
  version: '1.0'
  contact:
    name: Bank of America Developer Support
    url: https://developer.bankofamerica.com/
servers:
- url: https://api.bankofamerica.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Payments
paths:
  /payments:
    post:
      operationId: initiatePayment
      summary: Initiate Payment
      description: Initiate a payment transaction. Supports over 350 payment types including ACH, wire transfers, SWIFT, checks, and real-time payments. The payment type is determined by the paymentType field in the request body.
      tags:
      - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '201':
          description: Payment initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          description: Bad request — invalid payment data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: listPayments
      summary: List Payments
      description: Retrieve a list of payment transactions filtered by date range and status.
      tags:
      - Payments
      parameters:
      - name: fromDate
        in: query
        description: Start date filter (ISO 8601)
        schema:
          type: string
          format: date
      - name: toDate
        in: query
        description: End date filter (ISO 8601)
        schema:
          type: string
          format: date
      - name: status
        in: query
        description: Filter by payment status
        schema:
          type: string
          enum:
          - pending
          - processing
          - completed
          - rejected
          - cancelled
      - name: paymentType
        in: query
        description: Filter by payment type
        schema:
          type: string
      responses:
        '200':
          description: Payment list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentListResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /payments/{paymentId}:
    get:
      operationId: getPayment
      summary: Get Payment Status
      description: Retrieve the current status and details of a specific payment transaction.
      tags:
      - Payments
      parameters:
      - name: paymentId
        in: path
        required: true
        description: Unique payment transaction identifier
        schema:
          type: string
      responses:
        '200':
          description: Payment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: cancelPayment
      summary: Cancel Payment
      description: Cancel a pending payment that has not yet been processed.
      tags:
      - Payments
      parameters:
      - name: paymentId
        in: path
        required: true
        description: Unique payment identifier
        schema:
          type: string
      responses:
        '200':
          description: Payment cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — payment cannot be cancelled in current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      description: API error response
      properties:
        errorCode:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: array
          items:
            type: string
          description: Additional error details
        requestId:
          type: string
          description: Request identifier for support
    PaymentRequest:
      type: object
      description: Payment initiation request
      required:
      - paymentType
      - amount
      - currency
      - debitAccountId
      - beneficiary
      properties:
        paymentType:
          type: string
          description: Payment type (ACH_CREDIT, WIRE, SWIFT, CHECK, RTP, etc.)
        amount:
          type: number
          format: double
          description: Payment amount
        currency:
          type: string
          description: Payment currency (ISO 4217)
        debitAccountId:
          type: string
          description: Account to debit
        valueDate:
          type: string
          format: date
          description: Requested value date (ISO 8601)
        reference:
          type: string
          description: Client reference number
        memo:
          type: string
          description: Payment memo or description
        beneficiary:
          $ref: '#/components/schemas/Beneficiary'
    PaymentResponse:
      type: object
      description: Payment transaction response
      properties:
        paymentId:
          type: string
          description: Unique payment identifier
        clientReferenceId:
          type: string
          description: Client-provided reference
        status:
          type: string
          description: Payment status
          enum:
          - pending
          - processing
          - completed
          - rejected
          - cancelled
        paymentType:
          type: string
          description: Payment type
        amount:
          type: number
          format: double
        currency:
          type: string
        valueDate:
          type: string
          format: date
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        statusMessage:
          type: string
          description: Additional status information
    PaymentListResponse:
      type: object
      description: Paginated list of payments
      properties:
        payments:
          type: array
          items:
            $ref: '#/components/schemas/PaymentResponse'
        totalCount:
          type: integer
        pageSize:
          type: integer
        offset:
          type: integer
    Beneficiary:
      type: object
      description: Payment beneficiary details
      properties:
        name:
          type: string
          description: Beneficiary name
        accountNumber:
          type: string
          description: Beneficiary account number
        routingNumber:
          type: string
          description: Beneficiary bank routing number (ABA)
        bankName:
          type: string
          description: Beneficiary bank name
        bankAddress:
          type: string
          description: Beneficiary bank address
        swiftCode:
          type: string
          description: SWIFT/BIC code for international wires
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
externalDocs:
  description: Documentation
  url: https://developer.bankofamerica.com/