API Simulator

clock 6-minute read calender Rel. 4.0.0 | updated Nov. 12, 2024

Test and move your code in a mock environment

This guide explains how to use the Embedded Banking (EB) API simulator. Whether you are testing your application or practicing your API call, with the simulator you can interact with a mock environment without affecting any live systems.

Overview

API simulator high-level flow diagram

You can test APIs right in a production-like environment to get a real sense of how these endpoints operate. It is not a 100% reflection of the production environment, but a close mimic for API data controls and transmission activity. The API simulator is data-driven by the information you provide. You pass values in the request and verify the response returns the same information in data points like account number or name.

Since it is data-driven, this means that the more data you enter, the more scenarios you can test and interpret. The response data is smart and matches the critical data points from the different endpoint requests. You can simulate a series of related API calls that use the data from the previous requests.

Features

Simulate API calls
Make API requests without hitting real servers. This is useful for testing.
Test different scenarios
Simulate different responses, like successful calls, errors, and timeouts.
Log and analyze responses
View the data sent and received during API interactions.
Customize requests
Change parameters, headers, and body content of requests to simulate different conditions.

How to use the API simulator

01 Download the simulator API specifications

Before you begin, you will need the latest version of the simulator API specifications. The YAML file tells you what the API does, how to make request, what information you need to send, and what you'll get back.

Download the simulator YAML file for one of these products:

02 Select an endpoint

We embedded the word “simulator” is embedded into each API simulator endpoint. Make sure that when you download the YAML file, you include the word 'simulator' in its correct location on the path. Or simply copy an endpoint from the table below.

Simulator endpoints

API	Description	Method	Simulator endpoint
Account Validation	Verify an account	post	/accounts/validations/v2/simulator/verifyAccount
ACH Origination	Check the status of addenda records	post	/ach/payments/v1/simulator/status/addenda
	Send or collect a payment	post	/ach/payments/v1/simulator/ccd
	Make or collect payments to or from a corporate account with attached records	post	/ach/payments/v1/simulator/ctx
	Make deposits and withdrawals to or from consumer accounts	post	/ach/payments/v1/simulator/ppd
	Send a payment over the phone	post	/ach/payments/v1/simulator/tel
	Send an online payment	post	/ach/payments/v1/simulator/web
	Undo a payment request	post	/ach/payments/v1/simulator/undo
	Send additional addenda information	post	/ach/payments/v1/simulator/addenda
ACH Inquiry	Search for ACH transactions	GET	/accounts/transactions/v1/simulator/ach/detail/{parNumber}
ACH Inquiry	Search for ACH transaction details	post	/accounts/transactions/v1/simulator/ach/list
RTP Inquiry	Search real-time payment transactions	post	/rtp/v1/transactions/simulator/list
RTP Inquiry	View the details of a RTP transaction by its ID	GET	/rtp/v1/transactions/simulator/detail/{transactionId}

03 Customize your request

In each request, you can change details in the header and body. We recommend beginning with a simple copy and paste of the request body code from the YAML to get familiar with the API. Then, get creative and try some scenarios that are common for you and your clients.

04 Send request and view response

Once you hit send, the simulator returns a response. The response will have the standard HTTP response codes like 200 (success) or 404 (not found). Review the status codes and response body returned. If you get an error response, check for things like typos in the endpoint, missing headers, or incorrect data in the body. Check your logs to see a record of all system interactions.

Best practices

Understand the basics of APIs. While the simulator helps, the basic API knowledge is important. Know the different between GET and POST and how headers and body content work.
Use the logs for debugging. Always check the logs to see if your request was formatted correctly. If the response isn’t what you expect, the logs can help pinpoint errors.
Test different scenarios. Use the simulator to test both success and failures cases, includes edge cases (like testing with missing or incorrect data).
Stay organized. Label and document your simulated API tests to keep track of different test cases.

Requirements

You need to be a verified API consumer with the correct credentials, following KeyBank's onboarding requirements as described in our Getting Started Guide. If you are an existing API consumer of an endpoint that is also active in the simulator environment, you should have access to the API simulator. If not, reach out to your Payments Advisor/Technical Account Manager.
At KeyBank, we require a separate set of API keys for API simulator and production environments. You cannot use API keys for one environment to access the API in another environment. You need unique application credentials for the simulator environment.
There is a unique consumer key for the API simulator to avoid cross-pollinating the environments. You get a unique consumer_id and consumer_secret for the API simulator. You can use the same client credentials (client_id and client_key). All keys are securely provided to you by KeyBank.
When you submit a request for an access token, you should see API Simulator listed in the api_product_list_json. This field lists what API products and service you have permission to access.

Restrictions

You cannot access the API simulator unless you are a verified API consumer partnering with KeyBank. To learn more, go to the Getting Started Guide.
ACH data transmission goes to a simulated ACH batch that runs at 6:00 p.m. daily. After the daily batch run, you can inquire about the status of an ACH transaction.
Not all endpoints are currently available in the API simulator for each API product. KeyBank is working to expand simulated experiences for all of our API products.

RTP and Wire Payments API

5-minute read 1.2.4 | updated Aug. 07, 2024

Make a payment immediately and at any time

The RTP and Wire Payments API is a single product with two service capabilities: real-time payments (RTP) and wire transfers (WIRE). Specific permissions are required to access either the RTP Send Payment API or the Wires Transfer API. You can initiate a payment, check on its status, and get information about participating parties.

RTP Payments API Endpoints

What you can do	Endpoint
Health check	get /rtp/v1/payment/healthCheck
Get a list of RTP participants	get /rtp/v1/payment/rtp/participant
Get information about one RTP participant	get /rtp/v1/payment/rtp/participant/{routingNumber}
Get the status with the transaction ID	get /rtp/v1/payment/status/transactionId/{transactionId}
Get the status with the request reference number	get /rtp/v1/payment/status/debitAccount/{debitAccount}/reference/{reference}
Send a real-time payment	post /rtp/v1/payment/initiate
Perform validation checks	post /rtp/v1/payment/validate

Before you begin

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

Two in one

At KeyBank, the RTP and wire payment APIs are a single API product with two service capabilities. You need specific permissions to access either the RTP Send Payment API or the Wire Transfer API.

Overview

You can initiate a real-time payment, check on its status, and get information about participating parties.

RTP stands for Real-Time Payment. It is a modern payment system that enables immediate and real-time fund transfers between financial institution or individuals. RTP transactions use the clearing house’s RTP network, which operates 24/7, allowing for instant payment settlement. RTP payments are often used for person-to person transfers, bill payments, and business-to-business transactions.

The main difference between RTP payments and wire transfers is in their speed and settlement process. RTP payments are designed for real-time transfers, providing immediate availability of funds, while wire transfers may take longer to process and settle.

Payment chain parties

The two calls - initiate a payment and validate a payment - have the party object. This is a reusable object that has details about the person or entity sending a payment and the one receiving the payment. The party object reflects the payment chain of events. Use the request fields to direct the payment transaction from one account to another.

ORDER	PAYMENT CHAIN	REQUEST FIELDS TO USE
1	The individual or organization sends the payment.	Enter the debit account number of the individual or organization in debitParty.
2	The financial institution of the debit account holder transfers the funds.	We assume this is KeyBank. Enter the ABA or routing number for the financial institution in debitPartyBank.
3	The financial institution that services the recipient’s account receives the funds.	Enter the US ABA number for the financial institution in creditPartyBank.
4	The beneficiary party receives the funds.	Enter the account number of the beneficiary in creditParty.

API requirements

KeyClientId: When you initiate or validate a payment, you are required to provide the KeyClientId in the request header. The KeyClientId is a 32-character string provided by KeyBank during the onboarding process. This field is not the same as your client credentials (part of your API keys needed to obtain an access token).

Health check

get /rtp/v1/payment/healthCheck

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

Responses

Successful response

NAME	TYPE	DESCRIPTION
Statusoptional	string	The status of the health check response.
Sourceoptional	string	The system that produces the health response. The origin of the response can be 'Gateway' or 'Roundtrip.' Roundtrip returns a response from the farthest system involved.
Timestampoptional	string	The date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIpoptional	string	The client IP address the gateway receives from the request.
X-Forwarded-Foroptional	string	The sequence of the IP addresses for systems between the client and the gateway. Addresses are separated by a comma.

Response example (200)

{
   "Status": "Ok",
   "Source": "Roundtrip",
   "Timestamp": "2022-09-16T02:36:20",
   "ClientIp": "156.77.111.28",
   "X-Forwarded-For": "[156.77.111.28]"
}

Get a list of RTP participants

get /rtp/v1/payment/rtp/participant

Retrieve a list of active, online RTP banks. Use the limit and offset fields to control how many records to return and what records to skip.

Request

query FIELD	TYPE	DESCRIPTION
limitrequired	integer	Pagination parameter that indicates the maximum number of records to return in the response.
offsetrequired	integer	Pagination parameter that indicates the number of records skipped before generating the output.

header FIELD	TYPE	DESCRIPTION
KeyClientIdrequired	string	This value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions.

Request example

curl --location: 'https://partner-api-qv.keybank.com/rtp/v1/payment/rtp/participant?limit=15&offset=0'
--header 'KeyClientId: testwUhSQADUD4DwYyZz2hZkwLqsoFGK'
--header 'Accept: application/json'
--header 'Bearer testZcKJDWnwDWmmf9qah6PJvPy8'

Responses

Successful response

NAME	TYPE	DESCRIPTION
countrequired	string	The count of records that match the initial query.
limitrequired	integer	The maximum number of records returned in the response.
offsetrequired	integer	The number of records skipped before the response is returned.
partiesoptional	Object	party

Response example (200)

{
   "count": "65",
   "limit": 10,
   "offset": 0, 
   "parties": {
                                                                                                            "name": "CITIZENS BANK, NA",
                                                                                                            "accountNumber": "102258001",
                                                                                                            "aba": "100001995",
                                                                                                            "bic": "CITZUSL2XXX",
                                                                                                            "txid": "fa1354bkg3153kj13b4h34",
                                                                                                            "foreignBankSystemId": {
                                                                                                                "type": "USABA"
                                                                                                            },
                                                                                                            "postalAddress": {
                                                                                                                "adrLine": [
                                                                                                                    "BENEFICIARY ADDRESS LINE 1",
                                                                                                                    "BENEFICIARY ADDRESS LINE 2"
                                                                                                                ]
                                                                                                            }
                                                                                                        }
                                                                                                    }

Missing data in the request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (400)

{
                                                                                                        "ErrorMessage": "Error received from backend service.",
                                                                                                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                                                                                        "TransactionId": "US21052400000000",
                                                                                                        "TransactionTime": "2021-06-11T16:31:34.041Z",
                                                                                                        "ServiceError": {
                                                                                                            "status": "FAILED",
                                                                                                            "transactionId": "rrt-770941720727587-2383364-1",
                                                                                                            "requestReference": "RR-220818-01",
                                                                                                            "sendersReference": "SR-220818-01",
                                                                                                            "valueDate": 1683676800,
                                                                                                            "error": {
                                                                                                                "code": "KEY-1006",
                                                                                                                "title": "Required field missing",
                                                                                                                "description": "The object creditPartyBank is required in the request."
                                                                                                            }
                                                                                                        }
                                                                                                    }

Received request is unauthorized

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (401)

{
                                                                                                        "ErrorMessage": "Error received from backend service.",
                                                                                                        "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
                                                                                                        "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
                                                                                                        "TransactionTime": "2022-04-04T11:41:13.754Z",
                                                                                                        "ServiceError": {
                                                                                                            "status": "ERROR",
                                                                                                            "transactionId": "rrt-621075741872460927",
                                                                                                            "requestReference": "REQUEST-REF-220314.1",
                                                                                                            "sendersReference": "SENDER-REF-220314.1",
                                                                                                            "valueDate": "06-10-2023",
                                                                                                            "error": {
                                                                                                                "code": "KEY-0006",
                                                                                                                "title": "Not authorized for requested service",
                                                                                                                "description": "Check your credentials."
                                                                                                            },
                                                                                                            "doddFrank": "NO"
                                                                                                        }
                                                                                                    }

Request is forbidden to access the resource

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (403)

{
                                                                                                        "ErrorMessage": "Access to requested resource is forbidden.",
                                                                                                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                                                                                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                                                                                                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                                                                                                    }

Resource not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (404)

{
                                                                                                        "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request.",
                                                                                                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                                                                                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                                                                                                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                                                                                                    }

Requested method is not allowed.

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (405)

{
                                                                                                        "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request.",
                                                                                                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                                                                                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                                                                                                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                                                                                                    }

Requested unsupported media type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (415)

{
                                                                                                        "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request.",
                                                                                                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                                                                                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                                                                                                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                                                                                                    }

Too many requests received

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (429)

{
                                                                                                        "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime.",
                                                                                                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                                                                                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                                                                                                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                                                                                                    }

Internal server error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (500)

{
                                                                                                        "ErrorMessage": "Error received from backend service.",
                                                                                                        "TransactionId": "359681587523_SR-RMC-210729-11081",
                                                                                                        "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
                                                                                                        "TransactionTime": "2022-04-05T07:59:15.422Z",
                                                                                                        "ServiceError": {
                                                                                                            "status": "ERROR",
                                                                                                            "transactionId": "rrt-621075741872460927",
                                                                                                            "requestReference": "RR-RMC-210720-0123458981",
                                                                                                            "sendersReference": "SR-RMC-210729-11081",
                                                                                                            "valueDate": "06-10-2023",
                                                                                                            "error": {
                                                                                                                "code": "KEY-9999",
                                                                                                                "title": "Unknown error",
                                                                                                                "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials.",
                                                                                                                "detail": {
                                                                                                                    "code": "KEY-9999",
                                                                                                                    "title": "Unknown error",
                                                                                                                    "description": "Additional information about error code."
                                                                                                                }
                                                                                                            },
                                                                                                            "doddFrank": "NO"
                                                                                                        }
                                                                                                    }

Bad Gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

{
                                                                                                        "ErrorMessage": "Error received from backend service.",
                                                                                                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                                                                                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                                                                                                        "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"
                                                                                                        }
                                                                                                    }

Service Unavailable

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (503)

{
                                                                                                        "ErrorMessage": "Error received from backend service.",
                                                                                                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                                                                                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                                                                                                        "TransactionTime": "2021-06-11T16:31:34.041Z",
                                                                                                        "ServiceError": {
                                                                                                            "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
                                                                                                        }
                                                                                                    }

Gateway timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (504)

{
                                                                                                        "ErrorMessage": "Your request took too long to process. Please try again.",
                                                                                                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                                                                                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                                                                                                        "TransactionTime": "2021-06-11T16:31:34.041Z",
                                                                                                        "ServiceError": {
                                                                                                            "ConnectError": "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request."
                                                                                                        }
                                                                                                    }

Get information about one RTP participant

get /rtp/v1/payment/rtp/participant/{routingNumber}

This call returns information about a single RTP participant. Use the routing number of the financial institution to search for the RTP participant.

Request

path FIELD	TYPE	DESCRIPTION
routingNumberrequired	string	Routing number of the participating RTP bank.

header FIELD	TYPE	DESCRIPTION
KeyClientIdrequired	string	This value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions.

Request example

curl --location: 'https://partner-api-qv.keybank.com/rtp/v1/payment/rtp/participant/12345678
                    --header 'KeyClientId: testwUhSQADUD4DwYyZz2hZkwLqsoFGK'
                    --header 'Accept: application/json'
                    --header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8'

Responses

Successful response

NAME	TYPE	DESCRIPTION
namerequired	string	Name of the party. This can be an individual, a financial institution, or a beneficiary. The name cannot exceed 140 characters.
accountNumberoptional	string	Account number of the party.
abaoptional	string	If the party is a financial institution, this is the ABA number or routing number. This cannot exceed 9 numbers.
bicoptional	string	The bank identifier code (BIC) for the party. This is a combination code that identifies the bank, country, location, and possibly the bank branch.
txidoptional	string	The tax identification number for the party.
foreignBankSystemIdoptional	Object	foreignBankSystemType
adrLineoptional	array	An unstructured address line. You can have up to three lines of text that each cannot exceed 70 characters.

Response example (200)

{
                                            "name": "KeyBank National Association",
                                            "accountNumber": "8756654",
                                            "aba": "125200879",
                                            "bic": "KEYUSL2XXX",
                                            "txid": "fa125da513hj135j42b5",
                                            "foreignBankSystemId": {
                                                "type": "USABA"
                                            },
                                            "postalAddress": {
                                                "adrLine": [
                                                    "123 Keybank Street",
                                                    "Cleveland, OH"
                                                ]
                                            }
                                        }

Missing data in the request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (400)

{
                                            "ErrorMessage": "Error received from backend service.",
                                            "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                            "TransactionId": "US21052400000000",
                                            "TransactionTime": "2021-06-11T16:31:34.041Z",
                                            "ServiceError": {
                                                "status": "FAILED",
                                                "transactionId": "rrt-770941720727587-2383364-1",
                                                "requestReference": "RR-220818-01",
                                                "sendersReference": "SR-220818-01",
                                                "valueDate": 1683676800,
                                                "error": {
                                                    "code": "KEY-1006",
                                                    "title": "Required field missing",
                                                    "description": "The object creditPartyBank is required in the request."
                                                }
                                            }
                                        }

Received request is unauthorized

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (401)

{
                                            "ErrorMessage": "Error received from backend service.",
                                            "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
                                            "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
                                            "TransactionTime": "2022-04-04T11:41:13.754Z",
                                            "ServiceError": {
                                                "status": "ERROR",
                                                "transactionId": "rrt-621075741872460927",
                                                "requestReference": "REQUEST-REF-220314.1",
                                                "sendersReference": "SENDER-REF-220314.1",
                                                "valueDate": "06-10-2023",
                                                "error": {
                                                    "code": "KEY-0006",
                                                    "title": "Not authorized for requested service",
                                                    "description": "Check your credentials."
                                                },
                                                "doddFrank": "NO"
                                            }
                                        }

Request is forbidden to access the resource

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (403)

{
                                            "ErrorMessage": "Access to requested resource is forbidden.",
                                            "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                            "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                                            "TransactionTime": "2021-06-11T16:31:34.041Z"
                                        }

Requested resource is not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (404)

{
                                            "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request.",
                                            "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                            "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                                            "TransactionTime": "2021-06-11T16:31:34.041Z"
                                        }

Requested method is not allowed.

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (405)

{
                                            "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request.",
                                            "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                            "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                                            "TransactionTime": "2021-06-11T16:31:34.041Z"
                                        }

Requested unsupported media type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (415)

{
                                            "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request.",
                                            "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                            "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                                            "TransactionTime": "2021-06-11T16:31:34.041Z"
                                        }

Too many requests received

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (429)

{
                                            "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime.",
                                            "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                            "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                                            "TransactionTime": "2021-06-11T16:31:34.041Z"
                                        }

Internal server error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (500)

{
                                            "ErrorMessage": "Error received from backend service",
                                            "TransactionId": "359681587523_SR-RMC-210729-11081",
                                            "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
                                            "TransactionTime": "2022-04-05T07:59:15.422Z",
                                            "ServiceError": {
                                                "status": "ERROR",
                                                "transactionId": "rrt-621075741872460927",
                                                "requestReference": "REQUEST-REF-220314.1",
                                                "sendersReference": "SENDER-REF-220314.1",
                                                "valueDate": "06-10-2023",
                                                "error": {
                                                    "code": "KEY-9999",
                                                    "title": "Unknown error",
                                                    "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials."
                                                },
                                                "doddFrank": "NO"
                                            }
                                        }

Bad Gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

{
                                            "ErrorMessage": "Error received from backend service.",
                                            "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                            "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                                            "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"
                                            }
                                        }

Service Unavailable

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (503)

{
                                            "ErrorMessage": "Error received from backend service.",
                                            "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                            "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                                            "TransactionTime": "2021-06-11T16:31:34.041Z",
                                            "ServiceError": {
                                                "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
                                            }
                                        }

Gateway timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (504)

{
                                            "ErrorMessage": "Error received from backend service.",
                                            "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                                            "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                                            "TransactionTime": "2021-06-11T16:31:34.041Z",
                                            "ServiceError": {
                                                "ConnectError": "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request."
                                            }
                                        }

Get the status with the transaction ID

get /rtp/v1/payment/status/transactionId/{transactionId}

Get the status of a RTP transaction or a wire transfer.

Request

path FIELD	TYPE	DESCRIPTION
transactionIdrequired	string	The clearing system reference number (the US transaction number).

header FIELD	TYPE	DESCRIPTION
KeyClientIdrequired	string	This value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions.

Request example

curl --location: 'https://partner-api-qv.keybank.com/rtp/v1/payment/status/transactionId/test123321'
--header 'KeyClientId: testwUhSQADUD4DwYyZz2hZkwLqsoFGK'
--header 'Accept: application/json'
--header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8'

Responses

Successful response

NAME	TYPE	DESCRIPTION
statusrequired	Object	paymentStatus
transactionIdoptional	string	The unique ID number associated with the original payment request.
requestReferenceoptional	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptional	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 32 characters.
receiversReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberoptional	string	Debit account number. This cannot exceed 34 digits.
creditAccountNumberoptional	string	Credit account number. This cannot exceed 34 digits.
valueDateoptional	string	The date (YYYY-MM-DD) the transfer occurred.
transferAmountoptional	integer	Amount of money to transfer in the correct currency format.
transferCurrencyoptional	string	Currency code for the transfer amount.
erroroptional	Object	paymentError
doddFrankoptional	Object	noYesType
clearingSystemReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.

Response example (200)

{
                        "status": "COMPLETED",
                        "transactionId": "US21052400000000",
                        "requestReference": "RR-KEY-999999-01",
                        "sendersReference": "SR-KEY-999999-01",
                        "receiversReference": "INVC0054321",
                        "debitAccountNumber": "12345",
                        "creditAccountNumber": "987654321",
                        "valueDate": "2023-05-08",
                        "transferAmount": 10,
                        "transferCurrency": "USD",
                        "doddFrank": "NO"
                    }

Missing data in the request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (400)

{
                        "ErrorMessage": "Error received from backend service.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "US21052400000000",
                        "TransactionTime": "2021-06-11T16:31:34.041Z",
                        "ServiceError": {
                            "status": "FAILED",
                            "transactionId": "rrt-770941720727587-2383364-1",
                            "requestReference": "RR-220818-01",
                            "sendersReference": "SR-220818-01",
                            "valueDate": 1683676800,
                            "error": {
                                "code": "KEY-1006",
                                "title": "Required field missing",
                                "description": "The object creditPartyBank is required in the request."
                            }
                        }
                    }

Received request is unauthorized

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (401)

{
                        "ErrorMessage": "Error received from backend service.",
                        "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
                        "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
                        "TransactionTime": "2022-04-04T11:41:13.754Z",
                        "ServiceError": {
                            "status": "ERROR",
                            "transactionId": "rrt-621075741872460927",
                            "requestReference": "REQUEST-REF-220314.1",
                            "sendersReference": "SENDER-REF-220314.1",
                            "valueDate": "06-10-2023",
                            "error": {
                                "code": "KEY-0006",
                                "title": "Not authorized for requested service",
                                "description": "Check your credentials."
                            },
                            "doddFrank": "NO"
                        }
                    }

Request is forbidden to access the resource

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (403)

