openapi: 3.0.1
#---------------------------------------------------
# Information to contact the Service provider
#-------------------------------------------------
info:
  title: RTP Inquiry API
  description: Search and query real-time payments transactions
  version: 1.0.0
  contact:
    name: Embedded banking support
    email: embedded_banking_support@keybank.com
    
servers:
#---------------------------------------------------
# List of environments for the API
#---------------------------------------------------
 - url: https://partner-api-qv.keybank.com
 - url: https://partner-api.keybank.com
paths: 
  /rtp/v1/healthCheck:
    get:
      tags: # Apigee Product: Logical group based on functionality
        - HealthCheck 
      summary: Health check            
      description: Verify you can connect to the API service.
      operationId: healthCheck
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successful response
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. The ID is unique to each request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/healthResponse'
              example:
                 Status: Ok
                 Source: Roundtrip
                 Timestamp: '2022-09-15T04:49:03'
                 ClientIp: 156.77.111.28
                 X-Forwarded-For: '[156.77.111.28]'
  /rtp/v1/transactions/list:
    post:
      summary: Search real time payment transactions
      security:
        - bearerAuth: []
      operationId: searchRtpTransactions
      description: Based on search criteria provided, get a list of RTP transactions. The account number and date range are required for every request. 
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - accountNumber
                - fromDate
                - toDate
              properties:
                accountNumber:
                  type: string
                  description: The bank account number. This number cannot exceed 16 characters. 
                  minLength: 1
                  maxLength: 16
                  pattern: '/^\d+$/'
                  example: 3123456789
                fromDate:
                  description: 'Start date for the date range. This date can be the current day or within 100 days prior to the current date. To search for a single date, this value will be the same as the toDate. To search for a range of dates, make sure the date range is 31 days of the toDate. Format: YYYY-MM-DD'
                  type: string
                  format: date
                  example: 2024-02-01
                toDate:
                  description: 'End date for the date range. This date must be the same or later than the start date (fromDate). To search for a single date, this value will be the same as the fromDate.  To search for a range of dates, make sure the date range does not exceed 31 days. Format: YYYY-MM-DD'
                  type: string
                  format: date
                  example: 2024-02-01
                minimumAmount:
                  description: The minimum dollar amount of the transaction. This amount must be less than or equal to the maximum amount. Leave blank or enter zero for no minimum amount.
                  format: currency
                  minimum: 0
                  maximum: 1000000000
                  example: 100.00
                maximumAmount:
                  description: The maximum dollar amount of the transaction. This amount must be greater than or equal to the minimum amount. Leave blank to retrieve all amounts. This amount cannot exceed one billion dollars.
                  type: number
                  format: currency
                  minimum: 0
                  maximum: 1000000000
                  example: 75020.52
                pageNumber:
                  type: integer
                  description: The number of the page being viewed. This number must be greater than or equal to 1.
                  example: 1
                pageSize:
                  type: integer
                  description: The total number of pages returned. This number must be greater than or equal to 1 and cannot exceed 1000.
                  example: 500
      responses:
        '200':
          description: Search results match the criteria
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/RtpListTransaction'
                  metadata:
                    $ref: '#/components/schemas/Metadata'
              example:
                transactions:  
                - transactionId: "US99999000999999"
                  transactionStatus: "COMPLETED"
                  transactionDate: "2024-02-01"
                  transactionAmount: 32772.63
                  requestReference: "1122334455"
                  sendersReference: "US99999000999999"
                  creditor:
                    name: "Global Markets LLC"
                  creditorAccount: 
                    accountNumber: "987654321"
                  debtor:
                   name: "Paul Wilson"
                  debtorAccount:
                    accountNumber: "123456789"
                metadata:
                  messages:
                  - code: 
                    message:
                  page:
                    pageNumber: 1
                    pageSize: 25
                    totalPages: 3
                    totalRecords: 75
                    lastPage: true
        '400':
          description: Bad input parameter
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:               
                ErrorMessage: Error received from backend service.
                TransactionId: rrt-621075741872460927-c-gce-9129-15867185-4
                TransactionTime: djkdf
                X-CorrelationId: 80457bcb-2c3b-8c55-8cd6-3520c3157e8f
        '401':
          description: Received request is unauthorized
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. The ID is unique to each request.
          content:          
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:               
                ErrorMessage: "Received request is unauthorized, please provide valid credentials"
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
                TransactionTime: "2021-06-11T16:31:34.041Z" 
        '403':
          description: Request is forbidden to access the resource
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Access to requested resource is forbidden."
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
                TransactionTime: "2021-06-11T16:31:34.041Z"
        '404':
          description: Requested resource is not found
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Requested resource is not found, please verify the resource and resubmit the request."
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
                TransactionTime: "2021-06-11T16:31:34.041Z"
        '405':
          description: Requested method is not allowed
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Requested method is not allowed, please verify the method and resubmit the request."
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
                TransactionTime: "2021-06-11T16:31:34.041Z"
        '415':
          description: Requested unsupported media type
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Requested media type is not allowed, please verify the media type and resubmit the request."
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
                TransactionTime: "2021-06-11T16:31:34.041Z"
        '429':
          description: Too many requests received
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Number requests threshold reached, please resubmit the request after sometime."
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
                TransactionTime: "2021-06-11T16:31:34.041Z"    
        '502':
          description: Bad gateway
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Error received from backend service."
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"        
                TransactionTime: "2021-06-11T16:31:34.041Z"
                ServiceError: 
                  ConnectError: "Connectivity error occurred with the downstream service (unexpected EOF at target). Please check with application support team before resubmitting the request"
        '503':
          description: Service unavailable
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Error received from backend service."
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
                TransactionTime: "2021-06-11T16:31:34.041Z" 
                ServiceError: 
                  ConnectError: "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
        '504':
          description: Gateway timeout
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Error received from backend service"
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"       
                TransactionTime: "2021-06-11T16:31:34.041Z"
                ServiceError: 
                  ConnectError: "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request."
  /rtp/v1/transactions/detail/{transactionId}:
    get:
      summary: View the details of a RTP transaction by its ID
      security:
        - bearerAuth: []
      operationId: searchRtpTransaction
      description: Provide the transaction ID to retrieve all available fields for that single real time payment transaction.
      parameters:
        - name: transactionId
          in: path
          description: The unique ID number associated with the original payment request.
          required: true
          style: simple
          explode: false
          schema: 
            maxLength: 100
            type: string
          example: US99999000999999
      responses:
        '200':
          description: A RTP transaction matches the provided transactionId
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification. 
          content:
            application/json:
              schema:
                 $ref: '#/components/schemas/RtpDetailTransaction'
              example:  
                transactionId: "US99999000999999"
                transactionStatus: "COMPLETED"
                transactionDate: "2024-02-01"
                transactionAmount: 32772.63
                requestReference: "1122334455"
                sendersReference: "US99999000999999"
                creditor:
                  name: "Global Markets LLC"
                creditorAccount: 
                  accountNumber: "987654321"
                debtor:
                 name: "Paul Wilson"
                debtorAccount:
                  accountNumber: "123456789"
                remittanceInformation: "Payment 02/01/2024_Invoice - 123456789 Cust"
        '400':
          description: Bad input parameter
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:               
                ErrorMessage: Error received from backend service.
                TransactionId: rrt-621075741872460927-c-gce-9129-15867185-4
                X-CorrelationId: 80457bcb-2c3b-8c55-8cd6-3520c3157e8f
                ServiceError: 
                  messages:
                    - code: RTP-List-400-toDate
                      message: toDate format must be YYYY-MM-DD
        '401':
          description: Received request is unauthorized
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. The ID is unique to each request.
          content:          
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:               
                ErrorMessage: "Received request is unauthorized, please provide valid credentials"
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
                TransactionTime: "2021-06-11T16:31:34.041Z" 
        '403':
          description: Request is forbidden to access the resource
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Access to requested resource is forbidden."
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
                TransactionTime: "2021-06-11T16:31:34.041Z"
        '404':
          description: Requested resource is not found
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Requested resource is not found, please verify the resource and resubmit the request."
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
                TransactionTime: "2021-06-11T16:31:34.041Z"
        '405':
          description: Requested method is not allowed
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Requested method is not allowed, please verify the method and resubmit the request."
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
                TransactionTime: "2021-06-11T16:31:34.041Z"
        '415':
          description: Requested unsupported media type
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Requested media type is not allowed, please verify the media type and resubmit the request."
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
                TransactionTime: "2021-06-11T16:31:34.041Z"
        '429':
          description: Too many requests received
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Number requests threshold reached, please resubmit the request after sometime."
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
                TransactionTime: "2021-06-11T16:31:34.041Z"    
        '502':
          description: Bad gateway
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Error received from backend service."
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"        
                TransactionTime: "2021-06-11T16:31:34.041Z"
                ServiceError: 
                  ConnectError: "Connectivity error occurred with the downstream service (unexpected EOF at target). Please check with application support team before resubmitting the request"
        '503':
          description: Service unavailable
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Error received from backend service."
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
                TransactionTime: "2021-06-11T16:31:34.041Z" 
                ServiceError: 
                  ConnectError: "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
        '504':
          description: Gateway timeout
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: A unique identifier generated for each transaction that remains with the transaction through the chain fo API operations. The ID is unique to each request. 
          content:            
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
                ErrorMessage: "Error received from backend service"
                X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"       
                TransactionTime: "2021-06-11T16:31:34.041Z"
                ServiceError: 
                  ConnectError: "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request."
