openapi: 3.0.3
info:
  title: US Bank RTP Real-Time Payments API
  description: >-
    The RTP Real-Time Payments API enables 24/7/365 instant payment origination through
    The Clearing House RTP network. Supports credit transfer messages, request for payment (RFP),
    and RTP eligibility verification. All transactions settle instantly and are irrevocable.
  version: 1.0.0
  contact:
    name: US Bank API Onboarding Team
    url: https://developer.usbank.com/contact
    email: apionboarding@usbank.com
  termsOfService: https://developer.usbank.com/terms
servers:
  - url: https://api.usbank.com/v1
    description: US Bank production API

security:
  - OAuth2MFA: []

paths:
  /rtp/eligibility:
    get:
      operationId: getRTPEligibility
      summary: Check RTP Eligibility
      description: >-
        Check if the recipient's bank is part of the RTP Network. The routing number
        of the receiving bank is required to check RTP eligibility.
      tags:
        - RTP Eligibility
      parameters:
        - name: routingNumber
          in: query
          required: true
          description: 9-digit routing number of the receiver's bank
          schema:
            type: string
            pattern: '^\d{9}$'
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/json
        - name: Accept-Encoding
          in: header
          required: true
          schema:
            type: string
        - name: Correlation-ID
          in: header
          required: true
          description: Unique identifier for every request/response pair
          schema:
            type: string
            format: uuid
        - name: On-Behalf-Of
          in: header
          required: false
          description: The U.S. Bank customer ID if submitted by a service provider
          schema:
            type: string
      responses:
        '200':
          description: RTP eligibility information for the routing number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RTPEligibilityResponse'
        '400':
          description: Invalid routing number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /rtp/credit-transfers:
    post:
      operationId: initiateRTPCreditTransfer
      summary: Initiate RTP Credit Transfer
      description: >-
        Initiate an RTP credit transfer transaction. The payer must be a U.S. Bank customer.
        Transactions are processed 24/7/365 and settle instantly. All transactions are
        irrevocable once submitted.
      tags:
        - Credit Transfers
      parameters:
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            default: application/json
        - name: Correlation-ID
          in: header
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditTransferRequest'
      responses:
        '201':
          description: Credit transfer initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditTransferResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unable to process payment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /rtp/credit-transfers/{transactionId}:
    get:
      operationId: getRTPCreditTransferStatus
      summary: Get RTP Credit Transfer Status
      description: >-
        Retrieve the status and details of an RTP credit transfer that was initiated
        or an incoming credit transfer.
      tags:
        - Credit Transfers
      parameters:
        - name: transactionId
          in: path
          required: true
          description: The unique identifier of the RTP credit transfer transaction
          schema:
            type: string
        - name: Correlation-ID
          in: header
          required: true
          schema:
            type: string
            format: uuid
        - name: Accept
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Credit transfer status and details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditTransferResponse'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /rtp/requests-for-payment:
    post:
      operationId: initiateRTPRequestForPayment
      summary: Initiate RTP Request for Payment
      description: >-
        Initiate an RTP Request for Payment (RFP) to receive money in a U.S. Bank account.
        Supports configurable reminders, partial payments, and future payment scheduling.
      tags:
        - Request for Payment
      parameters:
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
        - name: Correlation-ID
          in: header
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestForPaymentRequest'
      responses:
        '201':
          description: Request for payment initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestForPaymentResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /rtp/requests-for-payment/{requestId}:
    get:
      operationId: getRTPRequestForPaymentStatus
      summary: Get RTP Request for Payment Status
      description: Retrieve the status and details of an RTP Request for Payment.
      tags:
        - Request for Payment
      parameters:
        - name: requestId
          in: path
          required: true
          description: The unique identifier of the RFP
          schema:
            type: string
        - name: Correlation-ID
          in: header
          required: true
          schema:
            type: string
            format: uuid
        - name: Accept
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: RFP status and details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestForPaymentResponse'
        '404':
          description: Request for payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  securitySchemes:
    OAuth2MFA:
      type: oauth2
      description: OAuth 2.0 with MFA using SinglePoint credentials
      flows:
        authorizationCode:
          authorizationUrl: https://api.usbank.com/oauth/authorize
          tokenUrl: https://api.usbank.com/oauth/token
          scopes:
            payment.write: Initiate payments
            payment.read: Read payment status

  schemas:
    RTPEligibilityResponse:
      type: object
      description: RTP eligibility information for a routing number
      properties:
        routingNumber:
          type: string
          description: The queried routing number
        eligible:
          type: boolean
          description: Whether the bank is RTP-eligible
        bankName:
          type: string
          description: Name of the bank associated with the routing number
      required:
        - routingNumber
        - eligible

    CreditTransferRequest:
      type: object
      description: Request to initiate an RTP credit transfer
      properties:
        payerAccountNumber:
          type: string
          description: U.S. Bank account number to debit
        payeeAccountNumber:
          type: string
          description: Recipient's account number
        payeeRoutingNumber:
          type: string
          description: Recipient's bank routing number
        payeeName:
          type: string
          description: Recipient's name
        amount:
          type: number
          format: double
          description: Payment amount in USD
        remittanceInfo:
          type: string
          description: Payment description or remittance information (max 140 characters)
        endToEndId:
          type: string
          description: Unique end-to-end identifier for the payment (client-assigned)
      required:
        - payerAccountNumber
        - payeeAccountNumber
        - payeeRoutingNumber
        - payeeName
        - amount

    CreditTransferResponse:
      type: object
      description: Credit transfer status and details
      properties:
        transactionId:
          type: string
          description: U.S. Bank transaction identifier
        endToEndId:
          type: string
          description: End-to-end identifier
        status:
          type: string
          enum: [PENDING, ACCEPTED, COMPLETED, REJECTED, FAILED]
          description: Transaction status
        amount:
          type: number
          format: double
          description: Payment amount
        createdAt:
          type: string
          format: date-time
          description: Transaction creation timestamp
        completedAt:
          type: string
          format: date-time
          description: Settlement completion timestamp
        statusMessage:
          type: string
          description: Additional status information
      required:
        - transactionId
        - status
        - amount
        - createdAt

    RequestForPaymentRequest:
      type: object
      description: Request to initiate an RTP Request for Payment
      properties:
        creditorAccountNumber:
          type: string
          description: U.S. Bank account to receive payment
        debtorName:
          type: string
          description: Name of the party being requested to pay
        debtorAccountNumber:
          type: string
          description: Debtor's account number
        debtorRoutingNumber:
          type: string
          description: Debtor's bank routing number
        amount:
          type: number
          format: double
          description: Requested payment amount
        dueDate:
          type: string
          format: date
          description: Payment due date
        remittanceInfo:
          type: string
          description: Invoice or billing reference information
        partialPaymentAllowed:
          type: boolean
          description: Whether partial payment is accepted
          default: false
      required:
        - creditorAccountNumber
        - debtorName
        - amount

    RequestForPaymentResponse:
      type: object
      properties:
        requestId:
          type: string
          description: Unique identifier for the RFP
        status:
          type: string
          enum: [PENDING, SENT, ACCEPTED, PAID, DECLINED, EXPIRED]
          description: RFP status
        amount:
          type: number
          description: Requested amount
        createdAt:
          type: string
          format: date-time
          description: RFP creation timestamp
      required:
        - requestId
        - status
        - amount
        - createdAt

    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Error message
        correlationId:
          type: string
          description: Correlation ID from the request