{
                        "ErrorMessage": "Access to requested resource is forbidden.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                    }

Requested resource is not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (404)

{
                        "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                    }

Requested method is not allowed

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (405)

{
                        "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                    }

Requested unsupported media type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (415)

{
                        "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                    }

Too many requests received

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (429)

{
                        "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                    }

Internal server error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (500)

{
                        "ErrorMessage": "Error received from backend service.",
                        "TransactionId": "359681587523_SR-RMC-210729-11081",
                        "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
                        "TransactionTime": "2022-04-05T07:59:15.422Z",
                        "ServiceError": {
                            "status": "ERROR",
                            "transactionId": "rrt-621075741872460927",
                            "requestReference": "REQUEST-REF-220314.1",
                            "sendersReference": "SENDER-REF-220314.1",
                            "valueDate": "06-10-2023",
                            "error": {
                                "code": "KEY-9999",
                                "title": "Unknown error",
                                "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials."
                            },
                            "doddFrank": "NO"
                        }
                    }

Bad Gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

{
                        "ErrorMessage": "Error received from backend service",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "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"
                        }
                    }

Service Unavailable

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (503)

{
                        "ErrorMessage": "Error received from backend service.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z",
                        "ServiceError": {
                            "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
                        }
                    }

Gateway timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (504)

{
                        "ErrorMessage": "Your request took too long to process. Please try again.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z",
                        "ServiceError": {
                            "ConnectError": "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request."
                        }
                    }

Get the status with the request reference number

get /rtp/v1/payment/status/debitAccount/{debitAccount}/reference/{reference}

Get the status of a payment with the debit account number of the payment originator and the request reference number. This call is typically used for troubleshooting an issue with timing or a technical error with a payment transaction. You can assign a request reference number when you initiate or validate a payment. This number is metadata for backend traceability and is not sent with the payment. Use this number with the debit account number for the originating payment. The account number and request reference number must be unique; you cannot use the same request reference number for different transactions.

Request

path FIELD	TYPE	DESCRIPTION
debitAccountrequired	string	The debit account number of the originator.
referencerequired	string	The clearing system reference number (the US transaction number).

header FIELD	TYPE	DESCRIPTION
KeyClientIdrequired	string	This value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions.

Request example

curl --location: 'https://partner-api-qv.keybank.com/rtp/v1/payment/status/debitAccount/12345/reference/RR-KEY-999999-01'
--header 'KeyClientId: testwUhSQADUD4DwYyZz2hZkwLqsoFGK'
--header 'Accept: application/json'
--header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8'

Responses

Successful response

NAME	TYPE	DESCRIPTION
statusrequired	Object	paymentStatus
transactionIdoptional	string	The unique ID number associated with the original payment request.
requestReferenceoptional	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptional	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 32 characters.
receiversReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberoptional	string	Debit account number. This cannot exceed 34 digits.
creditAccountNumberoptional	string	Credit account number. This cannot exceed 34 digits.
valueDateoptional	string	The date (YYYY-MM-DD) the transfer occurred.
transferAmountoptional	integer	Amount of money to transfer in the correct currency format.
transferCurrencyoptional	string	Currency code for the transfer amount.
erroroptional	Object	paymentError
doddFrankoptional	Object	noYesType
clearingSystemReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.

Response example (200)

{
                        "status": "COMPLETED",
                        "transactionId": "US21052400000000",
                        "requestReference": "RR-KEY-999999-01",
                        "sendersReference": "SR-KEY-999999-01",
                        "receiversReference": "INVC0054321",
                        "debitAccountNumber": "12345",
                        "creditAccountNumber": "987654321",
                        "valueDate": "2023-05-08",
                        "transferAmount": 10,
                        "transferCurrency": "USD",
                        "doddFrank": "NO"
                    }

Missing data in the request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (400)

{
                        "ErrorMessage": "Error received from backend service.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "US21052400000000",
                        "TransactionTime": "2021-06-11T16:31:34.041Z",
                        "ServiceError": {
                            "status": "FAILED",
                            "transactionId": "rrt-770941720727587-2383364-1",
                            "requestReference": "RR-220818-01",
                            "sendersReference": "SR-220818-01",
                            "valueDate": 1683676800,
                            "error": {
                                "code": "KEY-1006",
                                "title": "Required field missing",
                                "description": "The object creditPartyBank is required in the request."
                            }
                        }
                    }

Received request is unauthorized

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (401)

{
                        "ErrorMessage": "Error received from backend service.",
                        "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
                        "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
                        "TransactionTime": "2022-04-04T11:41:13.754Z",
                        "ServiceError": {
                            "status": "ERROR",
                            "transactionId": "rrt-621075741872460927",
                            "requestReference": "REQUEST-REF-220314.1",
                            "sendersReference": "SENDER-REF-220314.1",
                            "valueDate": "06-10-2023",
                            "error": {
                                "code": "KEY-0006",
                                "title": "Not authorized for requested service",
                                "description": "Check your credentials."
                            },
                            "doddFrank": "NO"
                        }
                    }

Request is forbidden to access the resource

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (403)

{
                        "ErrorMessage": "Access to requested resource is forbidden.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                    }

Requested resource is not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (404)

{
                        "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                    }

Requested method is not allowed

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (405)

{
                        "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                    }

Requested unsupported media type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (415)

{
                        "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                    }

Too many requests received

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (429)

{
                        "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                    }

Internal server error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (500)

{
                        "ErrorMessage": "Error received from backend service",
                        "TransactionId": "359681587523_SR-RMC-210729-11081",
                        "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
                        "TransactionTime": "2022-04-05T07:59:15.422Z",
                        "ServiceError": {
                            "status": "ERROR",
                            "transactionId": "rrt-621075741872460927",
                            "requestReference": "REQUEST-REF-220314.1",
                            "sendersReference": "SENDER-REF-220314.1",
                            "valueDate": "06-10-2023",
                            "error": {
                                "code": "KEY-9999",
                                "title": "Unknown error",
                                "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials."
                            },
                            "doddFrank": "NO"
                        }
                    }

Bad Gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

{
                        "ErrorMessage": "Error received from backend service",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "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"
                        }
                    }

Service Unavailable

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (503)

{
                        "ErrorMessage": "Error received from backend service.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z",
                        "ServiceError": {
                            "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
                        }
                    }

Gateway timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (504)

{
                        "ErrorMessage": "Error received from backend service",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z",
                        "ServiceError": {
                            "ConnectError": "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request."
                        }
                    }

Send a real-time payment

post /rtp/v1/payment/initiate

Initiate a RTP payment. Use the requestedService parameter to define the transaction as RTP or Wire. With the party object, you can define the receiver as an individual, corporation, or financial institution in the payment chain.

Request

header FIELD	TYPE	DESCRIPTION
KeyClientIdrequired	string	This value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions.

BODY FIELD	TYPE	DESCRIPTION
requestedServicerequired	string	The type of payment transaction. The transaction request is valid only for the API products with granted access. Valid values: RTP, WIRE
requestReferencerequired	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 32 characters.
typerequired	string	For RTP, the type can show if the transaction is a PAYMENT or a DRAFT. For Wire transfers, the type is always DRAFT.
requestedValueDaterequired	string	Date (YYYY-MM-DD) the transfer will occur.
originatorReferenceoptional	string	An additional reference value that is meaningful to the party originating the payment.
sendersReferencerequired	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.
bankToBankInstructionsoptional	string	Area to share messages or instructions from one bank to another bank. This cannot exceed 140 characters.
ultimateDebitPartyoptional	Object	ultParty
debitPartyrequired	Object	party
debitPartyBankoptional	Object	party
intermediaryBank1optional	Object	party
intermediaryBank2optional	Object	party
intermediaryBank3optional	Object	party
creditPartyBankrequired	Object	party
creditPartyrequired	Object	party
transferAmountrequired	number	Amount of money to transfer in the correct currency format.
transferCurrencyrequired	string	Currency code for the transfer amount.
externalTemplateNameoptional	string	Name of the external template. Text cannot exceed 2048 characters.
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

Request example

{
                        "requestedService": "RTP",
                        "requestReference": "AZX01234567891011",
                        "type": "PAYMENT",
                        "sendersReference": "INVC0012345",
                        "receiversReference": "INVC0054321",
                        "requestedValueDate": 1621814400,
                        "debitParty": {
                            "name": "YOUR COMPANY NAME HERE",
                            "accountNumber": "001122334455"
                        },
                        "creditPartyBank": {
                            "name": "BENEFICIARY BANK NAME",
                            "aba": "000000000"
                        },
                        "creditParty": {
                            "name": "BENEFICIARY NAME",
                            "accountNumber": "987654321",
                            "postalAddress": {
                                "adrLine": [
                                    "BENEFICIARY ADDRESS LINE 1",
                                    "BENEFICIARY ADDRESS LINE 2"
                                ]
                            }
                        },
                        "transferAmount": 10,
                        "transferCurrency": "USD"
                    }

Responses

Successful response

NAME	TYPE	DESCRIPTION
statusrequired	Object	paymentStatus
transactionIdoptional	string	The unique ID number associated with the original payment request.
requestReferenceoptional	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptional	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 32 characters.
receiversReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberoptional	string	Debit account number. This cannot exceed 34 digits.
creditAccountNumberoptional	string	Credit account number. This cannot exceed 34 digits.
valueDateoptional	string	The date (YYYY-MM-DD) the transfer occurred.
transferAmountoptional	integer	Amount of money to transfer in the correct currency format.
transferCurrencyoptional	string	Currency code for the transfer amount.
erroroptional	Object	paymentError
doddFrankoptional	Object	noYesType
clearingSystemReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.

Response example (200)

{
                        "status": "IN_PROCESS",
                        "transactionId": "US23050800214592",
                        "requestReference": "AZX01234567891011",
                        "sendersReference": "INVC0012345",
                        "receiversReference": "INVC0054321",
                        "debitAccountNumber": "001122334455",
                        "creditAccountNumber": "987654321",
                        "valueDate": "2023-05-08",
                        "transferAmount": 10,
                        "transferCurrency": "USD"
                    }

Missing data in the request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (400)

{
                        "ErrorMessage": "Error received from backend service.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "US21052400000000",
                        "TransactionTime": "2021-06-11T16:31:34.041Z",
                        "ServiceError": {
                            "status": "FAILED",
                            "transactionId": "rrt-770941720727587-2383364-1",
                            "requestReference": "RR-220818-01",
                            "sendersReference": "SR-220818-01",
                            "valueDate": 1683676800,
                            "error": {
                                "code": "KEY-1006",
                                "title": "Required field missing",
                                "description": "The object creditPartyBank is required in the request."
                            }
                        }
                    }

Received request is unauthorized

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (401)

{
                        "ErrorMessage": "Error received from backend service.",
                        "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
                        "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
                        "TransactionTime": "2022-04-04T11:41:13.754Z",
                        "ServiceError": {
                            "status": "ERROR",
                            "transactionId": "rrt-621075741872460927",
                            "requestReference": "REQUEST-REF-220314.1",
                            "sendersReference": "SENDER-REF-220314.1",
                            "valueDate": "06-10-2023",
                            "error": {
                                "code": "KEY-0006",
                                "title": "Not authorized for requested service",
                                "description": "Check your credentials."
                            },
                            "doddFrank": "NO"
                        }
                    }

Request is forbidden to access the resource

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (403)

{
                        "ErrorMessage": "Access to requested resource is forbidden.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                    }

Requested resource is not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (404)

{
                        "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                    }

Requested method is not allowed.

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (405)

{
                        "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                    }

Requested unsupported media type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (415)

{
                        "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                    }

Too many requests received

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (429)

{
                        "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z"
                    }

Internal server error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (500)

{
                        "ErrorMessage": "Error received from backend service.",
                        "TransactionId": "359681587523_SR-RMC-210729-11081",
                        "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
                        "TransactionTime": "2022-04-05T07:59:15.422Z",
                        "ServiceError": {
                            "status": "ERROR",
                            "transactionId": "rrt-621075741872460927",
                            "requestReference": "RR-RMC-210720-0123458981",
                            "sendersReference": "SR-RMC-210729-11081",
                            "valueDate": "06-10-2023",
                            "error": {
                                "code": "KEY-9999",
                                "title": "Unknown error",
                                "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials."
                            },
                            "doddFrank": "NO"
                        }
                    }

Bad Gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

{
                        "ErrorMessage": "Error received from backend service.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "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"
                        }
                    }

Service Unavailable

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (503)

{
                        "ErrorMessage": "Error received from backend service.",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z",
                        "ServiceError": {
                            "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
                        }
                    }

Gateway timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (504)

{
                        "ErrorMessage": "Error received from backend service",
                        "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
                        "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
                        "TransactionTime": "2021-06-11T16:31:34.041Z",
                        "ServiceError": {
                            "ConnectError": "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request."
                        }
                    }

Perform validation checks

post /rtp/v1/payment/validate

This call performs all the validation checks needed to initiate a payment without creating a payment.

Request

header FIELD	TYPE	DESCRIPTION
KeyClientIdrequired	string	This value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions.

BODY FIELD	TYPE	DESCRIPTION
requestedServicerequired	string	The type of payment transaction. The transaction request is valid only for the API products with granted access. Valid values: RTP, WIRE
requestReferencerequired	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 32 characters.
typerequired	string	For RTP, the type can show if the transaction is a PAYMENT or a DRAFT. For Wire transfers, the type is always DRAFT.
requestedValueDaterequired	string	Date (YYYY-MM-DD) the transfer will occur.
originatorReferenceoptional	string	An additional reference value that is meaningful to the party originating the payment.
sendersReferencerequired	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.
bankToBankInstructionsoptional	string	Area to share messages or instructions from one bank to another bank. This cannot exceed 140 characters.
ultimateDebitPartyoptional	Object	ultParty
debitPartyrequired	Object	party
debitPartyBankoptional	Object	party
intermediaryBank1optional	Object	party
intermediaryBank2optional	Object	party
intermediaryBank3optional	Object	party
creditPartyBankrequired	Object	party
creditPartyrequired	Object	party
transferAmountrequired	number	Amount of money to transfer in the correct currency format.
transferCurrencyrequired	string	Currency code for the transfer amount.
externalTemplateNameoptional	string	Name of the external template. Text cannot exceed 2048 characters.
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

Request example

{
    "requestedService": "RTP",
    "requestReference": "AZX01234567891011",
    "type": "PAYMENT",
    "requestedValueDate": 1621814400,
    "originatorReference": "",
    "sendersReference": "INVC0012345",
    "receiversReference": "INVC0054321",
    "ultimateDebitParty": {
        "name": ""
    },
    "debitParty": {
        "name": "YOUR COMPANY NAME HERE",
        "accountNumber": "001122334455"
    },
    "debitPartyBank": {
        "name": ""
    },
    "creditPartyBank": {
        "name": "BENEFICIARY BANK NAME",
        "aba": "000000000"
    },
    "creditParty": {
        "name": "BENEFICIARY NAME",
        "accountNumber": "987654321",
        "postalAddress": {
            "adrLine": [
                "BENEFICIARY ADDRESS LINE 1",
                "BENEFICIARY ADDRESS LINE 2"
            ]
        }
    },
    "transferAmount": 10,
    "transferCurrency": "USD",
    "customData": ""
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
statusrequired	Object	paymentStatus
transactionIdoptional	string	The unique ID number associated with the original payment request.
requestReferenceoptional	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptional	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 32 characters.
receiversReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberoptional	string	Debit account number. This cannot exceed 34 digits.
creditAccountNumberoptional	string	Credit account number. This cannot exceed 34 digits.
valueDateoptional	string	The date (YYYY-MM-DD) the transfer occurred.
transferAmountoptional	integer	Amount of money to transfer in the correct currency format.
transferCurrencyoptional	string	Currency code for the transfer amount.
erroroptional	Object	paymentError
doddFrankoptional	Object	noYesType
clearingSystemReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.

Response example (200)

{
    "status": "VALID",
    "transactionId": "XZ23050714000000",
    "requestReference": "testWBB25889710252",
    "sendersReference": "INVC0012345",
    "receiversReference": "INVC0054321",
    "debitAccountNumber": "12345",
    "creditAccountNumber": "987654321",
    "transferAmount": 10,
    "transferCurrency": "USD"
}

Missing data in the request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (400)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "US21052400000000",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "status": "FAILED",
        "transactionId": "rrt-770941720727587-2383364-1",
        "requestReference": "RR-220818-01",
        "sendersReference": "SR-220818-01",
        "valueDate": 1683676800,
        "error": {
            "code": "KEY-1006",
            "title": "Required field missing",
            "description": "The object creditPartyBank is required in the request."
        }
    }
}

Received request is unauthorized

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (401)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
    "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
    "TransactionTime": "2022-04-04T11:41:13.754Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-0006",
            "title": "Not authorized for requested service",
            "description": "Check your credentials."
        },
        "doddFrank": "NO"
    }
}

Request is forbidden to access the resource

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Requested resource is not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Requested method is not allowed

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Requested unsupported media type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Too many requests received

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Internal server error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (500)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "359681587523_SR-RMC-210729-11081",
    "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
    "TransactionTime": "2022-04-05T07:59:15.422Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-9999",
            "title": "Unknown error",
            "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials.",
            "detail": {
                "code": "KEY-1005",
                "title": "Error",
                "description": "Additional information about error code."
            }
        },
        "doddFrank": "NO"
    }
}

Bad Gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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"
    }
}

Service Unavailable

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Gateway timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (504)

{
    "ErrorMessage": "Your request took too long to process. Please try again.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request."
    }
}

Schemas

exception

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

serviceErrorData

NAME	TYPE	DESCRIPTION
statusrequired	Object	paymentStatus
transactionIdoptional	string	The unique ID number associated with the original payment request.
requestReferenceoptional	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptional	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional	string	The sender reference value from the original request. This is useful for traceability and reporting.
debitAccountNumberoptional	string	The sender reference value from the original request. This is useful for traceability and reporting.
creditAccountNumberoptional	string	The sender reference value from the original request. This is useful for traceability and reporting.
valueDateoptional	string	The date (YYYY-MM-DD) the transferred occurred.
erroroptional	Object	paymentError
doddFrankoptional	Object	noYesType

connectError

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

paymentTransactionRequestV1

NAME	TYPE	DESCRIPTION
requestedServicerequired	string	The type of payment transaction. The transaction request is valid only for the API products with granted access. Valid values: RTP, WIRE
requestReferencerequired	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 32 characters.
typerequired	string	For RTP, the type can show if the transaction is a PAYMENT or a DRAFT. For Wire transfers, the type is always DRAFT.
requestedValueDaterequired	string	Date (YYYY-MM-DD) the transfer will occur.
originatorReferenceoptional	string	An additional reference value that is meaningful to the party originating the payment.
sendersReferencerequired	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.
bankToBankInstructionsoptional	string	Area to share messages or instructions from one bank to another bank. This cannot exceed 140 characters.
ultimateDebitPartyoptional	Object	ultParty
debitPartyrequired	Object	party
debitPartyBankoptional	Object	party
intermediaryBank1optional	Object	party
intermediaryBank2optional	Object	party
intermediaryBank3optional	Object	party
creditPartyBankrequired	Object	party
creditPartyrequired	Object	party
transferAmountrequired	number	Amount of money to transfer in the correct currency format.
transferCurrencyrequired	string	Currency code for the transfer amount.
externalTemplateNameoptional	string	Name of the external template. Text cannot exceed 2048 characters.
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

party

NAME	TYPE	DESCRIPTION
namerequired	string	Name of the party. This can be an individual, a financial institution, or a beneficiary. The name cannot exceed 140 characters.
accountNumberoptional	string	Account number of the party.
abaoptional	string	If the party is a financial institution, this is the ABA number or routing number. This cannot exceed 9 numbers.
bicoptional	string	The bank identifier code (BIC) for the party. This is a combination code that identifies the bank, country, location, and possibly the bank branch.
txidoptional	string	The tax identification number for the party.
foreignBankSystemIdoptional	Object	foreignBankSystemType
adrLineoptional	array	An unstructured address line. You can have up to three lines of text that each cannot exceed 70 characters.

participantListResponse

NAME	TYPE	DESCRIPTION
countrequired	string	The count of records that match the initial query.
limitrequired	integer	The maximum number of records returned in the response.
offsetrequired	integer	The number of records skipped before the response is returned.
partiesoptional	Object	party

foreignBankSystemType

NAME	TYPE	DESCRIPTION
typeoptional	string	The five-digit global routing code for a foreign financial institution.
idoptional	string	The identification number associated with the foreign financial institution.

paymentTransactionResponse

NAME	TYPE	DESCRIPTION
statusrequired	Object	paymentStatus
transactionIdoptional	string	The unique ID number associated with the original payment request.
requestReferenceoptional	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptional	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 32 characters.
receiversReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberoptional	string	Debit account number. This cannot exceed 34 digits.
creditAccountNumberoptional	string	Credit account number. This cannot exceed 34 digits.
valueDateoptional	string	The date (YYYY-MM-DD) the transfer occurred.
transferAmountoptional	integer	Amount of money to transfer in the correct currency format.
transferCurrencyoptional	string	Currency code for the transfer amount.
erroroptional	Object	paymentError
doddFrankoptional	Object	noYesType
clearingSystemReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.

paymentStatus

NAME	TYPE	DESCRIPTION
paymentStatusoptional	string	The status of the payment transaction. Valid values: IN_PROCESS, IN_REVIEW, COMPLETED, FAILED, RETURNED, ERROR, VALID

paymentError

NAME	TYPE	DESCRIPTION
coderequired	string	Status code assigned to each error type.
titlerequired	string	Brief title about the error associated with the status code.
descriptionoptional	string	Description of the error.
codeoptional	string	A static code assigned by the network or payment system.
titleoptional	string	Brief title about the error associated with the status code.
descriptionoptional	string	Description of the error

noYesType

NAME	TYPE	DESCRIPTION
noYesTypeoptional	string	This field indicates whether the transaction qualifies for Dodd-Frank.

ultParty

NAME	TYPE	DESCRIPTION
nameoptional	string	Typically this is the name of the party that instructed the debit party to initiate a payment. This value cannot exceed 140 characters.

Errors

When an error occurs, the paymentTransactionResponse object returns with the paymentStatus of ERROR or FAILED. Certain violations report with an HTTP 200 response for issues where the API service successfully receives the request, but it encounters errors. KeyBank may include additional information about the error in API-specific error messages.

For more information about errors, see Error handling.

API-specific KeyBank error codes and details are in the error object of the response payload. Issues signify a failed payment that could have been caused by account restrictions, network timeout, or invalid data in the request.

API specific KeyBank codes and messages

CODE	MESSAGE
KEY-0001	Not authorized
KEY-0002	Not authorized for requested action
KEY-0003	Request exceeds authorized limit
KEY-0004	Unauthorized for account
KEY-0005	Internal use only fields
KEY-0006	Not authorized for requested service
KEY-1000	Transformation Error
KEY-1001	Invalid Data
KEY-1002	Invalid Bank Identifier
KEY-1003	Invalid or unknown template
KEY-1004	Invalid account
KEY-1005	Invalid Currency
KEY-1006	Required field missing
KEY-1007	Transaction Not Found
KEY-1008	Insufficient Funds
KEY-1009	Account has restrictions
KEY-1010	Duplicate Request
KEY-1011	Payor Account Restrictions
KEY-1012	Payee Account Restrictions
KEY-3001	Exceeds transaction limit for RTP transactions
KEY-3002	Field not usable for RTP transactions
KEY-3003	Payment network timeout. Please retry.
KEY-3004	Payment rejected by payment network
KEY-9997	Failed payment review
KEY-9998	Payment failed during processing
KEY-9999	Unknown error

API-specific error example

paymentTransactionResponse:
  { 
      "status": "FAILED", 
      "requestReference": "RR-999999-01", 
      "sendersReference": "SR-999999-01", 
      "error": { 
          "code": "KEY-1002", 
          "title": "Invalid Bank Identifier", 
          "description": "Credit Party Bank must be a valid USRTP Participant" 
      } 
  }

Changelog

Release	API version	Change description	Impact
August 2024	1.2.4	Added clarification to `type` parameter. For RTP the type can be PAYMENT or DRAFT. For wire transfers, the type will always be DRAFT.	MID
May 2024	1.2.3	`KeyClientId` is required for all endpoints, including GET calls.	MID
March 2024	1.2.1	Added 'IN_REVIEW' as a valid value for `status` in the `paymentStatus` object. Added new parameters to `paymentTransactionRequestV1`: `bankToBankInstructions` `debitPartyInstructions` `intermediaryBank1` `intermediaryBank2` `intermediaryBank3` `externalTemplateName` Added the `clearingSystemReference` in the `paymentTransactionResponse` object. Added the following parameter to `serviceErrorData`: `receiversReference` `debitAccountNumber` `creditAccountNumber` Changed min/max limits for the following parameters: `requestReference` and `sendersReference` changed from maxLength 35 to 32 with a minLength of 1. Added parameter limits for `originatorReference` with a minLength of 1 and a maxLength of 35. Added parameter limit for `transferAmount` with a maximum of 18 digits (which is like quintillion). Added parameter limit for `accountNumber` in the `party` to a minLength of 1. Added parameter limit for `aba` to a maxLength of 9 digits. Added parameter limit for `debitAccountNumber` to a maxLength 34 characters.	HIGH
September 2023	1.1.5	Parameter description updates. This change is for technical content only. The code and operations of the API remain the same. Clarified the `transactionId` for RTP payments is the clearing system reference number.	LOW
December 2022	1.1.3	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

Pagination

3-minute read Rel. 4.0.0 | updated Nov. 12, 2024

It's a real page-turner

Pagination keeps data manageable by breaking it into chunks, so systems handle large data requests without slowing down.

Row-based pagination: Use startRowIndex and endRowIndex to fetch rows by range.
Offset-based pagination: Set limit (items per page) and offset (start position).
Page size: Defines the number of items on each page and total count of records returned.

Common pagination controls

Row pagination

There are common pagination parameters like startRowIndex and endRowIndex that help retrieve and organize large data sets into separate, scrollable pages. This is commonly used with information reporting and transaction inquiry APIs. These are optional fields and not required for the request.

The startRowIndex query string parameter sets the first row of data of the response. The default value is 1.
The endRowIndex query string parameter sets the final row of data of the response. The default value is 1000 records and is also the maximum number of records allowed in a single transaction.
If the startRowIndex or endRowIndex parameters are blank, all the rows of data return up to the maximum limit of the endRowIndex value for transaction records.
In the response header of the API, an endpoint may return totalRows or retrievedRows. These parameters provide a summary of the total number of transactions that match the request criteria or were retrieved based on the request criteria.

Example

This is an example of a request with general pagination parameters applied in the query string for the Previous Day API:

POST /ddaReports/accounts/v1/transactions/list?startRowIndex=1&endRowIndex=20

In this example, the startRowIndex is 5 so the first row of data is the fifth row, skipping the first four rows of data. The endRowIndex is 20 so that there is only 20 records per page following the fifth row.

Offset pagination

The offset pagination parameters are limit and offset. These parameters tell the server how many records to search for at a time and what records to skip. This parameter is not reliant on the sort controls and is not a recommended parameter for very large sets of data. Offset pagination is available with the RTP Send Payment API and is required for the RTP list of participants endpoint.

The limit is a query string parameter field that tells the server what items to return during a search. The limit restricts how many rows are returned. There is no maximum limit to this parameter.
The offset is a query string parameter field that specifies which set of rows to return. You can use this field to set the starting row for the data that is returned, and control what rows of data to skip. The default value is zero (0).
Be cautious when you use these parameters because if the data set changes it can affect the result and may return an incorrect response.

Example

This is a request example with the offset pagination parameters applied in the query string for the RTP Send Payment API:

GET /rtp/v1/payment/rtp/participant?limit=15&offset=0

In this example, the offset is 0 so that no items are skipped, and the limit is 15 meaning the request will search 15 items at a time.

Page size

You can control how many pages and records are returned with page request parameters like pageSize and pageNumber

The pageNumber is a query string parameter the tells which page to start with the returned response set. Typically, this number is set to 1 at first until you get familiar with record sets based on common queries.
The pageSize is a query string parameter defines the total number of pages to return. This number must 1 or greater and cannot exceed 1000.

Example

This is a request example with the page size parameters applied in the query string for the ACH Inquiry API:

POST /accounts/transactions/v1/ach/list?pageNumber=1&pageSize=50

In this example, the pageNumber is 1 returning the first page of the result set and the pageSize is 50 meaning that only 50 pages from page 1 are returned.

Endpoints with Pagination

API	METHOD	ENDPOINT	PAGINATION PARAMETER
ACH Origination	POST	/ach/payments/v1/status/addenda	`pageSize`
ACH Inquiry	POST	/accounts/transactions/v1/ach/list	`pageNumber` `pageSize`
Wire Inquiry	POST	/wireInquiry/v1/transactions/details	`startRowIndex` `endRowIndex`
RTP Send Payment	GET	/rtp/v1/payment/rtp/participant	`limit` `offset`
RTP Inquiry	POST	/rtp/v1/transactions/list	`pageNumber` `pageSize`
Previous Day	POST	/ddaReports/accounts/v1/transactions/list	`startRowIndex` `endRowIndex`
Intraday	POST	/ddaReports/accounts/v1/transactions/intraday/list	`startRowIndex` `endRowIndex`

Data values

8-minute read 4.0.0 | updated Nov. 20, 2024

Decrypting and decoding API parameters

There are fields present across KeyBank APIs, in both request and response objects, that have predefined values. Some of these values are specific to KeyBank and others are industry-standard values. The purpose of this page is to catalog as many of these data values as possible and provide definitions for their usage within our APIs.

Each data value definition contains a brief description, the specific fields and APIs where the data value can be found, and a tabular listing of possible values and what these values mean.

Data values	Field names	Applicable APIs	Description
Addenda type codes	`addendaTypeCode`	ACH Origination ACH Inquiry	A two-digit code that defines the specific interpretation and format for the addenda information contained in the addenda record.
BAI codes	`baiCode`, `amountTypeCode`, `derivedBaiCode`,`transactionCodeBAI2`	ACH Inquiry Intraday Reporting Previous Day Reporting	A BAI (Bank Administration Institute) code is a three-digit code identifying a banking transaction and are divided into balance codes and transaction codes.
Change codes	`changeCode`, `nocChangeCode`	ACH Inquiry Webhooks (ACH alerts)	In the case of a Notification of Change (NOC), this is a three-character code beginning with the letter 'C' that indicates the information being changed.
Foreign bank type codes	`foreignBankSystemType`	Wire Transfer RTP Send Payment	Five-character global routing/clearing codes for payments in foreign countries.
Pay subtype codes	`paySubType`	Wire Inquiry	A four-digit code that corresponds to a particular wire drawdown scenario.
Return reason codes	`returnReasonCode`, `retReturnReasonCode`	ACH Inquiry Webhooks (ACH alerts)	In the case of a returned ACH payment, this is a three-character code beginning with the letter 'R' that identify a reason an ACH payment was returned.
Transaction codes	`transactionCode`, `retTranCode`, `tranCode`	ACH Inquiry ACH Origination, Intraday Reporting Webhooks (ACH alerts)	A two-digit code identifying various types of debit and credit entries.
Wire and RTP webhook statuses	`tranBusnStatusCode`	Webhooks (Wire/RTP alerts)	The intermittent or final status for Wire and RTP webhook alerts.

Addenda type codes

A two-digit code that defines the specific interpretation and format for the addenda information contained in the addenda record.

Addenda type codes can be found in the following fields:

addendaTypeCode: ACH Origination, ACH Inquiry

Code	Description
02	Point of Sale Entry (POS), Shared Network Transaction (SHR), or Machine Transfer Entry (MTE)
05	Corporate Credit or Debit (CCD), Customer Initiated Entries (CIE), Corporate Trade Exchange (CTX), Prearranged Payment and Deposit (PPD), Internet Initiated/Mobile Entries (WEB)
10-16	1st-7th addenda records for International ACH Transaction (IAT)
17	IAT Remittance Information addenda record
18	IAT Foreign Correspondent Bank addenda record
98	Used for Notification of Change (NOC) entries
99	Used for Return entries

BAI codes

A BAI (Bank Administration Institute) code is a three-digit code identifying a banking transaction and are divided into balance codes and transaction codes.

BAI codes can be found in the following fields:

baiCode: ACH Inquiry, Previous Day Reporting, Intraday Reporting
amountTypeCode: Intraday Reporting
derivedBaiCode: Intraday Reporting
transactionCodeBAI2: Intraday Reporting

Balance codes

Code	Description
010	Opening Ledger
015	Closing Ledger
040	Opening Available
045	Closing Available
072	One Day Float
074	Two or More Day Float
100	Total Credits
109	Current Day Total Lockbox Deposits
111	Lockbox Deposit - Zero Day Float
112	Lockbox Deposit - One Day Float
113	Lockbox Deposit - Two Day Float
115	Lockbox Deposit
140	Total ACH Credits
190	Total Incoming Money Transfers
400	Total Debits
450	Total ACH Debits
490	Total Outgoing Money Transfers
580	Total Controlled Disbursement Debits
584	Total Disbursements Late Amount
585	Disbursing Funding Requirement
602	Total CDA Adjustments

Transaction codes

Code	Description
158	Real Time Payment Credit
165	Pre-authorized ACH Credit
171	Individual Loan Deposit
172	Deposit Correction
195	Incoming Money Transfer
201	Individual Automatic Transfer Credit
206	Book Transfer Credit
213	Letter of Credit
214	Foreign Exchange Credit
229	Miscellaneous International Credit
237	Individual Collection Credit
238	Collection of Dividends
244	Interest / Matured Principle Payment
252	Debit Reversal
258	ACH Reversal Credit
275	ZBA Credit
295	ATM Credit
301	Commercial Deposit
306	Fed Funds Sold
351	Individual Investment Sold
354	Interest Credit
357	Credit Adjustment
359	Interest Adjustment Credit
395	Check Reversal
398	Miscellaneous Fee Refund
399	Miscellaneous Credit
451	ACH Debit Received
455	Pre-authorized ACH Debit
458	Real Time Payment Debit
475	Check Paid
481	Individual Loan Payment
495	Outgoing Money Transfer
501	Individual Automatic Transfer Debit
506	Book Transfer Debit
512	Letter of Credit Debit
513	Letter of Credit
514	Foreign Exchange Debit
529	Miscellaneous International Debit
544	Interest / Matured Principle Payment
552	Credit Reversal
555	Deposited Item Returned
558	ACH Reversal Debit
564	Overdraft Fee
567	Return Item Fee
575	ZBA Debit
595	ATM Debit
627	Fed Funds Purchased
631	Debit Adjustment
651	Individual Investment Purchased
654	Interest Debit
659	Interest Adjustment Debit
661	Account Analysis Fee
666	Currency and Coin Shipped
690	Miscellaneous Debit
694	Deposit Reversal
695	Deposit Correction Debit
698	Miscellaneous Fees
699	Miscellaneous Debit
760	Commercial Loan Debit

Change codes

In the case of a Notification of Change (NOC), this is a three-character code beginning with the letter 'C' that indicates the information being changed.

Change codes can be found in the following fields:

changeCode: ACH Inquiry
nocChangeCode: Webhooks (ACH alerts)

Code	Description
C01	Incorrect bank account number
C02	Incorrect transit/routing number
C03	Incorrect transit/routing number and bank account number
C04	Bank account name change
C05	Incorrect transaction code
C06	Incorrect bank account number and transaction code
C07	Incorrect transit/routing number, bank account number, and transaction code
C08	Incorrect Receiving DFI Identification (IAT only)
C09	Incorrect individual identification
C10	Incorrect company name
C11	Incorrect company identification
C12	Incorrect company name and identification
C13	Addenda format error

Foreign bank type codes

Five-character global routing/clearing codes for payments in foreign countries.

Foreign bank type codes can be found in the following field:

foreignBankSystemType: Wire Transfer, RTP Send Payment

Code	Description
ATBLZ	Austria
AUBSB	Australia
CACPA	Canada
CHSIC	Switzerland
DEBLZ	Germany
ESNCC	Spain
GBDSC	Great Britain
HKNCC	Hong Kong
IENCC	Ireland
INFSC	India
ITNCC	Italy
NZNCC	New Zealand
PTNCC	Portugal
USABA	US FedWire
ZANCC	South Africa

Pay subtype codes

A four-digit code that corresponds to a particular wire drawdown scenario.

Pay subtype codes can be found in the following field:

paySubType: Wire Inquiry

Code	Description
1031	Request for customer drawdown
1032	Transfer honoring customer drawdown request
1033	Refusal of customer drawdown request
1631	Request for bank-to-bank drawdown
1632	Transfer honoring bank-to-bank drawdown request
1633	Refusal of bank-to-bank drawdown request

Return reason codes

In the case of a returned ACH payment, this is a three-character code beginning with the letter 'R' that identify a reason an ACH payment was returned.

Return reason codes can be found in the following fields:

returnReasonCode: ACH Inquiry
retReturnReasonCode: Webhooks (ACH alerts)

Code	Description
R01	Insufficient funds - The available and/or cash reserve balance is not sufficient to cover the dollar value of the debit entry.
R02	Account closed – A previously active account has been closed by action of the customer or the RDFI.
R03	No account/unable to locate account – The account number structure is valid and it passes the check digit validation, but the account number does not correspond to the individual identified in the entry, or the account number designated is not an existing account.
R04	Invalid account number structure – The account number structure is not valid.
R05	Unauthorized debit to consumer account using corporate SEC code – CCD or CTX debit entry was transmitted to a Consumer Account of the receiver and was not authorized by the receiver.
R06	Returned per ODFI’s request – The ODFI has requested that the RDFI return an erroneous entry.
R07	Authorization revoked by customer – The RDFI’s customer (the receiver) revoked the authorization previously provided to the originator for this debit entry.
R08	Payment stopped – The receiver has placed a stop payment order on this debit entry.
R09	Uncollected funds – A sufficient ledger balance exists to satisfy the dollar value of the transaction, but the available balance is below the dollar value of the debit entry.
R10	Customer advises unauthorized, improper, ineligible, or part of an incomplete transaction – The RDFI has been notified by the receiver that the entry is unauthorized, improper, ineligible, or part of an Incomplete Transaction.

Transaction codes

A two-digit code identifying various types of debit and credit entries.

Transaction codes can be found in the following fields:

transactionCode: ACH Inquiry, ACH Origination, Intraday Reporting
retTranCode: Webhooks (ACH alerts)
tranCode: Webhooks (ACH alerts)

DDA credits

Code	Description
20	Reserved
21	Return or Notification of Change for original transaction code 22, 23, or 24
22	Demand credit (checking deposit)
23	Prenotification for a demand credit; death notification (non-dollar); automated enrollment entry (non-dollar)
24	Zero dollar with remittance data (for CCD, CTX, and IAT entries); acknowledgement entries (ACK and ATX entries)

DDA debits

Code	Description
25	Reserved
26	Return or Notification of Change for original transaction code 27, 28, or 29
27	Demand debit (checking withdrawal)
28	Prenotification for a demand debit (non-dollar)
29	Zero dollar with remittance data (for CCD, CTX, and IAT entries)

Savings credits

Code	Description
30	Reserved
31	Return or Notification of Change for original transaction code 32, 33, or 34
32	Savings credit (savings deposit)
33	Prenotification for a savings credit; death notification (non-dollar); automated enrollment entry (non-dollar)
34	Zero dollar with remittance data (for CCD, CTX, and IAT entries); acknowledgement entries (ACK and ATX entries)

Savings debits

Code	Description
35	Reserved
36	Return or Notification of Change for original transaction code 37, 38, or 39
37	Savings debit (savings withdrawal)
38	Prenotification for a savings debit (non-dollar)
39	Zero dollar with remittance data (for CCD, CTX, and IAT entries)

Loan credits

Code	Description
51	Return or Notification of Change for original transaction code 52, 53, or 54
52	Loan account credit
53	Prenotification for a loan account credit
54	Zero dollar with remittance data (for CCD, CTX, and IAT entries)

Loan debits

Code	Description
55	Loan account debit (reversals only)
56	Return or Notification of Change for original transaction code 55

Wire and RTP webhook alert statuses

Review the tranBusnStatusCode in the alertBody object. The status value identifies the payment event in an intermittent (payment under processing), final (completed payment processed), and success (payment successfully completed) status.

Status	Description	Interim Status	Final Status	Success
Pre Qualifying	Payment is being evaluated for errors by the Network.	X
Funds Release	Payment is waiting for OLDS memo post response.	X
PaymentNotification	Payment stopped pending manual release for various reasons.	X
Repair	Payment needs correction before it continues processing.	X
Duplicate Content	Payment matches criteria of another payment. Requires action to process further.	X
Regulatory Filter	Payment is waiting for response from Fraud or OFAC check.	X
Clearing	Payment is waiting for a response from the Payment Network.	X
Product Selection	EPP determines the product for the payment that drives which steps in the workflow will execute.	X
Limit check	Checks EPP for any applicable account or customer limits.	X
Advising	Most of our customer advising is done outside of EPP, but this could be performing payment network advising of some sort as well.	X
Pricing	Billing codes and/or network channel fees are applied to the payment	X
Held Requiring Cover	This payment requires an Operator to clear it out of the Direct and Cover Matching-in Payment Intervention.	X
Internal Filter	Scans EPP filters for alternate or special processing of the payment	X
Future Warehouse	The payment is moved to a future business date because it missed the payment network cutoff time. When that future business date arrives and the payment network opens for business, the payment will re-enter the workflow to ultimately reach a FINAL status.	X
Cancelled	Payment was cancelled.		X
Returned	Payment was returned by receiving bank.		X
Fatal	A serious error has occurred. Payment will not complete workflow.		X
Rejected	Payment was rejected by Network. Payment will not complete workflow.		X
Future Warehouse Cancelled	Payment was cancelled from Future Warehouse Queue.		X
Abandoned	Payment was manually forced to not complete in EPP.		X
Completed	Payment processed successfully through workflow.			X

Release notes

3-minute read V1.0 | updated Nov. 19, 2024

Summary notes about past and current changes to our portal

The developer portal release notes are organized by the month and year of the release, starting with the most current. We also identify the affected APIs and the level of impact for the changes made. This is a quick cue to know if you need to make any necessary changes immediately or if you can integrate the API enhancements at your own pace.

We categorize changes as either breaking or non-breaking.

Breaking changes require upgrading to a new version of the API framework. These changes can cause incompatibility and possibly disrupt your connection to API services. Some examples of breaking changes are a change to the type of a parameter, removing request fields, or developing an existing object with additional parameters.
Non-breaking changes are changes that do not require you to upgrade to a new version or disrupt your connection to current API services. Some examples of a non-breaking change are to add an optional parameter field like a custom data field or removing a deprecating parameter no longer valid or in use.

Levels of impact

Impact level	Description
Low	Non-breaking changes Small change requests to improve content like to better define a term or provide an example for added clarity.
Mid	May include breaking changes like adding or removing an API parameter. Code or configuration enhancement to an API in Production.
High	Breaking changes and/or a hot fix. New product being released.

Releases

2024

2023

2022

November 2024

Developer Portal Release 4.0.0

New API on the Developer Portal! Check out the RTP Inquiry API to search for a list or details about RTP transactions.
Read about our simulated environment with the API Simulator User Guide. Go to this page to download our simulator specifications.
Each API document page now has a changelog that acts as a revision history for the API specifications.
Webhooks onboarding and subscription process has been modified to reduce onboarding time. Look at the latest requirements and subscription tips.

Affected API	Impact
RTP Inquiry	HIGH
Check Image Retrieval	LOW
Webhooks	LOW

October 2024

Developer Portal Release 3.1.2

Improved Account Validation User Guide to be more direct in the steps to make a request and assess a response.
In the Account Validation API, updated the parameters:
- The amount in the request can only be a whole number. No cents. Make sense?
- Updated the request field parameters to better clarify the valid and acceptable values and conditions.
Updated the ACH APIs User Guide for the undo a transaction section. You can attempt to reverse a payment using ACH Direct.
For ACH Origination API, the companyEntryDescription is now a required field each SEC payment call.
For ACH Inquiry, transaction data can be recalled within 180 days of the current date.
Added DFID to the Glossary and enhanced parameter definitions for terms related to DFID in the ACH Origination API.

Affected API	Impact
Account Validation	LOW
ACH Origination	LOW
ACH Inquiry	LOW

September 2024

Developer Portal Release 3.1.1

Account signup and waitlist are currently on hold. When our portal is ready for user account management and an integrated sandbox environment, we will introduce account sign up and login. If you are interested in using an Embedded Banking API product, please go to the EB Payments Advisor Contact Form.
For ACH Origination API, changed the effective date range for ACH payments from 90 days to 31 days.
Enhanced error message in Webhook specifications. Retry mechanism is only triggered by HTTP 500 type error messages. Individual issue resolution is required for HTTP 400 type error messages. This is a content only change.
Added Terms of Services for the KeyBank API Developer Portal. This link is accessible on each page's footer.

Affected API	Impact
ACH Origination	LOW
Webhooks	LOW

August 2024

Developer Portal Release 3.1.0

Introduction of the Account Validation API v2. Includes enhancements to the Account Validation API User Guide that includes information about version 2 of the API with greater clarity about significant parameters that can help improve your validation process.
Webhooks ACH alerts have been simplified. Alert codes AL00902, AL00903, AL00904, AL00905 have been consolidated into a single and new code AL00906.
To help clarify the alert codes for Wire and RTP webhook alerts, we added an extended status table to the Data Values page that includes intermittent statuses.
Change the name of the Wire Origination API to its more common name, Wire Transfer.
In the RTP Send Payment API, added clarification to the type field that for RTP the type can be PAYMENT or DRAFT and for wire transfers, the type will always be DRAFT.
Minor modifications to our Stop Payment API technical content.

Affected API	Impact
Account Validation	MID
Wire Transfer	LOW
RTP Send Payment	LOW
Stop Payment	LOW
Webhooks	HIGH

May 2024

Developer Portal Release 2.5.0

X-CorrelationId has been removed as a request header field for all endpoints in each API product. The parameter is no longer in the request body, but still remains in the code. The system assigns a unique ID when you submit a request and returns the X-CorrelationId value in the response.
Changed the effectiveDate range for ACH payments from 90 days to 31 days.
In the ACH Inquiry API, added two new endpoints. These endpoints will eventually replace the other status queries in the upcoming v2 of the API.
- /accounts/transactions/v1/ach/details/{parNumber}
- /accounts/transaction/v1/ach/list
In the Wire Origination API and the RTP Send Payment API, the KeyClientId is required for all requests.
Added new parameters to the Wire Inquiry API.
KeyVAM introduction on the dev portal home page and an summary guide on KeyVAM with links to learn more.
Date range for Previous Day calls cannot be more than 90 days.
Minor modifications to our Check Image API technical content.
API Simulator product is now available for ACH API products endpoints (ACH Origination and ACH Inquiry). Speak to your Payments Advisor to learn more.

Affected API	Impact
ACH Origination	LOW
ACH Inquiry	MID
Wire Origination	HIGH
Wire Inquiry	MID
RTP Send Payment	HIGH
Previous Day	LOW
Check Image	LOW

April 2024

Developer Portal Release 2.4.0

Introducing the Account Validation User Guide, a helpful resource to get more familiar with our Account Validation API product.
Release notes are now available on the portal.
Added Wire/RTP alerts to the Data Values page.
Remove X-Point parameter from ACH Origination request headers.
Minor modifications to our Intraday API technical content.
Two updates to the Webhooks for the Wire and RTP alert notifications,:
- Added dbTranCurrencyCode and dbAngTypeCode to the alert body.
- Added the requestReferenceNumber to the alert body. If the requestReference field has a value, it will be included in the alert.

Affected API	Impact
ACH Origination	LOW
Intraday	LOW
Webhooks	MID

March 2024

Developer Portal Release 2.3.0

Added new fields the RTP Send Payment and Wire Origination APIs. Some fields had conditions (like format or character limits) modified for requests. Go to the API document to view specific changes about the fields added, which additional fields are now marked as required, setting minimum and maximum limits, and adding value pattern information.
Intraday addenda report for collected ACH transactions has been updated to match the ACH Memo Post.
Removed format restrictions for the channelCode field in the Wire Inquiry API.
Minor modifications to our Previous Day API technical content.
Getting Started User Guide talks about the onboarding process and how to access our API products.
Improved the layout of the API reference pages to simplify information and help you get you to stuff you really want to know.
Expand our Resources section to talk about Custom Data, Pagination, and Error Handling.
User feedback is now available on the dev portal!
Glossary banner is looking cool with a search bar and navigational directory.

Affected API	Impact
ACH Inquiry	LOW
Wire Origination	MID
Wire Inquiry	LOW
RTP Send Payment	MID
Previous Day	LOW
Intraday	LOW

December 2023

Developer Portal Release 2.2.0

Launched our new landing page and have divided our documentation into three sections: Guides, API Reference, and Resources.
- The Guides section includes our first user guide: ACH APIs User Guide.
- The new Resources section contains descriptions and details of data values found within our APIs.
- We now have a glossary of common terms.
The mdmId has officially deprecated. This affects ACH Inquiry, Wire Inquiry, Previous Day, and Intraday.
New fields added to the Wire Inquiry API
In the ACH Inquiry API, the "POSTED" status has been removed from ACH status inquiry endpoint.
Minor modifications to our Webhooks technical content.
Other updates include custom data clarifications, updated API error messaging, and improved navigation. These changes affect technical content only. The code and operations of the APIs remain the same.

Affected API	Impact
ACH Inquiry	HIGH
Wire Inquiry	HIGH
Previous Day	HIGH
Intraday	HIGH
Webhooks	LOW

September 2023

Developer Portal Release 2.1.0

We’ve added virtual account management (VAM) fields (creditVirtualAccount, debitVirtualAccount) to the Wire Inquiry API.
The mdmId description has been updated to communicate that this field will soon deprecate in an upcoming release. This affects ACH Inquiry, Wire Inquiry, Previous Day, and Intraday.
Added the customData to each endpoint in ACH Origination.
Minor field description updates in the ACH Origination and RTP Send Payment APIs.

Affected API	Impact
ACH Origination	LOW
Wire Origination	LOW
Wire Inquiry	MID
RTP Send Payment	LOW
Previous Day	LOW
Intraday	LOW

August 2023

Developer Portal Release 2.0.1

New API on the Developer Portal! We introduce our Webhooks specifications for ACH, Wire, and RTP transactions.
In ACH Inquiry, you can recall transaction activity up to 24 months in the past.
Our API consumers can now utilize the Wire and RTP transaction amounts for reconciliation and other business purposes when making an inquiry with the Intraday Information Reporting API. Each addenda object now includes a the transactionAmount field.
Deprecated unused objects in Previous Day API.

Affected API	Impact
ACH Inquiry	LOW
Previous Day	LOW
Intraday	MID
Webhooks	HIGH

July 2023

Developer Portal Release 2.0.0

New API on the Developer Portal! We introduce the Wire Origination API. This API transfers and processes large payments swiftly and securely.
We’ve set a 5 TPS throttling threshold for all our APIs. If you think you might exceed this threshold, please reach out to your KeyBank representative to talk about adjusting it.
MDM ID (mdmId) is no longer a required parameter for ACH Inquiry, Wire Inquiry, Previous Day, and Intraday Reporting. It’s now optional.
Added new parameters to Wire Inquiry.

Affected API	Impact
ACH Inquiry	LOW
Wire Origination	HIGH
Wire Inquiry	MID
Intraday	LOW

May 2023

Developer Portal Release 1.2.3

Hot fix for the ACH Origination API to require companyEntryDescription for each of the SEC payment endpoints. This field returns in the ACH status response payload.

Developer Portal Release 1.2.0

New API on the Developer Portal! We introduce the Account Validation API. This API validates a payee’s account to ensure a safe and secure transaction before authorizing payment.
Added customData to the ACH Inquiry API. With custom data, you can enter up to 500 alphanumeric characters to create a custom message or data set to associate with the item.
Modified date parameters in Wire Inquiry.
Deprecated unused parameters from the Previous Day and Intraday APIs.

Affected API	Impact
Account Validation	HIGH
ACH Origination API	MID
ACH Inquiry	MID
Wire Inquiry	MID
Previous Day	MID
Intraday	MID

December 2022

Developer Portal Release 1.1.0

Hello world! The KeyBank API Developer Portal is live!

Webhooks

6-minute read 2.2.0 | updated Nov. 12, 2024

Timely and automated payment status notifications

Overview

KeyBank’s payment webhooks provide timely and automated payment status notifications without the need for constant API polling or manual checks.

We currently facilitate alerts for both ACH and wire transaction status changes. You get near real-time updates whenever a specific payment event occurs, like a posted ACH transaction or a completed wire transfer.

Requirements

To subscribe to webhook alert notifications for ACH, Wire, or RTP transactions, you must be a commercial customer or fintech partner of KeyBank. Only authorized API consumers can subscribe to this feature.

For existing clients, reach out to your Payments Advisor to start the subscription process.
For new clients, you will first need to onboard with KeyBank (see our Getting Started Guide for the basic process). In addition, you will be asked to provide a few more details like:
- Type of alert subscription (see alert codes)
- A decision if the pre-production and production subscriptions accounts will be the same or different
- Expected volumes per day/month/year

KeyBank recommends that destination application always have authentication. To reduce setup time for webhook subscriptions while maintaining system integrity and security, we recommend these guidelines:

Use Basic Authentication (BasicAuth) which involves providing KeyBank with a unique username and password for your application.
KeyBank will send a Base64 encoded version of the credential to Authorization header of your HTTP request.
Connect securely with a TLS connection for an encrypted, safe exchange of data.

If you have a specialized needs or circumstances that require secure alternatives rather than BasicAuth, speak with your KeyBank Payment Advisor. This may extend setup time.

Got you hooked?

Check out some more content about our webhooks:

Alert codes
Payment webhook specifications
Retry mechanism

Payment webhooks

Alert notifications are triggered by specific payment status events and are sent in the form of an HTTP POST request. KeyBank can send up to 100 alerts per API call. After receiving an alert notification, KeyBank expects you to send an HTTP 2XX status code in response within 10 seconds and the response needs to adhere to KeyBank's format for an alert response.

Payment webhook alert notifications

Each payment webhook alert notification has an alertNotification object that is made up of two parts:

alertHeader: The header information gives you basic information about the request like date and time sent, the alert code, and a unique notification identifier.
alertBody: The body information contains transaction details. Each of the fields will be present in the request even if there is no data retrieved for a particular field. Fields that have no data show the null value.

Both the alertHeader and alertBody can vary by event type, ACH or Wire/RTP. The alertHeader for Wire/RTP notification contains the payType field that specifies if is a wire or RTP alert while the ACH alert header does not have this field. The alertBody fields are also different based on each event type as defined by the alert code.

Alert codes

Each alert notification contains the alert code for the payment status event that occurred. There is an alert code for Wire/RTP and ACH to monitor all payment status events related to that transaction type.

Alert code types

Wire/RTP alert code = AL00901
ACH alert code = AL00906

Note, with a latest specification update, all ACH payment events are now managed with alert code AL00906. This one code consolidates the legacy ACH alert codes: AL00902 (ACH Collected), AL00903 (ACH Posted), AL00904 (ACH Returned), AL00905 (ACH Notification of Change).

Before you begin

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

ACH alert notifications

ACH Notification Request

HEADER FIELD	TYPE	DESCRIPTION
alertSentDateAndTime	string	Date and time the alert was sent. Format: (YYYY-MM-DD)T(HH:MM:SS)Z
alertCode	string	Alert code. Valid values: AL00906
eapAlertGUID	string	Unique alert notification identifier.

BODY FIELD	TYPE	DESCRIPTION
transactionStatus	string	The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumber	string	The unique number for the transaction provided by the originator.
parNumber	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionAmount	number	The dollar amount of the transaction.
collectionDate	string	Date the transaction was processed. Format: YYYY-MM-DD
settlementDate	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCode	string	Two-digit code identifying the account type at the receiving financial institution.
transactionDescription	string	Description about the purpose of the transaction.
authorizedCustomerName	string	Authorized customer name
standardEntryClassCode	string	Three-digit Standard Entry Class (SEC) code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEB
receivingAccountNumber	string	Account number of the person or institution receiving the funds.
receivingCustomerIdentificationNumber	string	The customer identification number for the person receiving the transaction.
receivingCompanyName	string	Company name of the institution getting the funds.
originatingAccountNumber	string	Account number of the ACH transaction originator.
originatingCustomerIdentificationNumber	string	Originating customer identification number
returnReasonCode	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescription	string	Description as to why the ACH transaction is returned.
returnDate	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
notificationOfChangeAddendaCount	string	Count of change notifications for addenda records.
internationalAddendaCount	string	Count of international addenda records.
addendaCount	string	Count of addenda records.

Request example (ACH)

{
"alertNotificationRequest": [  
	{  
	"alertNotification": {
	  "alertHeader": {
		"alertSentDateAndTime": "2024-07-07T16:25:08Z",
		"alertCode": "AL00906",
		"eapAlertGUID": "4g0fda4b-156f-483c-98ae-bd8ccab266h0"
		},
	"alertBody": {
		"transactionStatus": "COLLECTED",
		"traceNumber": "41033956478656",
		"parNumber": "22010008879477",
		"transactionAmount": "287.40",
		"collectionDate": "2024-01-12",
		"settlementDate": "2024-01-12",
		"transactionCode": "22",
		"transactionDescription": "PAYMENT",
		"authorizedCustomerName": "HIGHMARK INC.",
		"standardEntryClassCode": "CCD",
		"receivingAccountNumber": "00000000001000004133",
		"receivingCustomerIdentificationNumber": "65A658990",
		"receivingCompanyName": "LEHIGH GASTROENTEROLOG",
		"originatingAccountNumber": "00000000001000005244",
		"originatingCustomerIdentificationNumber": "7498659450",
		"originatingCompanyName": "HIGHMARK INC.",
		"returnReasonCode": "R29",
		"returnReasonDescription": "Corporate Customer Advises Not Authorized",
		"returnDate": "2024-01-03",
		"notificationOfChangeAddendaCount": "1",
		"internationalAddendaCount": "0",
		"addendaCount": "0"
		}
	  }
	}
  ]
}

Wire/RTP alert notifications

The Wire/RTP alertBody identifies the status of the payment event in the tranBusnStatusCode field.

Wire/RTP statuses

The Wire and RTP statuses listed show the final status values. You may get an intermittent status that is not list in this table. Go to Data values > Wire and RTP webhook statuses to view the full list.

STATUS	DESCRIPTION
Abandoned	Payment is manually forced to not complete payment processing. Payment will not complete workflow.
Cancelled	Payment was cancelled. Payment will not complete workflow.
Completed	Payment processed successfully and completes the workflow.
Fatal	A serious error has occurred. Payment will not complete workflow.
Future Warehouse Cancelled	Payment was cancelled from Future Warehouse queue. Payments enter the Future Warehouse queue if the payment missed the payment network cutoff time and moves to a future business date. When the future business date arrives, the payment network re-enters the payment in the workflow to reach Future Warehouse Cancelled.
Rejected	Payment was rejected by the network. Payment will not complete workflow.
Returned	Payment was returned by receiving bank.

Wire/RTP Notification Request

HEADER FIELD	TYPE	DESCRIPTION
alertSentDateAndTime	string	Date and time the alert was sent. Format: (YYYY-MM-DD)T(HH:MM:SS)Z
alertCode	string	Alert code. Valid values: AL00901
payType	string	Identifies if the payment type was a Wire or RTP transaction. Valid values: WIRE, RTP
eapAlertGUID	string	Unique alert notification identifier.

BODY FIELD	TYPE	DESCRIPTION
crOrDbCode	string	Identifies the transaction type as credit or debit. Valid values: C (credit), D (debit)
crArngNum	string	Account number of the credit account.
crArngTypeCode	string	Type code of the credit account.
crArngBankNum	string	Bank number of the credit account.
crTranCurrencyCode	string	Transaction currency code of the credit account.
dbArngTypeCode	string	Type code of the debit account
dbTranCurrencyCode	string	Transaction currency code of the debit account.
requestReferenceNumber	string	Unique identification number for an originating wire or RTP transaction. This number is limited to 32 characters.
crIpId	string	Customer number associated with the credit account.
crIpNm	string	Customer name associated with the credit account.
dbArngNum	string	Account number of the debit account.
dbArngBankNum	string	Bank number of the debit account.
dbIpId	string	Customer number associated with the debit account.
dbIpINm	string	Customer name associated with the debit account.
payNotifyTs	string	Timestamp of the payment event.
wireEventNm	string	Payment status code
tranAmt	string	Dollar amount of the transaction.
tranExecutedDt	string	Date the transaction is executed. Format: YYYYMMDD
federalReferNum	string	Federal reference number
sndngBankReferNum	string	Reference number attached to a wire, issued by the sending bank.
tranId	string	Unique transaction identifier
tranBusnStatusCode	string	Transaction business status code
wireDirectionCode	string	Indicates the direction of the transaction.
tranType	string	Type of transaction.
tranValueTypeCode	string	Identifies the value of a transaction.
wireProcessTypeCode	string	Wire processing type code
benefitAba	string	ABA routing number of the beneficiary.
benefitArngNum	string	Account number of the beneficiary.
benefitIpAddrLine	string	Address lines 1-7 (array) of the beneficiary.
benefitBicCode	string	BIC number of the beneficiary.
benefitBankAbaNum	string	ABA routing number of the beneficiary's bank.
benefitBankArngNum	string	Account number of the beneficiary's bank.
benefirBankAddrLine	string	Address lines 1-7 (array) of the beneficiary's bank.
benefitBankBicCode	string	BIC number of the beneficiary's bank.
benefitBankNm	string	Name of the beneficiary's bank.
intrmdryBankAbaNum1	string	ABA routing number of the intermediary bank 1.
intrmdryBNankAddrLine1	string	Address lines 1-7 (array) of the intermediary bank 1.
intrmdryBankNm1	string	Name of the intermediary bank 1.
intrmdryBicCode1	string	BIC number of the intermediary bank 1.
intrmdryBankAbaNum2	string	ABA routing number of the intermediary bank 2.
intramdryBankAddrLine2	string	Address lines 1-7 (array) of the intermediary bank 2.
intrmdryBankNm2	string	Name of the intermediary bank 2.
intrmdryBicCode2	string	BIC number of the intermediary bank 2.
intrmdryBankAbaNum3	string	ABA routing number of the intermediary bank 3.
intrmdryBankAddrLine3	string	Address lines 1-7 (array) of the intermediary bank 3.
intrmdryBankNm3	string	Name of the intermediary bank 3.
intrmdryBicCode3	string	BIC number of the intermediary bank 3.
orgntngBankAbaNum	string	ABA routing number of the wire originator's bank.
orgntngBankAddrLine	string	Address lines 1-7 (array) of the wire originator's bank.
orgntngBankBicCode	string	BIC number of the wire originator's bank.
orgntngBankNm	string	Name of the wire originator's bank.
orgntngAba1	string	ABA routing number of the originator 1.
orgntngArngNum1	string	Account number of the originator 1.
orgntngIpNm1	string	Name of the originator 1.
orgntngIpAddrLine1	string	Address lines 1-7 (array) of the originator 1.
orgntngAba2	string	ABA routing number of the originator 2.
orgntngArngNum2	string	Account number of the originator 2.
orgntngIpNm2	string	Name of the originator 2.
orgntngIpAddrLine2	string	Address lines 1-7 (array) of the originator 2.
orgntngAba3	string	ABA routing number of the originator 3.
orgntngArngNum3	string	Account number of the originator 3.
orgntngIpNm3	string	Name of the originator 3.
orgntngIpAddrLine3	string	Address lines 1-7 (array) of the originator 3.
crVirtualNum	string	Virtual account number of the credit account.
dbVirtualNum	string	Virtual account number of the debit account.

Request example (Wire/RTP)

{
  "alertNotificationRequest": [
  {
	"alertNotification": 
	  "alertHeader": {
		"alertSentDateAndTime": "2023-02-1159T10:20:56Z",
		"alertCode": "AL00901",
		"payType": "WIRE",
		"eapAlertGUID": "f4d88cd2-446c-3cc4-9330-aa123456789"
		},
	  "alertBody": {
		"crOrDbCode": "C",
		"crArngNum": "359123456789",
		"crArngTypeCode": "DDA",
		"crArngBankNum": "0101",
		"crTranCurrencyCode": "USD",
		"dbArngTypeCode": "DDA",
		"dbTranCurrencyCode": "USD",
		"requestReferenceNumber": "4630123-20240212161123",
		"crIpId": "999997",
		"crIpNm": "BANKOFTEST",
		"dbArngNum": "201907987654321",
		"dbArngBankNum": "0101",
		"dbIpId": "30472222",
		"dbIpNm": "Test Name",
		"payNotifyTs": "1673615327943",
		"wireEventNm": "WirePaymentTransactionEvent",
		"tranAmt": "12.79",
		"tranExecutedDt": "20240112",
		"federalReferNum": "null",
		"sndngBankReferNum": "null",
		"tranId": "US23010987654321",
		"tranBusnStatusCode": "RegulatoryFilter",
		"wireDirectionCode": "OUTBOUND",
		"tranType": "null",>
		"tranValueTypeCode": "N",
		"wireProcessTypeCode": "null",
		"benefitAba": "null",
		"benefitArngNum": "3435656765",
		"benefitIpAddrLine": "250 Delaware Ave St",
		"benefitBicCode": "KEYBUS33 XXX",
		"benefitBankAbaNum": "null",
		"benefitBankArngNum": "null",
		"benefitBankAddrLine": "250 Delaware Ave St",
		"benefitBankBicCode": "KEYBUS33 XXX",
		"benefitBankNm": "KeyBank National Association",
		"intrmdryBankAbaNum1": "null",
		"intrmdryBankAddrLine1": "null",
		"intrmdryBankNm1": "KeyBank National Association",
		"intrmdryBicCode1": "21300077",
		"intrmdryBankAbaNum2": "null",
		"intrmdryBankAddrLine2": "null",
		"intrmdryBankNm2": "BANKOFTEST",
		"intrmdryBicCode2": "KEYBUS33 XXX",
		"intrmdryBankAbaNum3": "null",
		"intrmdryBankAddrLine3": "null",
		"intrmdryBankNm3": "null",
		"intrmdryBicCode3": "null",
		"orgntngBankAbaNum": "null",
		"orgntngBankAddrLine": "null",
		"orgntngBankBicCode": "null",
		"orgntngBankNm": "null",
		"orgntngAba1": "null",
		"orgntngArngNum1": "123456789",
		"orgntngIpNm1": "TEST COMPANY 1, LLC",
		"orgntngIpAddrLine1": "127 Public Sq, Cleveland,OH 44114,US",
		"orgntngAba2": "null",
		"orgntngArngNum2": "null",
		"orgntngIpNm2": "null",
		"orgntngIpAddrLine2": "null",
		"orgntngAba3": "null",
		"orgntngArngNum3": "null",
		"orgntngIpNm3": "null",
		"orgntngIpAddrLine3": "null"
		"crVirtualNum": "953456789",
		"dbVirtualNum": "953654321"
		}
	  }
	}
  ]
}

