Stop Payment

13 minute read 1.0.0 | updated Feb. 13, 2023

Use the Stop Payment API to stop an issued payment. A successful request stops the payment and returns confirmation and payment details.

KeyBank has some common prerequisites and best practices. All KeyBank APIs require certifications, user credentials, and certain permissions. Make sure to satisfy all prerequisites before building your API.

Follow these steps to prepare for operations:

  1. Have valid certificates for a secure connection.

  2. Make sure you have the API keys needed for basic authentication and API access.

  3. Request a bearer token before you start.

  4. Check the health of the API.

Certificates are a digital authentication method we use to encrypt the information exchanged between KeyBank and your app or service. To access KeyBank environments, you must exchange valid certificates with KeyBank. These certificates must be properly installed on your system before you start to send API calls.

You need API keys to get a bearer token and to grant access to the APIs and the Pre-Production or Production environments. These API keys are created only for authenticated users that have partnered with KeyBank. For more information, see API security or sign up to become a KeyBank API consumer.

Get a bearer token before you start. Only authenticated users with client credentials can request a bearer token. For more information, see API security or sign up to become a KeyBank API consumer.

Before you start building your API, perform a quick health check. A health check verifies that the API is operational and responding correctly with your system. A bearer token is required to perform a health check. For more information, see Health check.

Endpoint Result Description
post /accounts/payments/v1/stop Stop a payment Request a stop for an issued payment.

post /accounts/payments/v1/stop

Submit a request to stop an issue payment. A successful request returns the status of the payment, whether the request was successful in stopping the payment or if the payment has been processed and could not be stopped.

Required parameters: Content-Type, AccountNumber, BankNumber, CheckNumber, checkNumberLow

HEADER FIELD TYPE DESCRIPTION
X-CorrelationIdoptional string Universal id to trace the transaction across all the systems. CorrelationId is unique per request.
BODY FIELD TYPE DESCRIPTION
AccountNumberrequired string Account number for your request. The account number cannot be more than 16-digits.
BankNumberrequired string Bank number associated with the acocunt number. Valid values are 0101, 0241, 0618, 1256, 1961, 2912, 3211, 3290, 3720, 4451, 4560, 4731
CheckNumberrequired Object checkNumber
CheckAmountoptional number Check amount associated with the check.
Descriptionoptional string Comments that describes stop payment reasons. Maximum of 30 characters.

Request example

{
    "AccountNumber": "123456789",
    "BankNumber": "0101",
    "CheckNumber": {
        "CheckNumberLow": "590",
        "CheckNumberHigh": "591"
    },
    "CheckAmount": 1.52,
    "Description": "Test Stop_SB_08130116"
}
NAME TYPE DESCRIPTION
Statusrequired string Indicates status of the processed request. Possible values are Success or Failure.
StatusCoderequired string 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.
Severityrequired string Indicates severity level of the processed request. Possible values are Info, Error.
StatusDescrequired string 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.
TransactionIdrequired string Indicates the unique ID that gets assigned for processed request.
X-CorrelationIdrequired string Indicates the universal id assigned for the processed request that is used for tracing.
TransactionTimerequired string Indicates the transaction processed time.

Response example (200)

{
    "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"
}
NAME TYPE DESCRIPTION
Statusrequired string Indicates status of the processed request.
StatusCoderequired string Indicates status code of the processed request.
Severityrequired string Indicates severity level of the processed request.
StatusDescrequired string Indicates the status descrption of the processed request.
TransactionIdrequired string Indicates the unique ID that gets assigned for processed request.
X-CorrelationIdrequired string Indicates the universal id assigned for the processed request that is used for tracing.
TransactionTimerequired string Indicates the transaction processed time
ServiceErroroptional oneOf serviceErrorData connectError

Response example (400)

