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, real estate transactions, or international transfers.
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.
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 Origination API. 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.
Before you begin
All KeyBank APIs require certificates, user credentials, and certain permissions. Before you begin, see Key concepts to learn more about these fundamental elements as well as other recommended best practices.
API-specific requirements
KeyBank client ID
The KeyBank client ID is a 32-character string that identifies you as the client. The KeyClientId
value is provided by KeyBank during the onboarding process. This is required for all requests.
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. |
Custom data
Custom data in APIs provides the ability to send or receive data that is specific to your application or use case. The custom data feature is available when you send or validate a payment. Define the custom data in the request payload. It is a free-form text field that can contain up to 500 alphanumeric characters that you can use however you like - for invoice number, product number, customer number, date/time stamp, etc. KeyBank recommends the common custom data format of name:value pairs. You can list multiple name:value pairs in the custom data field within the 500-character limit. The custom data fields will return exactly what is sent; it does not parse name:value pairs within the API response. The custom data should not contain any personal identifiable information (PII).
Custom data examples
//Example of name:value pairs customData: Type:DD; Status:Submitted; POnumber:12556 //Example of regular text customData: General products //Example of timestamp customData: 05-MAR-2023:12:19:53EST
Custom data is only available within the API product suite, meaning Wire Origination and Wire Inquiry APIs. Custom data is not transmitted with the payment and is not visible to the recipient or any of the participating parties. The custom data is only visible and accessible from the originator with our Wire Inquiry API, where you can query wire transfers using the transactionId
to retrieve the custom data. The customData
field returns any custom values that were part of the payment request stored for recall after a successful wire transaction completes. If no custom data is defined, the response returns an empty field.
It may be best to first call with the normal request payload to determine how to best use the custom data field. Review the response and determine which values are best to include and use in future queries.
Wire Origination API Endpoints
Summary | Endpoint |
---|---|
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 |
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 |
---|---|---|
Acceptrequired | string | Acceptable media types for the response. Valid values: application/json, application/xml |
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all systems involved, useful for system logging and identification. |
KeyClientIdoptional | string | KeyClientId is provided by KeyBank. This is a 32-character string that identifies you as the client. |
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 'X-CorrelationId: test987654' --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 |
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
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": "Please make sure your request is correct and try again.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "US21052400000000", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "status": "FAILED", "requestReference": "RR-220818-01", "sendersReference": "SR-220818-01", "valueDate": 1586563200, "error": { "code": "KEY-1006", "title": "Required field missing", "description": "Object creditPartyBank is required", "detail": { "code": "KEY-1006", "title": "Required field missing", "description": "Object creditPartyBank is required" } } } }
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. |
TransactionTimeoptional | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (401)

{ "ErrorMessage": "Please make sure you're using the correct credentials. Then log in again.", "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", "requestReference": "REQUEST-REF-220314.1", "sendersReference": "SENDER-REF-220314.1", "valueDate": 1615766400, "error": { "code": "KEY-0006", "title": "Not authorized for requested service", "description": "Additional information.", "detail": { "code": "KEY-0006", "title": "Not authorized for requested service", "description": "Additional information." } } } }
Access denied
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" }
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": "We can't seem to find what you're looking for. Please verify the resource and try again.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Request method denied
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": "Looks like something went wrong. Please check your request method and try again.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Media type not supported
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": "We currently don't support that format. Please check the format type defined in your request and try again. ", "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
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": "Looks like you've sent too many requests. Please wait a moment and try again later.", "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": "Looks like something went wrong. Please try again when you're ready.", "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-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": "Looks like something went wrong. Submit your request 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": "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.
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 |
---|---|---|
Acceptrequired | string | Acceptable media types for the response. Valid values: application/json, application/xml |
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all systems involved, useful for system logging and identification. |
KeyClientIdoptional | string | KeyClientId is provided by KeyBank. This is a 32-character string that identifies you as the client. |
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 'X-CorrelationId: test6543' --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 |
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
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-621075741872460927", "requestReference": "RR-220818-01", "sendersReference": "SR-220818-01", "valueDate": 1654819200, "error": { "code": "KEY-1006", "title": "Unknown error", "description": "Object creditPartyBank is required", "detail": { "code": "KEY-1006", "title": "Unknown error", "description": "Additional information about error code." } }, "doddFrank": "NO" } }
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. |
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", "requestReference": "REQUEST-REF-220314.1", "sendersReference": "SENDER-REF-220314.1", "valueDate": 1664928000, "error": { "code": "KEY-0006", "title": "Not authorized for requested service", "description": "Additional information here.", "detail": { "code": "KEY-0006", "title": "Not authorized for requested service", "description": "Additional information here." } }, "doddFrank": "NO" } }
Access denied
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" }
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": "We can't seem to find what you're looking for. Please verify the resource and try again.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Request method denied
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": "Looks like something went wrong. Please check your request method and try again.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Media type not supported
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": "We currently don't support that format. Please check the format type defined in your request and try again. ", "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
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": "Looks like you've sent too many requests. Please wait a moment and try again later.", "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": "Looks like something went wrong. Please try again when you're ready.", "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-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": "Looks like something went wrong. Submit your request 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": "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." } }
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 |
---|---|---|
Acceptrequired | string | Acceptable media types for the response. Valid values: application/json, application/xml |
Content-Typerequired | string | Defines the content type of the API. Common content types are application/json or application/x-www-form-urlencoded. |
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all systems involved, useful for system logging and identification. |
KeyClientIdrequired | string | KeyClientId is provided by KeyBank. This is a 32-character string that identifies you as the client. |
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 |
requestReferenceoptional | string | A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters. |
typerequired | string | Indicate if the transaction type is a PAYMENT or a DRAFT. |
requestedValueDateoptional | 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. |
ultimateDebitPartyoptional | Object | ultParty |
debitPartyoptional | Object | party |
debitPartyBankoptional | Object | party |
creditPartyBankoptional | Object | party |
creditPartyoptional | Object | party |
transferAmountrequired | number | Amount of money to transfer in the correct currency format. |
transferCurrencyrequired | string | Currency code for the transfer amount. |
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 |
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
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": "Please make sure your request is correct and try again.", "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.", "detail": { "code": "KEY-1006", "title": "Required field missing", "description": "The object creditPartyBank is required in the request." } } } }
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. |
TransactionTimeoptional | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (401)