Payment webhook response

The top level alertNotificationResponse object is an array of alertAcknowledgment objects. Because KeyBank can send up to 100 alerts per API call, each alert notification sent must be responded to with its own alertAcknowledgment object. The format of the response needs to adhere to the format specified here.

Response

FIELD	TYPE	DESCRIPTION
alertStatus	string	Status of the alert notification.
confirmationGUID	string	API customer unique ID for the alert notification.
alertRecievedDateAndTime	string	Date and time the alert was received. Format: (YYYY-MM-DD)T(HH:MM:SS)Z
eapAlertGUID	string	Unique alert notification identifier passed through from the request.
message	string	Free-form text field to describe the response.

Successful response

{
  "alertNotificationResponse": [
  {
    "alertAcknowledgment": {
    "alertStatus": "SUCCESS",
    "confirmationGUID": "5f0ada5b-056f-483c-98ae-ac6ccab269c1",
    "alertRecievedDateAndTime": "2021-11-19T10:31:12Z",
    "eapAlertGUID": "f4d88cd2-446c-3cc4-9330-aa123456789",
    "message": "Successfully submitted the request"
    }
  }
 ]
}

Unsuccessful response

{
  "alertNotificationResponse": [
  {
    "alertAcknowledgment": {
      "alertStatus": "FAILURE",
      "confirmationGUID": "5f0ada5b-056f-483c-98ae-ac6ccab269c1",
      "alertRecievedDateAndTime": "2021-11-19T10:31:12Z",
      "eapAlertGUID": "f4d88cd2-446c-3cc4-9330-aa123456789",
      "message": "Required parameter(s) not found: [fieldName(s)]"
    }
  }
]
}

