Use the Stop Payment API to stop an issued payment. A successful request stops the payment and returns confirmation and payment details.
Prerequisites and best practices
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:
-
Have valid certificates for a secure connection.
-
Make sure you have the API keys needed for basic authentication and API access.
-
Request a bearer token before you start.
-
Check the health of the API.
Certificates
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.
API keys
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.
Bearer token
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.
Health check
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.
Endpoints
Endpoint | Result | Description |
---|---|---|
post /accounts/payments/v1/stop | Stop a payment | Request a stop for an issued payment. |
Stop a 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.
Request
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" }
Responses
Successful response
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" }
Missing data in 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 (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" }
Received request is unauthorized
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" }
Failure response from downstream
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" } } } }
Request is forbidden to access the resource
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" }
Requested resource is not found
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" }
Requested method is not allowed.
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" }
Requested unsupported media type
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" }
Too many requests received
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" }
Internal server error
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" } }
Bad Gateway
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" } }
Service Unavailable
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." } }
Gateway timeout
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." } }
Schemas
paymentsRequest
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. |
paymentsResponse
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. |
checkNumber
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. |
exception
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 |
serviceErrorData
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 |
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 |
errorData
NAME | TYPE | DESCRIPTION |
---|---|---|
Pathrequired | string | Indicates the operational path that failed and this is used for troubleshooting. |
connectError
NAME | TYPE | DESCRIPTION |
---|---|---|
connectErroroptional | string | Error information of the connectivity with downstream service. |
Error handling
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.
Status messages
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.
Standard error message format
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.
API-specific error messages
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.
Error codes and messages
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 serviceErrorData
object for additional information specific to the API request.
HTTP STATUS CODE | CUSTOM STATUS CODE | DESCRIPTION |
---|---|---|
400 |
|
|
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 |
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