{ "ErrorMessage": "Please make sure you're using the correct credentials. Then log in again.", "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4", "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.", "detail": { "code": "KEY-1001", "title": "No access", "description": "Additional information about error code." } }, "doddFrank": "NO" } }
Access denied
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": "You don't have access to this resource. Contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
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": "We can't seem to find what you're looking for. Please verify the resource and try again.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Request method denied
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": "Looks like something went wrong. Please check your request method and try again.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Media type not supported
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": "We currently don't support that format. Please check the format type defined in your request and try again. ", "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
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": "Looks like you've sent too many requests. Please wait a moment and try again later.", "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": "Looks like something went wrong. Please try again when you're ready. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.", "TransactionId": "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-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": "Looks like something went wrong. Please try again when you're ready. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "A connectivity error occurred with the downstream service (unexpected end of file at the target). Please check with your KeyBank Client Success Manager or email developers@keybank.com before trying the request again." } }
Service unavailable
NAME | TYPE | DESCRIPTION |
---|---|---|
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": "Looks like something went wrong. Please try again later. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "This service is currently unavailable(there are no active targets). Please check with your KeyBank Client Success Manager or email developers@keybank.com before trying the request again." } }
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. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.", "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 |
---|---|---|
Acceptrequired | string | Acceptable media types for the response. Valid values: application/json, application/xml |
Content-Typerequired | string | Defines the content type of the API. Common content types are application/json or application/x-www-form-urlencoded. |
X-CorrelationIdoptional | string | A universal ID to trace the transaction across all systems involved, useful for system logging and identification. |
KeyClientIdrequired | string | KeyClientId is provided by KeyBank. This is a 32-character string that identifies you as the client. |
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 |
requestReferenceoptional | string | A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters. |
typerequired | string | Indicates if the transaction type is a PAYMENT or a DRAFT. |
requestedValueDateoptional | 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. |
ultimateDebitPartyoptional | Object | ultParty |
debitPartyoptional | Object | party |
debitPartyBankoptional | Object | party |
creditPartyBankoptional | Object | party |
creditPartyoptional | Object | party |
transferAmountrequired | number | Amount of money to transfer in the correct currency format. |
transferCurrencyrequired | string | Currency code for the transfer amount. |
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 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 |
Response example (200)

{ "status": "VALID", "transactionId": "XZ23050714000000", "requestReference": "testWBB25889710252", "sendersReference": "INVC0012345", "receiversReference": "INVC0054321", "debitAccountNumber": "12345", "creditAccountNumber": "987654321", "transferAmount": 10, "transferCurrency": "USD" }
Missing data
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": "Please make sure your request is correct and try again.", "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.", "detail": { "code": "KEY-1006", "title": "Required field missing", "description": "The object creditPartyBank is required in the request." } } } }
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. |
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.", "detail": { "code": "KEY-0006", "title": "No access", "description": "Additional information about error code." } }, "doddFrank": "NO" } }
Access denied
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" }
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": "We can't seem to find what you're looking for. Please verify the resource and try again.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Request method denied
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": "Looks like something went wrong. Please check your request method and try again.", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Media type not supported
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": "We currently don't support that format. Please check the format type defined in your request and try again. ", "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
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": "Looks like you've sent too many requests. Please wait a moment and try again later.", "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": "Looks like something went wrong. Please try again when you're ready.", "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-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": "Looks like something went wrong. Submit your request 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": "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. |
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 |
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. |
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. |
foreignBankSystemIdoptional | Object | foreignBankSystemType |
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 |
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 |
paymentStatus
NAME | TYPE | DESCRIPTION |
---|---|---|
paymentStatusoptional | string | The status of the payment transaction. Valid values: IN PROCESS, COMPLETED, FAILED, RETURNED, ERROR, VALID |
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 |
requestReferenceoptional | string | A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters. |
typerequired | string | Indicate if the transaction type is a PAYMENT or a DRAFT. |
requestedValueDateoptional | 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. |
ultimateDebitPartyoptional | Object | ultParty |
debitPartyoptional | Object | party |
debitPartyBankoptional | Object | party |
creditPartyBankoptional | Object | party |
creditPartyoptional | Object | party |
transferAmountrequired | number | Amount of money to transfer in the correct currency format. |
transferCurrencyrequired | string | Currency code for the transfer amount. |
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 |
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. |
valueDateoptional | string | The date (YYYY-MM-DD) the transferred occurred. |
erroroptional | Object | paymentError |
doddFrankoptional | Object | noYesType |
ultParty
NAME | TYPE | DESCRIPTION |
---|
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 error messages
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.
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-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" } }
YAML file
