Wire Origination

6-minute read 1.2.1 | updated Mar. 13, 2024

Transfer money by wire for urgent payments or large volume transactions

 

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

Before you begin

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

 

Two in one

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

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

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

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

Payment chain parties

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

 

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

 

API requirements

KeyClientId: When you initiate or validate a payment, you are required to provide the KeyClientId in the request header. The KeyClientId is a 32-character string provided by KeyBank during the onboarding process and is only required for the POST method.

We like to keep it locked down. This field is not the same as your client credentials (part of your API keys needed to obtain an access token).

 

Psst...pass this note

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


get /rtp/v1/payment/healthCheck

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

header FIELDTYPEDESCRIPTION
X-CorrelationIdoptionalstringA universal ID to trace the transaction across all systems involved, useful for system logging and identification.
NAMETYPEDESCRIPTION
StatusoptionalstringThe status of the health check response.
SourceoptionalstringThe 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.
TimestampoptionalstringThe date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIpoptionalstringThe client IP address the gateway receives from the request.
X-Forwarded-ForoptionalstringThe sequence of the IP addresses for systems between the client and the gateway. Addresses are separated by a comma.

Response example (200)

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

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

Get the status of a wire transfer.

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

header FIELD TYPE DESCRIPTION
Acceptrequired string Acceptable media types for the response. Valid values: application/json, application/xml
X-CorrelationIdoptional string A universal ID to trace the transaction across all systems involved, useful for system logging and identification.
KeyClientIdoptional string KeyClientId is provided by KeyBank. This is a 32-character string that identifies you as the client.
path FIELD TYPE DESCRIPTION
transactionIdrequired string The unique ID number associated with the original payment request.

 

Request example

curl --location: 'https://partner-api-qv.keybank.com/rtp/v1/payment/status/transactionId/test123321'
--header 'X-CorrelationId: test987654'
--header 'KeyClientId: testwUhSQADUD4DwYyZz2hZkwLqsoFGK'
--header 'Accept: application/json'
--header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8'
          
NAME TYPE DESCRIPTION
statusrequired Object paymentStatus
transactionIdoptional string The unique ID number associated with the original payment request.
requestReferenceoptional string A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptional string A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional string A reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberoptional string Debit account number
creditAccountNumberoptional string Credit account number
valueDateoptional string The date (YYYY-MM-DD) the transfer occurred.
transferAmountoptional integer Amount of money to transfer in the correct currency format.
transferCurrencyoptional string Currency code for the transfer amount.
erroroptional Object paymentError
doddFrankoptional Object noYesType
clearingSystemReferenceoptional string Enter a reference value for the beneficiary. This value cannot exceed 140 characters.

Response example (200)

{
    "status": "COMPLETED",
    "transactionId": "US21052400000000",
    "requestReference": "RR-KEY-999999-01",
    "sendersReference": "SR-KEY-999999-01",
    "receiversReference": "INVC0054321",
    "debitAccountNumber": "12345",
    "creditAccountNumber": "987654321",
    "valueDate": "2023-05-08",
    "transferAmount": 10,
    "transferCurrency": "USD",
    "doddFrank": "NO"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (400)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "US21052400000000",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "status": "FAILED",
        "transactionId": "rrt-770941720727587-2383364-1",
        "requestReference": "RR-220818-01",
        "sendersReference": "SR-220818-01",
        "valueDate": 1683676800,
        "error": {
            "code": "KEY-1006",
            "title": "Required field missing",
            "description": "The object creditPartyBank is required in the request."
        }
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (401)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
    "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
    "TransactionTime": "2022-04-04T11:41:13.754Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-0006",
            "title": "Not authorized for requested service",
            "description": "Check your credentials."
        },
        "doddFrank": "NO"
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (403)

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

Response example (404)

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

Response example (405)

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

Response example (415)

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

Response example (429)

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

Response example (500)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "359681587523_SR-RMC-210729-11081",
    "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
    "TransactionTime": "2022-04-05T07:59:15.422Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-9999",
            "title": "Unknown error",
            "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials."
        },
        "doddFrank": "NO"
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend service",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (unexpected EOF at target). Please check with application support team before resubmitting the request"
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (504)

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

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

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

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