{
    "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"
}
NAME TYPE DESCRIPTION
Statusrequired string Indicates status of the processed request.
StatusCoderequired string Indicates status code of the processed request.
Severityrequired string Indicates severity level of the processed request.
StatusDescrequired string Indicates the status descrption of the processed request.
TransactionIdrequired string Indicates the unique ID that gets assigned for processed request.
X-CorrelationIdrequired string Indicates the universal id assigned for the processed request that is used for tracing.
TransactionTimerequired string Indicates the transaction processed time
ServiceErroroptional oneOf serviceErrorData connectError

Response example (401)

{
    "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"
}
NAME TYPE DESCRIPTION
Statusrequired string Indicates status of the processed request.
StatusCoderequired string Indicates status code of the processed request.
Severityrequired string Indicates severity level of the processed request.
StatusDescrequired string Indicates the status descrption of the processed request.
TransactionIdrequired string Indicates the unique ID that gets assigned for processed request.
X-CorrelationIdrequired string Indicates the universal id assigned for the processed request that is used for tracing.
TransactionTimerequired string Indicates the transaction processed time
ServiceErroroptional oneOf serviceErrorData connectError

Response example (402)

{
    "Status": "Failure",
    "StatusCode": 402,
    "Severity": "Error",
    "StatusDesc": "Failed to add stop payment on account; STAR failed  - stopPaymentAdd_20220513015308610",
    "TransactionId": "000000057307590591",
    "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"
            }
        }
    }
}
NAME TYPE DESCRIPTION
Statusrequired string Indicates status of the processed request.
StatusCoderequired string Indicates status code of the processed request.
Severityrequired string Indicates severity level of the processed request.
StatusDescrequired string Indicates the status descrption of the processed request.
TransactionIdrequired string Indicates the unique ID that gets assigned for processed request.
X-CorrelationIdrequired string Indicates the universal id assigned for the processed request that is used for tracing.
TransactionTimerequired string Indicates the transaction processed time
ServiceErroroptional oneOf serviceErrorData connectError

Response example (403)

{
    "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"
}
NAME TYPE DESCRIPTION
Statusrequired string Indicates status of the processed request.
StatusCoderequired string Indicates status code of the processed request.
Severityrequired string Indicates severity level of the processed request.
StatusDescrequired string Indicates the status descrption of the processed request.
TransactionIdrequired string Indicates the unique ID that gets assigned for processed request.
X-CorrelationIdrequired string Indicates the universal id assigned for the processed request that is used for tracing.
TransactionTimerequired string Indicates the transaction processed time
ServiceErroroptional oneOf serviceErrorData connectError

Response example (404)

{
    "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"
}
NAME TYPE DESCRIPTION
Statusrequired string Indicates status of the processed request.
StatusCoderequired string Indicates status code of the processed request.
Severityrequired string Indicates severity level of the processed request.
StatusDescrequired string Indicates the status descrption of the processed request.
TransactionIdrequired string Indicates the unique ID that gets assigned for processed request.
X-CorrelationIdrequired string Indicates the universal id assigned for the processed request that is used for tracing.
TransactionTimerequired string Indicates the transaction processed time
ServiceErroroptional oneOf serviceErrorData connectError

Response example (405)

{
    "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"
}
NAME TYPE DESCRIPTION
Statusrequired string Indicates status of the processed request.
StatusCoderequired string Indicates status code of the processed request.
Severityrequired string Indicates severity level of the processed request.
StatusDescrequired string Indicates the status descrption of the processed request.
TransactionIdrequired string Indicates the unique ID that gets assigned for processed request.
X-CorrelationIdrequired string Indicates the universal id assigned for the processed request that is used for tracing.
TransactionTimerequired string Indicates the transaction processed time
ServiceErroroptional oneOf serviceErrorData connectError

Response example (415)