components:
  securitySchemes:    
    bearerAuth:    # security scheme for authentication based on F5 APM token
      type: http
      scheme: bearer
  schemas:
    RtpDetailTransaction:
      type: object
      description: Contains the response payload with details about an RTP transaction.
      properties:
        transactionId:
          type: string
          description: The unique ID number associated with the original payment request.
          maxLength: 100
        transactionStatus:
          enum:
          - CANCELLED
          - COMPLETED
          - FAILED
          - IN PROCESS
          - IN REVIEW
          - RETURNED
          description: 'The status of the RTP payment. Valid values: CANCELLED, COMPLETED, FAILED, IN PROCESS, IN REVIEW, RETURNED'
          maxLength: 50
        transactionDate:
          description: 'Date the transfer occurred. Format: YYYY-MM-DD'
          type: string
          format: date
          example: 2024-07-22
        transactionAmount:
          description: The dollar amount of the transaction.
          type: number
          format: currency
        requestReference:
          type: string
          description: A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
          maxLength: 64
        sendersReference:
          type: string
          description: A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
          maxLength: 35
        creditor:
          $ref: '#/components/schemas/PartyList'
        creditorAccount:
          $ref: '#/components/schemas/AccountList'
        debtor:
          $ref: '#/components/schemas/PartyList'
        debtorAccount:
          $ref: '#/components/schemas/AccountList'
        remittanceInformation:
          type: string
          description: Specific details associated with a transaction like an invoice number or customer details that provide a reason for the payment.
          maxLength: 256
    RtpListTransaction:
      type: object
      description: Contains the response payload for RTP inquiries. 
      properties:
        transactionId:
          type: string
          description: The unique ID number associated with the original payment request
          maxLength: 100
        transactionStatus:
          enum:
          - CANCELLED
          - COMPLETED
          - FAILED
          - IN PROCESS
          - IN REVIEW
          - RETURNED
          description: 'The status of the RTP payment. Valid values: CANCELLED, COMPLETED, FAILED, IN PROCESS, IN REVIEW, RETURNED'
          maxLength: 50
        transactionDate:
          description: 'Date the transfer occurred. Format: YYYY-MM-DD'
          type: string
          format: date
          example: 2024-07-22
        transactionAmount:
          type: number
          description: The dollar amount of the transaction.
          format: currency
        requestReference:
          type: string
          description: A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
          maxLength: 64
        sendersReference:
          type: string
          description: A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
          maxLength: 35
        creditor:
          $ref: '#/components/schemas/PartyList'
        creditorAccount:
          $ref: '#/components/schemas/AccountList'
        debtor:
          $ref: '#/components/schemas/PartyList'
        debtorAccount:
          $ref: '#/components/schemas/AccountList'
    healthResponse:
      type: object
      description: The response for the API health check.
      title: healthResponse
      properties:
        Status:
          type: string
          description: Status of the health check response.
        Source:
          type: string
          description: The origin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved.
        Timestamp:
          type: string
          description: The date (YYYY-MM-DD) and time (HH:MM:SS) of the response from the API service. 
        ClientIp:
          type: string
          description: The client IP address the gateway gets from the request.
        X-Forwarded-For:
          type: string
          description: The sequence of all the IP addresses for systems involved between the client and the gateway.
    AccountList:
      type: object
      properties:
        accountNumber:
          type: string
          description: Account number of the party.
          maxLength: 20
    PartyList:
      type: object
      properties:
        name:
          type: string 
          description: Contains the customer identification number and the company name. 
          maxLength: 255  
    Message:
      type: object
      description: Informational code and message from the server. 
      properties:
        code:
          type: string
          description: Static code assigned by the network or payment system.
        message:
          type: string
          description: A human-readable message associated with the code. 
    Page:
      type: object
      properties:
        pageNumber:
          type: integer
          description: The number of the page being viewed. 
        pageSize:
          type: integer
          description: The number of records per page.
        totalPages:
          type: integer
          description: The total number of pages available.
        totalRecords:
          type: integer
          description: The total number of the transactions (records) available in the result set. 
        lastPage:
          type: boolean
          description: Indicates the last page of the total pages.
      description: Page information returned from the server.
    Metadata:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        page:
          $ref: '#/components/schemas/Page'
      description: Data information returned as a message or page information retrieved from the server. 
    exception:
      title: exceptionSchema
      type: object
      description: Contains information about the errors related to the request.
      properties:
        ErrorMessage: 
          type: string
          description: A human-readable message that describes the type or source of the error. 
        TransactionId:
          type: string
          description: A unique transaction ID returned with the response, useful for traceability. 
        TransactionTime: 
          type: string
          description: Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. 
        ServiceError:
          type: object
          title: ServiceError
          description: Detailed service-level error details, if available.
          oneOf:          
          - $ref: '#/components/schemas/serviceErrorData'
          - $ref: '#/components/schemas/connectError'
    serviceErrorData:
      title: serviceErrorData
      required:
      - status
      type: object
      description: The service error returns the same response payload as a successful response with additional details specific to the error. 
      properties:
      $ref: '#/components/schemas/Metadata'
    connectError:
      type: object
      properties:
        ConnectError:
          type: string
          description: API connectivity error information, if available.