Payment webhook errors

If your webhook receiver/handler encounters an error, KeyBank expects you to send one of the following HTTP status codes:

400 Invalid input
401 Authentication error
403 Authorization error
500 Internal error

Only the HTTP 500 error codes will prompt the retry mechanism. If you have one of the HTTP 400 error codes, you are expected to troubleshoot the issue. If you cannot find a resolution, please contact your Payments Advisor or Technical Account Manager.

Payment webhook alert retry mechanism

The retry mechanism is trigger for any backend error issues, typically associated with HTTP 500's status codes. With a unsuccessful HTTP 5XX response, the KeyBank retry mechanism will attempt to deliver a failed alert notification for 24 hours after the original failed notification. The retry attempts follow this schedule:

3 attempts, each attempt every 30 seconds
6 attempts, each attempt every 90 minutes
3 attempts, each attempt every 5 hours

Attempt number	Time between attempts	Time elapsed since first alert
1-3	30 seconds	30 seconds - 1.5 minutes
4-9	90 minutes	1.5 - 9 hours
10-12	5 hours	14 - 24 hours

After the 24-hour window, the notification fails and there are no more additional retry attempts. Notify your Payments Advisor if there is an outage for more than 24 hours or if you have an outage planned for your systems that extends past a 24-hour period. You can also notify us with our Support form.

To inquire about a payment event after 24 hours, you must use the ACH Inquiry or Wire Inquiry APIs.

Changelog

Release	API version	Change description	Impact
August 2024	2.2.0	We introduce the version 2 of our Webhooks. This API is sleek! For ACH alerts, the alert codes (AL00902, AL00903, AL00904, AL00905) have been consolidated into a single and new code, AL00906.	HIGH
April 2024	1.1.0	For Wire and RTP webhook alert notifications, `dbTranCurrencyCode` and `dbAngTypeCode` are in the alert body. Added the `requestReferenceNumber` to the alert body for Wire and RTP alert notification. If this parameter has a value, it will return in the alert body for RTP or Wire notifications.	MID
December 2023	1.1.0	Remove all leading zeros for the following account parameters: `crArngNum` `dbArngNum` `accountNumber`	LOW
August 2023	1.0.1	Published 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

Wire Transfer

6-minute read 1.2.4 | updated Aug. 07, 2024

Transfer money by wire for urgent payments or large volume transactions

Wire Transfer API Endpoints

What you can do	Endpoint
Health check	get /rtp/v1/payment/healthCheck
Get the status with the transaction ID	get /rtp/v1/payment/status/transactionId/{transactionId}
Get the status with the request reference number	get /rtp/v1/payment/status/debitAccount/{debitAccount}/reference/{reference}
Send a wire transfer	post /rtp/v1/payment/initiate
Perform validation checks	post /rtp/v1/payment/validate

Before you begin

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

Two in one

At KeyBank, the RTP and wire payment APIs are a single API product with two service capabilities. You need specific permissions to access either the RTP Send Payment API or the Wires Transfer API.

Overview

Wire transfers are great for urgent payments and suitable for large volume transactions. Use the Wire Origination API for urgent or time-sensitive transactions, such as large business payments or real estate transactions.

Wire transfers move money from one bank account to another. KeyBank transfers your funds using the secure SWIFT (Society for Worldwide Interbank Financial Telecommunication) system and Fedwire Clearing House. Through our secure network, wire transfers typically involve a processing time that can vary from a few hours to several business days depending on factors such as banks involved and any other intermediary institutions. Banks typically initiate and process wire transfers to provide a direct and expedited method of transferring funds. Usually, wire transfers involve a fee per transmission which can vary depending on the banks involved and the currency used.

Payment chain parties

ORDER	PAYMENT CHAIN	REQUEST FIELDS TO USE
1	The individual or organization sends the payment.	Enter the debit account number of the individual or organization in debitParty.
2	The financial institution of the debit account holder transfers the funds.	We assume this is KeyBank. Enter the ABA or routing number for the financial institution in debitPartyBank.
3	The financial institution that services the recipient’s account receives the funds.	Enter the US ABA number for the financial institution in creditPartyBank.
4	The beneficiary party receives the funds.	Enter the account number of the beneficiary in creditParty.

API requirements

Psst...pass this note

Want to apply a custom message or tags to your transaction? The custom data feature is available when you send or validate a payment. Define the custom data in the request payload. Learn more about our custom data feature here.

Health check

get /rtp/v1/payment/healthCheck

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

Responses

Successful response

NAME	TYPE	DESCRIPTION
Statusoptional	string	The status of the health check response.
Sourceoptional	string	The system that produces the health response. The origin of the response can be 'Gateway' or 'Roundtrip.' Roundtrip returns a response from the farthest system involved.
Timestampoptional	string	The date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIpoptional	string	The client IP address the gateway receives from the request.
X-Forwarded-Foroptional	string	The sequence of the IP addresses for systems between the client and the gateway. Addresses are separated by a comma.

Response example (200)

{
    "Status": "Ok",
    "Source": "Roundtrip",
    "Timestamp": "2022-09-16T02:36:20",
    "ClientIp": "156.77.111.28",
    "X-Forwarded-For": "[156.77.111.28]"
}

Get the status with the transaction ID

get /rtp/v1/payment/status/transactionId/{transactionId}

Get the status of a wire transfer.

With GET methods, use a cURL command to generate your request. Select Copy code for easy copy and paste into your command line. Modify the required fields with your information.

Request

header FIELD	TYPE	DESCRIPTION
KeyClientIdoptional	string	This value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions.

path FIELD	TYPE	DESCRIPTION
transactionIdrequired	string	The unique ID number associated with the original payment request.

Request example

curl --location: 'https://partner-api-qv.keybank.com/rtp/v1/payment/status/transactionId/test123321'
--header 'KeyClientId: testwUhSQADUD4DwYyZz2hZkwLqsoFGK'
--header 'Accept: application/json'
--header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8'

Responses

Successful response

NAME	TYPE	DESCRIPTION
statusrequired	Object	paymentStatus
transactionIdoptional	string	The unique ID number associated with the original payment request.
requestReferenceoptional	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptional	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberoptional	string	Debit account number
creditAccountNumberoptional	string	Credit account number
valueDateoptional	string	The date (YYYY-MM-DD) the transfer occurred.
transferAmountoptional	integer	Amount of money to transfer in the correct currency format.
transferCurrencyoptional	string	Currency code for the transfer amount.
erroroptional	Object	paymentError
doddFrankoptional	Object	noYesType
clearingSystemReferenceoptional	string	Enter a reference value for the beneficiary. This value cannot exceed 140 characters.

Response example (200)

{
    "status": "COMPLETED",
    "transactionId": "US21052400000000",
    "requestReference": "RR-KEY-999999-01",
    "sendersReference": "SR-KEY-999999-01",
    "receiversReference": "INVC0054321",
    "debitAccountNumber": "12345",
    "creditAccountNumber": "987654321",
    "valueDate": "2023-05-08",
    "transferAmount": 10,
    "transferCurrency": "USD",
    "doddFrank": "NO"
}

Missing data in the request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (400)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "US21052400000000",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "status": "FAILED",
        "transactionId": "rrt-770941720727587-2383364-1",
        "requestReference": "RR-220818-01",
        "sendersReference": "SR-220818-01",
        "valueDate": 1683676800,
        "error": {
            "code": "KEY-1006",
            "title": "Required field missing",
            "description": "The object creditPartyBank is required in the request."
        }
    }
}

Received request is unauthorized

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (401)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
    "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
    "TransactionTime": "2022-04-04T11:41:13.754Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-0006",
            "title": "Not authorized for requested service",
            "description": "Check your credentials."
        },
        "doddFrank": "NO"
    }
}

Request is forbidden to access the resource

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Requested resource is not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Requested method is not allowed

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Requested unsupported media type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Too many requests received

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Internal server error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (500)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "359681587523_SR-RMC-210729-11081",
    "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
    "TransactionTime": "2022-04-05T07:59:15.422Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-9999",
            "title": "Unknown error",
            "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials."
        },
        "doddFrank": "NO"
    }
}

Bad Gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend service",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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"
    }
}

Service Unavailable

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Gateway timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (504)

{
    "ErrorMessage": "Your request took too long to process. Please try again.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request."
    }
}

Get the status with the request reference number

get /rtp/v1/payment/status/debitAccount/{debitAccount}/reference/{reference}

With GET methods, use a cURL command to generate your request. Select Copy code for easy copy and paste into your command line. Modify the required fields with your information.

Request

header FIELD	TYPE	DESCRIPTION
KeyClientIdoptional	string	This value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions.

path FIELD	TYPE	DESCRIPTION
debitAccountrequired	string	The debit account number of the originator.
referencerequired	string	The unique request reference number from the original payment request.

Request example

curl --location: 'https://partner-api-qv.keybank.com/rtp/v1/payment/status/debitAccount/12345/reference/RR-KEY-999999-01'
--header 'KeyClientId: testwUhSQADUD4DwYyZz2hZkwLqsoFGK'
--header 'Accept: application/json'
--header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8'

Responses

Successful response

NAME	TYPE	DESCRIPTION
statusrequired	Object	paymentStatus
transactionIdoptional	string	The unique ID number associated with the original payment request.
requestReferenceoptional	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptional	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberoptional	string	Debit account number
creditAccountNumberoptional	string	Credit account number
valueDateoptional	string	The date (YYYY-MM-DD) the transfer occurred.
transferAmountoptional	integer	Amount of money to transfer in the correct currency format.
transferCurrencyoptional	string	Currency code for the transfer amount.
erroroptional	Object	paymentError
doddFrankoptional	Object	noYesType
clearingSystemReferenceoptional	string	Enter a reference value for the beneficiary. This value cannot exceed 140 characters.

Response example (200)

{
    "status": "COMPLETED",
    "transactionId": "US21052400000000",
    "requestReference": "RR-KEY-999999-01",
    "sendersReference": "SR-KEY-999999-01",
    "receiversReference": "INVC0054321",
    "debitAccountNumber": "12345",
    "creditAccountNumber": "987654321",
    "valueDate": "2023-05-08",
    "transferAmount": 10,
    "transferCurrency": "USD",
    "doddFrank": "NO"
}

Missing data in the request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (400)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "US21052400000000",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "status": "FAILED",
        "transactionId": "rrt-770941720727587-2383364-1",
        "requestReference": "RR-220818-01",
        "sendersReference": "SR-220818-01",
        "valueDate": 1683676800,
        "error": {
            "code": "KEY-1006",
            "title": "Required field missing",
            "description": "The object creditPartyBank is required in the request."
        }
    }
}

Received request is unauthorized

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (401)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
    "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
    "TransactionTime": "2022-04-04T11:41:13.754Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-0006",
            "title": "Not authorized for requested service",
            "description": "Check your credentials."
        },
        "doddFrank": "NO"
    }
}

Request is forbidden to access the resource

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Requested resource is not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Requested method is not allowed

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Requested unsupported media type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Too many requests received

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Internal server error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (500)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "359681587523_SR-RMC-210729-11081",
    "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
    "TransactionTime": "2022-04-05T07:59:15.422Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-9999",
            "title": "Unknown error",
            "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials."
        },
        "doddFrank": "NO"
    }
}

Bad Gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend service",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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"
    }
}

Service Unavailable

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Gateway timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend service",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request."
    }
}

Send a wire transfer

post /rtp/v1/payment/initiate

Send a wire transfer. Use the requestedService parameter to define the transaction as Wire. With the party object, you can define the receiver as an individual, corporation, or financial institution in the payment chain.

Request

header FIELD	TYPE	DESCRIPTION
KeyClientIdrequired	string	This value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions.

BODY FIELD	TYPE	DESCRIPTION
requestedServicerequired	string	The type of payment transaction. The transaction request is valid only for the API products with granted access. Valid values: RTP, WIRE
requestReferencerequired	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
typerequired	string	For RTP, the type can show if the transaction is a PAYMENT or a DRAFT. For Wire transfers, the type is always DRAFT.
requestedValueDaterequired	string	Date (YYYY-MM-DD) the transfer will occur.
originatorReferenceoptional	string	An additional reference value that is meaningful to the party originating the payment.
sendersReferencerequired	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.
bankToBankInstructionsoptional	string	Area to share messages or instructions from one bank to another bank.
ultimateDebitPartyoptional	Object	ultParty
debitPartyrequired	Object	party
debitPartyBankoptional	Object	party
intermediaryBank1optional	Object	party
intermediaryBank2optional	Object	party
intermediaryBank3optional	Object	party
creditPartyBankrequired	Object	party
creditPartyrequired	Object	party
transferAmountrequired	number	Amount of money to transfer in the correct currency format.
transferCurrencyrequired	string	Currency code for the transfer amount.
externalTemplateNameoptional	string	TBD
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

Request example

{
    "requestedService": "WIRE",
    "requestReference": "AZX01234567891011",
    "type": "PAYMENT",
    "sendersReference": "INVC0012345",
    "receiversReference": "INVC0054321",
    "requestedValueDate": 1621814400,
    "debitParty": {
        "name": "YOUR COMPANY NAME HERE",
        "accountNumber": "001122334455"
    },
    "creditPartyBank": {
        "name": "BENEFICIARY BANK NAME",
        "aba": "000000000"
    },
    "creditParty": {
        "name": "BENEFICIARY NAME",
        "accountNumber": "987654321",
        "postalAddress": {
            "adrLine": [
                "BENEFICIARY ADDRESS LINE 1",
                "BENEFICIARY ADDRESS LINE 2"
            ]
        }
    },
    "transferAmount": 10,
    "transferCurrency": "USD"
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
statusrequired	Object	paymentStatus
transactionIdoptional	string	The unique ID number associated with the original payment request.
requestReferenceoptional	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptional	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberoptional	string	Debit account number
creditAccountNumberoptional	string	Credit account number
valueDateoptional	string	The date (YYYY-MM-DD) the transfer occurred.
transferAmountoptional	integer	Amount of money to transfer in the correct currency format.
transferCurrencyoptional	string	Currency code for the transfer amount.
erroroptional	Object	paymentError
doddFrankoptional	Object	noYesType
clearingSystemReferenceoptional	string	Enter a reference value for the beneficiary. This value cannot exceed 140 characters.

Response example (200)

{
    "status": "IN_PROCESS",
    "transactionId": "US23050800214592",
    "requestReference": "AZX01234567891011",
    "sendersReference": "INVC0012345",
    "receiversReference": "INVC0054321",
    "debitAccountNumber": "001122334455",
    "creditAccountNumber": "987654321",
    "valueDate": "2023-05-08",
    "transferAmount": 10,
    "transferCurrency": "USD"
}

Missing data in the request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (400)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "US21052400000000",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "status": "FAILED",
        "transactionId": "rrt-770941720727587-2383364-1",
        "requestReference": "RR-220818-01",
        "sendersReference": "SR-220818-01",
        "valueDate": 1683676800,
        "error": {
            "code": "KEY-1006",
            "title": "Required field missing",
            "description": "The object creditPartyBank is required in the request."
        }
    }
}

Received request is unauthorized

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (401)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
    "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
    "TransactionTime": "2022-04-04T11:41:13.754Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-0006",
            "title": "Not authorized for requested service",
            "description": "Check your credentials."
        },
        "doddFrank": "NO"
    }
}

Request is forbidden to access the resource

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Requested resource is not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Requested method is not allowed.

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Requested unsupported media type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Too many requests received

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Internal server error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (500)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "359681587523_SR-RMC-210729-11081",
    "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
    "TransactionTime": "2022-04-05T07:59:15.422Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "RR-RMC-210720-0123458981",
        "sendersReference": "SR-RMC-210729-11081",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-9999",
            "title": "Unknown error",
            "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials."
        },
        "doddFrank": "NO"
    }
}

Bad Gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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"
    }
}

Service Unavailable

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Gateway timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend service",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request."
    }
}

Perform validation checks

post /rtp/v1/payment/validate

This call performs all the validation checks needed to initiate a payment without creating a payment.

Request

header FIELD	TYPE	DESCRIPTION
KeyClientIdrequired	string	This value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions.

BODY FIELD	TYPE	DESCRIPTION
requestedServicerequired	string	The type of payment transaction. The transaction request is valid only for the API products with granted access. Valid values: RTP, WIRE
requestReferencerequired	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
typerequired	string	For RTP, the type can show if the transaction is a PAYMENT or a DRAFT. For Wire transfers, the type is always DRAFT.
requestedValueDaterequired	string	Date (YYYY-MM-DD) the transfer will occur.
originatorReferenceoptional	string	An additional reference value that is meaningful to the party originating the payment.
sendersReferencerequired	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.
bankToBankInstructionsoptional	string	Area to share messages or instructions from one bank to another bank.
ultimateDebitPartyoptional	Object	ultParty
debitPartyrequired	Object	party
debitPartyBankoptional	Object	party
intermediaryBank1optional	Object	party
intermediaryBank2optional	Object	party
intermediaryBank3optional	Object	party
creditPartyBankrequired	Object	party
creditPartyrequired	Object	party
transferAmountrequired	number	Amount of money to transfer in the correct currency format.
transferCurrencyrequired	string	Currency code for the transfer amount.
externalTemplateNameoptional	string	TBD
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

Request example

{
    "requestedService": "WIRE",
    "requestReference": "AZX01234567891011",
    "type": "PAYMENT",
    "requestedValueDate": 1621814400,
    "originatorReference": "",
    "sendersReference": "INVC0012345",
    "receiversReference": "INVC0054321",
    "ultimateDebitParty": {
        "name": ""
    },
    "debitParty": {
        "name": "YOUR COMPANY NAME HERE",
        "accountNumber": "001122334455"
    },
    "debitPartyBank": {
        "name": ""
    },
    "creditPartyBank": {
        "name": "BENEFICIARY BANK NAME",
        "aba": "000000000"
    },
    "creditParty": {
        "name": "BENEFICIARY NAME",
        "accountNumber": "987654321",
        "postalAddress": {
            "adrLine": [
                "BENEFICIARY ADDRESS LINE 1",
                "BENEFICIARY ADDRESS LINE 2"
            ]
        }
    },
    "transferAmount": 10,
    "transferCurrency": "USD",
    "customData": ""
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
statusrequired	Object	paymentStatus
transactionIdoptional	string	The unique ID number associated with the original payment request.
requestReferenceoptional	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptional	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberoptional	string	Debit account number
creditAccountNumberoptional	string	Credit account number
valueDateoptional	string	The date (YYYY-MM-DD) the transfer occurred.
transferAmountoptional	integer	Amount of money to transfer in the correct currency format.
transferCurrencyoptional	string	Currency code for the transfer amount.
erroroptional	Object	paymentError
doddFrankoptional	Object	noYesType
clearingSystemReferenceoptional	string	Enter a reference value for the beneficiary. This value cannot exceed 140 characters.

Response example (200)

{
    "status": "VALID",
    "transactionId": "XZ23050714000000",
    "requestReference": "testWBB25889710252",
    "sendersReference": "INVC0012345",
    "receiversReference": "INVC0054321",
    "debitAccountNumber": "12345",
    "creditAccountNumber": "987654321",
    "transferAmount": 10,
    "transferCurrency": "USD"
}

Missing data in the request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (400)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "US21052400000000",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "status": "FAILED",
        "transactionId": "rrt-770941720727587-2383364-1",
        "requestReference": "RR-220818-01",
        "sendersReference": "SR-220818-01",
        "valueDate": 1683676800,
        "error": {
            "code": "KEY-1006",
            "title": "Required field missing",
            "description": "The object creditPartyBank is required in the request."
        }
    }
}

Received request is unauthorized

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (401)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
    "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
    "TransactionTime": "2022-04-04T11:41:13.754Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-0006",
            "title": "Not authorized for requested service",
            "description": "Check your credentials."
        },
        "doddFrank": "NO"
    }
}

Request is forbidden to access the resource

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Requested resource is not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Requested method is not allowed

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Requested unsupported media type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Too many requests received

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Internal server error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (500)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "359681587523_SR-RMC-210729-11081",
    "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
    "TransactionTime": "2022-04-05T07:59:15.422Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-9999",
            "title": "Unknown error",
            "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials.",
            "detail": {
                "code": "KEY-1005",
                "title": "Error",
                "description": "Additional information about error code."
            }
        },
        "doddFrank": "NO"
    }
}

Bad Gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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"
    }
}

Service Unavailable

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Gateway timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (504)

{
    "ErrorMessage": "Your request took too long to process. Please try again.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request."
    }
}

Schemas

connectError

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

detail

NAME	TYPE	DESCRIPTION
coderequired	string	A static code assigned by the network or payment system.
titlerequired	string	Brief title about the error associated with the status code.
descriptionoptional	string	Description of the error.

exception

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

healthResponse

NAME	TYPE	DESCRIPTION
Statusoptional	string	The status of the health check response.
Sourceoptional	string	The system that produces the health response. The origin of the response can be 'Gateway' or 'Roundtrip.' Roundtrip returns a response from the farthest system involved.
Timestampoptional	string	The date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIpoptional	string	The client IP address the gateway receives from the request.
X-Forwarded-Foroptional	string	The sequence of the IP addresses for systems between the client and the gateway. Addresses are separated by a comma.

noYesType

NAME	TYPE	DESCRIPTION
noYesTypeoptional	string	This field indicates whether the transaction qualifies for Dodd-Frank.

participantListResponse

NAME	TYPE	DESCRIPTION
countrequired	string	The count of records that match the initial query.
limitrequired	integer	The maximum number of records returned in the response.
offsetrequired	integer	The number of records skipped before the response is returned.
partiesoptional	Object	party

party

NAME	TYPE	DESCRIPTION
namerequired	string	Name of the party. This can be an individual, a financial institution, or a beneficiary. The name cannot exceed 140 characters.
accountNumberoptional	string	Account number of the party.
abaoptional	string	If the party is a financial institution, this is the ABA number or routing number.
bicoptional	string	The bank identifier code (BIC) for the party. This is a combination code that identifies the bank, country, location, and possibly the bank branch.
txidoptional	string	The tax identification number for the party.
adrLineoptional	array	An unstructured address line. You can have up to three lines of text.

paymentError

NAME	TYPE	DESCRIPTION
coderequired	string	Status code assigned to each error type.
titlerequired	string	Brief title about the error associated with the status code.
descriptionoptional	string	Description of the error.
detailoptional	Object	detail

paymentTransactionRequestV1