{
    "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"
}
NAME TYPE DESCRIPTION
Statusrequired string Indicates status of the processed request.
StatusCoderequired string Indicates status code of the processed request.
Severityrequired string Indicates severity level of the processed request.
StatusDescrequired string Indicates the status descrption of the processed request.
TransactionIdrequired string Indicates the unique ID that gets assigned for processed request.
X-CorrelationIdrequired string Indicates the universal id assigned for the processed request that is used for tracing.
TransactionTimerequired string Indicates the transaction processed time
ServiceErroroptional oneOf serviceErrorData connectError

Response example (429)

{
    "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"
}
NAME TYPE DESCRIPTION
Statusrequired string Indicates status of the processed request.
StatusCoderequired string Indicates status code of the processed request.
Severityrequired string Indicates severity level of the processed request.
StatusDescrequired string Indicates the status descrption of the processed request.
TransactionIdrequired string Indicates the unique ID that gets assigned for processed request.
X-CorrelationIdrequired string Indicates the universal id assigned for the processed request that is used for tracing.
TransactionTimerequired string Indicates the transaction processed time
ServiceErroroptional oneOf serviceErrorData connectError

Response example (500)

{
    "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"
    }
}
NAME TYPE DESCRIPTION
Statusrequired string Indicates status of the processed request.
StatusCoderequired string Indicates status code of the processed request.
Severityrequired string Indicates severity level of the processed request.
StatusDescrequired string Indicates the status descrption of the processed request.
TransactionIdrequired string Indicates the unique ID that gets assigned for processed request.
X-CorrelationIdrequired string Indicates the universal id assigned for the processed request that is used for tracing.
TransactionTimerequired string Indicates the transaction processed time
ServiceErroroptional oneOf serviceErrorData connectError

Response example (502)

{
    "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"
    }
}
NAME TYPE DESCRIPTION
Statusrequired string Indicates status of the processed request.
StatusCoderequired string Indicates status code of the processed request.
Severityrequired string Indicates severity level of the processed request.
StatusDescrequired string Indicates the status descrption of the processed request.
TransactionIdrequired string Indicates the unique ID that gets assigned for processed request.
X-CorrelationIdrequired string Indicates the universal id assigned for the processed request that is used for tracing.
TransactionTimerequired string Indicates the transaction processed time
ServiceErroroptional oneOf serviceErrorData connectError

Response example (503)

{
    "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."
    }
}
NAME TYPE DESCRIPTION
Statusrequired string Indicates status of the processed request.
StatusCoderequired string Indicates status code of the processed request.
Severityrequired string Indicates severity level of the processed request.
StatusDescrequired string Indicates the status descrption of the processed request.
TransactionIdrequired string Indicates the unique ID that gets assigned for processed request.
X-CorrelationIdrequired string Indicates the universal id assigned for the processed request that is used for tracing.
TransactionTimerequired string Indicates the transaction processed time
ServiceErroroptional oneOf serviceErrorData connectError

Response example (504)

