With the Real-Time Payment (RTP) Send Payment API, you can initiate a real-time payment, check on its status, and get information about participating parties.
Prerequisites and best practices
KeyBank has some common prerequisites and best practices. All KeyBank APIs require certifications, user credentials, and certain permissions. Make sure to satisfy all prerequisites before building your API.
Follow these steps to prepare for operations:
-
Have valid certificates for a secure connection.
-
Make sure you have the API keys needed for basic authentication and API access.
-
Request a bearer token.
-
Check the health of the API.
-
Know your KeyClientId. This is a 32-character string provided by KeyBank.
-
To initiate or validate a payment, know all the parties involved in the payment chain.
Certificates
Certificates are a digital authentication method we use to encrypt the information exchanged between KeyBank and your app or service. To access KeyBank environments, you must exchange valid certificates with KeyBank. These certificates must be properly installed on your system before you start to send API calls.
API keys
You need API keys to get a bearer token and to grant access to the APIs and the Pre-Production or Production environments. These API keys are created only for authenticated users that have partnered with KeyBank. For more information, see API security or sign up to become a KeyBank API consumer.
Bearer token
Get a bearer token before you start. Only authenticated users with client credentials can request a bearer token. For more information, see API security or sign up to become a KeyBank API consumer.
Health check
Before you start building your API, perform a quick health check. A health check verifies that the API is operational and responding correctly with your system. A bearer token is required to perform a health check. For more information, see Health check.
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 only required for POST requests to initiate or validate a payment.
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. |
For the endpoints retrieving information (GET calls), the party does not need to be identified.
Endpoints
Endpoint | Result | Description |
---|---|---|
post /rtp/v1/payment/initiate | Initiate a payment | Initiate an RTP or Wire payment transaction. |
get /rtp/v1/payment/rtp/participant | Get a list of RTP participants | Retrieve a list of active, online RTP-participating banks. |
get /rtp/v1/payment/rtp/participant/{routingNumber} | Get information about one RTP participant | Retrieve an active, participating RTP bank with a routing number. |
get /rtp/v1/payment/status/transactionId/{transactionId} | Get the status with the transaction ID | Get the status of an RTP transaction. |
get /rtp/v1/payment/status/debitAccount/{debitAccount}/reference/{reference} | Get the status with the request reference | Get the status of a debit account payment transaction with the request reference field. This is commonly used for troubleshooting. |
post /rtp/v1/payment/validate | Perform validation checks | Run validation checks without creating a payment. |
Initiate a payment
post /rtp/v1/payment/initiate
Initiate an RTP payment transaction. Use the party object to define an individual, corporation, or financial institution in the payment chain.
Request
HEADER FIELD | TYPE | DESCRIPTION |
---|---|---|
Acceptrequired | string | Specify the format of the request. This can either be application/json or application/xml. |
Content-Typerequired | string | Specify what information is being sent to the browser. This can either be application/json or application/xml. |
X-CorrelationIdoptional | string | Apply a universal ID to trace the transaction across all the systems involved. The ID is unique to each request. The ID must be alphanumeric with no spaces and cannot exceed 16 characters. If this field is left blank, the system generates a unique ID with the response. |
KeyClientIdrequired | string | Enter the KeyBank client ID provided by KeyBank. This is a 32-character string that identifies you as the client. |
BODY FIELD | TYPE | DESCRIPTION |
---|---|---|
requestedServicerequired | string | Enter RTP or WIRE for the transaction type. |
requestReferenceoptional | string | Enter a unique ID that is associated with the request. The ID must be alphanumeric with no spaces and cannot exceed 35 characters. This is backend metadata that is not sent with the payment. |
typerequired | string | Indicate if the transaction type is a PAYMENT or a DRAFT. |
requestedValueDateoptional | string | Enter the date (YYYY-MM-DD) for when the transfer will occur. |
originatorReferenceoptional | string | Enter an additional reference value that is meaningful to the party originating the payment. |
sendersReferencerequired | string | Enter the reference value provided by the sender. For outbound payments, this value is the transaction ID. |
receiversReferenceoptional | string | Enter 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 | Enter the amount of money to transfer in the correct currency format. |
transferCurrencyrequired | string | Enter the currency code for the transfer amount. |
Request example