NAME	TYPE	DESCRIPTION
requestedServicerequired	string	The type of payment transaction. The transaction request is valid only for the API products with granted access. Valid values: RTP, WIRE
requestReferencerequired	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
typerequired	string	For RTP, the type can show if the transaction is a PAYMENT or a DRAFT. For Wire transfers, the type is always DRAFT.
requestedValueDaterequired	string	Date (YYYY-MM-DD) the transfer will occur.
originatorReferenceoptional	string	An additional reference value that is meaningful to the party originating the payment.
sendersReferencerequired	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.
bankToBankInstructionsoptional	string	Area to share messages or instructions from one bank to another bank.
ultimateDebitPartyoptional	Object	ultParty
debitPartyrequired	Object	party
debitPartyBankoptional	Object	party
intermediaryBank1optional	Object	party
intermediaryBank2optional	Object	party
intermediaryBank3optional	Object	party
creditPartyBankrequired	Object	party
creditPartyrequired	Object	party
transferAmountrequired	number	Amount of money to transfer in the correct currency format.
transferCurrencyrequired	string	Currency code for the transfer amount.
externalTemplateNameoptional	string	TBD
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

paymentTransactionResponse

NAME	TYPE	DESCRIPTION
statusrequired	Object	paymentStatus
transactionIdoptional	string	The unique ID number associated with the original payment request.
requestReferenceoptional	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptional	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional	string	A reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberoptional	string	Debit account number
creditAccountNumberoptional	string	Credit account number
valueDateoptional	string	The date (YYYY-MM-DD) the transfer occurred.
transferAmountoptional	integer	Amount of money to transfer in the correct currency format.
transferCurrencyoptional	string	Currency code for the transfer amount.
erroroptional	Object	paymentError
doddFrankoptional	Object	noYesType
clearingSystemReferenceoptional	string	Enter a reference value for the beneficiary. This value cannot exceed 140 characters.

paymentStatus

NAME	TYPE	DESCRIPTION
paymentStatusoptional	string	The status of the payment transaction. Valid values: IN_PROCESS, IN_REVIEW, COMPLETED, FAILED, RETURNED, ERROR, VALID

serviceErrorData

NAME	TYPE	DESCRIPTION
statusrequired	Object	paymentStatus
transactionIdoptional	string	The unique ID number associated with the original payment request.
requestReferenceoptional	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptional	string	A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional	string	The sender reference value from the original request. This is useful for traceability and reporting.
debitAccountNumberoptional	string	The sender reference value from the original request. This is useful for traceability and reporting.
creditAccountNumberoptional	string	The sender reference value from the original request. This is useful for traceability and reporting.
valueDateoptional	string	The date (YYYY-MM-DD) the transferred occurred.
erroroptional	Object	paymentError
doddFrankoptional	Object	noYesType

ultParty

NAME	TYPE	DESCRIPTION
nameoptional	string	Typically this is the name of the party that instructed the debit party to initiate a payment. This value cannot exceed 140 characters.

foreignBankSystemType

NAME	TYPE	DESCRIPTION
typeoptional	string	The five-digit global routing code for a foreign financial institution.
idoptional	string	The identification number associated with the foreign financial institution.

Errors

When an error occurs, the paymentTransactionResponse object returns with the paymentStatus of ERROR. Some errors are reported with the standard HTTP error response. Certain violations report with an HTTP 200 response for issues where the API service successfully receives the request, but it encounters errors. KeyBank may include additional information about the error in API-specific error messages.

For more information about errors, see Error handling.

API-specific KeyBank error codes and details are in the error object of the response payload. Issues can be about account restrictions, network timeout, invalid data in the request, etc., and represent a failed payment.

API specific KeyBank codes and messages

CODE	MESSAGE
KEY-0001	Not authorized
KEY-0002	Not authorized for requested action
KEY-0003	Request exceeds authorized limit
KEY-0004	Unauthorized for account
KEY-0005	Internal use only fields
KEY-0006	Not authorized for requested service
KEY-0008	NSF
KEY-1000	Transformation Error
KEY-1001	Invalid Data
KEY-1002	Invalid Bank Identifier
KEY-1003	Invalid or unknown template
KEY-1004	Invalid account
KEY-1005	Invalid Currency
KEY-1006	Required field missing
KEY-1007	Transaction Not Found
KEY-1008	Insufficient Funds
KEY-1009	Account has restrictions
KEY-1010	Duplicate Request
KEY-1011	Payor Account Restrictions
KEY-1012	Payee Account Restrictions
KEY-3003	Payment network timeout. Please retry.
KEY-3004	Payment rejected by payment network
KEY-9997	Failed payment review
KEY-9998	Payment failed during processing
KEY-9999	Unknown error

API-specific error example

paymentTransactionResponse:
  { 
    "status": "FAILED", 
    "requestReference": "RR-999999-01", 
    "sendersReference": "SR-999999-01", 
    "error": { 
        "code": "KEY-1002", 
        "title": "Invalid Bank Identifier", 
        "description": "Credit Party Bank must be a valid USRTP Participant" 
    } 
}

Changelog

Release	API version	Change description	Impact
August 2024	1.2.4	Change the name of the Wire Origination API to its more common name, Wire Transfer. Added clarification to `type` field. For RTP the type can be PAYMENT or DRAFT. For wire transfers, the type will always be DRAFT.	MID
May 2024	1.2.3	`KeyClientId` is required for all endpoints, including GET calls.	MID
March 2024	1.2.1	Added 'IN_REVIEW' as a valid value for `status` in the `paymentStatus` object. Added new parameters to `paymentTransactionRequestV1`: `bankToBankInstructions` `debitPartyInstructions` `intermediaryBank1` `intermediaryBank2` `intermediaryBank3` `externalTemplateName` Added the `clearingSystemReference` in the `paymentTransactionResponse` object. Added the following parameters to `serviceErrorData`: `receiversReference` `debitAccountNumber` `creditAccountNumber` Changed min/max limits for the following parameters: `requestReference` and `sendersReference` changed from maxLength 35 to 32 with a minLength of 1. Added parameter limits for `originatorReference` with a minLength of 1 and a maxLength of 35. Added parameter limit for `transferAmount` with a maximum of 18 digits (which is like quintillion). Added parameter limit for `accountNumber` in the `party` to a minLength of 1. Added parameter limit for `aba` to a maxLength of 9 digits. Added parameter limit for `debitAccountNumber` to a maxLength 34 characters.	HIGH
September 2023	1.1.5	Parameter description updates. This change is for technical content only. The code and operations of the API remain the same.	LOW
July 2023	1.1.3	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

ACH Inquiry

4-minute read 1.2.1 | updated Oct. 15, 2024

Get the status for your ACH transactions

ACH Inquiry Endpoints

Summary	Endpoint
Health check	get /accounts/transactions/v1/healthCheck
Get details about an ACH transaction with a PAR number	get /accounts/transactions/v1/ach/detail/{parNumber}
Search for ACH transactions	post /accounts/transactions/v1/ach/list

Overview

You can use the ACH Inquiry API to get the status for ACH transactions as they are received and processed by KeyBank.

The consolidation settlement type affect what information is returned. The ACHStatus field defines the status of the transaction as in progress (COLLECTED), processed (SETTLED), or returned (RETURNED).

For clients with a non-consolidated settlement, you can receive information about collected, settled, and returned transactions.
For clients with a consolidated settlement, you will only receive collected and returned transactions. SETTLED is not an available status for consolidated settlement.

PAR-don me

ACH inquiries require a parNumber or traceNumber for inquiries. Learn more in our ACH APIs User Guide.

Health check

get /accounts/transactions/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	System producing the health response. Genesis of the response could either be just from “gateway” or “roundtrip” from the farthest possible system involved in generating this response.
Timestampoptional	string	Timestamp when the health response is being returned by this service.
ClientIpoptional	string	IP of the client from which this request for health check is received by the gateway.
X-Forwarded-Foroptional	string	Sequence of all the Ips of the systems involved 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]"
}

Get details about an ACH transaction with a PAR number

get /accounts/transactions/v1/ach/detail/{parNumber}

Use the PAR number to retrieve information about an ACH transaction.

Request

path FIELD	TYPE	DESCRIPTION
parNumberrequired	string	The unique PAR number assigned to the the transaction by the ACH product processor.

Responses

Successful response

NAME	TYPE	DESCRIPTION
parNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionStatusoptional	string	The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumberoptional	string	The unique number for the transaction provided by the originator.
transactionAmountoptional	number	The dollar amount of the transaction.
settlementDateoptional	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
transactionCodeDescriptionoptional	string	Description for the transaction code.
transactionDescriptionoptional	string	Description about the purpose of the transaction.
authorizedCustomerNameoptional	string	Authorized customer name
standardEntryClassCodeoptional	string	The three-digit Standard Entry Class code based on Nacha rules.
standardEntryClassDescriptionoptional	string	The description for the Nacha SEC code.
receivingAccountoptional	Object	AccountDetail
receivingPartyoptional	Object	PartyDetail
originatingAccountoptional	Object	AccountDetail
originatingPartyoptional	Object	PartyDetail
returnDateoptional	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCodeoptional	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescriptionoptional	string	Description as to why the ACH transaction is returned.
addendaCountoptional	integer	Count of addenda records.
notificationOfChangeAddendaCountoptional	integer	Count of change notifications for addenda records.
internationalAddendaCountoptional	integer	Count of international addenda records.
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.
checkSerialNumberoptional	string	Serial number for the check converted to an ACH transaction.
transactionDirectionoptional	string	Indicates the direction of the transaction. Valid values: ORIGINATING ITEM, RECEIVING ITEM
addendaoptional	array	Addendum
notificationOfChangeoptional	array	NotificationOfChange

Response example (200)

{
    "parNumber": "22018007665985",
    "transactionStatus": "COLLECTED",
    "traceNumber": "000000000000000",
    "transactionAmount": 10.01,
    "settlementDate": "2021-03-08",
    "transactionCode": "22",
    "transactionCodeDescription": "Automated Deposit",
    "transactionDescription": "DEPOSIT",
    "authorizedCustomerName": "TEST CUSTOMER1",
    "standardEntryClassCode": "CCD",
    "standardEntryClassDescription": "Cash Concentration or Disbursement",
    "receivingAccount": {
        "accountNumber": "123456789012",
        "bankNumber": "0000",
        "routingNumber": "1234567890"
    },
    "receivingParty": {
        "customerIdentificationNumber": "099999999",
        "companyName": "MERCHANT",
        "customerName": "TEST MERCHANT"
    },
    "originatingAccount": {
        "accountNumber": "123456789012",
        "bankNumber": "0000",
        "routingNumber": "1234567890"
    },
    "originatingParty": {
        "customerIdentificationNumber": "1234567",
        "companyName": "COMPANY NAME 1",
        "customerName": "CUSTOMER NAME 1"
    },
    "returnDate": "2024-02-01",
    "returnReasonCode": "R02",
    "returnReasonDescription": "Account Closed",
    "addendaCount": 1,
    "notificationOfChangeAddendaCount": 1,
    "internationalAddendaCount": 0,
    "customData": "merchant:status",
    "checkSerialNumber": "4345",
    "transactionDirection": "Receiving Item",
    "addenda": [
        {
            "sequenceNumber": 1,
            "entryDetailSequenceNumber": "188",
            "paymentRelatedInformation": "Addenda Record (Applies to CCD, CTX, PPD, and WEB entries)"
        }
    ],
    "notificationOfChange": [
        {
            "changeCode": "C02",
            "changeDescription": "Incorrect transit\/routing number",
            "correctedData": "1234567890"
        }
    ]
}

Successful response

NAME	TYPE	DESCRIPTION
parNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionStatusoptional	string	The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumberoptional	string	The unique number for the transaction provided by the originator.
transactionAmountoptional	number	The dollar amount of the transaction.
settlementDateoptional	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
transactionCodeDescriptionoptional	string	Description for the transaction code.
transactionDescriptionoptional	string	Description about the purpose of the transaction.
authorizedCustomerNameoptional	string	Authorized customer name
standardEntryClassCodeoptional	string	The three-digit Standard Entry Class code based on Nacha rules.
standardEntryClassDescriptionoptional	string	The description for the Nacha SEC code.
receivingAccountoptional	Object	AccountDetail
receivingPartyoptional	Object	PartyDetail
originatingAccountoptional	Object	AccountDetail
originatingPartyoptional	Object	PartyDetail
returnDateoptional	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCodeoptional	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescriptionoptional	string	Description as to why the ACH transaction is returned.
addendaCountoptional	integer	Count of addenda records.
notificationOfChangeAddendaCountoptional	integer	Count of change notifications for addenda records.
internationalAddendaCountoptional	integer	Count of international addenda records.
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.
checkSerialNumberoptional	string	Serial number for the check converted to an ACH transaction.
transactionDirectionoptional	string	Indicates the direction of the transaction. Valid values: ORIGINATING ITEM, RECEIVING ITEM
addendaoptional	array	Addendum
notificationOfChangeoptional	array	NotificationOfChange

Response example (200)

{
    "parNumber": "22018007665985",
    "transactionStatus": "COLLECTED",
    "traceNumber": "000000000000000",
    "transactionAmount": 10.01,
    "settlementDate": "2021-03-08",
    "transactionCode": "22",
    "transactionCodeDescription": "Automated Deposit",
    "transactionDescription": "DEPOSIT",
    "authorizedCustomerName": "TEST CUSTOMER1",
    "standardEntryClassCode": "CCD",
    "standardEntryClassDescription": "Cash Concentration or Disbursement",
    "receivingAccount": {
        "accountNumber": "123456789012",
        "bankNumber": "0000",
        "routingNumber": "1234567890"
    },
    "receivingParty": {
        "customerIdentificationNumber": "099999999",
        "companyName": "MERCHANT",
        "customerName": "TEST MERCHANT"
    },
    "originatingAccount": {
        "accountNumber": "123456789012",
        "bankNumber": "0000",
        "routingNumber": "1234567890"
    },
    "originatingParty": {
        "customerIdentificationNumber": "1234567",
        "companyName": "COMPANY NAME 1",
        "customerName": "CUSTOMER NAME 1"
    },
    "returnDate": "2024-02-01",
    "returnReasonCode": "R02",
    "returnReasonDescription": "Account Closed",
    "addendaCount": 1,
    "notificationOfChangeAddendaCount": 1,
    "internationalAddendaCount": 0,
    "customData": "merchant:status",
    "checkSerialNumber": "4345",
    "transactionDirection": "Receiving Item",
    "addenda": [
        {
            "sequenceNumber": 1,
            "entryDetailSequenceNumber": "188",
            "paymentRelatedInformation": "Addenda Record (Applies to CCD, CTX, PPD, and WEB entries)"
        }
    ],
    "notificationOfChange": [
        {
            "changeCode": "C02",
            "changeDescription": "Incorrect transit\/routing number",
            "correctedData": "1234567890"
        }
    ]
}

Advanced search for ACH transactions

post /accounts/transactions/v1/ach/list

Search for ACH transactions by passing certain search parameters. With ACH transactions, each status point has a start and end date. If you search using the fromDate and toDate parameters, use the dateSearchType to identify if it is the start and end date for when the transaction was collected, returned, or settled. If you leave the dateSearchType field blank, the request only searches the date range for collected transactions.

Request

NAME	TYPE	DESCRIPTION
accountNumberrequired	string	The bank account number. This field cannot exceed 16 characters.
dateSearchTypeoptional	string	Each ACH transaction status has an associated date range. Indicate the specific transaction date set to search. If left blank, the search defaults to collected transaction dates. Valid values: COLLECTED, RETURNED, SETTLED
fromDateoptional	string	Start date for the date range. This date must be the current date or prior to the current date. Transaction data can be recalled within 180 days of the current date. Format: YYYY-MM-DD
toDateoptional	string	End date for the date range. This date can be the current day or a later date from the start date (fromDate). The date range should not exceed 31 days. Format: YYYY-MM-DD
minimumAmountoptional	string	The minimum dollar amount of the transaction. This amount must be less than or equal to the maximum amount. Leave blank or enter zero for no minimum amount.
maximumAmountoptional	string	The maximum dollar amount of the transaction. This amount must be greater than or equal to the minimum amount. Leave blank to retrieve all amounts. This amount cannot exceed one billion dollars.
traceNumberoptional	string	The unique number for the transaction provided by the originator.
pageNumberoptional	string	The number of the page being viewed. This number must be greater than or equal to 1.
pageSizeoptional	string	The total number of pages returned. This number must be greater than or equal to 1 and cannot exceed 1000.

Request example

{
  "accountNumber": "3123456789",
  "dateSearchType": "COLLECTED",
  "fromDate": 1706745600,
  "toDate": 1706745600,
  "minimumAmount": 100,
  "maximumAmount": 75020.5,
  "traceNumber": "041001030016002",
  "pageNumber": 1,
  "pageSize": 150
 }

Responses

Successful response

NAME	TYPE	DESCRIPTION
transactionsoptional	string	AchListTransaction
metadataoptional	string	Metadata

Response example (200)

{
  "transactions": [{
    "parNumber": "22018007665985",
    "transactionStatus": "COLLECTED",
    "traceNumber": "000000000000000",
    "transactionAmount": 10.01,
    "settlementDate": "2021-03-08",
    "transactionCode": "22",
    "authorizedCustomerName": "TEST CUSTOMER1",
    "standardEntryClassCode": "CCD",
    "receivingAccount": {
      "accountNumber": "123456789012"
      },    
    "receivingParty": {
      "customerIdentificationNumber": "099999999",
      "companyName": "MERCHANT"
      },
    "originatingAccount": {
      "accountNumber": "123456789012"
      },
    "originatingParty": {
      "customerIdentificationNumber": "1234567",
      "companyName": "COMPANY NAME 1"
      },
    "returnDate": "2024-02-01",
    "returnReasonCode": "R02",
    "returnReasonDescription": "Account Closed",
    "addendaCount": 1,
    "notificationOfChangeAddendaCount": 1,
    "internationalAddendaCount": 0
    }
  ],
    "metadata": {
      "messages": [{
        "code": "099",
        "message": "Search results match the criteria"
          }    
    ],
    "page": {
    "pageNumber": 1,
    "pageSize": 10,
    "totalPages": 10,
    "totalRecords": 28,
    "lastPage": true
    }
    }    
    }

Bad input parameter

NAME	TYPE	DESCRIPTION
metadataoptional	string	Metadata

Response example (400)

{
  "metadata": {
    "messages": [{
      "code": "001",
      "message": "There are no transactions that match the parNumber."
     }  
  ],
  "page": {
    "pageNumber": 1,
    "pageSize": 1,
    "totalPages": 1,
    "totalRecords": 0,
    "lastPage": false
   }
  }
 }

Schemas

exception

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

serviceErrorData

NAME	TYPE	DESCRIPTION
ServiceErrorDataoptional	oneOf	returnACHtransactionslistResponse achCollectedTransactionsResponse achPostedTransactionsResponse achStatusInquiryResponse

connectError

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

returnACHtransactionslistResponse

NAME	TYPE	DESCRIPTION
getACHReturnTransactionsResponseoptional	Object	achReturnTransactionsResponse

ACHReturnTransaction

NAME	TYPE	DESCRIPTION
returnTransactionParNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
sourceBankNumberoptional	string	Originating entry bank number
sourceAccountNumberoptional	string	Originating account number
sourceTransactionRecordNumberoptional	string	Originating record number for the transaction
sourceSysCodeoptional	string	Do not use. This field is for internal purpose only.
sourceSysOfRecordCodeoptional	string	Do not use. This field is for internal purpose only.
snapshotDateoptional	string	This field is for internal purpose only.
originalACHTransactionParNumberoptional	string	The assigned PAR number for the original ACH transaction.
originalTransactionProcessDateoptional	string	Date the transaction is processed. Format: YYYY-MM-DD
originalTransactionProcessTimeoptional	string	Time the transaction is processed in 24-hour time. Format: HHMMSS
originalTransactionProcessTimestampoptional	string	The date and time the transaction is processed. Format: YYYY-MM-DD HH:MM:SS
originatingReceiverCodeoptional	string	Two-character code that identifies the transaction type as originating (O) or receiving (R) and if the transaction is incoming (I) or outgoing (O). Codes can be OI, OO, RI, or RO.
originatingReceiverDescriptionoptional	string	Description for the returned originating receiver code.
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
transactionCodeDescriptionoptional	string	Description for the transaction code.
transactionFlowTypeCodeoptional	string	Identifies if transaction is intrabank (within a single financial institution) or interbank (between two or more banks). Valid values: INTRA, INTER
transactionFlowTypeDescriptionoptional	string	Description for the transaction flow type code.
transactionAmountoptional	string	The dollar amount of the transaction.
transactionDescription1optional	string	A free form text field that provides the receiver with a description about the purpose of the transaction.
transactionDescription2optional	string	Additional transaction description information.
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
sourceTransactionCreatedDateoptional	string	Date when the user created the ACH transaction. Format: YYYY-MM-DD
sourceTransactionCreatedTimeoptional	string	Time when the user created the ACH transaction. The time format uses the 24-hour clock. Format: HHMM
sourceTransactionCreatedTimestampoptional	string	The date and time that the ACH transaction was created. Format: YYYY-MM-DD HH:MM:SS
sourceTransactionProcessDateoptional	string	Date when the transaction was collected by the ACH product processor. Format: YYYY-MM-DD
sourceTransactionProcessTimeoptional	string	Time when the transaction was collected by the ACH product processor. The time format uses the 24-hour clock. Format: HHMMSS
sourceTransactionProcessTimestampoptional	string	The date and time the ACH transaction was collected by the ACH product processor. Format: YYYY-MM-DD HH:MM:SS
inboundCollectionWindowoptional	string	The time window when the transaction collection is processed. The time format uses the 24-hour clock. Format: HHMM
outboundCollectionWindowoptional	string	The outbound processing window for the transaction collection. The time format uses the 24-hour clock. Format: HHMM
sourceTransactionSettledDateoptional	string	Date when the transaction is settled. Format: YYYY-MM-DD
sourceTransactionSettledTimeoptional	string	The time window when the transaction is settled. The time format uses the 24-hour clock. Format: HHMM
sourceTransactionSettledTimestampoptional	string	The date and time the ACH transaction is settled. Format: YYYY-MM-DD HH:MM:SS
receivingAccountNumberoptional	string	Account number of the person or institution receiving the funds.
receivingCustIdentificationNumberoptional	string	The customer identification number for the person receiving the transaction.
receivingCustomerNameoptional	string	Customer name of the person receiving the funds.
receivingCompanyNameoptional	string	Company name of the institution getting the funds.
receivingFIBankNumberoptional	string	Bank number for the financial institution receiving the funds.
receivingFIRoutingNumberoptional	string	Routing number for the receiving financial institution.
originatingAccountNumberoptional	string	Account number of the ACH transaction originator.
originatingCustIdentificationNumberoptional	string	Originating customer identification number
originatingCustomerNameoptional	string	Originating customer name
originatingCompanyNameoptional	string	Originating company name
originatingFIBankNumberoptional	string	Originating financial institution bank number
originatingFIRoutingNumberoptional	string	Originating financial institution routing number
authorizedCustomerNameoptional	string	Authorized customer name
immediateDestinationIDoptional	string	The ID indicates the next location of the file once it leaves KeyBank.
returnReleaseDateoptional	string	Release date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCodeoptional	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescriptionoptional	string	Description as to why the ACH transaction is returned.
checkSerialNumberoptional	string	Serial number for the check converted to an ACH transaction.
nachaBatchNumberoptional	string	The sequential number of the Nacha batch job.
nachaFileHeadRefererenceNumberoptional	string	The Nacha transaction file reference number.
nachaSecondarySecCodeoptional	string	The secondary Nacha standard entry class (SEC) code for the transaction, if applicable. Valid values: CCD, CTX, PPD, TEL, WEB.
nachaSecondarySecDescriptionoptional	string	The description for the secondary Nacha SEC code.
traceIdoptional	string	The trace ID number from the source application.
postCompanyCostcontrolNumberoptional	string	Do not use. This field is for internal purpose only.
glAccountNumberoptional	string	Do not use. This field is for internal purpose only.
collectionPointoptional	string	Transaction collection point
collectionApplicationTypeCodeoptional	string	Do not use. This field is for internal purpose only.
collectionApplicationTypeDescriptionoptional	string	Do not use. This field is for internal purpose only.
batchIDoptional	string	The identification number for the batch job.
customDataoptional	string	Custom data from the originating payment request.

businessFault

NAME	TYPE	DESCRIPTION
errorCodeoptional	string	Business error code
errorDescriptionoptional	string	Business error description

achReturnTransactionsResponse

NAME	TYPE	DESCRIPTION
responseHeaderrequired	Object	responseHeader
ACHReturnTransactionoptional	array	ACHReturnTransaction
errorResponseoptional	Object	errorResponse

systemFault

NAME	TYPE	DESCRIPTION
errorCodeoptional	string	System error code
errorDescriptionoptional	string	System error description

achReturnTransactionsRequest

NAME	TYPE	DESCRIPTION
getACHReturnTransactionsRequestoptional	Object	getACHReturnTransactionsRequest

getACHReturnTransactionsRequest

NAME	TYPE	DESCRIPTION
accountNumberrequired	array	One or more bank account numbers. To look up multiple accounts, separate the account numbers with a comma. This field cannot exceed than 16 characters.
fromDaterequired	string	The start date of a date range for submitted transactions. This date should be less than or equal to the current date. Date range cannot exceed more than one year. Format: YYYY-MM-DD
toDaterequired	string	The end date of a date range for the submitted transactions. The date must be later than the start date (fromDate). Date range cannot exceed more than one year. Format: YYYY-MM-DD
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
fromAmountoptional	string	Transaction amount lower limit value to be searched.
toAmountoptional	string	Transaction amount upper limit value to be searched.
parNumberoptional	string	The PAR (Payment Assigned Reference) number is a unique identifier assigned by the ACH Product Processor. Use a comma to separate multiple PAR numbers.
detailsFlagrequired	string	Return a detailed response (Y) or a brief response (N). Valid values: Y, N
receivingCustIdentificationNumberoptional	string	The unique ID number associated with the payment recipient. This number is defined in the originating payment request.
startRowIndexoptional	string	Pagination parameter that indicates the starting count available for the records. If this parameter is not provided, value will default to 1.
endRowIndexoptional	string	Pagination parameter that indicates the last count available for the records. If this parameter is not provided, value will default to 1000. The request can't exceed more than 1000 records from the startRowIndex.

responseHeader

NAME	TYPE	DESCRIPTION
statusrequired	string	Indicates whether the result was successful or not. Valid values: accepted, failure
statusDescriptionrequired	string	Description of the status
retrivedRowsoptional	string	Total number of transactions retrieved.
totalRowsoptional	string	Total number of transactions matching the requested criteria.
dataLoadDateoptional	string	Indicates the date that the requested data was loaded. Format: YYYY-MM-DD

errorResponse

NAME	TYPE	DESCRIPTION
businessFaultoptional	array	businessFault
systemFaultoptional	array	systemFault

achCollectedTransactionsRequest

NAME	TYPE	DESCRIPTION
getACHCollectedTransactionsRequestoptional	Object	getACHCollectedTransactionsRequest

getACHCollectedTransactionsRequest

NAME	TYPE	DESCRIPTION
accountNumberrequired	array	One or more bank account numbers. To look up multiple accounts, separate the account numbers with a comma. This field cannot exceed than 16 characters.
fromDaterequired	string	The start date of a date range for submitted transactions. This date should be less than or equal to the current date. Date range cannot exceed more than one year. Format: YYYY-MM-DD
toDaterequired	string	The end date of a date range for the submitted transactions. The date must be later than the start date (fromDate). Date range cannot exceed more than one year. Format: YYYY-MM-DD
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
fromAmountoptional	string	Transaction amount lower limit value to be searched.
toAmountoptional	string	Transaction amount upper limit value to be searched.
addendaFlagrequired	string	Retrieves addenda information if set to Y for yes. Valid values: Y, N
secCodeoptional	string	The three-digit Standard Entry Class code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEB
traceNumberoptional	string	The unique number for the transaction provided by the originator. Multiple trace numbers can be comma separated.
parNumberoptional	string	The PAR (Payment Assigned Reference) number is a unique identifier assigned by the ACH Product Processor. Use a comma to separate multiple PAR numbers.
detailsFlagrequired	string	Return a detailed response (Y) or a brief response (N). Valid values: Y, N
receivingCustIdentificationNumberoptional	string	The unique ID number associated with the payment recipient. This number is defined in the originating payment request.
startRowIndexoptional	string	Pagination parameter that indicates the starting count available for the records. If this parameter is not provided, value will default to 1.
endRowIndexoptional	string	Pagination parameter that indicates the last count available for the records. If this parameter is not provided, value will default to 1000. The request can't exceed more than 1000 records from the startRowIndex.

achStatusInquiryParRequest

NAME	TYPE	DESCRIPTION
getACHStatusInquiryRequestoptional	Object	getACHStatusInquiryParRequest

achStatusInquiryTraceNumberRequest

NAME	TYPE	DESCRIPTION
getACHStatusInquiryRequestoptional	Object	getACHStatusInquiryTraceNumberRequest

getACHStatusInquiryParRequest

