Make a payment immediately and at any time
What you can do | Endpoint |
---|---|
Health check | get /rtp/v1/payment/healthCheck |
Send a real-time payment | post /rtp/v1/payment/initiate |
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} |
Perform validation checks | post /rtp/v1/payment/validate |
Key notes
Before you begin
All KeyBank APIs require certificates, user credentials, and certain permissions. 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.
Check out our Getting Started Guide to learn more.
Requirements
Key Client ID
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).
Reference IDs
The reference numbers reduces manuals processes or payment identification errors. It can also help the recipient auto-reconcile incoming payment.
requestReference
: A unique identifier specific to this request. This is used for idempotency and deduplication. If you retry the same request due to network or system error, using the same requestReference
makes sure the bank does not process it twice.
originatorReference
: A reference number that represents the party that initiated the payment. This is usually your end customer or payment originator.
sendersReference
: A unique reference identification generated by you - the API client or sender of the RTP request. Use this to track or identify the transaction with your system.
receiversReference
: A reference value that the recipient of the payment can use to reconcile or track the payment on their side. This gives the payee an extra piece of information for their own system, like an order ID or case number that they can tie back to the payment.
How reference IDs work
REFERENCE FIELD | WHO SETS IT | WHAT IT TRACKS | WHO SEES IT | EXAMPLE |
---|---|---|---|---|
requestReference | You (API client) | Unique API request identifier for idempotency and retries. | Bank or RTP network (for deduplication) | "req-20250617-001" |
originatorReference | Payment originator (your customer or the system on their behalf) | Their reason for the payment, like an invoice number they are paying. | Recipient (payee) | "INV-4567" |
sendersReference | You (API client) | Your internal transaction tracking number, like a PO number or system ID. | You and the bank | "ERP-PO-7890" |
receiversReference | You (API client) | Helps the recipient's system reconcile the payment, like a order or case number for their system. | Recipient (payee) | "SupplierOrder123" |
Party object for payments
The party
object is required for any payment or validation request. The party object defines each participant in the payment chain, sender (debitParty
, debitPartyBank
) and receiver (creditParty
, creditPartyBank
). The receiver can be an individual, corporation, beneficiary, or financial institution.
Depending on the party type in the payment chain, there are certain details required about the person or entity sending a payment and the one receiving the payment. Define the following request fields to successfully send a payment from one account to another or validate a recent transaction.
Payment chain request objects
ORDER | PAYMENT CHAIN ACTIVITY | REQUEST FIELD/VAULES |
---|---|---|
1 | You send a payment as an individual or as a business. | debitParty Enter the name associated with the account ( name ) and your debit account number (accountNumber ). |
2 | Your bank transfers the funds. | debitPartyBank Enter the ABA or routing number ( aba ) for your bank. Usually, this is KeyBank. |
3 | The recipient's bank receives the funds from your bank. |
If the |
4 | The person or business ("beneficiary party") you are sending money to receives the funds. |
If the |
Use the right characters in ISO messages
Use only the supported characters in ISO messages. If you use a character that isn't supported, an error message returns. Review the entered values to make sure you did not use a restricted character (like the pipe delimiter).
ISO messages only support the following characters:
- Alphabet characters, uppercase (A-Z) and lowercase (a-z)
- Numeric characters (0-9)
- Special characters limited to .,-()?+'=:?@-#{!"%&*;<>
- Single space, carriage return, and line feed
API double-check to avoid duplicates
All payments go through two levels of checks to avoid duplicate transactions. You will receive an error if the transaction is not unique.
Level 1: We look at the requestReference
field defined in the request. This must be a unique number for the originated transaction. This ID stays with the transaction and helps prevent duplicate transactions.
Level 2: Check additional fields in the request to make sure the transaction is not a duplicate.
debitParty
>accountNumber
creditPartyBank
>aba
creditParty
>accountNumber
requestedValueDate
transferAmount
receiversReference
(This is a critical field if you may be sending similar, almost identical payments.)
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 |
---|---|---|
Status | string | The status of the health check response. |
Source | 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. |
Timestamp | string | The date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service. |
ClientIp | string | The client IP address the gateway receives from the request. |
X-Forwarded-For | 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]" }
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.
Review the request requirements to get a better understanding about request identifiers and the party
object.
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 32 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": "CLARK GABLE", "accountNumber": "001122334455" }, "creditPartyBank": { "name": "CLARK GABLE", "aba": "123456789" }, "creditParty": { "name": "CLARK GABLE", "accountNumber": "987654321", "postalAddress": { "adrTp": "HOME", "dept": "Test Dept", "subDept": "Test Sub Dept", "strtNm": "123 Main Street", "bldgNb": 10, "pstCd": 12345, "twnNm": "Central Town", "ctrySubDvsn": "Test Sub Division", "ctry": "US", "adrLine": [ "123 Main Street", "Central Town, US" ] } }, "transferAmount": 10, "transferCurrency": "USD" }
Responses
Successful response
NAME | TYPE | DESCRIPTION |
---|---|---|
statusrequired | Object | paymentStatus |
transactionId | string | The unique ID number associated with the original payment request. |
requestReference | string | A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters. |
sendersReference | 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. |
receiversReference | string | A reference value for the beneficiary. This value cannot exceed 140 characters. |
debitAccountNumber | string | Debit account number. This cannot exceed 34 digits. |
creditAccountNumber | string | Credit account number. This cannot exceed 34 digits. |
valueDate | string | The date (YYYY-MM-DD) the transfer occurred. |
transferAmount | integer | Amount of money to transfer in the correct currency format. |
transferCurrency | string | Currency code for the transfer amount. |
error | Object | paymentError |
doddFrank | Object | noYesType |
clearingSystemReference | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 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
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. |
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. |
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. |
parties | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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
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. |
path FIELD | TYPE | DESCRIPTION |
---|---|---|
routingNumberrequired | string | Routing number of the participating RTP bank. |
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 is required for the creditParty. This cannot exceed 140 characters. |
accountNumber | string | Account number of the party. If this is a wire transfer, you must provide the name and address with the account number for all parties, except debitParty and debitPartyBank. This cannot exceed 34 digits. |
aba | string | The ABA or routing number of the financial institution. If this is a wire transfer, you do not need to provide other account information like address or name, unless it is for debitParty or debitPartyBank. This cannot exceed 9 digits. |
bic | 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. |
txid | string | The tax identification number for the party. |
foreignBankSystemId | Object | foreignBankSystemType |
adrTp | string | Address type for the party that specifies if it is a home, business, or mailing address. Valid values: ADDR, PBOX, HOME, BIZZ, MLTO, DLVY |
dept | string | Department of the party for the mailing address, if applicable. This field cannot exceed 70 characters. |
subDept | string | Sub-department of the party, if applicable. This field cannot exceed 70 characters. |
strtNm | string | Street address for the party. This field cannot exceed 70 characters. |
bldgNb | string | Building number. This field cannot exceed 16 characters. |
pstCd | string | The postal code or zip code for the address. This field cannot exceed 16 characters. |
twnNm | string | Name of the town. This field cannot exceed 35 characters. |
ctrySubDvsn | string | Name of subdivision of a country like a state, region, or county. This field cannot exceed 35 characters. |
ctry | string | Country name or abbreviation. |
adrLineoptional | array | An unstructured address line. You can have up to three lines of text. Each line can be 70 characters or less. |
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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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.
Review the request requirements to get a better understanding about request identifiers and the party
object.
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 32 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": "CLARK GABLE" }, "debitParty": { "name": "CLARK GABLE", "accountNumber": "001122334455" }, "creditPartyBank": { "name": "CLARK GABLE", "aba": "123456789" }, "creditParty": { "name": "CLARK GABLE", "accountNumber": "987654321", "postalAddress": { "adrTp": "HOME", "dept": "Test Dept", "subDept": "Test Sub Dept", "strtNm": "123 Main Street", "bldgNb": 10, "pstCd": 12345, "twnNm": "Central Town", "ctrySubDvsn": "Test Sub Division", "ctry": "US" } }, "transferAmount": 10, "transferCurrency": "USD", "customData": "" }
Responses
Successful response
NAME | TYPE | DESCRIPTION |
---|---|---|
statusrequired | Object | paymentStatus |
transactionId | string | The unique ID number associated with the original payment request. |
requestReference | string | A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters. |
sendersReference | 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. |
receiversReference | string | A reference value for the beneficiary. This value cannot exceed 140 characters. |
debitAccountNumber | string | Debit account number. This cannot exceed 34 digits. |
creditAccountNumber | string | Credit account number. This cannot exceed 34 digits. |
valueDate | string | The date (YYYY-MM-DD) the transfer occurred. |
transferAmount | integer | Amount of money to transfer in the correct currency format. |
transferCurrency | string | Currency code for the transfer amount. |
error | Object | paymentError |
doddFrank | Object | noYesType |
clearingSystemReference | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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 |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | 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
healthResponse
NAME | TYPE | DESCRIPTION |
---|---|---|
Status | string | The status of the health check response. |
Source | 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. |
Timestamp | string | The date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service. |
ClientIp | string | The client IP address the gateway receives from the request. |
X-Forwarded-For | string | The sequence of the IP addresses for systems between the client and the gateway. Addresses are separated by a comma. |
exception
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessage | string | A human-readable message that describes the type or source of the error. |
TransactionId | string | A unique transaction ID returned with the response, useful for traceability. |
TransactionTime | string | Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceError | oneOf | serviceErrorData connectError |
serviceErrorData
NAME | TYPE | DESCRIPTION |
---|---|---|
statusrequired | Object | paymentStatus |
transactionId | string | The unique ID number associated with the original payment request. |
requestReference | string | A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters. |
sendersReference | 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. |
receiversReference | string | The sender reference value from the original request. This is useful for traceability and reporting. |
debitAccountNumber | string | The sender reference value from the original request. This is useful for traceability and reporting. |
creditAccountNumber | string | The sender reference value from the original request. This is useful for traceability and reporting. |
valueDate | string | The date (YYYY-MM-DD) the transferred occurred. |
error | Object | paymentError |
doddFrank | Object | noYesType |
connectError
NAME | TYPE | DESCRIPTION |
---|---|---|
ConnectError | 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. |
originatorReference | 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 32 characters. |
receiversReference | string | A reference value for the beneficiary. This value cannot exceed 140 characters. |
bankToBankInstructions | string | Area to share messages or instructions from one bank to another bank. This cannot exceed 140 characters. |
ultimateDebitParty | Object | ultParty |
debitPartyrequired | Object | party |
debitPartyBank | Object | party |
intermediaryBank1 | Object | party |
intermediaryBank2 | Object | party |
intermediaryBank3 | 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. |
externalTemplateName | string | Name of the external template. Text cannot exceed 2048 characters. |
customData | 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 is required for the creditParty. This cannot exceed 140 characters. |
accountNumber | string | Account number of the party. If this is a wire transfer, you must provide the name and address with the account number for all parties, except debitParty and debitPartyBank. This cannot exceed 34 digits. |
aba | string | The ABA or routing number of the financial institution. If this is a wire transfer, you do not need to provide other account information like address or name, unless it is for debitParty or debitPartyBank. This cannot exceed 9 digits. |
bic | 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. |
txid | string | The tax identification number for the party. |
foreignBankSystemId | Object | foreignBankSystemType |
adrTp | string | Address type for the party that specifies if it is a home, business, or mailing address. Valid values: ADDR, PBOX, HOME, BIZZ, MLTO, DLVY |
dept | string | Department of the party for the mailing address, if applicable. This field cannot exceed 70 characters. |
subDept | string | Sub-department of the party, if applicable. This field cannot exceed 70 characters. |
strtNm | string | Street address for the party. This field cannot exceed 70 characters. |
bldgNb | string | Building number. This field cannot exceed 16 characters. |
pstCd | string | The postal code or zip code for the address. This field cannot exceed 16 characters. |
twnNm | string | Name of the town. This field cannot exceed 35 characters. |
ctrySubDvsn | string | Name of subdivision of a country like a state, region, or county. This field cannot exceed 35 characters. |
ctry | string | Country name or abbreviation. |
adrLineoptional | array | An unstructured address line. You can have up to three lines of text. Each line can be 70 characters or less. |
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. |
parties | Object | party |
foreignBankSystemType
NAME | TYPE | DESCRIPTION |
---|---|---|
type | string | The five-digit global routing code for a foreign financial institution. |
id | string | The identification number associated with the foreign financial institution. |
paymentTransactionResponse
NAME | TYPE | DESCRIPTION |
---|---|---|
statusrequired | Object | paymentStatus |
transactionId | string | The unique ID number associated with the original payment request. |
requestReference | string | A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters. |
sendersReference | 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. |
receiversReference | string | A reference value for the beneficiary. This value cannot exceed 140 characters. |
debitAccountNumber | string | Debit account number. This cannot exceed 34 digits. |
creditAccountNumber | string | Credit account number. This cannot exceed 34 digits. |
valueDate | string | The date (YYYY-MM-DD) the transfer occurred. |
transferAmount | integer | Amount of money to transfer in the correct currency format. |
transferCurrency | string | Currency code for the transfer amount. |
error | Object | paymentError |
doddFrank | Object | noYesType |
clearingSystemReference | 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. |
description | string | Description of the error. |
code | string | A static code assigned by the network or payment system. |
title | string | Brief title about the error associated with the status code. |
description | 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 |
---|---|---|
name | string | Typically this is the name of the party that instructed the debit party to initiate a payment. This applies only to RTP transactions and the 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. For more information about our standard HTTP errors, see Error handling.
KeyBank may include additional information about the error in API-specific error messages. The 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.
KeyBank codes with 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-2101 | Unable to construct wire from template |
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 |
---|---|---|---|
June 2025 | 1.3.0 |
| MID |
April 2025 | 1.2.6 |
| LOW |
December 2024 | 1.2.5 |
| LOW |
August 2024 | 1.2.4 |
| MID |
May 2024 | 1.2.3 |
| MID |
March 2024 | 1.2.1 |
| HIGH |
September 2023 | 1.1.5 |
| LOW |
December 2022 | 1.1.3 |
|
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