header FIELD TYPE DESCRIPTION
Acceptrequired string Acceptable media types for the response. Valid values: application/json, application/xml
X-CorrelationIdoptional string A universal ID to trace the transaction across all systems involved, useful for system logging and identification.
KeyClientIdoptional string KeyClientId is provided by KeyBank. This is a 32-character string that identifies you as the client.
path FIELD TYPE DESCRIPTION
debitAccountrequired string The debit account number of the originator.
referencerequired string The unique request reference number from the original payment request.

 

Request example

curl --location: 'https://partner-api-qv.keybank.com/rtp/v1/payment/status/debitAccount/12345/reference/RR-KEY-999999-01'
--header 'X-CorrelationId: test6543'
--header 'KeyClientId: testwUhSQADUD4DwYyZz2hZkwLqsoFGK'
--header 'Accept: application/json'
--header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8'
NAME TYPE DESCRIPTION
statusrequired Object paymentStatus
transactionIdoptional string The unique ID number associated with the original payment request.
requestReferenceoptional string A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptional string A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional string A reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberoptional string Debit account number
creditAccountNumberoptional string Credit account number
valueDateoptional string The date (YYYY-MM-DD) the transfer occurred.
transferAmountoptional integer Amount of money to transfer in the correct currency format.
transferCurrencyoptional string Currency code for the transfer amount.
erroroptional Object paymentError
doddFrankoptional Object noYesType
clearingSystemReferenceoptional string Enter a reference value for the beneficiary. This value cannot exceed 140 characters.

Response example (200)

{
    "status": "COMPLETED",
    "transactionId": "US21052400000000",
    "requestReference": "RR-KEY-999999-01",
    "sendersReference": "SR-KEY-999999-01",
    "receiversReference": "INVC0054321",
    "debitAccountNumber": "12345",
    "creditAccountNumber": "987654321",
    "valueDate": "2023-05-08",
    "transferAmount": 10,
    "transferCurrency": "USD",
    "doddFrank": "NO"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (400)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "US21052400000000",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "status": "FAILED",
        "transactionId": "rrt-770941720727587-2383364-1",
        "requestReference": "RR-220818-01",
        "sendersReference": "SR-220818-01",
        "valueDate": 1683676800,
        "error": {
            "code": "KEY-1006",
            "title": "Required field missing",
            "description": "The object creditPartyBank is required in the request."
        }
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (401)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
    "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
    "TransactionTime": "2022-04-04T11:41:13.754Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-0006",
            "title": "Not authorized for requested service",
            "description": "Check your credentials."
        },
        "doddFrank": "NO"
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (403)

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

Response example (404)

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

Response example (405)

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

Response example (415)

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

Response example (429)

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

Response example (500)

{
    "ErrorMessage": "Error received from backend service",
    "TransactionId": "359681587523_SR-RMC-210729-11081",
    "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
    "TransactionTime": "2022-04-05T07:59:15.422Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-9999",
            "title": "Unknown error",
            "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials."
        },
        "doddFrank": "NO"
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend service",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (unexpected EOF at target). Please check with application support team before resubmitting the request"
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (504)

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

post /rtp/v1/payment/initiate

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

header FIELD TYPE DESCRIPTION
Acceptrequired string Acceptable media types for the response. Valid values: application/json, application/xml
Content-Typerequired string Defines the content type of the API. Common content types are application/json or application/x-www-form-urlencoded.
X-CorrelationIdoptional string A universal ID to trace the transaction across all systems involved, useful for system logging and identification.
KeyClientIdrequired string KeyClientId is provided by KeyBank. This is a 32-character string that identifies you as the client.

 

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

Request example

{
    "requestedService": "WIRE",
    "requestReference": "AZX01234567891011",
    "type": "PAYMENT",
    "sendersReference": "INVC0012345",
    "receiversReference": "INVC0054321",
    "requestedValueDate": 1621814400,
    "debitParty": {
        "name": "YOUR COMPANY NAME HERE",
        "accountNumber": "001122334455"
    },
    "creditPartyBank": {
        "name": "BENEFICIARY BANK NAME",
        "aba": "000000000"
    },
    "creditParty": {
        "name": "BENEFICIARY NAME",
        "accountNumber": "987654321",
        "postalAddress": {
            "adrLine": [
                "BENEFICIARY ADDRESS LINE 1",
                "BENEFICIARY ADDRESS LINE 2"
            ]
        }
    },
    "transferAmount": 10,
    "transferCurrency": "USD"
}
NAME TYPE DESCRIPTION
statusrequired Object paymentStatus
transactionIdoptional string The unique ID number associated with the original payment request.
requestReferenceoptional string A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptional string A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional string A reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberoptional string Debit account number
creditAccountNumberoptional string Credit account number
valueDateoptional string The date (YYYY-MM-DD) the transfer occurred.
transferAmountoptional integer Amount of money to transfer in the correct currency format.
transferCurrencyoptional string Currency code for the transfer amount.
erroroptional Object paymentError
doddFrankoptional Object noYesType
clearingSystemReferenceoptional string Enter a reference value for the beneficiary. This value cannot exceed 140 characters.

