openapi: 3.0.2
info:
#---------------------------------------------------
# Information to contact the API provider
#---------------------------------------------------
  title: Stop Payment API
  description: Use the Stop Payment API to stop an issued check payment. A successful request stops the check payment and returns confirmation and payment details. You can stop a payment between the hours of 6:00 AM and 11:59 PM EST.
  contact: 
   name: "KeyBank Developer Support"
   email: "developers@keybank.com"
  version: 1.0.4

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/healthCheck:
    get:
      tags: # Logical group based on functionality
        - HealthCheck
      summary: Health check
      description: Verify you can connect to the API service. A bearer token is required.
      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.
          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]'
  /accounts/payments/v1/stop:
    post:
      tags: # Logical group based on functionality
        - Accounts-StopPayments
      summary: Stop a payment
      description: Stop a check payment
      operationId: addStopPayment
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:     # Media type
            schema:             
              $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: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
          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 mandatory information
          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.
          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: Unauthorized request
          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.
          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: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
          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: Forbidden request access
          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.
          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: Resource not found
          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.
          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: Invalid request method
          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.
          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: Invalid request type
          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.
          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: Request timeout
          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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
               Status: "Failure"
               StatusCode: "429"
               Severity: "Error"
               StatusDesc: "Looks like you've sent too many requests. Please wait a moment and try again later."
               TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
               X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
               TransactionTime: "2022-05-17T04:39:32.449Z"
        '500':
          description: Unknown error
          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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              example:
               Status: "Failure"
               StatusCode: "500"
               Severity: "Error"
               StatusDesc: "Runtime error occurred in the service, please check with application 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: 
                connectError: "Runtime error occurred in the service, please check with application support team before resubmitting the request"
        '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 of API operations.
          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 occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
        '503':
          description: Unavailable service
          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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
              examples:
                sample1:
                  value:
                    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 application support before resubmitting the request."
                sample2:
                  value:
                    Status: "Failure"
                    StatusCode: "209"
                    Severity: "Error"
                    StatusDesc: "STOP SERVICE UNAVAILABLE. PLEASE RETRY BETWEEN 6:00AM AND 11:59PM ET."
                    TransactionId:  "rrt-7709400285867417207-b-gce-27587-2383364-1"
                    X-CorrelationId: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
                    TransactionTime: "2021-06-11T16:31:34.041Z"   
        '504':
          description: Unable to process request
          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.
          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."
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: Origin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved.
        Timestamp:
          type: string
          description: Date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
        ClientIp:
          type: string
          description: Client IP address the gateway receives from the request.
        X-Forwarded-For:
          type: string
          description: Sequence of IP addresses for systems between the client and the gateway.
    paymentsRequest:
      title: paymentsRequest
      type: object
      required: 
        - AccountNumber
        - BankNumber
        - CheckNumber
      properties:
        AccountNumber:
          type: string
          description: Bank account number. This field cannot exceed 16 characters.
          example: "123456789"
        BankNumber:
          type: string
          description: "Bank number associated with the account number. Valid values: 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: Amount of the check
          example: "1.52"
        Description:
          type: string
          description: Comments that describes stop payment reasons. This field cannot exceed 30 characters.
          example: "Test Stop_SB_08130116"
    paymentsResponse:
      title: paymentsResponse
      type: object
      required:  
        - Status
        - StatusCode
        - Severity
        - StatusDesc
        - TransactionId
        - X-CorrelationId
        - TransactionTime
      properties:
        Status:
          type: string
          description: "Status of the processed request. Valid values: Success, Failure"
          example: Success
        StatusCode:
          type: string
          description: Status code of the processed request.
          example: "000"
        Severity:
          type: string
          description: "Severity level of the processed request. Valid values: Info, Error"
          example: "Info"
        StatusDesc:
          type: string
          description: Status description of the processed request.
          example: stopPaymentAdd operation executed successfully - stopPaymentAdd_20190205024213818
        TransactionId:
          type: string
          description: Unique ID that gets assigned for the processed request.
          example: rrt-120879173347656522-b-gce-9473-8002956-1
        X-CorrelationId:
          type: string
          description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
          example: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
        TransactionTime:
          type: string
          description: Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
          example: "2021-06-30T18:55:10.337Z"
    checkNumber:
      type: object
      title: checkDetails
      description: 'Allows a range of check numbers to be stopped if both attributes (CheckNumberLow, CheckNumberHigh) are used together.'
      required:  
        - CheckNumberLow
      properties:
        CheckNumberLow:
          type: string
          description: To stop a single check, use this field to specify that check number. To stop a range of checks, use this field to specify the first check number of the range.
          example: "10002"
        CheckNumberHigh:
          type: string
          description: To stop a range of checks, use this field to specify the last check number in the range. This field is unnecessary when stopping a single check.
          example: "10010"
    exception:
      type: object
      title: exceptionSchema
      required:  
        - Status
        - StatusCode
        - Severity
        - StatusDesc
        - TransactionId
        - X-CorrelationId
        - TransactionTime
      properties:
        Status:
          type: string
          description: "Status of the processed request. Valid values: Success, Failure"
          example: Failure
        StatusCode:
          type: string
          description: Status code of the processed request.
          example: "402"
        Severity:
          type: string
          description: "Severity level of the processed request. Valid values: Info, Error"
          example: "Error"
        StatusDesc:
          type: string
          description: Status description of the processed request.
          example: Failed to add stop payment on account; STAR failed - stopPaymentAdd_20220526054255041
        TransactionId:
          type: string
          description: Unique ID that gets assigned for the processed request.
          example: "rrt-7354978519411102852-c-gce-30597-7590748-1"
        X-CorrelationId:
          type: string
          description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
          example: "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab"
        TransactionTime:
          type: string
          description: Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
          example: "2021-06-30T18:55:10.337Z"
        ServiceError:
          type: object
          title: ServiceError
          description: Detailed service-level error details, if available.
          oneOf:
          - $ref: '#/components/schemas/serviceErrorData'
          - $ref: '#/components/schemas/connectError'
    serviceErrorData:
      type: object
      title: serviceErrorData
      description: Detailed service-level error information, if available.
      required:
        - SEStatusCode
        - SESeverity
        - SEStatusDesc
        - AdditionalStatus
      properties:
        SEStatusCode:
         type: string
         description: Service error status code of the processed request.
         example: "402"
        SESeverity:
         type: string
         description: Service error severity of the processed request.
         example: "Error"
        SEStatusDesc:
         type: string
         description: 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: Additional status data object of the processed request.
      required:  
        - ASStatusCode
        - ASSeverity
        - ASStatusDesc
        - SubjectElement
      properties:
        ASStatusCode:
         type: string
         description: Additional status code of the processed request. For 402 errors, this field contains the unique error code returned from the Stop Payment downstream service.
         example: "202"
        ASSeverity:
         type: string
         description: Additional status severity of the processed request.
         example: "Error"
        ASStatusDesc:
         type: string
         description: Additional status description of the processed request. For 402 errors, this field contains the unique error description returned from the Stop Payment downstream service.
         example: CHECK(S) ALREADY STOPPED
        SubjectElement:
          description: Additional parameters for failures.
          $ref: '#/components/schemas/errorData'
    errorData:
      type: object
      title: errorDetails
      description: Additional parameters for failure
      required:
        - Path
      properties:
        Path:
          type: string
          description: Troubleshooting field that contains the operational path that failed.
          example: STAR
    connectError:
      type: object
      properties:
        connectError:
          type: string
          description: API connectivity error information, if available.
security:
#---------------------------------------------------
# List of supported security patterns
#---------------------------------------------------
  - bearerAuth: [] # Secured API
