Check Services | Developer Portal

Modern control for an old school payment

Check Services Endpoints

Summary	Endpoint
Health check	get /commercial/checks/v1/healthCheck
Place a stop payment	post /commercial/checks/v1/stops/place
List of check images	post /commercial/checks/v1/images/list

Key notes

Before you begin

All KeyBank APIs require certificates, user credentials, and certain permissions. Check out our Getting started sections to learn more.

Stop payment limits

You can only stop a payment between the hours of 06:00 a.m. and 11:59 p.m. ET.
The standard rate limiting applies of 5 TPS.

Special characters

All special characters are allowed if properly escaped except for the ampersand (&) character.

Special character	Name
*	asterisk
#	hash or number symbol
@	at sign
&	ampersand Note: Not allowed for /stops/place endpoint.
-	hyphen
_	underscore
,	comma
.	period
/	forward slash
\	back slash
" "	quotations

Health check

get /commercial/checks/v1/healthCheck

Check the health of an API service and verify you can successfully connect. A bearer token is required.

Request example

curl "https://partner-api-qv.key.com/commercial/checks/v1/healthCheck"
--header 'Bearer testZcKJDWnwDWmmf9qah6PJvPy8'

Responses

Successful response

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.

Response example (200)

{
    "Status": "Ok",
    "Source": "Roundtrip",
    "Timestamp": "2022-09-15T04:49:03",
    "ClientIp": "192.0.2.1",
    "X-Forwarded-For": "[192.0.2.1]"
}

Place a stop payment

post /commercial/checks/v1/stops/place

Places a stop payment for an account using an account number and check number. You can only stop a payment between the hours of 06:00 a.m. and 11:59 p.m. ET.

Note: This API is currently undergoing enhancements to improve synchronization. During this transition period, some capabilities may be limited. For full functionality, continue using the legacy endpoint: POST /accounts/payments/v1/stop.

Contact your Technical Account Manager for access or support.

Request

NAME	TYPE	DESCRIPTION
accountNumberrequired	string	The account number to place the stop payment. This is a numeric ID and should not exceed 16 characters.
checkAmount	number	The amount of the check to stop. Must be a valid monetary value with no more than two decimal places.
issueDate	string	The original check issue date. This must be a valid calendar date in the correct format. Format: YYYY-MM-DD
checkNumberStartrequired	integer	The starting (lowest) check number in the range for which a stop payment is requested.
checkNumberEnd	integer	The last (hightest) check number in the range for which a stop payment is requested. If the number is not specified, it will default to the same value as checkNumberStart.
description	string	A custom text field to provide a brief explanation of the stop payment request.

Request example

{
  "accountNumber": "12345678910",
  "checkAmount": 12.12,
  "issueDate": "2026-02-14",
  "checkNumberStart": 8940,
  "checkNumberEnd": 8963,
  "description": "Stop payment for issued check range"
}

Responses

Successful response with stop payment records

NAME	TYPE	DESCRIPTION
stopPayments	Object	StopPayments

Response example (200)

{
  "accountNumber": "12345678910",
  "checkNumberStart": 8940,
  "checkNumberEnd": 8963,
  "checkAmount": 12.12,
  "expirationDate": "2026-09-14",
  "description": "Stop payment for issued check range",
  "placedDate": "2026-03-14",
  "issueDate": "2026-02-14"  
}

Accepted response with stop payment records

The stop payment request was accepted and submitted for processing, but final confirmation was not available before the response timeout. Do not assume the request failed and there is not a need to immediately resubmit the same stop payment request. The original request may still complete successfully. If the same request is submitted again after processing completes, the API will return a HTTP 409 Duplicate Stop response indicating the first request completed successfully. Retain the X-CorrelationId for tracking or support.

NAME	TYPE	DESCRIPTION
stopPayments	Object	StopPayments

Response example (202)

{
    "metadata": {
        "messages": [
            {
                "code": "STOP-Place-202-processing",
                "message": "Your request for placing a stop is accepted and is still being processed."
            }
        ]
    }
}

Validation failure on request payload

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (400)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/stops/place",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "STOP-Place-400-accountNumber",
                    "message": "accountNumber must be numeric"
                }
            ]
        }
    }
}

Unauthorized request

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "0635f201-8fbb-418f-b93a-138d5103e2b91348",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/stops/place"
}

Entitlements validation failed

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (403)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/stops/place",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "Forbidden",
                    "message": "Entitlements Validation Failed"
                }
            ]
        }
    }
}