Response example (200)

{
    "status": "IN_PROCESS",
    "transactionId": "US23050800214592",
    "requestReference": "AZX01234567891011",
    "sendersReference": "INVC0012345",
    "receiversReference": "INVC0054321",
    "debitAccountNumber": "001122334455",
    "creditAccountNumber": "987654321",
    "valueDate": "2023-05-08",
    "transferAmount": 10,
    "transferCurrency": "USD"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (400)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "US21052400000000",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "status": "FAILED",
        "transactionId": "rrt-770941720727587-2383364-1",
        "requestReference": "RR-220818-01",
        "sendersReference": "SR-220818-01",
        "valueDate": 1683676800,
        "error": {
            "code": "KEY-1006",
            "title": "Required field missing",
            "description": "The object creditPartyBank is required in the request."
        }
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (401)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
    "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
    "TransactionTime": "2022-04-04T11:41:13.754Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-0006",
            "title": "Not authorized for requested service",
            "description": "Check your credentials."
        },
        "doddFrank": "NO"
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (403)

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

Response example (404)

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

Response example (405)

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

Response example (415)

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

Response example (429)

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

Response example (500)

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

Response example (502)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (unexpected EOF at target). Please check with application support team before resubmitting the request"
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (504)

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

post /rtp/v1/payment/validate

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

header FIELD TYPE DESCRIPTION
Acceptrequired string Acceptable media types for the response. Valid values: application/json, application/xml
Content-Typerequired string Defines the content type of the API. Common content types are application/json or application/x-www-form-urlencoded.
X-CorrelationIdoptional string A universal ID to trace the transaction across all systems involved, useful for system logging and identification.
KeyClientIdrequired string KeyClientId is provided by KeyBank. This is a 32-character string that identifies you as the client.
BODY FIELD TYPE DESCRIPTION
requestedServicerequired string The type of payment transaction. The transaction request is valid only for the API products with granted access. Valid values: RTP, WIRE
requestReferencerequired string A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
typerequired string Indicates if the transaction type is a PAYMENT or a DRAFT.
requestedValueDaterequired string Date (YYYY-MM-DD) the transfer will occur.
originatorReferenceoptional string An additional reference value that is meaningful to the party originating the payment.
sendersReferencerequired string A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional string A reference value for the beneficiary. This value cannot exceed 140 characters.
bankToBankInstructionsoptional string Area to share messages or instructions from one bank to another bank.
ultimateDebitPartyoptional Object ultParty
debitPartyrequired Object party
debitPartyBankoptional Object party
intermediaryBank1optional Object party
intermediaryBank2optional Object party
intermediaryBank3optional Object party
creditPartyBankrequired Object party
creditPartyrequired Object party
transferAmountrequired number Amount of money to transfer in the correct currency format.
transferCurrencyrequired string Currency code for the transfer amount.
externalTemplateNameoptional string TBD
customDataoptional string The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

 

Request example

