Stop a check payment
| What you can do | Endpoint |
|---|---|
| Health check | get /accounts/payments/v1/healthCheck |
| Stop a payment | post /accounts/payments/v1/stop |
Before you begin
All KeyBank APIs require certificates, user credentials, and certain permissions. Check out our Getting Started Guide to learn more.
Overview
Use the Stop Payment API to stop a check payment. A successful request stops the payment and returns confirmation and payment details. You can stop a payment between the hours of 06:00 a.m. and 11:59 p.m. EST.
Health check
get /accounts/payments/v1/healthCheck
Verify you can connect to the API service. A bearer token is required.
Responses
Successful response
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| Statusoptional | string | Status of the health check response. |
| Sourceoptional | string | Origin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved. |
| Timestampoptional | string | Date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service. |
| ClientIpoptional | string | Client IP address the gateway receives from the request. |
| X-Forwarded-Foroptional | string | Sequence of IP addresses for systems between the client and the gateway. |
Response example (200)
{
"Status": "Ok",
"Source": "Roundtrip",
"Timestamp": "2022-09-15T04:49:03",
"ClientIp": "156.77.111.28",
"X-Forwarded-For": "[156.77.111.28]"
}
Stop a payment
post /accounts/payments/v1/stop
Stop a check payment
Request
| BODY FIELD | TYPE | DESCRIPTION |
|---|---|---|
| AccountNumberrequired | string | Bank account number. This field cannot exceed 16 characters. |
| BankNumberrequired | string | A four-digit code that corresponds with the state location of the client's account. Use the USA code, 3211, if the state is not listed. Valid values: 0101 (OH), 0242 (AK), 0618 (CO), 1256 (ID), 1961 (ME), 2912 (NH), 3211 (USA), 3290 (NY), 3720 (OR), 4451 (UT), 4560 (VT), 4731 (WA) |
| CheckNumberrequired | Object | checkNumber |
| CheckAmountoptional | number | Amount of the check |
| Descriptionoptional | string | Comments that describes stop payment reasons. This field cannot exceed 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 | Status of the processed request. Valid values: Success, Failure |
| StatusCoderequired | string | Status code of the processed request. |
| Severityrequired | string | Severity level of the processed request. Valid values: Info, Error |
| StatusDescrequired | string | Status description of the processed request. |
| TransactionIdrequired | string | Unique ID that gets assigned for the processed request. |
| X-CorrelationIdrequired | string | A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. |
| TransactionTimerequired | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed. |
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 mandatory information
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| Statusrequired | string | Status of the processed request. Valid values: Success, Failure |
| StatusCoderequired | string | Status code of the processed request. |
| Severityrequired | string | Severity level of the processed request. Valid values: Info, Error |
| StatusDescrequired | string | Status description of the processed request. |
| TransactionIdrequired | string | Unique ID that gets assigned for the processed request. |
| X-CorrelationIdrequired | string | A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. |
| TransactionTimerequired | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed. |
| Api-Url | string | The API URL path of the call that generated the response. |
| ServiceError | 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",
"Api-Url": "\/accounts\/payments\/v1\/stop"
}Unauthorized request
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| Statusrequired | string | Status of the processed request. Valid values: Success, Failure |
| StatusCoderequired | string | Status code of the processed request. |
| Severityrequired | string | Severity level of the processed request. Valid values: Info, Error |
| StatusDescrequired | string | Status description of the processed request. |
| TransactionIdrequired | string | Unique ID that gets assigned for the processed request. |
| X-CorrelationIdrequired | string | A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. |
| TransactionTimerequired | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed. |
| Api-Url | string | The API URL path of the call that generated the response. |
| ServiceError | 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",
"Api-Url": "\/accounts\/payments\/v1\/stop"
}Failure response from downstream
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| Statusrequired | string | Status of the processed request. Valid values: Success, Failure |
| StatusCoderequired | string | Status code of the processed request. |
| Severityrequired | string | Severity level of the processed request. Valid values: Info, Error |
| StatusDescrequired | string | Status description of the processed request. |
| TransactionIdrequired | string | Unique ID that gets assigned for the processed request. |
| X-CorrelationIdrequired | string | A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. |
| TransactionTimerequired | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed. |
| Api-Url | string | The API URL path of the call that generated the response. |
| ServiceError | 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": "000000057307_590_591",
"X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
"TransactionTime": "2022-05-13T05:53:08.702Z",
"Api-Url": "\/accounts\/payments\/v1\/stop",
"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"
}
}
}
}Forbidden request access
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| Statusrequired | string | Status of the processed request. Valid values: Success, Failure |
| StatusCoderequired | string | Status code of the processed request. |
| Severityrequired | string | Severity level of the processed request. Valid values: Info, Error |
| StatusDescrequired | string | Status description of the processed request. |
| TransactionIdrequired | string | Unique ID that gets assigned for the processed request. |
| X-CorrelationIdrequired | string | A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. |
| TransactionTimerequired | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed. |
| Api-Url | string | The API URL path of the call that generated the response. |
| ServiceError | 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",
"Api-Url": "\/accounts\/payments\/v1\/stop"
}Resource not found
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| Statusrequired | string | Status of the processed request. Valid values: Success, Failure |
| StatusCoderequired | string | Status code of the processed request. |
| Severityrequired | string | Severity level of the processed request. Valid values: Info, Error |
| StatusDescrequired | string | Status description of the processed request. |
| TransactionIdrequired | string | Unique ID that gets assigned for the processed request. |
| X-CorrelationIdrequired | string | A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. |
| TransactionTimerequired | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed. |
| Api-Url | string | The API URL path of the call that generated the response. |
| ServiceError | 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",
"Api-Url": "\/accounts\/payments\/v1\/stop"
}Invalid request method
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| Statusrequired | string | Status of the processed request. Valid values: Success, Failure |
| StatusCoderequired | string | Status code of the processed request. |
| Severityrequired | string | Severity level of the processed request. Valid values: Info, Error |
| StatusDescrequired | string | Status description of the processed request. |
| TransactionIdrequired | string | Unique ID that gets assigned for the processed request. |
| X-CorrelationIdrequired | string | A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. |
| TransactionTimerequired | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed. |
| Api-Url | string | The API URL path of the call that generated the response. |
| ServiceError | 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",
"Api-Url": "\/accounts\/payments\/v1\/stop"
}Invalid request type
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| Statusrequired | string | Status of the processed request. Valid values: Success, Failure |
| StatusCoderequired | string | Status code of the processed request. |
| Severityrequired | string | Severity level of the processed request. Valid values: Info, Error |
| StatusDescrequired | string | Status description of the processed request. |
| TransactionIdrequired | string | Unique ID that gets assigned for the processed request. |
| X-CorrelationIdrequired | string | A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. |
| TransactionTimerequired | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed. |
| Api-Url | string | The API URL path of the call that generated the response. |
| ServiceError | 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",
"Api-Url": "\/accounts\/payments\/v1\/stop"
}Request timeout
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| Statusrequired | string | Status of the processed request. Valid values: Success, Failure |
| StatusCoderequired | string | Status code of the processed request. |
| Severityrequired | string | Severity level of the processed request. Valid values: Info, Error |
| StatusDescrequired | string | Status description of the processed request. |
| TransactionIdrequired | string | Unique ID that gets assigned for the processed request. |
| X-CorrelationIdrequired | string | A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. |
| TransactionTimerequired | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed. |
| Api-Url | string | The API URL path of the call that generated the response. |
| ServiceError | oneOf | serviceErrorData connectError |
Response example (429)