{ "requestedService": "RTP\/WIRE", "requestReference": "UNIQUE REQUEST REFERENCE", "type": "PAYMENT", "sendersReference": "UNIQUE SENDERS REFERENCE", "receiversReference": "REFERENCE TO BENEFICIARY", "requestedValueDate": 1621814400, "debitParty": { "name": "YOUR COMPANY NAME HERE", "accountNumber": "000000000000" }, "creditPartyBank": { "name": "BENEFICIARY BANK NAME", "aba": "000000000" }, "creditParty": { "name": "BENEFICIARY NAME", "accountNumber": "000000000000", "postalAddress": { "adrLine": [ "BENEFICIARY ADDRESS LINE 1", "BENEFICIARY ADDRESS LINE 2" ] } }, "transferAmount": "10.00", "transferCurrency": "USD" }
Responses
Successful response
NAME | TYPE | DESCRIPTION |
---|---|---|
statusrequired | Object | paymentStatus |
transactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
requestReferenceoptional | string | The request reference value from the original request. This is useful for traceability and reporting. |
sendersReferenceoptional | string | The sender reference value from the original request. This is useful for traceability and reporting. |
valueDateoptional | string | The date (YYYY-MM-DD) the transfer occurred. |
erroroptional | Object | paymentError |
doddFrankoptional | Object | noYesType |
Response example (200)

{ "status": "IN_PROCESS", "transactionId": "US21052400000000", "requestReference": "01623178067027R", "sendersReference": "KTT01623178067027R", "valueDate": "2021-05-24", "doddFrank": "NO" }
Missing data in the request
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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", "requestReference": "RR-220818-01", "sendersReference": "SR-220818-01", "error": { "code": "KEY-1006", "title": "Required field missing", "description": "Object creditPartyBank is required" } } }
Received request is unauthorized
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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", "error": { "code": "KEY-0006", "title": "Not authorized for requested service", "description": null } } }
Request is forbidden to access the resource
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (403)

