Stop Payment

Stop a check payment

Stop Payment endpoints

What you can do	Endpoint
Health check	get /accounts/payments/v1/healthCheck
Stop a payment	post /accounts/payments/v1/stop

Key notes

Before you begin

All KeyBank APIs require certificates, user credentials, and certain permissions. Check out our Get Started Guide to learn more.

Payment stop window

You can only stop a payment between the hours of 06:00 a.m. and 11:59 p.m. EST.

Stop a payment

post /accounts/payments/v1/stop

Stop a check payment

Request

NAME	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
CheckAmount	number	Amount of the check
Description	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

healthResponse

NAME	TYPE	DESCRIPTION
Status	string	Status of the health check response.
Source	string	Origin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved.
Timestamp	string	Date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIp	string	Client IP address the gateway receives from the request.
X-Forwarded-For	string	Sequence of IP addresses for systems between the client and the gateway.

paymentsRequest

NAME	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
CheckAmount	number	Amount of the check
Description	string	Comments that describes stop payment reasons. This field cannot exceed 30 characters. Make sure special characters are correctly escaped to avoid errors.

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.

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.
CheckNumberHigh	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.
ServiceError	oneOf	serviceErrorData connectError

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

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

errorData

NAME	TYPE	DESCRIPTION
Pathrequired	string	Troubleshooting field that contains the operational path that failed.

connectError

NAME	TYPE	DESCRIPTION
connectError	string	API connectivity error information, if available.

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	`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.
503	209	`STOP SERVICE UNAVAILABLE, PLEASE RETRY BETWEEN 6:00AM AND 11:59PM ET` 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	Added `Api-Url` parameter to all instances of the `exception` schema. This parameter is now a standard part of all error messages to help you identify which call triggered an unsuccessful response.	LOW
April 2025	1.0.5	For `BankNumber`, added a reference table for code values to state locations. Modified the parameter description to include state abbreviates for each four-digit code.	LOW
August 2024	1.0.4	Added clarity to the `checkNumber` description. Parameter description updates. This change is for technical content only. The code and operations of the API remain the same.	MID
December 2022	1.0.0	Released on the Developer Portal.

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

Stop Payment endpoints

Key notes

Before you begin

Payment stop window

Stop a payment

Request

Request example

Responses

Successful response

Response example (200)

Missing mandatory information

Response example (400)

Unauthorized request

Response example (401)

Failure response from downstream

Response example (402)

Forbidden request access

Response example (403)

Resource not found

Response example (404)

Invalid request method

Response example (405)

Invalid request type

Response example (415)

Request timeout

Response example (429)

Unknown error

Response example (500)

Bad gateway

Response example (502)

Unavailable service

Response example (502)

Unable to process request

Response example (504)

Schemas

healthResponse

paymentsRequest

paymentsResponse

checkNumber

exception

serviceErrorData

additionalStatusData

errorData

connectError

Errors

Changelog

Impact levels

We value your feedback