Stop Payment | API Documentation

Use the Stop Payment API to stop an issued payment. A successful request stops the payment and returns confirmation and payment details. You can stop a payment between the hours of 6:00 AM and 11:59 PM EST.

Before you begin

All KeyBank APIs require certificates, user credentials, and certain permissions. Before you begin, see Key concepts to learn more about these fundamental elements as well as other recommended best practices.

Stop Payment Endpoints

Summary	Endpoint
Stop a payment	post /accounts/payments/v1/stop

Stop a payment

post /accounts/payments/v1/stop

Request a stop for an issued payment.

Request

header FIELD	TYPE	DESCRIPTION
X-CorrelationIdoptional	string	A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.

BODY FIELD	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.

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
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 data

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimerequired	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (400)

{
    "Status": "Failure",
    "StatusCode": 400,
    "Severity": "Error",
    "StatusDesc": "Please make sure your request is correct and try again.",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimerequired	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (401)

{
    "Status": "Failure",
    "StatusCode": 401,
    "Severity": "Error",
    "StatusDesc": "Please make sure you're using the correct credentials. Then log in again.",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Failure 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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimerequired	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
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"
            }
        }
    }
}

Access denied

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimerequired	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (403)

{
    "Status": "Failure",
    "StatusCode": 403,
    "Severity": "Error",
    "StatusDesc": "You don't have access to this resource. Contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimerequired	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (404)

{
    "Status": "Failure",
    "StatusCode": 404,
    "Severity": "Error",
    "StatusDesc": "We can't seem to find what you're looking for. Please verify the resource and try again.",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request method denied

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimerequired	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (405)

{
    "Status": "Failure",
    "StatusCode": 405,
    "Severity": "Error",
    "StatusDesc": "Looks like something went wrong. Please check your request method and try again.",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Media type not supported

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimerequired	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (415)

{
    "Status": "Failure",
    "StatusCode": 415,
    "Severity": "Error",
    "StatusDesc": "We currently don't support that format. Please check the format type defined in your request and try again. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "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

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimerequired	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
ServiceErroroptional	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"
}

Internal server 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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimerequired	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (500)

{
    "Status": "Failure",
    "StatusCode": 500,
    "Severity": "Error",
    "StatusDesc": "Looks like something went wrong. Please try again when you're ready. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "3288b87c-d4e7-639a-88d0-9cdfede8941e",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "connectError": "Runtime error occurred in the service, please check with application support team before resubmitting the request"
    }
}

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimerequired	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

{
    "Status": "Failure",
    "StatusCode": 502,
    "Severity": "Error",
    "StatusDesc": "Looks like something went wrong. Please try again when you're ready. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "connectError": "A connectivity error occurred with the downstream service (unexpected end of file at the target). Please check with your KeyBank Client Success Manager or email developers@keybank.com before trying the request again."
    }
}

Service unavailable

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimerequired	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

{
    "Status": "Failure",
    "StatusCode": 502,
    "Severity": "Error",
    "StatusDesc": "Looks like something went wrong. Please try again when you're ready. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "connectError": "A connectivity error occurred with the downstream service (unexpected end of file at the target). Please check with your KeyBank Client Success Manager or email developers@keybank.com before trying the request again."
    }
}

Gateway 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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimerequired	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (504)

{
    "Status": "Failure",
    "StatusCode": 504,
    "Severity": "Error",
    "StatusDesc": "Your request took too long to process. Please try again. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "connectError": "The request could not be processed on time (gateway timeout). Please wait a moment and try again later."
    }
}

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.

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.

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimerequired	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
ServiceErroroptional	oneOf	serviceErrorData connectError

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 universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
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 errors, see Error handling.

Note: The Stop Payment API is unavailable between the hours of 12:00 AM and 6:00 AM EST. If a request to stop payment is submitted within this timeframe you will receive an error.

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
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 AM and 6:00 AM EST. Please retry your request outside of this time window.

YAML file