{
"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",
"Api-Url": "\/accounts\/payments\/v1\/stop"
}Unknown error
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| Statusrequired | string | Status of the processed request. Valid values: Success, Failure |
| StatusCoderequired | string | Status code of the processed request. |
| Severityrequired | string | Severity level of the processed request. Valid values: Info, Error |
| StatusDescrequired | string | Status description of the processed request. |
| TransactionIdrequired | string | Unique ID that gets assigned for the processed request. |
| X-CorrelationIdrequired | string | A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. |
| TransactionTimerequired | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed. |
| Api-Url | string | The API URL path of the call that generated the response. |
| ServiceError | oneOf | serviceErrorData connectError |
Response example (500)

{
"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",
"Api-Url": "\/accounts\/payments\/v1\/stop",
"ServiceError": {
"connectError": "Runtime error occurred in the service, please check with application support team before resubmitting the request"
}
}Bad gateway
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| Statusrequired | string | Status of the processed request. Valid values: Success, Failure |
| StatusCoderequired | string | Status code of the processed request. |
| Severityrequired | string | Severity level of the processed request. Valid values: Info, Error |
| StatusDescrequired | string | Status description of the processed request. |
| TransactionIdrequired | string | Unique ID that gets assigned for the processed request. |
| X-CorrelationIdrequired | string | A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. |
| TransactionTimerequired | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed. |
| Api-Url | string | The API URL path of the call that generated the response. |
| ServiceError | 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",
"Api-Url": "\/accounts\/payments\/v1\/stop",
"ServiceError": {
"connectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
}
}Unavailable service
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| Statusrequired | string | Status of the processed request. Valid values: Success, Failure |
| StatusCoderequired | string | Status code of the processed request. |
| Severityrequired | string | Severity level of the processed request. Valid values: Info, Error |
| StatusDescrequired | string | Status description of the processed request. |
| TransactionIdrequired | string | Unique ID that gets assigned for the processed request. |
| X-CorrelationIdrequired | string | A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. |
| TransactionTimerequired | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed. |
| Api-Url | string | The API URL path of the call that generated the response. |
| ServiceError | 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",
"Api-Url": "\/accounts\/payments\/v1\/stop",
"ServiceError": {
"connectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
}
}Unable to process request
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| Statusrequired | string | Status of the processed request. Valid values: Success, Failure |
| StatusCoderequired | string | Status code of the processed request. |
| Severityrequired | string | Severity level of the processed request. Valid values: Info, Error |
| StatusDescrequired | string | Status description of the processed request. |
| TransactionIdrequired | string | Unique ID that gets assigned for the processed request. |
| X-CorrelationIdrequired | string | A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. |
| TransactionTimerequired | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed. |
| Api-Url | string | The API URL path of the call that generated the response. |
| ServiceError | 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",
"Api-Url": "\/accounts\/payments\/v1\/stop",
"ServiceError": {
"connectError": "Request could not be processed on time (GatewayTimeout), please wait a moment and resubmit the request."
}
}Schemas
additionalStatusData
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| ASStatusCoderequired | string | Additional status code of the processed request. For 402 errors, this field contains the unique error code returned from the Stop Payment downstream service. |
| ASSeverityrequired | string | Additional status severity of the processed request. |
| ASStatusDescrequired | string | Additional status description of the processed request. For 402 errors, this field contains the unique error description returned from the Stop Payment downstream service. |
| SubjectElementrequired | Object | errorData |
checkNumber
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| CheckNumberLowrequired | string | 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. |
| CheckNumberHighoptional | string | 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. |
exception
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| Statusrequired | string | Status of the processed request. Valid values: Success, Failure |
| StatusCoderequired | string | Status code of the processed request. |
| Severityrequired | string | Severity level of the processed request. Valid values: Info, Error |
| StatusDescrequired | string | Status description of the processed request. |
| TransactionIdrequired | string | Unique ID that gets assigned for the processed request. |
| X-CorrelationIdrequired | string | A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. |
| TransactionTimerequired | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed. |
| Api-Url | string | The API URL path of the call that generated the response. |
| ServiceError | oneOf | serviceErrorData connectError |
connectError
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| connectErroroptional | string | API connectivity error information, if available. |
errorData
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| Pathrequired | string | Troubleshooting field that contains the operational path that failed. |
paymentsRequest
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| AccountNumberrequired | string | Bank account number. This field cannot exceed 16 characters. |
| BankNumberrequired | string | Bank number associated with the account number. Valid values: 0101, 0242, 0618, 1256, 1961, 2912, 3211, 3290, 3720, 4451, 4560, 4731 |
| CheckNumberrequired | Object | checkNumber |
| CheckAmountoptional | number | Amount of the check |
| Descriptionoptional | string | Comments that describes stop payment reasons. This field cannot exceed 30 characters. |
paymentsResponse
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| Statusrequired | string | Status of the processed request. Valid values: Success, Failure |
| StatusCoderequired | string | Status code of the processed request. |
| Severityrequired | string | Severity level of the processed request. Valid values: Info, Error |
| StatusDescrequired | string | Status description of the processed request. |
| TransactionIdrequired | string | Unique ID that gets assigned for the processed request. |
| X-CorrelationIdrequired | string | A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. |
| TransactionTimerequired | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed. |
serviceErrorData
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| SEStatusCoderequired | string | Service error status code of the processed request. |
| SESeverityrequired | string | Service error severity of the processed request. |
| SEStatusDescrequired | string | Service error status description of the processed request. |
| AdditionalStatusrequired | Object | additionalStatusData |
Errors
For more information about general errors, see Error handling.
Note: The Stop Payment API is unavailable between the hours of 12:00 a.m. and 6:00 a.m. EST. If a request to stop payment is submitted within this timeframe you will receive an error.
There may be additional error information in the exception schema. API-specific KeyBank error codes and details are in the serviceErrorData. object for additional information specific to the API request.
| HTTP STATUS CODE | CUSTOM STATUS CODE | DESCRIPTION |
|---|---|---|
| 402 | 202 |
A stop payment has already been placed on that check and or account. |
| 402 | 201 |
Check has already posted to the account. |
| 402 | 203 |
The payment was already stopped. |
| 402 | 208 |
There is an invalid value for the |
| 503 | 209 |
The Stop Payment API is unavailable between the hours of 12:00 a.m. and 06:00 a.m. EST. Please retry your request outside of this time window. |
Changelog
| Release | API version | Change description | Impact |
|---|---|---|---|
| September 2025 | 1.0.6 |
| LOW |
| April 2025 | 1.0.5 |
| LOW |
| August 2024 | 1.0.4 |
| MID |
| December 2022 | 1.0.0 |
|
Impact levels
- LOW: This is a minor change or enhancement that does not alter the operations of the API. Upgrading to the latest specifications is preferable but not required.
- MID: The previous API version is valid and operates, but does not contain latest enhancements. You need to update your specifications to get these enhancements.
- HIGH: The previous API version is no longer operable. You must upgrade to the latest specifications to access and use this API product.
YAML file