{
    "requestedService": "WIRE",
    "requestReference": "AZX01234567891011",
    "type": "PAYMENT",
    "requestedValueDate": 1621814400,
    "originatorReference": "",
    "sendersReference": "INVC0012345",
    "receiversReference": "INVC0054321",
    "ultimateDebitParty": {
        "name": ""
    },
    "debitParty": {
        "name": "YOUR COMPANY NAME HERE",
        "accountNumber": "001122334455"
    },
    "debitPartyBank": {
        "name": ""
    },
    "creditPartyBank": {
        "name": "BENEFICIARY BANK NAME",
        "aba": "000000000"
    },
    "creditParty": {
        "name": "BENEFICIARY NAME",
        "accountNumber": "987654321",
        "postalAddress": {
            "adrLine": [
                "BENEFICIARY ADDRESS LINE 1",
                "BENEFICIARY ADDRESS LINE 2"
            ]
        }
    },
    "transferAmount": 10,
    "transferCurrency": "USD",
    "customData": ""
}
NAME TYPE DESCRIPTION
statusrequired Object paymentStatus
transactionIdoptional string The unique ID number associated with the original payment request.
requestReferenceoptional string A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptional string A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional string A reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberoptional string Debit account number
creditAccountNumberoptional string Credit account number
valueDateoptional string The date (YYYY-MM-DD) the transfer occurred.
transferAmountoptional integer Amount of money to transfer in the correct currency format.
transferCurrencyoptional string Currency code for the transfer amount.
erroroptional Object paymentError
doddFrankoptional Object noYesType
clearingSystemReferenceoptional string Enter a reference value for the beneficiary. This value cannot exceed 140 characters.

Response example (200)

{
    "status": "VALID",
    "transactionId": "XZ23050714000000",
    "requestReference": "testWBB25889710252",
    "sendersReference": "INVC0012345",
    "receiversReference": "INVC0054321",
    "debitAccountNumber": "12345",
    "creditAccountNumber": "987654321",
    "transferAmount": 10,
    "transferCurrency": "USD"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (400)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "US21052400000000",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "status": "FAILED",
        "transactionId": "rrt-770941720727587-2383364-1",
        "requestReference": "RR-220818-01",
        "sendersReference": "SR-220818-01",
        "valueDate": 1683676800,
        "error": {
            "code": "KEY-1006",
            "title": "Required field missing",
            "description": "The object creditPartyBank is required in the request."
        }
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (401)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
    "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
    "TransactionTime": "2022-04-04T11:41:13.754Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-0006",
            "title": "Not authorized for requested service",
            "description": "Check your credentials."
        },
        "doddFrank": "NO"
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (403)

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

Response example (404)

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

Response example (405)

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

Response example (415)

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

Response example (429)

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

Response example (500)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "359681587523_SR-RMC-210729-11081",
    "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
    "TransactionTime": "2022-04-05T07:59:15.422Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-9999",
            "title": "Unknown error",
            "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials."
        },
        "doddFrank": "NO"
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (unexpected EOF at target). Please check with application support team before resubmitting the request"
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend service.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (504)

