Stop Payment

3-minute read 1.0.2 | updated Dec. 13, 2023

 

Stop an issued 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.

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 06:00 a.m. and 11:59 p.m. EST.

 

get /accounts/payments/v1/healthCheck

Verify you can connect to the API service. A bearer token is required.

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.
 
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]"
}

Request a stop for an issued payment.

post /accounts/payments/v1/stop

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, 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"
}
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"
}
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": "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"
}
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": "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"
}
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"
            }
        }
    }
}
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": "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"
}
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": "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"
}
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": "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"
}
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": "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"
}
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"
}
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": "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": {
        "ConnetError": "Runtime error occurred in the service, please check with application support team before resubmitting the 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 (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"
    }
}
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": "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"
    }
}
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": "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."
    }
}
NAMETYPEDESCRIPTION
ASStatusCoderequiredstringAdditional status code of the processed request. For 402 errors, this field contains the unique error code returned from the Stop Payment downstream service.
ASSeverityrequiredstringAdditional status severity of the processed request.
ASStatusDescrequiredstringAdditional status description of the processed request. For 402 errors, this field contains the unique error description returned from the Stop Payment downstream service.
SubjectElementrequiredObjecterrorData
NAMETYPEDESCRIPTION
CheckNumberLowrequiredstringTo 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.
CheckNumberHighoptionalstringTo 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.
NAMETYPEDESCRIPTION
connectErroroptionalstringAPI connectivity error information, if available.
NAMETYPEDESCRIPTION
PathrequiredstringTroubleshooting field that contains the operational path that failed.
NAMETYPEDESCRIPTION
StatusrequiredstringStatus of the processed request. Valid values: Success, Failure
StatusCoderequiredstringStatus code of the processed request.
SeverityrequiredstringSeverity level of the processed request. Valid values: Info, Error
StatusDescrequiredstringStatus description of the processed request.
TransactionIdrequiredstringUnique ID that gets assigned for the processed request.
X-CorrelationIdrequiredstringA universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimerequiredstringDate (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
ServiceErroroptionaloneOfserviceErrorData connectError
NAMETYPEDESCRIPTION
StatusoptionalstringStatus of the health check response.
SourceoptionalstringOrigin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved.
TimestampoptionalstringDate (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIpoptionalstringClient IP address the gateway receives from the request.
X-Forwarded-ForoptionalstringSequence of IP addresses for systems between the client and the gateway.
NAMETYPEDESCRIPTION
AccountNumberrequiredstringBank account number. This field cannot exceed 16 characters.
BankNumberrequiredstringBank number associated with the account number. Valid values: 0101, 0242, 0618, 1256, 1961, 2912, 3211, 3290, 3720, 4451, 4560, 4731
CheckNumberrequiredObjectcheckNumber
CheckAmountoptionalnumberAmount of the check
DescriptionoptionalstringComments that describes stop payment reasons. This field cannot exceed 30 characters.
NAMETYPEDESCRIPTION
StatusrequiredstringStatus of the processed request. Valid values: Success, Failure
StatusCoderequiredstringStatus code of the processed request.
SeverityrequiredstringSeverity level of the processed request. Valid values: Info, Error
StatusDescrequiredstringStatus description of the processed request.
TransactionIdrequiredstringUnique ID that gets assigned for the processed request.
X-CorrelationIdrequiredstringA universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
TransactionTimerequiredstringDate (YYYY-MM-DD) and time (HH:MM:SS) the transaction processed.
NAMETYPEDESCRIPTION
SEStatusCoderequiredstringService error status code of the processed request.
SESeverityrequiredstringService error severity of the processed request.
SEStatusDescrequiredstringService error status description of the processed request.
AdditionalStatusrequiredObjectadditionalStatusData

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.

 

YAML file