openapi: 3.0.2
info:
#---------------------------------------------------
# Information to contact the API provider
#---------------------------------------------------
  title: Stop Payment
  description: Request a stop for an issued payment.
  contact: 
   name: "KeyBank Developers Support"
   email: "developers@keybank.com"
  version: "1.0.0"

servers: 
#---------------------------------------------------
# List of environments for the API
#---------------------------------------------------
 - url: https://partner-api-qv.keybank.com
 - url: https://partner-api.keybank.com

paths:
#---------------------------------------------------
# List of API flows
#---------------------------------------------------    
  
  /accounts/payments/v1/stop:
    post:
      tags: # Apigee Product: Logical group based on functionality
        - Accounts-StopPayments
      summary: Stop a payment        
      description: Request a stop for an issued payment.
      operationId: addStopPayment
      security:
        - bearerAuth: []
      parameters:
        - name: X-CorrelationId
          in: header
          schema:
            type: string
          required: false
          description: Universal id to trace the transaction across all the systems. CorrelationId is unique per request.
      requestBody:
        content:
          application/json:     # Media type
            schema:             # Request body contents
              $ref: '#/components/schemas/paymentsRequest'
            example:
             AccountNumber: "123456789"
             BankNumber: "0101"
             CheckNumber:
              CheckNumberLow: "590"
              CheckNumberHigh: "591"
             CheckAmount: 1.52
             Description: "Test Stop_SB_08130116"
      responses:
        # Response code
        '200':
          description: Successful response
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: Universal id to trace the transaction across all the systems involved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paymentsResponse'
              example:
               Status: "Success"
               StatusCode: "000"          
               Severity: "Info"          
               StatusDesc: "stopPaymentAdd operation executed successfully - stopPaymentAdd_20190205024213818"        
               TransactionId:  "000000057307_590_1.52"
               X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
               TransactionTime: "2021-06-30T18:55:10.337Z"
        '400':
          description: Missing data in the request
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: Universal id to trace the transaction across all the systems involved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
               Status: "Failure"
               StatusCode: 400
               Severity: "Error"
               StatusDesc: "Mandatory data not provided, please verify the data and resubmit the request"
               TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1" 
               X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
               TransactionTime: "2021-06-11T16:31:34.041Z"
        '401':
          description: Received request is unauthorized
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: Universal id to trace the transaction across all the systems involved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:               
               Status: "Failure"
               StatusCode: 401
               Severity: "Error"
               StatusDesc: "Received request is unauthorized, please provide valid credentials"
               TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1" 
               X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
               TransactionTime: "2021-06-11T16:31:34.041Z"
        '402':
          description: Failure response from downstream
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: Universal id to trace the transaction across all the systems involved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:               
               Status: Failure
               StatusCode: 402
               Severity: Error
               StatusDesc: Failed to add stop payment on account; STAR failed  - stopPaymentAdd_20220513015308610
               TransactionId: 000000057307_590_591
               X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
               TransactionTime: '2022-05-13T05:53:08.702Z'
               ServiceError:
                 SEStatusCode: 402
                 SESeverity: Error
                 SEStatusDesc: Failed to add stop payment on account; STAR failed  - stopPaymentAdd_20220513015308610
                 AdditionalStatus:
                   ASStatusCode: 202
                   ASSeverity: Error
                   ASStatusDesc: CHECK(S) ALREADY STOPPED
                   SubjectElement:
                     Path: STAR
        '403':
          description: Request is forbidden to access the resource
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: Universal id to trace the transaction across all the systems involved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
               Status: "Failure"
               StatusCode: 403
               Severity: "Error"
               StatusDesc: "Access Denied for client ip"
               TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
               X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
               TransactionTime: "2021-06-11T16:31:34.041Z"         
        '404':
          description: Requested resource is not found
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: Universal id to trace the transaction across all the systems involved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
               Status: "Failure"
               StatusCode: 404
               Severity: "Error"
               StatusDesc: "Requested resource is not found, please verify the resource and resubmit the request"
               TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
               X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
               TransactionTime: "2021-06-11T16:31:34.041Z"
        '405':
          description: Requested method is not allowed.
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: Universal id to trace the transaction across all the systems involved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
               Status: "Failure"
               StatusCode: 405
               Severity: "Error"
               StatusDesc: "Requested method is not allowed, please verify the method and resubmit the request"
               TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
               X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
               TransactionTime: "2021-06-11T16:31:34.041Z"
        '415':
          description: Requested unsupported media type
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: Universal id to trace the transaction across all the systems involved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
               Status: "Failure"
               StatusCode: 415
               Severity: "Error"
               StatusDesc: "Requested media type is not allowed, please verify the media type and resubmit the request"
               TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
               X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
               TransactionTime: "2021-06-11T16:31:34.041Z"        
        '429':
          description: Too many requests received
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: Universal id to trace the transaction across all the systems involved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
               Status: "Failure"
               StatusCode: 429
               Severity: "Error"
               StatusDesc: "STOP SERVICE UNAVAILABLE, PLEASE RETRY BETWEEN 6:00AM AND 11:59PM EST"
               TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
               X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
               TransactionTime: "2022-05-17T04:39:32.449Z"
        '500':
          description: Internal server error
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: Universal id to trace the transaction across all the systems involved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
               Status: "Failure"
               StatusCode: 500
               Severity: "Error"
               StatusDesc: "Runtime error occured in the service, please check with appplication support team before resubmitting the request"
               TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1" 
               X-CorrelationId: "3288b87c-d4e7-639a-88d0-9cdfede8941e"
               TransactionTime: "2021-06-11T16:31:34.041Z"
               ServiceError: 
                ConnetError: "Runtime error occured in the service, please check with appplication support team before resubmitting the request"
        '502':
          description: Bad Gateway
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: Universal id to trace the transaction across all the systems involved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
               Status: "Failure"
               StatusCode: 502
               Severity: "Error"
               StatusDesc: "Error received from backend"
               TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
               X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
               TransactionTime: "2021-06-11T16:31:34.041Z"   
               ServiceError: 
                 connectError: "Connectivity error occured with the downstream service(Unexpected EOF at target), please check with appplication support team before resubmitting the request"
        '503':
          description: Service Unavailable
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: Universal id to trace the transaction across all the systems involved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
               Status: "Failure"
               StatusCode: 503
               Severity: "Error"
               StatusDesc: "Error received from backend"
               TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
               X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
               TransactionTime: "2021-06-11T16:31:34.041Z"   
               ServiceError: 
                 connectError: "Service is currently unavailable(NoActiveTargets), please check with appplication support before resubmitting the request."               
        '504':
          description: Gateway timeout
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: Universal id to trace the transaction across all the systems involved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
               Status: "Failure"
               StatusCode: 504
               Severity: "Error"
               StatusDesc: "Error received from backend"
               TransactionId: "rrt-7709400285867417207-b-gce-27587-2383364-1"
               X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
               TransactionTime: "2021-06-11T16:31:34.041Z"   
               ServiceError: 
                 connectError: "Request could not be processed on time(GatewayTimeout), please wait a moment and resubmit the request."                                                                         
  /accounts/payments/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: []
      parameters:
        - name: X-CorrelationId
          in: header
          schema:
            type: string
          required: false
          description: Universal id to trace the transaction across all the systems. CorrelationId is unique per request.
      responses:
        '200':
          description: Successful response
          headers:
            X-CorrelationId:
              schema:
                type: string
              description: Universal id to trace the transaction across all the systems involved.
          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]'             