NAME	TYPE	DESCRIPTION
accountNumberrequired	array	One or more bank account numbers. To look up multiple accounts, separate the account numbers with a comma. This field cannot exceed than 16 characters.
parNumberrequired	array	The PAR (Payment Assigned Reference) number is a unique identifier assigned by the ACH Product Processor. Use a comma to separate multiple PAR numbers.
traceNumberoptional	array	The unique number for the transaction provided by the originator. Multiple trace numbers can be comma separated.
receivingCustIdentificationNumberoptional	string	The unique ID number associated with the payment recipient. This number is defined in the originating payment request.
startRowIndexoptional	string	Pagination parameter that indicates the starting count available for the records. If this parameter is not provided, value will default to 1.
endRowIndexoptional	string	Pagination parameter that indicates the last count available for the records. If this parameter is not provided, value will default to 1000. The request can't exceed more than 1000 records from the startRowIndex.

getACHStatusInquiryTraceNumberRequest

NAME	TYPE	DESCRIPTION
accountNumberrequired	array	One or more bank account numbers. To look up multiple accounts, separate the account numbers with a comma. This field cannot exceed than 16 characters.
traceNumberrequired	array	The unique number for the transaction provided by the originator. Multiple trace numbers can be comma separated.
parNumberoptional	array	The PAR (Payment Assigned Reference) number is a unique identifier assigned by the ACH Product Processor. Use a comma to separate multiple PAR numbers.
receivingCustIdentificationNumberoptional	string	The unique ID number associated with the payment recipient. This number is defined in the originating payment request.
startRowIndexoptional	string	Pagination parameter that indicates the starting count available for the records. If this parameter is not provided, value will default to 1.
endRowIndexoptional	string	This is a pagination field. It indicates the last count available for the records. If the field is not provided, value will default to 1000. The request can't exceed more than 1000 records from the startRowIndex.

achPostedTransactionsRequest

NAME	TYPE	DESCRIPTION
getACHPostedTransactionsRequestoptional	Object	getACHPostedTransactionsRequest

getACHPostedTransactionsRequest

NAME	TYPE	DESCRIPTION
accountNumberrequired	array	One or more bank account numbers. To look up multiple accounts, separate the account numbers with a comma. This field cannot exceed than 16 characters.
fromDaterequired	string	The start date of a date range for submitted transactions. This date should be less than or equal to the current date. Date range cannot exceed more than one year. Format: YYYY-MM-DD
toDaterequired	string	The end date of a date range for the submitted transactions. The date must be later than the start date (fromDate). Date range cannot exceed more than one year. Format: YYYY-MM-DD
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
fromAmountoptional	string	Transaction amount lower limit value to be searched.
toAmountoptional	string	Transaction amount upper limit value to be searched.
parNumberoptional	string	The PAR (Payment Assigned Reference) number is a unique identifier assigned by the ACH Product Processor. Use a comma to separate multiple PAR numbers.
receivingCustIdentificationNumberoptional	string	The unique ID number associated with the payment recipient. This number is defined in the originating payment request.
startRowIndexoptional	string	Pagination parameter that indicates the starting count available for the records. If this parameter is not provided, value will default to 1.
endRowIndexoptional	string	Pagination parameter that indicates the last count available for the records. If this parameter is not provided, value will default to 1000. The request can't exceed more than 1000 records from the startRowIndex.

achCollectedTransactionsResponse

NAME	TYPE	DESCRIPTION
getACHCollectedTransactionsResponserequired	Object	getACHCollectedTransactionsResponse

getACHCollectedTransactionsResponse

NAME	TYPE	DESCRIPTION
responseHeaderrequired	Object	responseHeader
ACHCollectedTransactionoptional	array	achCollectedTransactionsResult
errorResponseoptional	Object	errorResponse

achCollectedTransactionsResult

NAME	TYPE	DESCRIPTION
transactionParNumberoptional	string	The unique PAR number assigned to the transaction by the ACH product processor.
sourceBankNumberoptional	string	Originating entry bank number
sourceAccountNumberoptional	string	Originating account number.
origAcctSuffixoptional	string	Do not use. This field is for internal purpose only.
sourceSysCodeoptional	string	Do not use. This field is for internal purpose only.
sourceSysOfRecordCodeoptional	string	Do not use. This field is for internal purpose only.
snapshotDateoptional	string	This field is for internal purpose only.
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
transactionCodeDescriptionoptional	string	Description for the transaction code.
transactionFlowTypeCodeoptional	string	Identifies if transaction is intrabank (within a single financial institution) or interbank (between two or more banks). Valid values: INTRA, INTER
transactionFlowTypeDescriptionoptional	string	Description for the transaction flow type code.
originatingReceiverCodeoptional	string	Two-character code that identifies the transaction type as originating (O) or receiving (R) and if the transaction is incoming (I) or outgoing (O). Codes can be OI, OO, RI, or RO.
transactionAmountoptional	string	The dollar amount of the transaction.
transactionDescriptionoptional	string	A free form text field that provides the receiver with a description about the purpose of the transaction.
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
inboundCollectionWindowoptional	string	The time window when the transaction collection is processed. The time format uses the 24-hour clock. Format: HHMM
sourceTransactionProcessDateoptional	string	Date when the transaction was collected by the ACH product processor. Format: YYYY-MM-DD
sourceTransactionProcessTimeoptional	string	Time when the transaction was collected by the ACH product processor. The time format uses the 24-hour clock. Format: HHMMSS
sourceTransactionProcessTimestampoptional	string	The date and time the ACH transaction was collected by the ACH product processor. Format: YYYY-MM-DD HH:MM:SS
sourceTransactionSettledDateoptional	string	Date when the transaction is settled. Format: YYYY-MM-DD
sourceTransactionSettledTimeoptional	string	The time window when the transaction is settled. The time format uses the 24-hour clock. Format: HHMM
sourceTransactionSettledTimestampoptional	string	The date and time the ACH transaction is settled. Format: YYYY-MM-DD HH:MM:SS
sourceTransactionPostDateoptional	string	Date the ACH transaction is posted. Format: YYYY-MM-DD
sourceTransactionPostTimeoptional	string	Time the ACH transaction is posted. The time format uses the 24-hour clock. Format: HHMMSS
sourceTransactionPostTimestampoptional	string	The date and time the transaction is posted. Format: YYYY-MM-DD HH:MM:SS
deliveryStatusCodeoptional	string	The code abbreviation for the delivery status of the ACH transaction.
deliveryStatusDescriptionoptional	string	The delivery status description for the abbreviated code.
receivingAccountNumberoptional	string	Account number of the person or institution receiving the funds.
receivingFIBankNumberoptional	string	Bank number for the financial institution receiving the funds.
receivingFIRoutingNumberoptional	string	Routing number for the receiving financial institution.
receivingCustIdentificationNumberoptional	string	The customer identification number for the person receiving the transaction.
receivingCustomerNameoptional	string	Customer name of the person receiving the funds.
receivingCompanyNameoptional	string	Company name of the institution getting the funds.
originatingAccountNumberoptional	string	Account number of the ACH transaction originator.
originatingFIBankNumberoptional	string	Originating financial institution bank number
originatingFIRoutingNumberoptional	string	Originating financial institution routing number
originatingCustIdentificationNumberoptional	string	Originating customer identification number
originatingCompanyNameoptional	string	Originating company name
originatingCustomerNameoptional	string	Originating customer name
checkSerialNumberoptional	string	Serial number for the check converted to an ACH transaction.
nachaBatchNumberoptional	string	The sequential number of the Nacha batch job.
nachaFileHeadRefererenceNumberoptional	string	The Nacha transaction file reference number.
nachaSecCodeoptional	string	The Nacha standard entry class (SEC) code for the transaction. Valid values: CCD, CTX, PPD, TEL WEB
nachaSecDescriptionoptional	string	The description for the Nacha SEC code.
traceNumberoptional	string	The unique number for the transaction provided by the originator. Multiple trace numbers can be comma separated.
postCompanyCostcontrolNumberoptional	string	Do not use. This field is for internal purpose only.
glAccountNumberoptional	string	Do not use. This field is for internal purpose only.
addendaPresentFlagoptional	string	Indicates if there are addenda records or not.
addendaRecordNumberoptional	string	Number of addenda records.
originatingReceiverDescriptionoptional	string	Description for the collected originating receiver code.
goRoutingNumberoptional	string	Gateway operator routing number for international transactions.
authorizedCustomerNameoptional	string	Authorized customer name
iatFlagoptional	string	International transaction identifier
collectionPointoptional	string	Transaction collection point
batchIdoptional	string	The identification number for the batch job.
transactionTraceIdoptional	string	The trace ID number from the source application.
addendaInformationoptional	Object	addendaInformation
customDataoptional	string	Custom data from the originating payment request.

achPostedTransactionsResponse

NAME	TYPE	DESCRIPTION
getACHPostedTransactionsResponserequired	Object	getACHPostedTransactionsResponse

getACHPostedTransactionsResponse

NAME	TYPE	DESCRIPTION
responseHeaderrequired	Object	responseHeader
ACHPostedTransactionoptional	array	achPostedTransactionsResult
errorResponseoptional	Object	errorResponse

achPostedTransactionsResult

NAME	TYPE	DESCRIPTION
snapshotDateoptional	string	Do not use. This field is for internal purpose only.
processDateoptional	string	Date the transaction was processed. Format: YYYY-MM-DD
sourceBankNumberoptional	string	Originating entry bank number
sourceAccountNumberoptional	string	Originating account number
transactionParNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionAmountoptional	string	The dollar amount of the transaction.
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
hoganTransactionCodeoptional	string	The KeyBank Hogan code for the transaction.
baiCodeoptional	string	The three-digit BAI (Bank Administration Institute) code for the transaction.
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
regulationDescription1optional	string	Regulation description for the transaction.
regulationDescription2optional	string	Additional regulation information for the transaction.
regulationDescription3optional	string	Additional regulation information for the transaction.
regulationDescription4optional	string	Additional regulation information for the transaction.
postingWindowoptional	string	The time window when the transaction collection is posted. The time format uses the 24-hour clock. Format: HHMM
batchIDoptional	string	The identification number for the batch job.
customDataoptional	string	Custom data from the originating payment request.

achStatusInquiryResponse

NAME	TYPE	DESCRIPTION
responseHeaderrequired	Object	responseHeader
ACHTransactionStatusoptional	array	achStatusInquiryResult
errorResponseoptional	Object	errorResponse

achStatusInquiryResult

NAME	TYPE	DESCRIPTION
ACHStatusoptional	string	The status informs you if the ACH transaction has been collected or returned. Valid values: COLLECTED or RETURNED
ACHCollectedTransactionoptional	Object	achCollectedTransactionsStatusResult
ACHPostedTransactionoptional	Object	achPostedTransactionsStatusResult
ACHReturnTransactionoptional	Object	achReturnTransactionsStatusResult

achCollectedTransactionsStatusResult

NAME	TYPE	DESCRIPTION
transactionParNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
sourceBankNumberoptional	string	Originating entry bank number
sourceAccountNumberoptional	string	Originating account number.
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
transactionAmountoptional	string	The dollar amount of the transaction.
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
sourceTransactionProcessDateoptional	string	Date when the transaction was collected by the ACH product processor. Format: YYYY-MM-DD
sourceTransactionProcessTimeoptional	string	Time when the transaction was collected by the ACH product processor. The time format uses the 24-hour clock. Format: HHMMSS
sourceTransactionProcessTimestampoptional	string	The date and time the ACH transaction was collected by the ACH product processor. Format: YYYY-MM-DD HH:MM:SS
sourceTransactionSettledDateoptional	string	Date when the transaction is settled. Format: YYYY-MM-DD
sourceTransactionSettledTimeoptional	string	The time window when the transaction is settled. The time format uses the 24-hour clock. Format: HHMM
sourceTransactionSettledTimestampoptional	string	The date and time the ACH transaction is settled. Format: YYYY-MM-DD HH:MM:SS
sourceTransactionPostDateoptional	string	Date the ACH transaction is posted. Format: YYYY-MM-DD
sourceTransactionPostTimeoptional	string	Time the ACH transaction is posted. The time format uses the 24-hour clock. Format: HHMMSS
sourceTransactionPostTimestampoptional	string	The date and time the transaction is posted. Format: YYYY-MM-DD HH:MM:SS
receivingCustomerNameoptional	string	Customer name of the person receiving the funds.
receivingCompanyNameoptional	string	Company name of the institution getting the funds.
originatingCompanyNameoptional	string	Originating company name
originatingCustomerNameoptional	string	Originating customer name
nachaSecCodeoptional	string	The Nacha standard entry class (SEC) code for the transaction. Valid values: CCD, CTX, PPD, TEL, WEB
traceNumberoptional	string	The unique number for the transaction provided by the originator. Multiple trace numbers can be comma separated.
transactionDescriptionoptional	string	A free form text field that provides the receiver with a description about the purpose of the transaction.
receivingCustIdentificationNumberrequired	string	The unique ID number associated with the payment recipient. This number is defined in the originating payment request.

achPostedTransactionsStatusResult

NAME	TYPE	DESCRIPTION
processDateoptional	string	Date the transaction was processed. Format: YYYY-MM-DD
transactionParNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionAmountoptional	string	The dollar amount of the transaction.
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
baiCodeoptional	string	The three-digit BAI (Bank Administration Institute) code for the transaction.
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
regulationDescription1optional	string	Regulation description for the transaction.
regulationDescription2optional	string	Additional regulation information for the transaction.
regulationDescription3optional	string	Additional regulation information for the transaction.
regulationDescription4optional	string	Additional regulation information for the transaction.
postingWindowoptional	string	The time window when the transaction collection is posted. The time format uses the 24-hour clock. Format: HHMM

achReturnTransactionsStatusResult

NAME	TYPE	DESCRIPTION
transactionParNumberoptional	string	The unique PAR number assigned to the transaction by the ACH product processor.
transactionCodeoptional	string	Two digit code identifying the account type at the receiving financial institution.
transactionCodeDescriptionoptional	string	Description for the transaction code.
transactionAmountoptional	string	The dollar amount of the transaction.
transactionDescription1optional	string	A free form text field that provides the receiver with a description about the purpose of the transaction.
transactionDescription2optional	string	Additional transaction description information.
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
returnReleaseDateoptional	string	Release date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCodeoptional	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescriptionoptional	string	Description as to why the ACH transaction is returned.

addendaInformation

NAME	TYPE	DESCRIPTION
iatAddendumoptional	Object	iatAddendum
nonIatAddendumoptional	Object	nonIatAddendum
nocAddendumoptional	Object	nocAddendum

iatAddendum

NAME	TYPE	DESCRIPTION
addendaParNumberoptional	string	The unique PAR number assigned to the addendum by the ACH product processor.
snapshotDateoptional	string	Do not use. This field is for internal purpose only.
transactionParNumberoptional	string	The unique PAR number assigned to the transaction by the ACH product processor.
payInformationoptional	string	Additional information about the remittance payment.
addendaTypeCodeoptional	string	Two-digit code identifying the type of information.
addendaTypeDescriptionoptional	string	Description of the addenda type associated with the code.
transactionTypeCodeoptional	string	This field contains a three-character code used to identify the type of transaction.
transactionTypeDescroptional	string	This field contains description of the the transaction type code
originatingFiIdentificationNumberCodeoptional	string	Originating financial institution code
originatingFiNameoptional	string	Originating financial institution name
originatingFiIdentificationNumberoptional	string	Originating financial institution identification number
originatingFiBranchCountryCodeoptional	string	Originating company country branch code
originatingCompanyNameoptional	string	Originating company name
originatingCompanyAddress1optional	string	Originating bank physical street address, line 1
originatingCompanyAddress2optional	string	Originating bank physical street address, line 2
originatingCompanyCityStateProvinceoptional	string	Originator city and state
originatingCompanyCountryPostalCodeoptional	string	Originator country and postal code
receivingFiNameoptional	string	Receiving financial institution name
receivingFiIdentificationNumberoptional	string	Receiving financial institution identification number
receivingFiIdentificationNumberCodeoptional	string	Receiving financial institution code
receivingFiBranchCountryCodeoptional	string	Receiving company country branch code
receivingCustomerNameoptional	string	Receiving customer name
receivingCompanyNameoptional	string	Receiving company name
receivingCompanyNumberoptional	string	Receiving company number
receivingCompanyAddress1optional	string	Receiving company physical address, line 1
receivingCompanyAddress2optional	string	Receiving company physical address, line 2
receivingCompanyCityStateProvinceoptional	string	Receiving company city and state
receivingCompanyCountryPostalCodeoptional	string	Receiving company country and postal code
foreignCorrespondentFiIdNumberCodeoptional	string	Foreign correspondent bank identification number qualifier
foreignCorrespondentFiNameoptional	string	Correspondent bank name
foreignCorrespondentFiBRCountryCodeoptional	string	Correspondent bank country code
foreignCorrespondentBankIdNumberoptional	string	Correspondent bank identifier
foreignOriginatingAmountoptional	string	Foreign payment amount
foreignOriginatingCurrencyCodeoptional	string	Foreign currency code
foreignTraceNumberoptional	string	Identifier number of the foreign transaction.
addendaSequenceNumberoptional	string	The sequence number of the addenda. The number cannot exceed 4 digits.
entryDetailSequenceNumberoptional	string	Sequence number of the entry detail
operatorCommandFlagoptional	string	Operator command flag

nonIatAddendum

NAME	TYPE	DESCRIPTION
addendaParNumberoptional	string	The unique PAR number assigned to the addendum by the ACH product processor.
snapshotDateoptional	string	Do not use. This field is for internal purpose only.
transactionParNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionSerialNumberoptional	string	Serial number for the transaction
transactionDescriptionoptional	string	A free form text field that provides the receiver with a description about the purpose of the transaction.
sourceTransactionCreatedDateoptional	string	Date when the user created the ACH transaction. Format: YYYY-MM-DD
sourceTransactionCreatedTimeoptional	string	Time when the user created the ACH transaction. The time format uses the 24-hour clock. Format: HHMM
payInformationoptional	string	Additional information associated with the payment transaction.
addendaTypeCodeoptional	string	Two-digit code identifying the type of information.
addendaTypeDescriptionoptional	string	Description of the addenda type associated with the code.
entryDetailSequenceNumberoptional	string	Sequence number of the entry detail
referenceInformation1optional	string	Free form text field with additional reference information.
referenceInformtion2optional	string	Free form text field with additional reference information.
networkIdentificationCodeoptional	string	Network identification code (NIC)
terminalIdentificationCodeoptional	string	Terminal identification code
terminalCityoptional	string	City location of the terminal
terminalStateoptional	string	State location of the terminal
keyBankTransactionReferenceNumberoptional	string	Unique ACH transaction identifier created by KeyBank.
operatorCommandFlagoptional	string	Operator command flag

nocAddendum

NAME	TYPE	DESCRIPTION
addendaParNumberoptional	string	The unique PAR number assigned to the addendum by the ACH product processor.
snapshotDateoptional	string	Do not use. This field is for internal purpose only.
transactionParNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
addendaTypeCodeoptional	string	Two-digit code identifying the type of information.
addendaTypeDescriptionoptional	string	Description of the addenda type associated with the code.
changeCodeoptional	string	The three-character change code begins with the letter 'C'. This code is applied to all NOCs to indicate the information that is being changed.
changeDescriptionoptional	string	The description associated with the change code.
receivingFiIdentificationNumberoptional	string	Receiving financial institution identification number
correctedDataoptional	string	The corrected data per the correction change code.
externalFiTransactionIdentificationNumberoptional	string	The number used by an external financial institution to identify the transaction.
keyBankTransactionReferenceNumberoptional	string	Unique ACH transaction identifier created by KeyBank.
operatorCommandFlagoptional	string	Operator command flag.

AccountList

NAME	TYPE	DESCRIPTION
accountNumberoptional	string	Bank account number.

AccountDetail

NAME	TYPE	DESCRIPTION
accountNumberoptional	string	Bank account number of the ACH originator or receiver.
bankNumberoptional	string	Bank number associated with the account number.
routingNumberoptional	string	Nine-digit routing number for the account provided in the original request.

AchDetailTransaction

NAME	TYPE	DESCRIPTION
parNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionStatusoptional	string	The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumberoptional	string	The unique number for the transaction provided by the originator.
transactionAmountoptional	number	The dollar amount of the transaction.
settlementDateoptional	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
transactionCodeDescriptionoptional	string	Description for the transaction code.
transactionDescriptionoptional	string	Description about the purpose of the transaction.
authorizedCustomerNameoptional	string	Authorized customer name
standardEntryClassCodeoptional	string	The three-digit Standard Entry Class code based on Nacha rules.
standardEntryClassDescriptionoptional	string	The description for the Nacha SEC code.
receivingAccountoptional	Object	AccountDetail
receivingPartyoptional	Object	PartyDetail
originatingAccountoptional	Object	AccountDetail
originatingPartyoptional	Object	PartyDetail
returnDateoptional	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCodeoptional	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescriptionoptional	string	Description as to why the ACH transaction is returned.
addendaCountoptional	integer	Count of addenda records.
notificationOfChangeAddendaCountoptional	integer	Count of change notifications for addenda records.
internationalAddendaCountoptional	integer	Count of international addenda records.
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.
checkSerialNumberoptional	string	Serial number for the check converted to an ACH transaction.
transactionDirectionoptional	string	Indicates the direction of the transaction. Valid values: ORIGINATING ITEM, RECEIVING ITEM
addendaoptional	array	Addendum
notificationOfChangeoptional	array	NotificationOfChange

AchListTransaction

NAME	TYPE	DESCRIPTION
parNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionStatusoptional	string	The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumberoptional	string	The unique number for the transaction provided by the originator.
transactionAmountoptional	number	The dollar amount of the transaction.
settlementDateoptional	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
authorizedCustomerNameoptional	string	Authorized customer name
standardEntryClassCodeoptional	string	The three-digit Standard Entry Class code based on Nacha rules.
receivingAccountoptional	Object	AccountList
receivingPartyoptional	Object	PartyList
originatingAccountoptional	Object	AccountList
originatingPartyoptional	Object	PartyList
returnDateoptional	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCodeoptional	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescriptionoptional	string	Description as to why the ACH transaction is returned.
addendaCountoptional	integer	Count of addenda records.
notificationOfChangeAddendaCountoptional	integer	Count of change notifications for addenda records.
internationalAddendaCountoptional	integer	Count of international addenda records.

Addendum

NAME	TYPE	DESCRIPTION
sequenceNumberoptional	integer	The addenda record item number in order of sequence. Number cannot exceed 4 digits.
entryDetailSequenceNumberoptional	string	The entry number in order of sequence. Number cannot exceed 7 digits.
paymentRelatedInformationoptional	string	The related payment information from the addenda records. The maximum character limit is 255.

Message

NAME	TYPE	DESCRIPTION
codeoptional	string	Code for the related message.
messageoptional	string	Message associated with the code.

Page

NAME	TYPE	DESCRIPTION
pageNumberoptional	integer	The number of the page being viewed.
pageSizeoptional	integer	The number of records per page.
totalPagesoptional	integer	The number of pages there are in total.
totalRecordsoptional	integer	The total number of transactions available in the result set.
lastPageoptional	boolean	Indicates if the current page (page number) is the last page of the result set. Valid values: true, false

Metadata

NAME	TYPE	DESCRIPTION
messagesoptional	array	Message
pageoptional	Object	Page

PartyList

NAME	TYPE	DESCRIPTION
customerIdentificationNumberoptional	string	The unique identification number associated with the customer.
companyNameoptional	string	The name of the corporation or institution making the request.

PartyDetail

NAME	TYPE	DESCRIPTION
customerIdentificationNumberoptional	string	The unique identification number associated with the customer.
companyNameoptional	string	The name of the corporation or institution making the request.
customerNameoptional	string	The name of the customer.

NotificationOfChange

NAME	TYPE	DESCRIPTION
changeCodeoptional	string	The three-character change code begins with the letter 'C'. This code is applied to all NOCs to indicate the information that is being changed.
changeDescriptionoptional	string	The description associated with the change code.
correctedDataoptional	string	The corrected data per the correction change code.

Errors

For more information about general errors, see Error handling.

API-specific KeyBank error codes and details are in the ServiceError or errorResponse object with additional information specific to the API. The KeyBank error codes start with ECA-W with a three-digit number that follows. The number increases by one digit for each error message. For example, if you have an issue with your request that generates two error messages specific to the API, the codes will be ECA-W-001 and ECA-W-002.

API specific KeyBank codes and messages

HTTP
STATUS CODE CUSTOM
STATUS CODE DESCRIPTION

299

ECA-W-001 Request processing completed with warnings.

This message occurs when multiple request parameters are provided, and some of the data are not available as part of response.

400

ECA-W-001 Request Validation failed.

There is missing mandatory information like accountNumber, fromDate, or toDate. Review values for mandatory request fields.

400

ECA-W-002 Requested records range is greater than the allowed limit - 1000

Response goes beyond 1000 transactions for the requested account. Change the request criteria to help limit returned transactions to the allowed amount.

Changelog

Release	API version	Change description	Impact
October 2024	1.2.1	Date parameters adjusted to support the maximum date range search limit of 180 days. Do not enter a `fromDate` and `toDate` date range that goes beyond 31 days.	LOW
May 2024	1.2.0	Two new endpoints available in all environments, including the API simulator! We have added: `GET /accounts/transactions/v1/ach-transactions/{parNumber}` `POST /accounts/transactions/v1/ach-transactions`	MID
December 2023	1.1.6	Deprecated the `mdmID` field. Backend services and processes have been enhanced to authenticate client API calls without the need for an MDM ID. Removed the POSTED status from the list of valid values for the `ACHStatus` field in the `achStatusInquiryResult` object. Valid values for this field now only include COLLECTED or RETURNED.	MID
September 2023	1.1.5	The `mdmId` description has been updated to communicate that this field will soon deprecate in an upcoming release.	LOW
August 2023	1.1.4	Modified the format for date parameters to match with KeyBank API standard date format of YYYY-MM-DD. `fromDate` and `toDate` were updated to recall transaction data from the previous 24 months.	LOW
July 2023	1.1.3	Added the `settlementDate` field in the response to provide you the ability to filter by date in response. MDM ID (`mdmId`) is no longer a required field, it is now optional.	LOW
May 2023	1.1.2	Added `customData` to the following objects: `achCollectedTransactionsResult` `achPostedTransactionsResult` `ACHReturnTransaction` Added `receivingCustIdentificationNumber` to the request payloads. In the `achCollectedTransactionsResult` response, we added an example for the `nonIatAddendum` schema.	MID
December 2022	1.0.0	Released on the Developer Portal.

Impact levels

LOW: This is a minor change or enhancement that does not alter the operations of the API. Upgrading to the latest specifications is preferable but not required.
MID: The previous API version is valid and operates, but does not contain latest enhancements. You need to update your specifications to get these enhancements.
HIGH: The previous API version is no longer operable. You must upgrade to the latest specifications to access and use this API product.

YAML file

ACH Origination

8-minute read 1.3.2 | updated Oct. 15, 2024

Send or collect an ACH transaction, report on the status, or undo a payment

ACH Origination Endpoints

What you can do	Endpoint
Health check	get /ach/payments/v1/healthCheck
Check the status of a payment request	post /ach/payments/v1/status
Check the status of addenda records	post /ach/payments/v1/status/addenda
Send or collect a payment	post /ach/payments/v1/ccd
Make or collect payments to or from a corporate account with attached records	post /ach/payments/v1/ctx
Make deposits and withdrawals to or from consumer accounts	post /ach/payments/v1/ppd
Authorize a payment over the phone	post /ach/payments/v1/tel
Send an online payment	post /ach/payments/v1/web
Undo a payment request	post /ach/payments/v1/undo
Send additional addenda information	post /ach/payments/v1/addenda

Before you begin

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

Sometimes it's the details

You can add details to your transaction. Use custom data feature when you send or validate a payment. Define the customData in the request payload. Learn more about our custom data feature here.

Overview

ACH stands for Automated Clearing House. ACH payments are electronic funds transfers (EFTs), a type of electronic payment that transfers funds between bank accounts within the United States. ACH payments are often less expensive than wire transfers, with lower or no transaction fees. Most commonly, ACH payments are used for direct deposit of payroll, recurring bill payments, online purchases, and person-to-person transfers.

How does it work?

The ACH Origination process starts with a payment or collection request made by a financial institution or client (business or individual). In the request, the payment method (SEC code) and transaction type (credit or debit) must be defined. The API automatically assigns the effective date and other data, like the trace number.

You get a trace number after you initiate an ACH transaction. The trace number is a unique identifier for an ACH transaction generated by the API. The trace number is useful for transaction inquiries and traceability. Save this trace number if you intend to check on the progress of the ACH transaction. For multiple payment requests, the trace number may not be in sequential order.