{
    "ErrorMessage": "Your request took too long to process. Please try again.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request."
    }
}
NAMETYPEDESCRIPTION
ConnectErroroptionalstringAPI connectivity error information, if available.
NAMETYPEDESCRIPTION
ErrorMessageoptionalstringA human-readable message that describes the type or source of the error.
TransactionIdoptionalstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptionalstringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptionaloneOfserviceErrorData connectError
NAMETYPEDESCRIPTION
StatusoptionalstringThe status of the health check response.
SourceoptionalstringThe 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.
TimestampoptionalstringThe date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIpoptionalstringThe client IP address the gateway receives from the request.
X-Forwarded-ForoptionalstringThe sequence of the IP addresses for systems between the client and the gateway. Addresses are separated by a comma.
NAMETYPEDESCRIPTION
noYesTypeoptionalstringThis field indicates whether the transaction qualifies for Dodd-Frank.
NAMETYPEDESCRIPTION
countrequiredstringThe count of records that match the initial query.
limitrequiredintegerThe maximum number of records returned in the response.
offsetrequiredintegerThe number of records skipped before the response is returned.
partiesoptionalObjectparty
NAME TYPE DESCRIPTION
namerequired string Name of the party. This can be an individual, a financial institution, or a beneficiary. The name cannot exceed 140 characters.
accountNumberoptional string Account number of the party.
abaoptional string If the party is a financial institution, this is the ABA number or routing number.
bicoptional string The bank identifier code (BIC) for the party. This is a combination code that identifies the bank, country, location, and possibly the bank branch.
txidoptional string The tax identification number for the party.
adrLineoptional array An unstructured address line. You can have up to three lines of text.
NAMETYPEDESCRIPTION
coderequiredstringStatus code assigned to each error type.
titlerequiredstringBrief title about the error associated with the status code.
descriptionoptionalstringDescription of the error.
detailoptionalObjectdetail
NAMETYPEDESCRIPTION
coderequiredstringA static code assigned by the network or payment system.
titlerequiredstringBrief title about the error associated with the status code.
descriptionoptionalstringDescription of the error.
NAMETYPEDESCRIPTION
requestedServicerequiredstringThe type of payment transaction. The transaction request is valid only for the API products with granted access. Valid values: RTP, WIRE
requestReferencerequiredstringA reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
typerequiredstringIndicates if the transaction type is a PAYMENT or a DRAFT.
requestedValueDaterequiredstringDate (YYYY-MM-DD) the transfer will occur.
originatorReferenceoptionalstringAn additional reference value that is meaningful to the party originating the payment.
sendersReferencerequiredstringA reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptionalstringA reference value for the beneficiary. This value cannot exceed 140 characters.
bankToBankInstructionsoptionalstringArea to share messages or instructions from one bank to another bank.
ultimateDebitPartyoptionalObjectultParty
debitPartyrequiredObjectparty
debitPartyBankoptionalObjectparty
intermediaryBank1optionalObjectparty
intermediaryBank2optionalObjectparty
intermediaryBank3optionalObjectparty
creditPartyBankrequiredObjectparty
creditPartyrequiredObjectparty
transferAmountrequirednumberAmount of money to transfer in the correct currency format.
transferCurrencyrequiredstringCurrency code for the transfer amount.
externalTemplateNameoptionalstringTBD
customDataoptionalstringThe 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.
NAMETYPEDESCRIPTION
statusrequiredObjectpaymentStatus
transactionIdoptionalstringThe unique ID number associated with the original payment request.
requestReferenceoptionalstringA reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptionalstringA reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptionalstringA reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberoptionalstringDebit account number
creditAccountNumberoptionalstringCredit account number
valueDateoptionalstringThe date (YYYY-MM-DD) the transfer occurred.
transferAmountoptionalintegerAmount of money to transfer in the correct currency format.
transferCurrencyoptionalstringCurrency code for the transfer amount.
erroroptionalObjectpaymentError
doddFrankoptionalObjectnoYesType
clearingSystemReferenceoptionalstringEnter a reference value for the beneficiary. This value cannot exceed 140 characters.
NAMETYPEDESCRIPTION
paymentStatusoptionalstringThe status of the payment transaction. Valid values: IN_PROCESS, IN_REVIEW, COMPLETED, FAILED, RETURNED, ERROR, VALID
NAMETYPEDESCRIPTION
statusrequiredObjectpaymentStatus
transactionIdoptionalstringThe unique ID number associated with the original payment request.
requestReferenceoptionalstringA reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferenceoptionalstringA reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptionalstringThe sender reference value from the original request. This is useful for traceability and reporting.
debitAccountNumberoptionalstringThe sender reference value from the original request. This is useful for traceability and reporting.
creditAccountNumberoptionalstringThe sender reference value from the original request. This is useful for traceability and reporting.
valueDateoptionalstringThe date (YYYY-MM-DD) the transferred occurred.
erroroptionalObjectpaymentError
doddFrankoptionalObjectnoYesType
NAMETYPEDESCRIPTION
nameoptionalstringTypically this is the name of the party that instructed the debit party to initiate a payment. This value cannot exceed 140 characters.

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

For more information about errors, see Error handling.

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

CODE MESSAGE

KEY-0001

Not authorized

KEY-0002

Not authorized for requested action

KEY-0003

Request exceeds authorized limit

KEY-0004

Unauthorized for account

KEY-0005

Internal use only fields

KEY-0006

Not authorized for requested service

KEY-0008 NSF

KEY-1000

Transformation Error

KEY-1001

Invalid Data

KEY-1002

Invalid Bank Identifier

KEY-1003

Invalid or unknown template

KEY-1004

Invalid account

KEY-1005

Invalid Currency

KEY-1006

Required field missing

KEY-1007

Transaction Not Found

KEY-1008

Insufficient Funds

KEY-1009

Account has restrictions

KEY-1010

Duplicate Request

KEY-1011

Payor Account Restrictions

KEY-1012

Payee Account Restrictions

KEY-3003

Payment network timeout. Please retry.

KEY-3004

Payment rejected by payment network

KEY-9997

Failed payment review

KEY-9998

Payment failed during processing

KEY-9999

Unknown error

 

API-specific error example

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

YAML file