components:
#---------------------------------------------------
# Data definitions
#--------------------------------------------------- 
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    healthResponse:
      type: object
      title: healthResponse
      properties:
        Status:
          type: string
          description: Status of the health check response.
        Source:
          type: string
          description: System producing the health response. Genesis of the response could either be just from “gateway” or “roundtrip” from the farthest possible system involved in generating this response.
        Timestamp:
          type: string
          description: Timestamp when the health response is being returned by this service.
        ClientIp:
          type: string
          description: IP of the client from which this request for health check is received by the gateway.
        X-Forwarded-For:
          type: string
          description: Sequence of all the Ips of the systems involved between the client and the gateway.  
    paymentsRequest: 
      title: paymentsRequest
      type: object
      required:  # List the required properties here
        - AccountNumber
        - BankNumber
        - CheckNumber
      properties:
        AccountNumber:
          type: string
          description: Account number for your request. The account number cannot be more than 16-digits.     
          example: "123456789"          
        BankNumber:
          type: string
          description: Bank number associated with the acocunt number. Valid values are 0101, 0241, 0618, 1256, 1961, 2912, 3211, 3290, 3720, 4451, 4560, 4731
          example: "3290"
        CheckNumber:
          description: Allows a range of check numbers to be stopped if both attributes (CheckNumberLow, CheckNumberHigh)  are used together.          
          $ref: '#/components/schemas/checkNumber'
        CheckAmount:  
          type: number
          description: Check amount associated with the check.
          example: "1.52"
        Description: 
          type: string
          description: Comments that describes stop payment reasons. Maximum of 30 characters.
          example: "Test Stop_SB_08130116"
    paymentsResponse:
      title: paymentsResponse
      type: object
      required:  # List the required properties here
        - Status
        - StatusCode
        - Severity
        - StatusDesc
        - TransactionId
        - X-CorrelationId
        - TransactionTime
      properties:
        Status: 
          type: string
          description: Indicates status of the processed request. Possible values are Success or Failure.
          example: Success        
        StatusCode:
          type: string
          description: Indicates status code of the processed request. For 402 errors, unique error code and description of the specific error will be returned from Stop Payment downstream system.
          example: "000"
        Severity:
          type: string
          description: Indicates severity level of the processed request. Possible values are Info, Error.
          example: "Info"  
        StatusDesc:
          type: string
          description: Indicates the status description of the processed request. For 402 errors, ASStatusCode and ASStatusDesc will have unique error code and description of the specific error returned from Stop Payment downstream system.
          example: stopPaymentAdd operation executed successfully - stopPaymentAdd_20190205024213818
        TransactionId:
          type: string
          description: Indicates the unique ID that gets assigned for processed request. 
          example: rrt-120879173347656522-b-gce-9473-8002956-1
        X-CorrelationId:
          type: string
          description: Indicates the universal id assigned for the processed request that is used for tracing.
          example: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
        TransactionTime: 
          type: string
          description: Indicates the transaction processed time. 
          example: "2021-06-30T18:55:10.337Z"
    checkNumber:
      type: object
      title: checkDetails
      required:  # List the required properties here
        - CheckNumberLow
      properties:
        CheckNumberLow:
          type: string
          description: If only one check  is to be stopped, use this field to enter that check number. If a range of checks are to be stopped, use this field to enter the starting range of check numbers.
          example: "10002"
        CheckNumberHigh: 
          type: string
          description: Use this field only when a range of checks are to be stopped where this field will indicate the maximum value of the check within the range to be stopped.        
          example: "10010"
    exception:
      type: object
      title: exceptionSchema
      required:  # List the required properties here
        - Status
        - StatusCode
        - Severity
        - StatusDesc
        - TransactionId
        - X-CorrelationId
        - TransactionTime
      properties:
        Status:
          type: string
          description: Indicates status of the processed request.
          example: Failure
        StatusCode:
          type: string
          description: Indicates status code of the processed request.
          example: "402"
        Severity:
          type: string
          description: Indicates severity level of the processed request.
          example: "Error"
        StatusDesc:
          type: string
          description: Indicates the status descrption of the processed request.
          example: Failed to add stop payment on account; STAR failed - stopPaymentAdd_20220526054255041
        TransactionId:
          type: string
          description: Indicates the unique ID that gets assigned for processed request. 
          example: "rrt-7354978519411102852-c-gce-30597-7590748-1"
        X-CorrelationId:
          type: string
          description: Indicates the universal id assigned for the processed request that is used for tracing.
          example: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
        TransactionTime: 
          type: string
          description: Indicates the transaction processed time
          example: "2021-06-30T18:55:10.337Z"
        ServiceError:
          type: object
          title: ServiceError
          description: Indicates the service error details, if available.   
          oneOf:          
          - $ref: '#/components/schemas/serviceErrorData'
          - $ref: '#/components/schemas/connectError'
    serviceErrorData:
      type: object
      title: serviceErrorData
      description: Detailed error information as generated by the chain of services involved.
      required:  # List the required properties here
        - SEStatusCode
        - SESeverity
        - SEStatusDesc
        - AdditionalStatus
      properties:
        SEStatusCode:
         type: string
         description: Indicates service error status code of the processed request.
         example: "402"
        SESeverity:
         type: string
         description: Indicates service error severity of the processed request.
         example: "Error"
        SEStatusDesc:
         type: string
         description: Indicates service error status description  of the processed request.
         example: Failed to add stop payment on account; STAR failed - stopPaymentAdd_20220526054255041
        AdditionalStatus:         
         $ref: '#/components/schemas/additionalStatusData'
    additionalStatusData:
      type: object
      title: Additional Status Data
      description: Indicates additional status data object of the processed request.     
      required:  # List the required properties here
        - ASStatusCode
        - ASSeverity
        - ASStatusDesc
        - SubjectElement
      properties:
        ASStatusCode:
         type: string
         description: Indicates additional status code  of the processed request.
         example: "202"
        ASSeverity:
         type: string
         description: Indicates additional status severity  of the processed request
         example: "Error"
        ASStatusDesc:
         type: string
         description: Indicates additional status  description  of the processed request.
         example: CHECK(S) ALREADY STOPPED
        SubjectElement:         
         $ref: '#/components/schemas/errorData'
    errorData:
      type: object
      title: errorDetails
      description: Indicates additional status code  of the processed request
      required:  # List the required properties here
        - Path
      properties:
        Path:
          type: string
          description: Indicates the operational path that failed and this is used for troubleshooting.
          example: STAR
    connectError:
      type: object
      properties:
        connectError:
          type: string
          description: Error information of the connectivity with downstream service.        
security:
#---------------------------------------------------
# List of supported security patterns
#---------------------------------------------------      
  - bearerAuth: [] # Secured API