A request generates a batch response that includes the status and payment details by SEC code. For the consolidation, we store records from the batch, detail, and addenda schemas. You can include up to ten accounts with each request. For each submitted request, you can check on the status and progress of the payment or addenda report.

Except for TEL type transaction, all the SEC code types can include addenda information with the response. If an addenda item returns a large set of records (common with CTX), it initiates the addenda request. This request adds additional addenda records to a detail item. Currently, only details that are associated to a batch having a CTX SEC code can have additional addenda records added.

API requirements

UUID: UUID stands for Universally Unique Identifier. This is a useful attribute to recall a transaction before the next batch cycle runs. Since the UUID field is required to undo an ACH payment request, KeyBank strongly encourages the UUID is included with all ACH Origination calls.

The batch and the individual UUID can be the same, but KeyBank recommends that you use different UUID values.

Client information values: After you have completed the onboarding process with KeyBank, KeyBank provides the client (point) and client account (collectionApplicationId, collectionApplicationType) information via secure email. These fields are required for any ACH Origination call with a SEC code.

SEC code: In the request payload, you must specify the Standard Entry Class (SEC) code for the transaction. The ACH Origination API supports these SEC codes: CCD, CTX, PPD, TEL, WEB. Review the details on SEC codes in our user guide.

Health check

get /ach/payments/v1/healthCheck

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

Responses

Successful response

NAME	TYPE	DESCRIPTION
Statusoptional	string	The status of the health check response.
Sourceoptional	string	The origin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved.
Timestampoptional	string	The date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIpoptional	string	The client IP address the gateway receives from the request.
X-Forwarded-Foroptional	string	The sequence of the 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]"
}

Check the status of a payment request

post /ach/payments/v1/status

Check the return status of one or more transactions. Use this request to see if the originated item failed, was accepted, is waiting for one or more addenda items, or is being processed.

Request

BODY FIELD	TYPE	DESCRIPTION
detailStatusoptional	array	paymentInquiryDetailRequest

Request example