Resource not found

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (404)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/stops/place",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "STOP-Place-404-Not-Found",
                    "message": "No static resource v1/stops/place"
                }
            ]
        }
    }
}

Requested method denied

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (405)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/stops/place",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "STOP-Place-405-Method-Not-Allowed",
                    "message": "Method 'Get' is not supported."
                }
            ]
        }
    }
}

Duplicate stop

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (409)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/stops/place",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "STOP-Place-409-duplicate",
                    "message": "A Stop Payment already exists for the requested check(s)"
                }
            ]
        }
    }
}

Precondition failed

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (412)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/stops/place",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "STOP-Place-412-accountNumber",
                    "message": "Invalid Account"
                }
            ]
        }
    }
}

Media type not supported

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (415)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/stops/place",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "STOP-Place-415-Unsupported-Media-Type",
                    "message": "Content-Type 'X' is not supported."
                }
            ]
        }
    }
}

Unexpected backend server error

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (422)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/stops/place",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "STOP-Place-422-error",
                    "message": "Unable to place the requested Stop Payment."
                }
            ]
        }
    }
}

Too many requests

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/stops/place"
}

Unexpected server error

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (500)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "Api-Url": "/commercial/checks/v1/stops/place",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "STOP-Place-500-error",
                    "message": "Unable to place the requested Stop Payment."
                }
            ]
        }
    }
}

Bad gateway

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "Api-Url": "/commercial/checks/v1/stops/place",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
    }
}

Service unavailable

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "Api-Url": "/commercial/checks/v1/stops/place",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
    }
}

Gateway timeout

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/stops/place",
    "ServiceError": {
        "ConnectError": "Request could not be processed on time (GatewayTimeout), please wait a moment and resubmit the request."
    }
}

List of check images

post /commercial/checks/v1/images/list

Get check data with an account number and check number. To return a check image, define the image format in the request.

Request

NAME	TYPE	DESCRIPTION
accountNumberrequired	string	Account number related to the check holder. This is a numeric ID and should not exceed 16 characters.
checkNumberrequired	integer	The number of the check to retrieve. This is a numeric ID.
checkAmount	number	The amount of the check. Must be a valid monetary value with no more than two decimal places.
checkProcessDaterequired	string	The date the check was processed. Format: YYYY-MM-DD
imageFormat	string	Indicates the output format of the check images. If no format is defined, no image is returned. Valid values: BMP, JPEG, PNG, TIF, TIFF, TIFG_4

Request example

{
  "accountNumber": "12345678910",
  "checkNumber": "123",
  "checkAmount": "111.11",
  "checkProcessDate": "2026-01-27",
  "imageFormat": "PNG"
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
checkImages	Object	CheckImage

Response example (200)

{
  "accountNumber": "12345678910",
  "checkNumber": 123,
  "checkAmount": 111.11,
  "checkProcessDate": "2026-01-27",
  "sequenceNumber": 1,
  "transactionType": "DEBIT",
  "checkRoutingNumber": "04120704",
  "checkFrontImage": "lUwXMGBwTm4dy/5pe8GwlRZULmMfPkzL8yZKfDxRTU7HFMW/b7DYqjBq0vyC85PxMObQ2UxtcbVe78MWsdgIBkKY7pCB4eE7GQr9QOcFRW2O7FQshj8ExEy0bmCV8cQFyxzKh04XPWIDxp71PIw/BFWy2GG+R3b1SFP/Mbj0Hdppoxn+rUxAz7Red+39BodSSz1xZteU8hu6fYvvNmbqasZmkVAEE6hS2H+3uVKqaMmnpHJ2oIie0rtowueFradOWhNGvV5pRuEhEd6j93X/7mt=",
  "checkRearImage": "73mfoZbjXF4Gr9XuIYSieWR0o3NV2bvMcwiurzvU8Dyvy2CG+1DYdw3IyHHZRdY6CKiarVFK7mG+IgJKVaDwqA2Ma7YxopwgEIJ5oc8gS/O8BzX7zms/6hmRn9wrcZj3ZhaSUmAdOtSc3qOzp6JPLoYyJg2hQwnEtJyormF8GT5ajF8ADV6XQD+d3Ym8bKsR6rHWwGB0bmiKu+9r+33mR8QZmzmmCPIUZXzj6CXaLr0dNA4+xXszgMbWAHI00ZGhTsSfzyWp8FHYZx24fbEOkS9ApuVBRihL+Eb14ldJayOgAXI3OjLJgo2pB4EUvbQmhwu="
}

Validation failure on request payload

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (400)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/images/list",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "IMAGE-Check-400-accountNumber",
                    "message": "accountNumber must be numeric"
                }
            ]
        }
    }
}