{
    "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."
    }
}
NAME TYPE DESCRIPTION
AccountNumberrequired string Account number for your request. The account number cannot be more than 16-digits.
BankNumberrequired string Bank number associated with the acocunt number. Valid values are 0101, 0241, 0618, 1256, 1961, 2912, 3211, 3290, 3720, 4451, 4560, 4731
CheckNumberrequired Object checkNumber
CheckAmountoptional number Check amount associated with the check.
Descriptionoptional string Comments that describes stop payment reasons. Maximum of 30 characters.
NAME TYPE DESCRIPTION
Statusrequired string Indicates status of the processed request. Possible values are Success or Failure.
StatusCoderequired string 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.
Severityrequired string Indicates severity level of the processed request. Possible values are Info, Error.
StatusDescrequired string 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.
TransactionIdrequired string Indicates the unique ID that gets assigned for processed request.
X-CorrelationIdrequired string Indicates the universal id assigned for the processed request that is used for tracing.
TransactionTimerequired string Indicates the transaction processed time.
NAME TYPE DESCRIPTION
CheckNumberLowrequired string 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.
CheckNumberHighoptional string 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.
NAME TYPE DESCRIPTION
Statusrequired string Indicates status of the processed request.
StatusCoderequired string Indicates status code of the processed request.
Severityrequired string Indicates severity level of the processed request.
StatusDescrequired string Indicates the status descrption of the processed request.
TransactionIdrequired string Indicates the unique ID that gets assigned for processed request.
X-CorrelationIdrequired string Indicates the universal id assigned for the processed request that is used for tracing.
TransactionTimerequired string Indicates the transaction processed time
ServiceErroroptional oneOf serviceErrorData connectError
NAME TYPE DESCRIPTION
SEStatusCoderequired string Indicates service error status code of the processed request.
SESeverityrequired string Indicates service error severity of the processed request.
SEStatusDescrequired string Indicates service error status description of the processed request.
AdditionalStatusrequired Object additionalStatusData
NAME TYPE DESCRIPTION
ASStatusCoderequired string Indicates additional status code of the processed request.
ASSeverityrequired string Indicates additional status severity of the processed request
ASStatusDescrequired string Indicates additional status description of the processed request.
SubjectElementrequired Object errorData
NAME TYPE DESCRIPTION
Pathrequired string Indicates the operational path that failed and this is used for troubleshooting.
NAME TYPE DESCRIPTION
connectErroroptional string Error information of the connectivity with downstream service.

An error can indicate a problem with the request, the network, or the API itself. Use the error handling information to get a better understanding of what went wrong and possible corrective actions.

Some APIs contain status messages in their response payload. These messages can contain custom error details particular to the API call. For the Stop Payment API, the response has three status fields: Status, StatusCode, and StatusDesc. Status will indicate whether the request was a success or a failure. StatusCode returns the HTTP status code and the StatusDesc returns the message with additional information.

An erroneous response returns the HTTP code number with the content of the exception schema. Additional information in this schema like the transaction ID and transaction time can help you diagnose the issue.

The schema includes the X-CorrelationId field to help with traceability.

Custom messages are used for API-related functional business messages or faults. Each API can contain custom messages specific to KeyBank operations or the API. These messages can be part of the exception schema or a separate object.

KeyBank uses the serviceErrorData object for errors specific to the API.

Most of the errors use HTTP status codes. Messages specific to KeyBank have an asterisk (*) after the message code number. Business error messages use the serviceErrorDataobject for additional information specific to the API request.

HTTP STATUS CODE CUSTOM STATUS CODE DESCRIPTION
400  

Missing data in the request.
Mandatory data not provided, please verify the data and resubmit the request.
401   Received request is unauthorized.
Received request is unauthorized, please provide valid credentials.
402* 202 CHECK(S) ALREADY STOPPED
Failed to add stop payment on account.

A stop payment has already been placed on that check and or account.
402* 201 CHECKS(S) ALREADY POSTED TODAY
Failed to add stop payment on account.

Check has already posted to the account.
402* 203 TELLER CHECK HOLD ON ACCOUNT
Failed to add stop payment on account.

The payment was already stopped.
402* 208 ERROR LOCATING DDA
Failed to add stop payment on account.

There is an invalid value for the accountNumber field. Review and make sure the accountNumber is correct.
403   Request is forbidden to access the resource.
Access to requested resource is forbidden.
404   Request resource is not found.
Requested resource is not found, please verify the resource and resubmit the request.
405   Request method is not allowed.
Requested method is not allow, please verify the method and resubmit the request.
415   Requested unsupported media type.
Requested media type is not allowed, please verify the media type and resubmit the request.
429   Too many request received.
Number requests threshold reached, please resubmit the request after sometime.
500   Internal server error.
Unknown error occurred, please resubmit the request.
502   Bad Gateway.
Bad Gateway, please resubmit the request
503   Service Unavailable.
Service is currently unavailable, please resubmit the request.
504   Gateway timeout.
Request could not be processed on time, please resubmit the request.
YAML file