Stop a check payment
Stop Payment API Endpoints
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 an issued check payment. A successful request stops the check 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 | Bank number associated with the account number. Valid values: 0101, 0241, 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 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. |
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" }
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. |
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 | 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. |
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": "000000057307_590_591", "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" } } } }
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. |
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" }
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. |
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" }
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. |
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" }
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. |
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" }
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. |
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" }
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. |
ServiceErroroptional | 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", "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. |
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 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. |
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 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. |
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
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 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. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
healthResponse
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. |
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 | 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 |
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. |
YAML file