{ "ErrorMessage": "Access to requested resource is forbidden", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested resource is not found
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (404)

{ "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested method is not allowed.
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (405)

{ "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested unsupported media type
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (415)

{ "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Too many requests received
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (429)

{ "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Internal server error
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (500)

{ "ErrorMessage": "Error received from backend service", "TransactionId": "359681587523_SR-RMC-210729-11081", "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688", "TransactionTime": "2022-04-05T07:59:15.422Z", "ServiceError": { "status": "ERROR", "requestReference": "RR-RMC-210720-0123458981", "sendersReference": "SR-RMC-210729-11081", "error": { "code": "KEY-9999", "title": "Unknown error", "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials." } } }
Bad Gateway
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (502)

{ "ErrorMessage": "Error received from backend service", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Connectivity error occured with the downstream service(Unexpected EOF at target), please check with appplication support team before resubmitting the request" } }
Service Unavailable
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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 appplication support before resubmitting the request." } }
Gateway timeout
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (504)

{ "ErrorMessage": "Error received from backend service", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Request could not be processed on time(GatewayTimeout), please wait a moment and resubmit the request" } }
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 |
---|---|---|
Acceptrequired | string | Specify the format of the request. This can either be application/json or application/xml. |
X-CorrelationIdoptional | string | Apply a universal ID to trace the transaction across all the systems involved. The ID is unique to each request. The ID must be alphanumeric with no spaces and cannot exceed 16 characters. If this field is left blank, the system generates a unique ID with the response. |
KeyClientIdoptional | string | Enter the KeyBank client ID provided by KeyBank. This is a 32-character string that identifies you as the client. |
QUERY STRING PARAMETER | TYPE | DESCRIPTION |
---|---|---|
limitrequired | integer | Enter the maximum number of records to return in the response. |
offsetrequired | integer | Enter the number of records skipped before generating the output. |
Responses
Successful response
NAME | TYPE | DESCRIPTION |
---|---|---|
countrequired | string | The count of records that match the initial query. |
limitrequired | integer | The maximum number of records returned in the response. |
offsetrequired | integer | The number of records skipped before the response is returned. |
partiesoptional | Object | party |
Response example (200)

{ "count": "65", "limit": "10", "offset": "0", "parties": { "name": "CITIZENS BANK, NA", "aba": "011500120", "postalAddress": { "twnNm": "NEW YORK", "ctrySubDvsn": "NY", "adrLine": [ "BENEFICIARY ADDRESS LINE 1", "BENEFICIARY ADDRESS LINE 2" ] } } }
Missing data in the request
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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", "requestReference": "RR-220818-01", "sendersReference": "SR-220818-01", "error": { "code": "KEY-1006", "title": "Required field missing", "description": "Object creditPartyBank is required" } } }
Received request is unauthorized
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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", "error": { "code": "KEY-0006", "title": "Not authorized for requested service", "description": null } } }
Request is forbidden to access the resource
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (403)

{ "ErrorMessage": "Access to requested resource is forbidden", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested resource is not found
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (404)

{ "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested method is not allowed.
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (405)

{ "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested unsupported media type
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (415)

{ "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Too many requests received
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (429)

{ "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Internal server error
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (500)

{ "ErrorMessage": "Error received from backend service", "TransactionId": "359681587523_SR-RMC-210729-11081", "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688", "TransactionTime": "2022-04-05T07:59:15.422Z", "ServiceError": { "status": "ERROR", "requestReference": "RR-RMC-210720-0123458981", "sendersReference": "SR-RMC-210729-11081", "error": { "code": "KEY-9999", "title": "Unknown error", "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials." } } }
Bad Gateway
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (502)

{ "ErrorMessage": "Error received from backend service", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Connectivity error occured with the downstream service(Unexpected EOF at target), please check with appplication support team before resubmitting the request" } }
Service Unavailable
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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 appplication support before resubmitting the request." } }
Gateway timeout
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (504)

{ "ErrorMessage": "Error received from backend service", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Request could not be processed on time(GatewayTimeout), please wait a moment and resubmit the request" } }
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 |
---|---|---|
Acceptrequired | string | Specify the format of the request. This can either be application/json or application/xml. |
X-CorrelationIdoptional | string | Apply a universal ID to trace the transaction across all the systems involved. The ID is unique to each request. The ID must be alphanumeric with no spaces and cannot exceed 16 characters. If this field is left blank, the system generates a unique ID with the response. |
KeyClientIdoptional | string | Enter the KeyBank client ID provided by KeyBank. This is a 32-character string that identifies you as the client. |
PATH PARAMETER | TYPE | DESCRIPTION |
---|---|---|
routingNumberrequired | string | In the URL path, specify the routing number of the participating RTP bank. |
Responses
Successful response
NAME | TYPE | DESCRIPTION |
---|---|---|
namerequired | string | The name of the party. This can be an individual, a financial institution, or a beneficiary. The name cannot exceed 140 characters. |
accountNumberoptional | string | The 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. |
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. |
Response example (200)

{ "name": "CITIZENS BANK, NA", "aba": "011500120", "postalAddress": { "twnNm": "NEW YORK", "ctrySubDvsn": "NY", "adrLine": [ "BENEFICIARY ADDRESS LINE 1", "BENEFICIARY ADDRESS LINE 2" ] } }
Missing data in the request
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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", "requestReference": "RR-220818-01", "sendersReference": "SR-220818-01", "error": { "code": "KEY-1006", "title": "Required field missing", "description": "Object creditPartyBank is required" } } }
Received request is unauthorized
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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", "error": { "code": "KEY-0006", "title": "Not authorized for requested service", "description": null } } }
Request is forbidden to access the resource
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (403)

{ "ErrorMessage": "Access to requested resource is forbidden", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested resource is not found
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (404)

{ "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested method is not allowed.
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (405)

{ "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested unsupported media type
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (415)

{ "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Too many requests received
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (429)

{ "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Internal server error
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (500)

{ "ErrorMessage": "Error received from backend service", "TransactionId": "359681587523_SR-RMC-210729-11081", "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688", "TransactionTime": "2022-04-05T07:59:15.422Z", "ServiceError": { "status": "ERROR", "requestReference": "RR-RMC-210720-0123458981", "sendersReference": "SR-RMC-210729-11081", "error": { "code": "KEY-9999", "title": "Unknown error", "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials." } } }
Bad Gateway
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (502)

{ "ErrorMessage": "Error received from backend service", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Connectivity error occured with the downstream service(Unexpected EOF at target), please check with appplication support team before resubmitting the request" } }
Service Unavailable
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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 appplication support before resubmitting the request." } }
Gateway timeout
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (504)

{ "ErrorMessage": "Error received from backend service", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Request could not be processed on time(GatewayTimeout), please wait a moment and resubmit the request" } }
Get the status with the transaction ID
get /rtp/v1/payment/status/transactionId/{transactionId}
Retrieve the status of a RTP payment transaction. Use the transaction ID number associated with the payment to get the status and transaction details.
Request
HEADER FIELD | TYPE | DESCRIPTION |
---|---|---|
Acceptrequired | string | Specify the format of the request. This can either be application/json or application/xml. |
X-CorrelationIdoptional | string | Apply a universal ID to trace the transaction across all the systems involved. The ID is unique to each request. The ID must be alphanumeric with no spaces and cannot exceed 16 characters. If this field is left blank, the system generates a unique ID with the response. |
KeyClientIdoptional | string | Enter the KeyBank client ID provided by KeyBank. This is a 32-character string that identifies you as the client. |
PATH PARAMETER | TYPE | DESCRIPTION |
---|---|---|
transactionIdrequired | string | Enter the transaction ID number associated with the original payment. |
Responses
Successful response
NAME | TYPE | DESCRIPTION |
---|---|---|
statusrequired | Object | paymentStatus |
transactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
requestReferenceoptional | string | The request reference value from the original request. This is useful for traceability and reporting. |
sendersReferenceoptional | string | The sender reference value from the original request. This is useful for traceability and reporting. |
valueDateoptional | string | The date (YYYY-MM-DD) the transfer occurred. |
erroroptional | Object | paymentError |
doddFrankoptional | Object | noYesType |
Response example (200)

{ "status": "IN_PROCESS", "transactionId": "US21052400000000", "requestReference": "RR-KEY-999999-01", "sendersReference": "SR-KEY-999999-01", "valueDate": "2021-05-24", "error": null, "doddFrank": "YES-" }
Missing data in the request
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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": null, "status": "FAILED", "requestReference": "RR-220818-01", "sendersReference": "SR-220818-01", "error": { "code": "KEY-1006", "title": "Required field missing", "description": "Object creditPartyBank is required" } }
Received request is unauthorized
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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", "error": { "code": "KEY-0006", "title": "Not authorized for requested service", "description": null } } }
Request is forbidden to access the resource
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (403)

{ "ErrorMessage": "Access to requested resource is forbidden", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested resource is not found
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (404)

{ "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested method is not allowed.
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (405)

{ "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested unsupported media type
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (415)

{ "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Too many requests received
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (429)

{ "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Internal server error
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (500)

{ "ErrorMessage": "Error received from backend service", "TransactionId": "359681587523_SR-RMC-210729-11081", "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688", "TransactionTime": "2022-04-05T07:59:15.422Z", "ServiceError": { "status": "ERROR", "requestReference": "RR-RMC-210720-0123458981", "sendersReference": "SR-RMC-210729-11081", "error": { "code": "KEY-9999", "title": "Unknown error", "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials." } } }
Bad Gateway
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (502)

{ "ErrorMessage": "Error received from backend service", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Connectivity error occured with the downstream service(Unexpected EOF at target), please check with appplication support team before resubmitting the request" } }
Service Unavailable
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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 appplication support before resubmitting the request." } }
Gateway timeout
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (504)

{ "ErrorMessage": "Error received from backend service", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Request could not be processed on time(GatewayTimeout), please wait a moment and resubmit the request" } }
Get the status with the request reference
get /rtp/v1/payment/status/debitAccount/{debitAccount}/reference/{reference}
Get the status of a payment with the debit account number of the payment originator and the request reference number. This call is typically used for troubleshooting an issue with timing or a technical error with a payment transaction.
You can assign a request reference number when you initiate or validate a payment. This number is metadata for backend traceability and is not sent with the payment. Use this number with the debit account number for the originating payment. The account number and request reference number must be unique; you cannot use the same request reference number for different transactions.
Request
HEADER FIELD | TYPE | DESCRIPTION |
---|---|---|
Acceptrequired | string | Specify the format of the request. This can either be application/json or application/xml. |
X-CorrelationIdoptional | string | Apply a universal ID to trace the transaction across all the systems involved. The ID is unique to each request. The ID must be alphanumeric with no spaces and cannot exceed 16 characters. If this field is left blank, the system generates a unique ID with the response. |
KeyClientIdoptional | string | Enter the KeyBank client ID provided by KeyBank. This is a 32-character string that identifies you as the client. |
PATH PARAMETER | TYPE | DESCRIPTION |
---|---|---|
debitAccountrequired | string | In the URL path, specify the debit account number. |
referencerequired | string | Enter the unique request reference number from the original payment request. |
Responses
Successful response
NAME | TYPE | DESCRIPTION |
---|---|---|
statusrequired | Object | paymentStatus |
transactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
requestReferenceoptional | string | The request reference value from the original request. This is useful for traceability and reporting. |
sendersReferenceoptional | string | The sender reference value from the original request. This is useful for traceability and reporting. |
valueDateoptional | string | The date (YYYY-MM-DD) the transfer occurred. |
erroroptional | Object | paymentError |
doddFrankoptional | Object | noYesType |
Response example (200)

{ "status": "IN_PROCESS", "transactionId": "US21052400000000", "requestReference": "RR-KEY-999999-01", "sendersReference": "SR-KEY-999999-01", "valueDate": "2021-05-24", "error": null, "doddFrank": "YES" }
Missing data in the request
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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": null, "status": "FAILED", "requestReference": "RR-220818-01", "sendersReference": "SR-220818-01", "error": { "code": "KEY-1006", "title": "Required field missing", "description": "Object creditPartyBank is required" } }
Received request is unauthorized
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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", "error": { "code": "KEY-0006", "title": "Not authorized for requested service", "description": null } } }
Request is forbidden to access the resource
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (403)

{ "ErrorMessage": "Access to requested resource is forbidden", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested resource is not found
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (404)

{ "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested method is not allowed.
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (405)

{ "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested unsupported media type
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (415)

{ "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Too many requests received
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (429)

{ "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Internal server error
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (500)

{ "ErrorMessage": "Error received from backend service", "TransactionId": "359681587523_SR-RMC-210729-11081", "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688", "TransactionTime": "2022-04-05T07:59:15.422Z", "ServiceError": { "status": "ERROR", "requestReference": "RR-RMC-210720-0123458981", "sendersReference": "SR-RMC-210729-11081", "error": { "code": "KEY-9999", "title": "Unknown error", "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials." } } }
Bad Gateway
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (502)

{ "ErrorMessage": "Error received from backend service", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Connectivity error occured with the downstream service(Unexpected EOF at target), please check with appplication support team before resubmitting the request" } }
Service Unavailable
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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 appplication support before resubmitting the request." } }
Gateway timeout
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (504)

{ "ErrorMessage": "Error received from backend service", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Request could not be processed on time(GatewayTimeout), please wait a moment and resubmit the request" } }
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 | Specify the format of the request. This can either be application/json or application/xml. |
Content-Typerequired | string | Specify what information is being sent to the browser. This can either be application/json or application/xml. |
X-CorrelationIdoptional | string | Apply a universal ID to trace the transaction across all the systems involved. The ID is unique to each request. The ID must be alphanumeric with no spaces and cannot exceed 16 characters. If this field is left blank, the system generates a unique ID with the response. |
KeyClientIdrequired | string | Enter the KeyBank client ID provided by KeyBank. This is a 32-character string that identifies you as the client. |
BODY FIELD | TYPE | DESCRIPTION |
---|---|---|
requestedServicerequired | string | Enter RTP or WIRE for the transaction type. |
requestReferenceoptional | string | Enter a unique ID that is associated with the request. The ID must be alphanumeric with no spaces and cannot exceed 35 characters. This is backend metadata that is not sent with the payment. |
typerequired | string | Indicate if the transaction type is a PAYMENT or a DRAFT. |
requestedValueDateoptional | string | Enter the date (YYYY-MM-DD) for when the transfer will occur. |
originatorReferenceoptional | string | Enter an additional reference value that is meaningful to the party originating the payment. |
sendersReferencerequired | string | Enter the reference value provided by the sender. For outbound payments, this value is the transaction ID. |
receiversReferenceoptional | string | Enter 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 | Enter the amount of money to transfer in the correct currency format. |
transferCurrencyrequired | string | Enter the currency code for the transfer amount. |
Request example

{ "requestedService": "RTP\/WIRE", "requestReference": "UNIQUE REQUEST REFERENCE", "type": "PAYMENT", "sendersReference": "UNIQUE SENDERS REFERENCE", "receiversReference": "REFERENCE TO BENEFICIARY", "requestedValueDate": 1621814400, "debitParty": { "name": "YOUR COMPANY NAME HERE", "accountNumber": "000000000000" }, "creditPartyBank": { "name": "BENEFICIARY BANK NAME", "aba": "000000000" }, "creditParty": { "name": "BENEFICIARY NAME", "accountNumber": "000000000000", "postalAddress": { "adrLine": [ "BENEFICIARY ADDRESS LINE 1", "BENEFICIARY ADDRESS LINE 2" ] } }, "transferAmount": "10.00", "TransferCurrency": "USD" }
Responses
Successful response
NAME | TYPE | DESCRIPTION |
---|---|---|
statusrequired | Object | paymentStatus |
transactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
requestReferenceoptional | string | The request reference value from the original request. This is useful for traceability and reporting. |
sendersReferenceoptional | string | The sender reference value from the original request. This is useful for traceability and reporting. |
valueDateoptional | string | The date (YYYY-MM-DD) the transfer occurred. |
erroroptional | Object | paymentError |
doddFrankoptional | Object | noYesType |
Response example (200)

{ "status": "IN_PROCESS", "transactionId": "US21052400000000", "requestReference": "RR-KEY-999999-01", "sendersReference": "SR-KEY-999999-01", "valueDate": "2021-05-24", "error": null, "doddFrank": "YES" }
Missing data in the request
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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": null, "status": "FAILED", "requestReference": "RR-220818-01", "sendersReference": "SR-220818-01", "error": { "code": "KEY-1006", "title": "Required field missing", "description": "Object creditPartyBank is required" } }
Received request is unauthorized
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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", "error": { "code": "KEY-0006", "title": "Not authorized for requested service", "description": null } } }
Request is forbidden to access the resource
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (403)

{ "ErrorMessage": "Access to requested resource is forbidden", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested resource is not found
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (404)

{ "ErrorMessage": "Requested resource is not found, please verify the resource and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested method is not allowed.
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (405)

{ "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Requested unsupported media type
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (415)

{ "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Too many requests received
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (429)

{ "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z" }
Internal server error
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (500)

{ "ErrorMessage": "Error received from backend service", "TransactionId": "359681587523_SR-RMC-210729-11081", "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688", "TransactionTime": "2022-04-05T07:59:15.422Z", "ServiceError": { "status": "ERROR", "requestReference": "RR-RMC-210720-0123458981", "sendersReference": "SR-RMC-210729-11081", "error": { "code": "KEY-9999", "title": "Unknown error", "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials." } } }
Bad Gateway
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (502)

{ "ErrorMessage": "Error received from backend service", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Connectivity error occured with the downstream service(Unexpected EOF at target), please check with appplication support team before resubmitting the request" } }
Service Unavailable
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The 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 appplication support before resubmitting the request." } }
Gateway timeout
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
Response example (504)

{ "ErrorMessage": "Error received from backend service", "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab", "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1", "TransactionTime": "2021-06-11T16:31:34.041Z", "ServiceError": { "ConnectError": "Request could not be processed on time(GatewayTimeout), please wait a moment and resubmit the request" } }
Schemas
exception
NAME | TYPE | DESCRIPTION |
---|---|---|
ErrorMessageoptional | string | Error message that describes the type or source of the error. |
TransactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
TransactionTimeoptional | string | The date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred. |
ServiceErroroptional | oneOf | serviceErrorData connectError |
serviceErrorData
NAME | TYPE | DESCRIPTION |
---|---|---|
statusrequired | Object | paymentStatus |
transactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
requestReferenceoptional | string | The request reference value from the original request. This is useful for traceability and reporting. |
sendersReferenceoptional | string | The sender reference value from the original request. This is useful for traceability and reporting. |
valueDateoptional | string | The date (YYYY-MM-DD) the transferred occurred. |
erroroptional | Object | paymentError |
doddFrankoptional | Object | noYesType |
connectError
NAME | TYPE | DESCRIPTION |
---|---|---|
ConnectErroroptional | string | Error information about the connectivity with downstream service. |
paymentTransactionRequestV1
NAME | TYPE | DESCRIPTION |
---|---|---|
requestedServicerequired | string | Enter RTP or WIRE for the transaction type. |
requestReferenceoptional | string | Enter a unique ID that is associated with the request. The ID must be alphanumeric with no spaces and cannot exceed 35 characters. This is backend metadata that is not sent with the payment. |
typerequired | string | Indicate if the transaction type is a PAYMENT or a DRAFT. |
requestedValueDateoptional | string | Enter the date (YYYY-MM-DD) for when the transfer will occur. |
originatorReferenceoptional | string | Enter an additional reference value that is meaningful to the party originating the payment. |
sendersReferencerequired | string | Enter the reference value provided by the sender. For outbound payments, this value is the transaction ID. |
receiversReferenceoptional | string | Enter 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 | Enter the amount of money to transfer in the correct currency format. |
transferCurrencyrequired | string | Enter the currency code for the transfer amount. |
party
NAME | TYPE | DESCRIPTION |
---|---|---|
namerequired | string | The name of the party. This can be an individual, a financial institution, or a beneficiary. The name cannot exceed 140 characters. |
accountNumberoptional | string | The 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. |
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. |
participantListResponse
NAME | TYPE | DESCRIPTION |
---|---|---|
countrequired | string | The count of records that match the initial query. |
limitrequired | integer | The maximum number of records returned in the response. |
offsetrequired | integer | The number of records skipped before the response is returned. |
partiesoptional | Object | party |
foreignBankSystemType
NAME | TYPE | DESCRIPTION |
---|---|---|
typeoptional | string | Enter the 5-digit global routing code for a foreign financial institution. |
idoptional | string | Enter the identification number associated with the foreign financial institution. |
paymentTransactionResponse
NAME | TYPE | DESCRIPTION |
---|---|---|
statusrequired | Object | paymentStatus |
transactionIdoptional | string | The unique transaction ID returned with the response, useful for traceability. |
requestReferenceoptional | string | The request reference value from the original request. This is useful for traceability and reporting. |
sendersReferenceoptional | string | The sender reference value from the original request. This is useful for traceability and reporting. |
valueDateoptional | string | The date (YYYY-MM-DD) the transfer occurred. |
erroroptional | Object | paymentError |
doddFrankoptional | Object | noYesType |
paymentStatus
NAME | TYPE | DESCRIPTION |
---|---|---|
paymentStatusoptional | string | The status of the payment transaction. Possible response values include IN PROCESS, COMPLETED, FAILED, RETURNED, ERROR, and VALID. |
paymentError
NAME | TYPE | DESCRIPTION |
---|---|---|
coderequired | string | A status code assigned to each error type. |
titlerequired | string | A brief title about the error associated with the status code. |
descriptionoptional | string | A description of the error. |
coderequired | string | A static code assigned by the network or payment system. |
titlerequired | string | A brief title about the error associated with the status code. |
descriptionoptional | string | A description of the error. |
noYesType
NAME | TYPE | DESCRIPTION |
---|---|---|
noYesTypeoptional | string | This field indicates whether the transaction qualifies for Dodd-Frank. |
ultParty
NAME | TYPE | DESCRIPTION |
---|---|---|
ultPartyoptional | string | Enter a third-party name. Typically, this is the name of the party that instructed the debit party to initiate a payment. This value cannot exceed 140 characters. |
Error handling
An error can indicate a problem with the request, the network, or the API itself. Use the error handling information to get a better understanding of what went wrong and possible ways to fix it.
Standard error message format
An erroneous response returns the HTTP code number with the content of the exception
schema. Additional information in this schema like the transaction ID and transaction time can help you diagnose the issue.
API-specific error messages
Custom messages are used for API-related functional business messages or faults. Each API can contain custom messages specific to KeyBank operations or the API. These messages can be part of the exception
schema or a separate object.
For RTP Send Payment API, custom messages can display with the HTTP 400, 401, 403, or 500 status codes. The message and details are in the error
object. Errors can be about account restrictions, network timeout, invalid data in the request, etc.
KEYBANK CODES AND MESSAGES
CODE | MESSAGE |
---|---|
KEY-0001 |
Not authorized |
KEY-0002 |
Not authorized for requested action |
KEY-0003 |
Request exceeds authorized limit |
KEY-0004 |
Unauthorized for account |
KEY-0005 |
Internal use only fields |
KEY-0006 |
Not authorized for requested service |
KEY-1000 |
Transformation Error |
KEY-1001 |
Invalid Data |
KEY-1002 |
Invalid Bank Identifier |
KEY-1003 |
Invalid or unknown template |
KEY-1004 |
Invalid account |
KEY-1005 |
Invalid Currency |
KEY-1006 |
Required field missing |
KEY-1007 |
Transaction Not Found |
KEY-1008 |
Insufficient Funds |
KEY-1009 |
Account has restrictions |
KEY-1010 |
Duplicate Request |
KEY-1011 |
Payor Account Restrictions |
KEY-1012 |
Payee Account Restrictions |
KEY-3001 |
Exceeds transaction limit for RTP transactions |
KEY-3002 |
Field not usable for RTP transactions |
KEY-3003 |
Payment network timeout. Please retry. |
KEY-3004 |
Payment rejected by payment network |
KEY-9997 |
Failed payment review |
KEY-9998 |
Payment failed during processing |
KEY-9999 |
Unknown error |
Error codes and messages
Most of the errors use HTTP status codes. Business error messages use the serviceError
object for additional information specific to the API request.
HTTP STATUS CODE | CUSTOM STATUS CODE | DESCRIPTION |
---|---|---|
204 |
|
|
400 |
|
|
401 |
|
|
403 |
|
|
404 |
|
|
405 |
|
|
415 |
|
|
429 |
|
|
500 |
|
|
502 |
|
|
503 |
|
|
504 |
|
YAML file