{
    "detailStatus": [
        {
            "uuid": "qas220602x-49eb-47664-b94rhd1-e52e2re11001"
        }
    ]
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
detailsoptional	array	detailStatusResponse

Missing mandatory information

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Check the status of addenda records

post /ach/payments/v1/status/addenda

Check the return status of one or more addenda records

Request

BODY FIELD	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
pageSizeoptional	string	The number of records to be returned in the pagination search.
startAddendaSequenceNumberoptional	string	The starting number for the addenda record sequence.

Request example

{
    "uuid": "qas220517x-49eb-47664-b94rhd1-e52e2re13001",
    "pageSize": "10",
    "startAddendaSequenceNumber": "0001"
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
uuidoptional	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusoptional	string	The status of the batch can be accepted or rejected.
errorMessagesoptional	array	detailMessage
traceNumberoptional	string	The unique number for the ACH transaction. Record this number for possible ACH inquiry requests.
informationMessagesoptional	array	detailMessage
addendaoptional	array	baseAddendaDetailResponse

Response example (200)

{
    "uuid": "qas220517x-49eb-47664-b94rhd1-e52e2re13001",
    "status": "accepted",
    "traceNumber": "041001030009004",
    "informationMessages": [
        {
            "code": "1002040-50I",
            "moreInfo": "All addenda have been received."
        }
    ],
    "errorMessages": [],
    "addenda": [
        {
            "addendaTypeCode": "05",
            "addendaSequenceNumber": "0001",
            "paymentRelatedInformation": "Undo WEB PAYMENT GOOD ITEM"
        }
    ]
}

Missing mandatory information

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Send or collect a payment

post /ach/payments/v1/ccd

Make or collect payments to a corporate account. This call originates an ACH transaction for SEC code CCD (Corporate Credit or Debit). Use this request to send or collect cash, debit, or credit transactions between the buyer and seller financial institution accounts. This can also be used by companies to move funds and deposit to a central bank account.

Request

BODY FIELD	TYPE	DESCRIPTION
batchrequired	Object	batchRequestCCDDetailRequest
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

Request example

{
    "batch": {
        "collectionApplicationId": "TEST",
        "point": "APITEST1",
        "secCode": "CCD",
        "uuid": "daily001-qas230109-010300-005",
        "collectionApplicationType": "",
        "effectiveDate": "230211",
        "companyDescriptiveDate": "230211",
        "companyEntryDescription": "Payroll",
        "details": [
            {
                "DFIAccountNumber": "123456",
                "accountType": "C",
                "amount": "0.01",
                "checkDigit": "9",
                "creditDebitCode": "C",
                "receivingCompanyName": "ProdTest001",
                "receivingDFIId": "04100103",
                "transactionType": "L",
                "uuid": "daily001-qas230109-010301-0026",
                "identificationNumber": "099999999a",
                "discretionaryData": "AB",
                "addenda": [
                    {
                        "paymentRelatedInformation": "DAILYTEST0103A"
                    }
                ]
            }
        ]
    }
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
batchrequired	Object	acceptedBatchResponseAcceptedDetailResponse

Response example (200)

{
    "batch": {
        "uuid": "daily001-qas230109-010300-005",
        "status": "accepted",
        "requestAcceptedUTCTime": "2023-05-03T17:04:03Z",
        "effectiveDate": "230211",
        "informationMessages": [
            {
                "code": "1006040-65I",
                "moreInfo": "Effective date assigned 230211."
            }
        ],
        "errorMessages": [],
        "details": [
            {
                "uuid": "daily001-qas230109-010301-0026",
                "status": "accepted",
                "errorMessages": [],
                "informationMessages": [],
                "traceNumber": "041001030013025",
                "requestAcceptedUTCTime": "2023-05-03T17:04:03Z"
            }
        ]
    }
}

Missing mandatory information

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Make or collect payments to or from a corporate account with attached records

post /ach/payments/v1/ctx

Submit or collect a payment from one business/entity to another. This call originates an ACH transaction for SEC code CTX (Corporate Trade Exchange). Use this request to send or collect an electronic payment with remittance information.

Request

BODY FIELD	TYPE	DESCRIPTION
batchrequired	Object	batchRequestCTXDetailRequest
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

Request example

{
    "batch": {
        "collectionApplicationId": "TEST2",
        "point": "APITEST1",
        "secCode": "CTX",
        "uuid": "test3c377-bat338-ctxf-bcd6fehdd0-031103",
        "collectionApplicationType": "",
        "effectiveDate": "230411",
        "companyDescriptiveDate": "230411",
        "companyEntryDescription": "Payroll",
        "details": [
            {
                "DFIAccountNumber": "111011",
                "accountType": "S",
                "checkDigit": "0",
                "creditDebitCode": "C",
                "numberOfAddendaRecords": "1",
                "receivingCompanyNameIDNumber": "YourTest301",
                "receivingDFIId": "06100001",
                "totalAmount": "1.31",
                "transactionType": "L",
                "uuid": "test3c377-det338-ctxf-dcd6fehdd0-030104",
                "identificationNumber": "099999999",
                "discretionaryData": "AK",
                "addenda": [
                    {
                        "paymentRelatedInformation": "YourTest03.01"
                    }
                ]
            }
        ]
    }
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
batchrequired	Object	acceptedBatchResponseAcceptedDetailResponse

Response example (200)

{
    "batch": {
        "uuid": "test3c377-bat338-ctxf-bcd6fehdd0-031103",
        "status": "accepted",
        "requestAcceptedUTCTime": "2023-05-03T17:06:02Z",
        "effectiveDate": "230411",
        "informationMessages": [
            {
                "code": "1006040-65I",
                "moreInfo": "Effective date assigned 230411."
            }
        ],
        "errorMessages": [],
        "details": [
            {
                "uuid": "test3c377-det338-ctxf-dcd6fehdd0-030104",
                "status": "accepted",
                "errorMessages": [],
                "informationMessages": [],
                "traceNumber": "041001030013026",
                "requestAcceptedUTCTime": "2023-05-03T17:06:02Z"
            }
        ]
    }
}

Missing mandatory information

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Make deposits and withdrawals to or from consumer accounts

post /ach/payments/v1/ppd

Submit or collect a payment based on consumer authorization and terms of service. This call originates an ACH transaction for SEC code PPD (Prearranged Payments and Debits). Use this request to send or collect a routine electronic payment, like a subscription or monthly payment plan.

Request

BODY FIELD	TYPE	DESCRIPTION
batchrequired	Object	batchRequestPPDDetailRequest
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

Request example

{
    "batch": {
        "collectionApplicationId": "TEST",
        "point": "APITEST1",
        "secCode": "PPD",
        "uuid": "qas22517-4d3338-4c6f-bcd6fehdd0-1234360",
        "collectionApplicationType": "",
        "effectiveDate": "230211",
        "companyDescriptiveDate": "230211",
        "companyEntryDescription": "Payroll",
        "details": [
            {
                "DFIAccountNumber": "123456789",
                "accountType": "S",
                "amount": "520.25",
                "checkDigit": "9",
                "creditDebitCode": "C",
                "individualName": "QASTest005",
                "receivingDFIId": "04100103",
                "transactionType": "L",
                "uuid": "qas220330A-49eb-47664-b94rhd1-12361",
                "individualIdentificationNumber": "099999999a",
                "discretionaryData": "AB",
                "addenda": [
                    {
                        "paymentRelatedInformation": "QASTest02.02A"
                    }
                ]
            },
            {
                "DFIAccountNumber": "234567891",
                "accountType": "S",
                "amount": "0.00",
                "checkDigit": "2",
                "creditDebitCode": "C",
                "individualName": "QASTest006",
                "receivingDFIId": "24107121",
                "transactionType": "P",
                "uuid": "qas220330A-49eb-47664-b94rhd1-12362",
                "individualIdentificationNumber": "099999999b",
                "discretionaryData": "BC"
            },
            {
                "DFIAccountNumber": "345678912",
                "accountType": "S",
                "amount": "1794.91",
                "checkDigit": "2",
                "creditDebitCode": "D",
                "individualName": "QASTest006",
                "receivingDFIId": "24107121",
                "transactionType": "L",
                "uuid": "qas220330A-49eb-47664-b94rhd1-12363",
                "individualIdentificationNumber": "099999999c",
                "discretionaryData": "BC",
                "addenda": [
                    {
                        "paymentRelatedInformation": "QASTest02.02C"
                    }
                ]
            }
        ]
    }
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
batchrequired	Object	acceptedBatchResponseAcceptedDetailResponse

Response example (200)

{
    "batch": {
        "uuid": "qas22517-4d3338-4c6f-bcd6fehdd0-1234360",
        "status": "accepted",
        "requestAcceptedUTCTime": "2023-05-03T17:08:45Z",
        "effectiveDate": "230211",
        "informationMessages": [
            {
                "code": "1006040-65I",
                "moreInfo": "Effective date assigned 230211."
            }
        ],
        "errorMessages": [],
        "details": [
            {
                "uuid": "qas220330A-49eb-47664-b94rhd1-12361",
                "status": "accepted",
                "errorMessages": [],
                "informationMessages": [],
                "traceNumber": "041001030012784",
                "requestAcceptedUTCTime": "2023-05-03T17:08:45Z"
            },
            {
                "uuid": "qas220330A-49eb-47664-b94rhd1-12362",
                "status": "accepted",
                "errorMessages": [],
                "informationMessages": [],
                "traceNumber": "041001030012785",
                "requestAcceptedUTCTime": "2023-05-03T17:08:45Z"
            },
            {
                "uuid": "qas220330A-49eb-47664-b94rhd1-12363",
                "status": "accepted",
                "errorMessages": [],
                "informationMessages": [],
                "traceNumber": "041001030012786",
                "requestAcceptedUTCTime": "2023-05-03T17:08:45Z"
            }
        ]
    }
}

Missing mandatory information

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Send a payment over the phone

post /ach/payments/v1/tel

Authorize and submit a payment by the phone.

Request

BODY FIELD	TYPE	DESCRIPTION
batchrequired	Object	batchRequestTELDetailRequest
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

Request example

{
    "batch": {
        "collectionApplicationId": "TEST",
        "point": "APITEST1",
        "secCode": "TEL",
        "uuid": "qas22523-4d3338-4c6f-bcd6fehdd0-12349",
        "collectionApplicationType": "",
        "effectiveDate": "230211",
        "companyDescriptiveDate": "230211",
        "companyEntryDescription": "Payroll",
        "details": [
            {
                "DFIAccountNumber": "1234567890123452",
                "accountType": "C",
                "amount": "5963.88",
                "checkDigit": "0",
                "creditDebitCode": "D",
                "individualName": "QASTest014",
                "receivingDFIId": "06100001",
                "transactionType": "L",
                "uuid": "qas22523-f76-44eb-a7014041047",
                "individualIdentificationNumber": "099999999",
                "paymentTypeCode": "R"
            }
        ]
    }
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
batchrequired	Object	acceptedBatchResponseAcceptedDetailResponse

Response example (200)

{
    "batch": {
        "uuid": "qas22523-4d3338-4c6f-bcd6fehdd0-12349",
        "status": "accepted",
        "requestAcceptedUTCTime": "2023-05-03T17:10:58Z",
        "effectiveDate": "230211",
        "informationMessages": [
            {
                "code": "1006040-65I",
                "moreInfo": "Effective date assigned 230211."
            }
        ],
        "errorMessages": [],
        "details": [
            {
                "uuid": "qas22523-f76-44eb-a7014041047",
                "status": "accepted",
                "errorMessages": [],
                "informationMessages": [],
                "traceNumber": "041001030013030",
                "requestAcceptedUTCTime": "2023-05-03T17:10:58Z"
            }
        ]
    }
}

Missing mandatory information

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Send an online payment

post /ach/payments/v1/web

Authorize and submit a payment on a website.

Request

BODY FIELD	TYPE	DESCRIPTION
batchrequired	Object	batchRequestWEBDetailRequest
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

Request example

{
    "batch": {
        "collectionApplicationId": "TEST",
        "point": "APITEST1",
        "secCode": "WEB",
        "uuid": "qas22523-4d3338-4c6f-bcd6fehdd0-41033",
        "collectionApplicationType": "",
        "effectiveDate": "230211",
        "companyDescriptiveDate": "",
        "companyEntryDescription": "Payroll",
        "details": [
            {
                "DFIAccountNumber": "123546789",
                "accountType": "C",
                "amount": "0.00",
                "checkDigit": "0",
                "creditDebitCode": "D",
                "individualName": "QASTest014",
                "receivingDFIId": "06100001",
                "transactionType": "P",
                "uuid": "qas22523-f76-44eb-a7014041034",
                "individualIdentificationNumber": "099999999",
                "paymentTypeCode": "R",
                "addenda": [
                    {
                        "paymentRelatedInformation": "DAILYTEST0103A"
                    }
                ]
            }
        ]
    }
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
batchrequired	Object	acceptedBatchResponseAcceptedDetailResponse

Response example (200)

{
    "batch": {
        "uuid": "qas22523-4d3338-4c6f-bcd6fehdd0-41033",
        "status": "accepted",
        "requestAcceptedUTCTime": "2023-05-03T17:13:45Z",
        "effectiveDate": "230211",
        "informationMessages": [
            {
                "code": "1006040-65I",
                "moreInfo": "Effective date assigned 230211."
            }
        ],
        "errorMessages": [],
        "details": [
            {
                "uuid": "qas22523-f76-44eb-a7014041034",
                "status": "accepted",
                "errorMessages": [],
                "informationMessages": [],
                "traceNumber": "041001030012787",
                "requestAcceptedUTCTime": "2023-05-03T17:13:45Z"
            }
        ]
    }
}

Missing mandatory information

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Undo a payment request

post /ach/payments/v1/undo

Reverse a payment request before it enters consolidation.

Request

BODY FIELD	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.

Request example

{
    "uuid": "qas220517x-49eb-47664-b94rhd1-e52e2re13001"
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusoptional	string	The status of a batch record can be accepted or rejected. The status of a detailed record can be deleted, accepted, rejected, notFound, or waitingForAddenda.
errorMessagesoptional	array	detailMessage
informationMessagesoptional	array	detailMessage
traceNumberoptional	string	The unique number for the ACH transaction. Record this number for possible ACH inquiry requests.

Response example (200)

{
    "uuid": "qas220517x-49eb-47664-b94rhd1-e52e2re13001",
    "status": "accepted",
    "errorMessages": [
        {
            "code": "1006040-651"
        },
        {
            "moreInfo": "Effective date assigned 220411"
        }
    ],
    "informationMessages": [
        {
            "code": "1006040-651"
        },
        {
            "moreInfo": "Effective date assigned 220411"
        }
    ],
    "traceNumber": "041001030008013"
}

Missing mandatory information

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Send additional addenda information

post /ach/payments/v1/addenda

Add records to an existing ACH transaction.

Request

BODY FIELD	TYPE	DESCRIPTION
addendarequired	array	addendaRequest
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.

Request example

{
    "addenda": [
        {
            "paymentRelatedInformation": "0410*820412***PER*AP*QAS TESTING*IT*N1*PR*THE QAS COMPANY*         0",
            "addendaSequenceNumber": "002"
        },
        {
            "paymentRelatedInformation": "3*ROUTE 1234*BOX 1234\\N5*TESTING*",
            "addendaSequenceNumber": "003"
        },
        {
            "paymentRelatedInformation": "TM*003*820311\\RMT*IV*0302892**252640\\DTM*003*820315\\RMT*IV*0302960**593835\\",
            "addendaSequenceNumber": "004"
        }
    ],
    "uuid": "qas220517x-49eb-47664-b94rhd1-e52e2re13001"
}

Responses

Successfully staged ACH file data into ACH Origination API.

NAME	TYPE	DESCRIPTION
uuidoptional	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusoptional	string	The overall status of the addenda request can be accepted or rejected.
traceNumberoptional	string	The unique number for the ACH transaction. Record this number for possible ACH inquiry requests.
informationMessagesoptional	array	detailMessage
errorMessagesoptional	array	detailMessage
addendaoptional	array	addendaResponse
requestAcceptedUTCTimeoptional	string	The date and time the request was accepted in UTC time. Format: YYYY-MM-DDTHH:MM:SSZ

Response example (200)

{
    "uuid": "qas220517x-49eb-47664-b94rhd1-e52e2re13001",
    "status": "accepted",
    "traceNumber": "41001030008011",
    "informationMessages": [
        {
            "code": "1002040-50II",
            "moreInfo": "All addenda have been received."
        }
    ],
    "errorMessages": [],
    "addenda": [
        {
            "status": "accepted",
            "errorMessages": [],
            "informationMessages": []
        }
    ],
    "requestAcceptedUTCTime": "2022-05-25T16:33:46Z"
}

Missing mandatory information

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "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": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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

healthResponse

NAME	TYPE	DESCRIPTION
Statusoptional	string	The status of the health check response.
Sourceoptional	string	The origin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved.
Timestampoptional	string	The date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIpoptional	string	The client IP address the gateway receives from the request.
X-Forwarded-Foroptional	string	The sequence of the IP addresses for systems between the client and the gateway.

exception

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	Error message related to system generating this error.
TransactionIdoptional	string	Unique functional identifier from the data to identify a message.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

connectError

NAME	TYPE	DESCRIPTION
ConnectErroroptional	string	Error information of the connectivity with downstream service.

acceptedAddendaResponseEnvelope

NAME	TYPE	DESCRIPTION
uuidoptional	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusoptional	string	The overall status of the addenda request can be accepted or rejected.
traceNumberoptional	string	The unique number for the ACH transaction. Record this number for possible ACH inquiry requests.
informationMessagesoptional	array	detailMessage
errorMessagesoptional	array	detailMessage
addendaoptional	array	addendaResponse
requestAcceptedUTCTimeoptional	string	The date and time the request was accepted in UTC time. Format: YYYY-MM-DDTHH:MM:SSZ

acceptedBatchResponseAcceptedDetailResponse

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusrequired	string	The status of the batch can be accepted or rejected.
requestAcceptedUTCTimeoptional	string	The date and time the request was accepted in UTC time. Format: YYYY-MM-DDTHH:MM:SSZ
effectiveDateoptional	string	The date the transaction is posted. This date must be within 31 days of the current date. Format: YYMMDD
informationMessagesoptional	array	detailMessage
errorMessagesoptional	array	detailMessage
detailsoptional	array	acceptedDetailResponse

acceptedDetailResponse

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusoptional	string	The overall status of the addenda can be accepted or rejected.
errorMessagesoptional	array	detailMessage
informationMessagesoptional	array	detailMessage
traceNumberoptional	string	The unique number for the ACH transaction. Record this number for possible ACH inquiry requests.
requestAcceptedUTCTimeoptional	string	The date and time the request was accepted in UTC time. Format: YYYY-MM-DDTHH:MM:SSZ

addendaRequest

NAME	TYPE	DESCRIPTION
paymentRelatedInformationrequired	string	The related payment information for the addenda records. The limit is 80 characters.
addendaSequenceNumberrequired	string	The sequence number of the addenda. The number cannot exceed 4 digits.

addendaRequestEnvelope

NAME	TYPE	DESCRIPTION
addendarequired	array	addendaRequest
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.

addendaResponse

NAME	TYPE	DESCRIPTION
statusoptional	string	The overall status of the addenda request can be accepted or rejected.
errorMessagesoptional	array	detailMessage
informationMessagesoptional	array	detailMessage

addendaStatusRequestEnvelope

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
pageSizeoptional	string	The number of records to be returned in the pagination search.
startAddendaSequenceNumberoptional	string	The starting number for the addenda record sequence.

addendaStatusResponseEnvelope

NAME	TYPE	DESCRIPTION
uuidoptional	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusoptional	string	The status of the batch can be accepted or rejected.
errorMessagesoptional	array	detailMessage
traceNumberoptional	string	The unique number for the ACH transaction. Record this number for possible ACH inquiry requests.
informationMessagesoptional	array	detailMessage
addendaoptional	array	baseAddendaDetailResponse

baseAddendaDetailResponse

NAME	TYPE	DESCRIPTION
addendaTypeCodeoptional	string	The type code for the addenda. The value is '05'.
addendaSequenceNumberoptional	string	The sequence number of the addenda. The number cannot exceed 4 digits.
paymentRelatedInformationoptional	string	The related payment information from the addenda records. The maximum character limit is 80.

baseAddendaRequest

NAME	TYPE	DESCRIPTION
paymentRelatedInformationrequired	string	The related payment information for the addenda records. The limit is 80 characters.

baseDetailResponse

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusoptional	string	The status of a batch record can be accepted or rejected. The status of a detailed record can be deleted, accepted, rejected, notFound, or waitingForAddenda.
errorMessagesoptional	array	detailMessage
informationMessagesoptional	array	detailMessage
traceNumberoptional	string	The unique number for the ACH transaction. Record this number for possible ACH inquiry requests.

batchRequestCCDDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
pointrequired	string	A short name specific to your company provided by KeyBank. This is included in the file name and improves security for file transfers.
collectionApplicationIdrequired	string	This ID is provided by KeyBank and cannot exceed the maximum of 9 alphanumeric characters.
collectionApplicationTypeoptional	string	A subset of the collection application parameters. This is not commonly used and by default, left blank. If there is a collection application type, the value is provided by KeyBank during onboarding and cannot exceed 6 characters.
secCoderequired	string	The three-digit Standard Entry Class code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEB.
effectiveDateoptional	string	The date the transaction is posted. This date must be within 31 days of the current date. Format: YYMMDD
companyDescriptiveDateoptional	string	Company descriptive date. Format: YYMMDD
companyEntryDescriptionrequired	string	Provides the receiver a description of the payment purpose. The value cannot exceed 10 characters and cannot be blank. Possible values: 'REVERSAL', 'RETURN FEE', 'RECLAIM', 'REDEPCHECK' for RCK entries, 'HCCLAIMPMT' for Health Care EFTs, or 'ACCTVERIFY' for clients sending in a micro-entry as a type of ACH entry.
detailsoptional	array	cCDDetailRequest

batchRequestCTXDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
pointrequired	string	A short name specific to your company provided by KeyBank. This is included in the file name and improves security for file transfers.
collectionApplicationIdrequired	string	This ID is provided by KeyBank and cannot exceed the maximum of 9 alphanumeric characters.
collectionApplicationTypeoptional	string	A subset of the collection application parameters. This is not commonly used and by default, left blank. If there is a collection application type, the value is provided by KeyBank during onboarding and cannot exceed 6 characters.
secCoderequired	string	The three-digit Standard Entry Class code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEB.
effectiveDateoptional	string	The date the transaction is posted. This date must be within 31 days of the current date. Format: YYMMDD
companyDescriptiveDateoptional	string	Company descriptive date. Format: YYMMDD
companyEntryDescriptionrequired	string	Provides the receiver a description of the payment purpose. The value cannot exceed 10 characters and cannot be blank. Possible values: 'REVERSAL', 'RETURN FEE', 'RECLAIM', 'REDEPCHECK' for RCK entries, 'HCCLAIMPMT' for Health Care EFTs, or 'ACCTVERIFY' for clients sending in a micro-entry as a type of ACH entry.
detailsoptional	array	cTXDetailRequest

batchRequestEnvelopeBatchRequestCCDDetailRequest

NAME	TYPE	DESCRIPTION
batchrequired	Object	batchRequestCCDDetailRequest
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

batchRequestEnvelopeBatchRequestCTXDetailRequest

NAME	TYPE	DESCRIPTION
batchrequired	Object	batchRequestCTXDetailRequest
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

batchRequestEnvelopeBatchRequestPPDDetailRequest

NAME	TYPE	DESCRIPTION
batchrequired	Object	batchRequestPPDDetailRequest
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

batchRequestEnvelopeBatchRequestTELDetailRequest

NAME	TYPE	DESCRIPTION
batchrequired	Object	batchRequestTELDetailRequest
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

batchRequestEnvelopeBatchRequestWEBDetailRequest

NAME	TYPE	DESCRIPTION
batchrequired	Object	batchRequestWEBDetailRequest
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

batchRequestPPDDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
pointrequired	string	A short name specific to your company provided by KeyBank. This is included in the file name and improves security for file transfers.
collectionApplicationIdrequired	string	This ID is provided by KeyBank and cannot exceed the maximum of 9 alphanumeric characters.
collectionApplicationTypeoptional	string	A subset of the collection application parameters. This is not commonly used and by default, left blank. If there is a collection application type, the value is provided by KeyBank during onboarding and cannot exceed 6 characters.
secCoderequired	string	The three-digit Standard Entry Class code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEB.
effectiveDateoptional	string	The date the transaction is posted. This date must be within 31 days of the current date. Format: YYMMDD
companyDescriptiveDateoptional	string	Company descriptive date. Format: YYMMDD
companyEntryDescriptionrequired	string	Provides the receiver a description of the payment purpose. The value cannot exceed 10 characters and cannot be blank. Possible values: 'REVERSAL', 'RETURN FEE', 'RECLAIM', 'REDEPCHECK' for RCK entries, 'HCCLAIMPMT' for Health Care EFTs, or 'ACCTVERIFY' for clients sending in a micro-entry as a type of ACH entry.
detailsoptional	array	pPDDetailRequest

batchRequestTELDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
pointrequired	string	A short name specific to your company provided by KeyBank. This is included in the file name and improves security for file transfers.
collectionApplicationIdrequired	string	This ID is provided by KeyBank and cannot exceed the maximum of 9 alphanumeric characters.
collectionApplicationTypeoptional	string	A subset of the collection application parameters. This is not commonly used and by default, left blank. If there is a collection application type, the value is provided by KeyBank during onboarding and cannot exceed 6 characters.
secCoderequired	string	Standard Entry Class Code. Length must be exactly 3 alphabetical characters and adhere to Nacha rules.
effectiveDateoptional	string	The date the transaction is posted. This date must be within 31 days of the current date. Format: YYMMDD
companyDescriptiveDateoptional	string	Company descriptive date. Format: YYMMDD
companyEntryDescriptionrequired	string	Provides the receiver a description of the payment purpose. The value cannot exceed 10 characters and cannot be blank. Possible values: 'REVERSAL', 'RETURN FEE', 'RECLAIM', 'REDEPCHECK' for RCK entries, 'HCCLAIMPMT' for Health Care EFTs, or 'ACCTVERIFY' for clients sending in a micro-entry as a type of ACH entry.
detailsoptional	array	telDetailRequest

batchRequestWEBDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
pointrequired	string	A short name specific to your company provided by KeyBank. This is included in the file name and improves security for file transfers.
collectionApplicationIdrequired	string	This ID is provided by KeyBank and cannot exceed the maximum of 9 alphanumeric characters.
collectionApplicationTypeoptional	string	A subset of the collection application parameters. This is not commonly used and by default, left blank. If there is a collection application type, the value is provided by KeyBank during onboarding and cannot exceed 6 characters.
secCoderequired	string	The three-digit Standard Entry Class code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEB.
effectiveDateoptional	string	The date the transaction is posted. This date must be within 31 days of the current date. Format: YYMMDD
companyDescriptiveDateoptional	string	Company descriptive date. Format: YYMMDD
companyEntryDescriptionrequired	string	Provides the receiver a description of the payment purpose. The value cannot exceed 10 characters and cannot be blank. Possible values: 'REVERSAL', 'RETURN FEE', 'RECLAIM', 'REDEPCHECK' for RCK entries, 'HCCLAIMPMT' for Health Care EFTs, or 'ACCTVERIFY' for clients sending in a micro-entry as a type of ACH entry.
detailsoptional	array	webDetailRequest

batchResponseEnvelopeAccepted

NAME	TYPE	DESCRIPTION
batchrequired	Object	acceptedBatchResponseAcceptedDetailResponse

cCDDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
accountTyperequired	string	The account type can be checking (C) or savings (S). Valid values: C, S.
creditDebitCoderequired	string	One-character field indicates if the ACH transaction is a credit (C) or debit (D). Valid values: C, D.
transactionTyperequired	string	Nacha-defined transaction types can be live (L), prenote (P), or zero (Z). Valid values: L, P, Z.
receivingDFIIdrequired	string	The bank routing number (ABA number) of the receiving designated financial institution. The number can be a maximum of 8 digits.
checkDigitrequired	string	The final character of a routing number that can be used to validate a specific routing number. This is a single digit.
DFIAccountNumberrequired	string	The recipient account number at the designated financial institution. The account number can be a maximum of 17 characters.
amountrequired	string	The transaction amount in valid currency format. The amount can have up to 8 digits before the decimal and 2 digits after the decimal.
identificationNumberoptional	string	Identification number for the detail record. The number cannot exceed 15 characters.
receivingCompanyNamerequired	string	The name of the receiving company. The name cannot exceed a maximum of 22 characters.
discretionaryDataoptional	string	Further identification of the company or used to describe the type of entries being processed. The ID can be a maximum of 2 characters.
addendaoptional	array	baseAddendaRequest

cTXDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
accountTyperequired	string	The account type can be checking (C) or savings (S). Valid values: C, S.
creditDebitCoderequired	string	One-character field indicates if the ACH transaction is a credit (C) or debit (D). Valid values: C, D
transactionTyperequired	string	Nacha-defined transaction types can be live (L), prenote (P), or zero (Z). Valid values: L, P, Z
receivingDFIIdrequired	string	The bank routing number (ABA number) of the receiving designated financial institution. The number can be a maximum of 8 digits.
checkDigitrequired	string	The final character of a routing number that can be used to validate a specific routing number. This is a single digit.
DFIAccountNumberrequired	string	The recipient account number at the designated financial institution. The account number can be a maximum of 17 characters.
totalAmountrequired	string	The total amount of the transactions in valid currency format. The amount can have up to 8 digits before the decimal and 2 digits after the decimal.
identificationNumberoptional	string	Identification number for the detail record. The number cannot exceed 15 characters.
numberOfAddendaRecordsrequired	string	Count of addenda records. This cannot exceed 4 digits.
receivingCompanyNameIDNumberrequired	string	The name and ID of the receiving company. This field cannot exceed 16 characters.
discretionaryDataoptional	string	Further identification of the company or used to describe the type of entries being processed. The ID can be a maximum of 2 characters.
addendaoptional	array	baseAddendaRequest

detailMessage

NAME	TYPE	DESCRIPTION
codeoptional	string	A static status code assigned by the network or payment system.
moreInfooptional	string	Detailed descriptive message.

detailStatusRequestEnvelopePaymentInquiryDetailRequest

NAME	TYPE	DESCRIPTION
detailStatusoptional	array	paymentInquiryDetailRequest

detailStatusResponse

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusoptional	string	The status of the batch tells if data is valid, contains errors, or has been received by the ACH core processing system. Valid values: accepted, rejected, extracted
errorMessagesoptional	array	detailMessage
informationMessagesoptional	array	detailMessage
traceNumberoptional	string	The unique number for the ACH transaction. Record this number for possible ACH inquiry requests.
requestAcceptedUTCTimeoptional	string	The date and time the request was accepted in UTC time. Format: YYYY-MM-DDTHH:MM:SSZ
requestDeletedUTCTimeoptional	string	The date and time the request was deleted in UTC time. Format: YYYY-MM-DDTHH:MM:SSZ
requestLastUpdatedUTCTimeoptional	string	The date and time the request was updated in UTC time. Format: YYYY-MM-DDTHH:MM:SSZ
pointoptional	string	A short name specific to your company provided by KeyBank. This is included in the file name and improves security for file transfers.
collectionApplicationIdoptional	string	This ID is provided by KeyBank and cannot exceed the maximum of 9 alphanumeric characters.
collectionApplicationTypeoptional	string	A subset of the collection application parameters. This is not commonly used and by default, left blank. If there is a collection application type, the value is provided by KeyBank during onboarding and cannot exceed 6 characters.
secCodeoptional	string	The three-digit Standard Entry Class code based on Nacha rules. Valid values: CCD, CTX, IAT, PPD, TEL, WEB.
effectiveDateoptional	string	The date the transaction is posted. This date must be within 31 days of the current date. Format: YYMMDD
companyDescriptiveDateoptional	string	Company descriptive date. Format: YYMMDD
batchNumberoptional	string	The number associated with the batch. It can be a maximum of 7 digits.
companyNameoptional	string	The name of the corporation or institution making the request. The name cannot exceed 16 characters or have spaces.
companyDiscretionaryDataoptional	string	Discretionary data for the company.
companyIdentificationoptional	string	The identification number of the company. This cannot exceed 15 digits.
companyEntryDescriptionoptional	string	Provides the receiver a description of the payment purpose. The value cannot exceed 10 characters and cannot be blank. Possible values: 'REVERSAL', 'RETURN FEE', 'RECLAIM', 'REDEPCHECK' for RCK entries, 'HCCLAIMPMT' for Health Care EFTs, or 'ACCTVERIFY' for clients sending in a micro-entry as a type of ACH entry.
originatingDFIIdoptional	string	The bank routing number (ABA number) of the originating designated financial institution. The number can be a maximum of 8 digits.
accountTypeoptional	string	The account type can be checking (C) or savings (S). Valid values: C, S.
creditDebitCodeoptional	string	One-character field indicates if the ACH transaction is a credit (C) or debit (D). Valid values: C, D.
transactionTypeoptional	string	Nacha-defined transaction types can be live (L), prenote (P), or zero (Z). Valid values: L, P, Z
transactionCodeoptional	string	A two-character field that specifies the billing credit transaction code.
receivingDFIIdoptional	string	The bank routing number (ABA number) of the receiving designated financial institution. The number can be a maximum of 8 digits.
checkDigitoptional	string	The final character of a routing number that can be used to validate a specific routing number. This is a single digit.
dfiAccountNumberoptional	string	The recipient account number at the recipient's bank.
amountoptional	string	The transaction amount in valid currency format. The amount can have up to 8 digits before the decimal and 2 digits after the decimal.
identificationNumberoptional	string	Identification number for the detail record. The number cannot exceed 15 characters.
receivingCompanyNameoptional	string	The name of the receiving company. The name cannot exceed a maximum of 22 characters.
discretionaryDataoptional	string	Further identification of the company or used to describe the type of entries being processed. The ID cannot exceed the maximum of 20 characters.
totalAmountoptional	string	The total amount of the transactions in valid currency format. The amount can have up to 8 digits before the decimal and 2 digits after the decimal.
receivingCompanyNameIDNumberoptional	string	The name and ID of the receiving company. This field cannot exceed 16 characters.
individualIdentificationNumberoptional	string	The ID number for the individual. This cannot exceed 15 characters.
individualNameoptional	string	The name of the individual. This cannot exceed 22 characters.
paymentTypeCodeoptional	string	The code is a maximum of four characters. This field returns two empty spaces if the code is not provided by the client.
numberOfAddendaRecordsoptional	string	Count of addenda records. This cannot exceed 4 digits.
numberOfAddendaReceivedoptional	string	Count of addenda records received.
addendaoptional	array	baseAddendaDetailResponse
fileCreationDateoptional	string	The date the file was created. Format: YYMMDD
fileCreationTimeoptional	string	The time the file was created.
fileIdModifieroptional	string	The file ID modifier to control the totals with a single alphanumeric value.

detailStatusResponseEnvelopeDetailStatusResponse

NAME	TYPE	DESCRIPTION
detailsoptional	array	detailStatusResponse

detailUndoRequestEnvelope

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.

pPDDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
accountTyperequired	string	The account type can be checking (C) or savings (S). Valid values: C, S.
creditDebitCoderequired	string	One-character field indicates if the ACH transaction is a credit (C) or debit (D). Valid values: C, D.
transactionTyperequired	string	Nacha-defined transaction types can be live (L), prenote (P), or zero (Z). Valid values: L, P, Z.
receivingDFIIdrequired	string	The bank routing number (ABA number) of the receiving designated financial institution. The number can be a maximum of 8 digits.
checkDigitrequired	string	The final character of a routing number that can be used to validate a specific routing number. This is a single digit.
DFIAccountNumberrequired	string	The recipient account number at the designated financial institution. The account number can be a maximum of 17 characters.
amountrequired	string	The transaction amount in valid currency format. The amount can have up to 8 digits before the decimal and 2 digits after the decimal.
individualNamerequired	string	The name of the individual. This cannot exceed 22 characters.
individualIdentificationNumberoptional	string	The ID number for the individual. This cannot exceed 15 characters.
discretionaryDataoptional	string	Further identification of the company or used to describe the type of entries being processed. The ID can be a maximum of 2 characters.
addendaoptional	array	baseAddendaRequest

paymentInquiryDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.

telDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
accountTyperequired	string	The account type can be checking (C) or savings (S). Valid values: C, S.
creditDebitCoderequired	string	One-character field indicates if the ACH transaction is a credit (C) or debit (D). Valid values: C, D.
transactionTyperequired	string	Nacha-defined transaction types can be live (L), prenote (P), or zero (Z). Valid values: L, P, Z.
receivingDFIIdrequired	string	The bank routing number (ABA number) of the receiving designated financial institution. The number can be a maximum of 8 digits.
checkDigitrequired	string	The final character of a routing number that can be used to validate a specific routing number. This is a single digit.
DFIAccountNumberrequired	string	The recipient account number at the designated financial institution. The account number can be a maximum of 17 characters.
amountrequired	string	The transaction amount in valid currency format. The amount can have up to 8 digits before the decimal and 2 digits after the decimal.
individualIdentificationNumberoptional	string	The ID number for the individual. This cannot exceed 15 characters.
individualNamerequired	string	The name of the individual. This cannot exceed 22 characters.
paymentTypeCodeoptional	string	The code is a maximum of two characters. The code is two empty spaces if the code is not provided by the client.

webDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
accountTyperequired	string	The account type can be checking (C) or savings (S). Valid values: C, S
creditDebitCoderequired	string	One-character field indicates if the ACH transaction is a credit (C) or debit (D). Valid values: C, D
transactionTyperequired	string	Nacha-defined transaction types can be live (L), prenote (P), or zero (Z). Valid values: L, P, Z
receivingDFIIdrequired	string	The bank routing number (ABA number) of the receiving designated financial institution. The number can be a maximum of 8 digits.
checkDigitrequired	string	The final character of a routing number that can be used to validate a specific routing number. This is a single digit.
DFIAccountNumberrequired	string	The recipient account number at the designated financial institution. The account number can be a maximum of 17 characters.
amountrequired	string	The transaction amount in valid currency format. The amount can have up to 8 digits before the decimal and 2 digits after the decimal.
individualIdentificationNumberoptional	string	The ID number for the individual. This cannot exceed 15 characters.
individualNamerequired	string	The name of the individual. This cannot exceed 22 characters.
paymentTypeCodeoptional	string	The code is a maximum of two characters. The code is two empty spaces if the code is not provided by the client.
addendaoptional	array	baseAddendaRequest

Errors

For more information about errors, see Error handling.

Changelog

Release	API version	Change description	Impact
October 2024	1.3.2	Updated `companyEntryDescription` to include possible values like 'REVERSAL', 'RETURN FEE', 'RECLAIM', 'REDEPCHECK' for RCK entries, and 'HCCLAIMPMT' for health care EFTs, or 'ACCTVERIFY' for clients sending in micro-entry as a type of ACH entry.	LOW
May 2024	1.3.1	Changed the `effectiveDate` range for ACH payments from 90 days to 31 days. `X-CorrelationId` has been removed as a request header field for all endpoints. The parameter is no longer in the request body, but still remains in the code. The system assigns a unique ID when you submit a request and returns the value in the response.	MID
April 2024	1.3.0	Removed `X-Point` from all endpoints. This is an internal field and is not required for API requests.	LOW
September 2023	1.2.0	Added `customData` field to each of the SEC payment endpoints. You can enter up to 500 alphanumeric characters that will stay with the transaction through its lifecycle. Removed unused objects: `batchResponseEnvelopeRejected` `successSearchResponseNotificationEventResponse` `successResponseString` `successMetaResponse` `sortControl` `notifcationEventResponse` `messageResponse` `baseDataObject` `rejectedBatchResponseBaseDetailResponse` The `traceNumber` was updated to remove a reference to an internal database table, TBDACHDETAIL. `DFIAccountNumber` was updated to clarify that this is the recipient account number at the recipient’s bank. `receivingDFIID` was updated to clarify that this is the ABA of the recipient’s bank.	MID
May 2023	1.1.6	Added the require `companyEntryDescription` for each of the SEC payment endpoints. ACH requests will no longer have a default description. You can set the description for each transaction. This field returns in the ACH status response payload.	MID
December 2022	1.1.5	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

Account Validation

4-minute read 2.0.1 | updated Oct. 15, 2024

Validate an account and its owner with confidence

Account Validation v2 API Endpoints

Summary	Endpoint
Health check	get /accounts/validations/v2/healthCheck
Verify an account	post /accounts/validations/v2/verifyAccount

Before you begin

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

Overview

The Account Validation API evaluates account owner data through an inquiry request and response process, validating the account owner and their account for validity.

API maturity

Account Validation is growing up. Right now there are two operating versions of the Account Validation API with v2 being the most current and v1 about to deprecate. The latest version includes security and request schema enhancements to help deliver more meaningful responses. The first and original version of the Account Validation API will be obsolete by end of the first quarter in 2025. Until then, Account Validation v1 specifications are available here.

We recommend you use the latest version or upgrade to Account Validation API v2 specifications.

Make a request

When you submit a request to the Account Validation API, the data in that request is compared to information in the National Shared Database. The National Shared Database is the financial industry's leading source of up-to-date, collaborative financial data. Results from the database comparison are evaluated and then returns a response to you in real time, verifying the account owner status quickly.

Request requirements

When you submit a request, in addition to your authentication credentials, you must provide:

The account number of the person or business you want to validate. (accountNumber)
The routing number for the financial institution of the person or business. (routingNumber)
Set the validation type to Owner to request for owner status and validation. (serviceType)
An ID provided during KeyBank onboarding that is a secondary authentication method for the call besides the access token. This is not the same as your client or consumer ID. (secondaryId)

Interpret the response

Results from the database comparison are evaluated and then returns a response to you in real time, verifying the account owner status quickly. The following response rules apply for all fields:

All fields included in the request will be matched against the database.
Case, spacing, and punctuation are ignored.
The account data matched in the database is determined based on the account number (accountNumber) and routing number (routingNumber) in the request.
Account matching will be performed only if a request contains the person's full name (firstName and lastName) OR the name of the business (businessName).

Result codes

Account Validation responses include a variety of codes and classifications to help you assess if the account is legitimate or not. Refer to the Account Validation User Guide to help decipher codes like these:

errorCode: Three-digit code about system errors. If there are no errors, you receive three zeros (000).
conditionCode: Three-digit code about the state and validity of account ownership.
primaryStatusCode: Three-digit code for account status.
accountOwnerResponse object: Account owner field matching showing a Y (Yes), N (No), C (Conditional), or U (Unknown).

Loads of codes

If you get code with your error message, look at our error handling section for more details.

Health check

get /accounts/validations/v2/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]"
}

Verify an account

post /accounts/validations/v2/verifyAccount

Verify that an account owner's name, address, and other identifying elements match the account information in the National Shared Database Resource and that they are authorized to transact on the account. The National Shared Database Resource is the financial industry's leading source of up-to-date, collaborative financial data.

Request

BODY FIELD	TYPE	DESCRIPTION
accountValidationV2Requestrequired	Object	accountValidationV2Request

Request example

{
    "accountValidationV2Request": {
        "AOARequest": {
            "Inquiry": {
                "serviceType": "Owner",
                "secondaryId": "KeyCli03",
                "additionalId": "AddCli04",
                "routingNumber": "122199983",
                "accountNumber": "89455",
                "amount": "110",
                "serialNumber": "",
                "AcctOwner": {
                    "firstName": "Paul",
                    "lastName": "wilson",
                    "middleName": "Dan",
                    "namePrefix": "Mr",
                    "nameSuffix": "Lal",
                    "businessName": "",
                    "addressLine1": "206 GOODWIN ST",
                    "addressLine2": "Land",
                    "city": "MERRIT",
                    "state": "MI",
                    "zipCode": "49667",
                    "homePhone": "3077553623",
                    "workPhone": "3077555330",
                    "ssn": "666082367",
                    "dob": "19730801",
                    "idType": "2",
                    "idNo": "590909812",
                    "idState": "AL"
                },
                "Client": {
                    "clientDate": "2022-12-31",
                    "clientTime": "14:00:80",
                    "userDefined": ""
                }
            }
        }
    }
}

Responses

OK

NAME	TYPE	DESCRIPTION
accountValidationV2Responserequired	Object	accountValidationV2Response

Response example (200)

{
    "accountValidationV2Response": {
        "AOAResponse": {
            "Result": {
                "errorCode": "000",
                "systemRecordId": "8168140724120284",
                "primaryId": "TROM122101",
                "secondaryId": "KeyCli01",
                "routingNumber": "122199983",
                "accountNumber": "89455",
                "feeAttrib": "HH",
                "AcctOwner": {
                    "conditionCode": "000",
                    "addressMatch": "Y",
                    "cityMatch": "Y",
                    "stateMatch": "Y",
                    "zipCodeMatch": "Y",
                    "ssnMatch": "Y",
                    "overallMatchScore": "100"
                },
                "AcctStatus": {
                    "primaryStatusCode": "099",
                    "primMessage": "Open Valid"
                },
                "Client": {
                    "clientDate": "2022-12-31",
                    "clientTime": "14:00:80",
                    "userDefined": ""
                }
            }
        },
        "errorResponse": {
            "businessFault": {
                "errorDescription": "Text displays if there is an issue with the business applications."
            },
            "systemFault": {
                "errorDescription": "Text displays if there is an issue with backend systems."
            }
        }
    }
}

Missing mandatory information

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (400)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "abcgd133",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "AOAResponse": {
            "Result": {
                "errorCode": "104"
            }
        }
    }
}

Unauthorized request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (403)

{
    "ErrorMessage": "Access Denied for client ip",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (500)

{
    "ErrorMessage": "Runtime error occurred in the service, please check with application support team before resubmitting the request",
    "X-CorrelationId": "abcgd133",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend service",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend service",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process request

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend service",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "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

exception

NAME	TYPE	DESCRIPTION
ErrorMessageoptional	string	A human-readable message that describes the type or source of the error.
TransactionIdoptional	string	A unique transaction ID returned with the response, useful for traceability.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

connectError

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

serviceErrorData

NAME	TYPE	DESCRIPTION
errorCodeoptional	string	Three-digit error code. Returns a "000" when no errors are present.

accountValidationV2Request

NAME	TYPE	DESCRIPTION
AOARequestoptional	Object	AOARequest

Inquiry

NAME	TYPE	DESCRIPTION
serviceTyperequired	string	Represents the type of request made to the API. This value is case-sensitive and must be set to "Owner".
secondaryIdrequired	string	Secondary client ID provided by KeyBank. No special characters are allowed. This value is different from your client credentials.
additionalIdoptional	string	This ID is rarely used. If it is required, KeyBank will provide this value during onboarding.
routingNumberrequired	string	Nine-digit routing number for the account, including leading zeroes.
accountNumberrequired	string	Full bank account number, without separators or leading zeroes. The length and format depends on the bank. This field cannot exceed 17 characters.
amountoptional	string	Do not use. This field is deprecating in an upcoming version. Dollar amount of the transaction or this field can be zero-filled. The amount must be a whole number and cannot exceed 12 characters.
serialNumberoptional	string	Do not use. This field is deprecating in an upcoming version. Serial number of the check. This number does not apply for ACH inquiries.
AcctOwneroptional	Object	AcctOwner
Clientoptional	Object	Client

AOARequest

NAME	TYPE	DESCRIPTION
Inquiryoptional	Object	Inquiry

AOAResponse

NAME	TYPE	DESCRIPTION
Resultoptional	Object	Result

errorResponse

NAME	TYPE	DESCRIPTION
businessFaultoptional	Object	businessFault
systemFaultoptional	Object	systemFault

AcctOwner_1

NAME	TYPE	DESCRIPTION
conditionCodeoptional	string	Three-digit system response code that reflects the state of the account owner provided.
nameMatchoptional	string	First name, middle name, and last name match status. Valid values: Y, N, U
firstNameMatchoptional	string	First name match status. Valid values: Y, N, U
lastNameMatchoptional	string	Last name match status. Valid values: Y, N, U
middleNameMatchoptional	string	Middle name or initial match status. Valid values: Y, N, U
namePrefixMatchoptional	string	Name prefix match status. U will always be returned for a name prefix if included in the request.
nameSuffixMatchoptional	string	Name suffix match status. U will always be returned for a name suffix if included in the request.
businessNameMatchoptional	string	Business name match status. Valid values: Y, N, U
addressMatchoptional	string	Combined address line one and two match status. Valid values: Y, N, U
cityMatchoptional	string	City match status. Valid values: Y, N, U
stateMatchoptional	string	State match status. Valid values: Y, N, U
zipCodeMatchoptional	string	ZIP code match status. Valid values: Y, N, U
homePhoneMatchoptional	string	Home phone number match status. Valid values: Y, N, U
workPhoneMatchoptional	string	Work phone number match status. Valid values: Y, N, U
ssnMatchoptional	string	SSN/TIN or last four digits of SSN match status. If you are a merchant provider, the value returned will always be 'U'. Valid values: Y, N, U
dobMatchoptional	string	Date of birth match status. Valid values: Y, N, U
idTypeMatchoptional	string	ID type match status. Valid values: Y, N, U
idNoMatchoptional	string	ID number match status. Valid values: Y, N, U
idStateMatchoptional	string	State or place of issuance match status. Valid values: Y, N, U
overallMatchScoreoptional	string	The measure of how closely the inquiry request attributes match the actual account ownership data. This number is calculated based on the analysis of all information sent. Valid values: 0-100

Result

NAME	TYPE	DESCRIPTION
errorCodeoptional	string	Three-digit error code. Returns a "000" when no errors are present.
systemRecordIdoptional	string	Unique, system-generated transaction ID.
primaryIdoptional	string	Primary client ID returned via a KeyBank lookup. This is a KeyBank ID.
secondaryIdoptional	string	Secondary client ID provided in the original request.
additionalIdoptional	string	Additional client ID, if provided in the original request. This is rarely used.
routingNumberoptional	string	Nine-digit routing number for the account provided in the original request.
accountNumberoptional	string	Full bank account number provided in the original request.
feeAttriboptional	string	Two-character code that represents how a transaction took place. Currently, the only value reported is "HH", which represents an ACH transaction.
amountoptional	string	Do not use. This field is deprecating. Amount of the transaction, if provided in the original request.
AcctOwneroptional	Object	AcctOwner_1
AcctStatusoptional	Object	AcctStatus
Clientoptional	Object	Client_1

systemFault

NAME	TYPE	DESCRIPTION
errorDescriptionoptional	string	Descriptive error message that identifies if it is a system issue or business fault.

AcctStatus

NAME	TYPE	DESCRIPTION
primaryStatusCodeoptional	string	Primary three-digit account status code. This is an informational response code that represents the status of an account.
primMessageoptional	string	Message associated with the primary status code.

accountValidation_POST_bodyParameters

NAME	TYPE	DESCRIPTION
accountValidationV2Requestrequired	Object	accountValidationV2Request

businessFault

NAME	TYPE	DESCRIPTION
errorDescriptionoptional	string	Descriptive error message that identifies if it is a system issue or business fault.

Client

NAME	TYPE	DESCRIPTION
clientDateoptional	string	Client-provided date the inquiry request was made. Format: YYYY-MM-DD
clientTimeoptional	string	Client-provided time the inquiry request was made. Format: HH:MM:SS
userDefinedoptional	string	Client-provided descriptive text about the inquiry request. This field cannot exceed 255 characters.

accountValidation_POST_response

NAME	TYPE	DESCRIPTION
accountValidationV2Responserequired	Object	accountValidationV2Response

accountValidationV2Response

NAME	TYPE	DESCRIPTION
AOAResponseoptional	Object	AOAResponse
errorResponserequired	Object	errorResponse

Client_1

NAME	TYPE	DESCRIPTION
clientDateoptional	string	Client-provided date the inquiry request was made. Format: YYYY-MM-DD
clientTimeoptional	string	Client-provided time the inquiry request was made. Format: HH:MM:SS
userDefinedoptional	string	Client-provided descriptive text about the inquiry request. This field cannot exceed 255 characters.

AcctOwner

NAME	TYPE	DESCRIPTION
firstNameoptional	string	First name of the account owner. Required with lastName for a personal inquiry.
lastNameoptional	string	Last name of the account owner. Required with firstName for a personal inquiry.
middleNameoptional	string	Middle initial or name of the account owner. If the middle initial is provided do not include a period.
namePrefixoptional	string	Optional name prefix of the account owner. This field cannot exceed four characters. Example: Dr., Mr., Mrs.
nameSuffixoptional	string	Optional name suffix of the account owner. This field cannot exceed four characters. Example: Jr., PhD
businessNameoptional	string	Business name or the individual's full name (first and last name) that owns the account. This is a required field for a business inquiry.
addressLine1optional	string	First line of the address on the account. This field cannot exceed 40 characters.
addressLine2optional	string	Second line of the address on the account.
cityoptional	string	City on the account.
stateoptional	string	Two-character state abbreviation on the account.
zipCodeoptional	string	ZIP code on the account. This can either be five digits or nine digits. If a nine-digit ZIP code is provided, a dash between the groups of digits is acceptable. Do not use a space. Possible examples: 52255, 522551313, or 52255-1313.
homePhoneoptional	string	10-digit home phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
workPhoneoptional	string	10-digit work phone number on the account. Do not add dashes, parenthesis, or any other non-numeric value.
ssnoptional	string	Full social security/tax ID number or the last four digits of the social security number of the account owner.
doboptional	string	Date of birth for the individual on the account. Format: YYYYMMDD
idTypeoptional	string	One-character code that represents the type of identification used to verify the account owner. Valid values: 0-9, A-Z
idNooptional	string	ID number for the account owner's form of identification. This field cannot exceed 28 characters.
idStateoptional	string	Two-character state of issuance for the account owner's form of identification. If not a US state, enter the place of issuance. This field must be between 2-6 characters in length.

Errors

For more information about errors, see Error handling.

System error codes

When a problem occurs with the capture of the account information from a draftable account item or the evaluation of the request message fields, a 3-digit error code is provided in the response payload (errorCode). If no errors are present, this field is filled with three zeroes.

ERROR CODE	DESCRIPTION
000	Normal response - no errors
001	Invalid routing number
003	Invalid account number
005	Invalid serial number
006	Missing a required field
008	Length of account number is incorrect
010	Inquiry field length too short
011	Inquiry field length too long
013	Invalid amount field
103	Client ID does not match
104	Improper data type or value
105	Bad layout or format
106	Missing client record ID
107	Invalid required format
997	Authorization unavailable
998	System failure
999	Timeout

Changelog

Release	API version	Change description	Impact
October 2024	2.0.1	For the `amount` field, the whole dollar amount is an acceptable value (no cents). Note, this field will be deprecating in the future. Updated the `businessName` field and any supporting content to specify that you can use an individual's full name for a business account inquiry. Added format and field description details to help define the meaning, use, and limitations of the field.	MID
August 2024	2.0.0	We introduced the Account Validation API v2. This API executes the same objective as its predecessor, but now with a sleeker search criteria that condenses the code base to improve performance. Account Validation V1 is deprecating. The first and original version of the Account Validation API will be obsolete by end of the first quarter in 2025. Account Validation v1 specifications are available here.	MID
May 2024	1.0.3	`X-CorrelationId` has been removed as a request header field for all endpoints. The parameter is no longer in the request body, but still remains in the code. The system assigns a unique ID when you submit a request and returns the value in the response.	LOW
May 2023	1.0.2	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

Subscribe to