Unauthorized request

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "0635f201-8fbb-418f-b93a-138d5103e2b91348",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/images/list"
}

Entitlements validation failed

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (403)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/images/list",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "Forbidden",
                    "message": "Entitlements Validation Failed"
                }
            ]
        }
    }
}

Resource not found

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (404)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/images/list",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "IMAGE-Check-404-Not-Found",
                    "message": "No static resource v1/images/list"
                }
            ]
        }
    }
}

Requested method denied

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (405)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/images/list",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "IMAGE-Check-405-Method-Not-Allowed",
                    "message": "Method 'Get' is not supported."
                }
            ]
        }
    }
}

Media type not supported

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (415)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/images/list",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "IMAGE-Check-415-Unsupported-Media-Type",
                    "message": "Content-Type 'X' is not supported."
                }
            ]
        }
    }
}

Too many requests

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/stops/place"
}

Unexpected server error

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (500)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "Api-Url": "/commercial/checks/v1/images/list",
    "ServiceError": {
        "metadata": {
            "messages": [
                {
                    "code": "IMAGE-Check-500-error",
                    "message": "Unable to process the request."
                }
            ]
        }
    }
}

Bad gateway

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "Api-Url": "/commercial/checks/v1/images/list",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
    }
}

Service unavailable

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "Api-Url": "/commercial/checks/v1/images/list",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
    }
}

Gateway timeout

NAME	TYPE	DESCRIPTION
ErrorMessage	string	A human-readable message that describes the type or source of the error.
TransactionId	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationId	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTime	string	Date and time the error occurred.
Api-Url	string	The API URL path of the call that generated the response.
ServiceError	oneOf	ServiceErrorData ConnectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "84293235-5d2c-42ba-afc3-a5d4afc5f88e27097",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "Api-Url": "/commercial/checks/v1/images/list",
    "ServiceError": {
        "ConnectError": "Request could not be processed on time (GatewayTimeout), please wait a moment and resubmit the request."
    }
}

Schemas

StopPaymentPlaceResponse

NAME	TYPE	DESCRIPTION
stopPayments	Object	StopPayments

CheckImageListResponse

NAME	TYPE	DESCRIPTION
checkImages	Object	CheckImage

ResponseMetadata

NAME	TYPE	DESCRIPTION
messagesoptional	array	Message

Message

NAME	TYPE	DESCRIPTION
code	string	Machine-readable code.
message	string	Human-readable message associated with the code.

StopPayments

NAME	TYPE	DESCRIPTION
accountNumber	string	The account number to place the stop payment.
checkNumberStart	integer	The starting (lowest) check number in the range for which a stop payment is requested.
checkNumberEnd	integer	The last (hightest) check number in the range for which a stop payment is requested. If the number is not specified, it will default to the same value as checkNumberStart.
checkAmount	number	The amount of the check to stop.
expirationDate	string	Stop payment expiration date. Format: YYYY-MM-DD
description	string	A custom text field to provide a brief explanation of the stop payment request.
placedDate	string	Stop payment placed or effective date. Format: YYYY-MM-DD
issueDate	string	Original check issue date. Format: YYYY-MM-DD

CheckImage

NAME	TYPE	DESCRIPTION
accountNumber	string	Account number related to the check holder.
checkNumber	integer	Check number associated with the check image.
checkAmount	number	Amount of the check provided.
checkProcessDate	string	Check process date (YYYY-MM-DD).
sequenceNumber	integer	System generated sequence number.
transactionType	string	Type of transaction for the check.
checkRoutingNumber	string	Routing number on the check.
checkFrontImage	string	The Base64 encoded string for the front image of the check.
checkRearImage	string	The Base64 encoded string for the back image of the check.

ServiceErrorData

NAME	TYPE	DESCRIPTION
metadata	Object	ResponseMetadata

ConnectError

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

Errors

Check Services uses standard HTTP status codes for error handling. Additional error information may be present in ErrorMetadata, ServiceErrorData, or ConnectError. Review the associated code and message for additional details as to why your call encountered an error.

For more information about general HTTP status codes, see Error Handling. Or if you get stuck, review possible ways to resolve on the Troubleshooting page.

Changelog

1.1.1

June 2026

Added format details and additional parameter control information.
Standardized and improved error messaging, utilizing the Exception schema.

1.1.0

April 2026

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