Wire Origination

33-minute read 1.1.5 | updated Sep. 26, 2023

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

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

At KeyBank, the RTP and wire payment APIs are a single API product with two service capabilities. You need specific permissions to access either the RTP Send Payment API or the Wires Origination API. The main difference between RTP payments and wire transfers is in their speed and settlement process. RTP payments are designed for real-time transfers, providing immediate availability of funds, while wire transfers may take longer to process and settle.

All KeyBank APIs require certificates, user credentials, and certain permissions. Before you begin, see Key concepts to learn more about these fundamental elements as well as other recommended best practices.

KeyBank client ID

The KeyBank client ID is a 32-character string that identifies you as the client. The KeyClientId value is provided by KeyBank during the onboarding process. This is required for all requests.

Payment chain parties

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

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

 

Custom data

Custom data in APIs provides the ability to send or receive data that is specific to your application or use case. The custom data feature is available when you send or validate a payment. Define the custom data in the request payload. It is a free-form text field that can contain up to 500 alphanumeric characters that you can use however you like - for invoice number, product number, customer number, date/time stamp, etc. KeyBank recommends the common custom data format of name:value pairs. You can list multiple name:value pairs in the custom data field within the 500-character limit. The custom data fields will return exactly what is sent; it does not parse name:value pairs within the API response. The custom data should not contain any personal identifiable information (PII).

Custom data examples

//Example of name:value pairs
customData: Type:DD; Status:Submitted; POnumber:12556 

//Example of regular text 
customData: General products 

//Example of timestamp 
customData: 05-MAR-2023:12:19:53EST

 

Custom data is only available within the API product suite, meaning Wire Origination and Wire Inquiry APIs. Custom data is not transmitted with the payment and is not visible to the recipient or any of the participating parties. The custom data is only visible and accessible from the originator with our Wire Inquiry API, where you can query wire transfers using the transactionId to retrieve the custom data. The customData field returns any custom values that were part of the payment request stored for recall after a successful wire transaction completes. If no custom data is defined, the response returns an empty field.

It may be best to first call with the normal request payload to determine how to best use the custom data field. Review the response and determine which values are best to include and use in future queries.

 
Summary Endpoint
Get the status with the transaction ID get /rtp/v1/payment/status/transactionId/{transactionId}
Get the status with the request reference number get /rtp/v1/payment/status/debitAccount/{debitAccount}/reference/{reference}
Send a wire transfer post /rtp/v1/payment/initiate
Perform validation checks post /rtp/v1/payment/validate

get /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

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": "Please make sure your request is correct and try again.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "US21052400000000",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "status": "FAILED",
        "requestReference": "RR-220818-01",
        "sendersReference": "SR-220818-01",
        "valueDate": 1586563200,
        "error": {
            "code": "KEY-1006",
            "title": "Required field missing",
            "description": "Object creditPartyBank is required",
            "detail": {
                "code": "KEY-1006",
                "title": "Required field missing",
                "description": "Object creditPartyBank is required"
            }
        }
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (401)

{
    "ErrorMessage": "Please make sure you're using the correct credentials. Then log in again.",
    "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
    "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
    "TransactionTime": "2022-04-04T11:41:13.754Z",
    "ServiceError": {
        "status": "ERROR",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": 1615766400,
        "error": {
            "code": "KEY-0006",
            "title": "Not authorized for requested service",
            "description": "Additional information.",
            "detail": {
                "code": "KEY-0006",
                "title": "Not authorized for requested service",
                "description": "Additional information."
            }
        }
    }
}
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": "We can't seem to find what you're looking for. Please verify the resource and try again.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (405)

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

Response example (415)

{
    "ErrorMessage": "We currently don't support that format. Please check the format type defined in your request and try again. ",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (429)

{
    "ErrorMessage": "Looks like you've sent too many requests. Please wait a moment and try again later.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (500)

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

Response example (502)

{
    "ErrorMessage": "Looks like something went wrong. Submit your request again.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (unexpected EOF at target). Please check with application support team before resubmitting the request"
    }
}
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

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-621075741872460927",
        "requestReference": "RR-220818-01",
        "sendersReference": "SR-220818-01",
        "valueDate": 1654819200,
        "error": {
            "code": "KEY-1006",
            "title": "Unknown error",
            "description": "Object creditPartyBank is required",
            "detail": {
                "code": "KEY-1006",
                "title": "Unknown error",
                "description": "Additional information about error code."
            }
        },
        "doddFrank": "NO"
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (401)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
    "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
    "TransactionTime": "2022-04-04T11:41:13.754Z",
    "ServiceError": {
        "status": "ERROR",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": 1664928000,
        "error": {
            "code": "KEY-0006",
            "title": "Not authorized for requested service",
            "description": "Additional information here.",
            "detail": {
                "code": "KEY-0006",
                "title": "Not authorized for requested service",
                "description": "Additional information here."
            }
        },
        "doddFrank": "NO"
    }
}
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": "We can't seem to find what you're looking for. Please verify the resource and try again.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (405)

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

Response example (415)

{
    "ErrorMessage": "We currently don't support that format. Please check the format type defined in your request and try again. ",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (429)

{
    "ErrorMessage": "Looks like you've sent too many requests. Please wait a moment and try again later.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (500)

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

Response example (502)

{
    "ErrorMessage": "Looks like something went wrong. Submit your request again.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (unexpected EOF at target). Please check with application support team before resubmitting the request"
    }
}
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."
    }
}

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
requestReferenceoptional string A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
typerequired string Indicate if the transaction type is a PAYMENT or a DRAFT.
requestedValueDateoptional string Date (YYYY-MM-DD) the transfer will occur.
originatorReferenceoptional string An additional reference value that is meaningful to the party originating the payment.
sendersReferencerequired string A reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferenceoptional string A reference value for the beneficiary. This value cannot exceed 140 characters.
ultimateDebitPartyoptional Object ultParty
debitPartyoptional Object party
debitPartyBankoptional Object party
creditPartyBankoptional Object party
creditPartyoptional Object party
transferAmountrequired number Amount of money to transfer in the correct currency format.
transferCurrencyrequired string Currency code for the transfer amount.
customDataoptional string The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

Request example

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

Response example (200)

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

Response example (400)

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

Response example (401)

{
    "ErrorMessage": "Please make sure you're using the correct credentials. Then log in again.",
    "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
    "TransactionTime": "2022-04-04T11:41:13.754Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-0006",
            "title": "Not authorized for requested service",
            "description": "Check your credentials.",
            "detail": {
                "code": "KEY-1001",
                "title": "No access",
                "description": "Additional information about error code."
            }
        },
        "doddFrank": "NO"
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (403)

{
    "ErrorMessage": "You don't have access to this resource. Contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (404)

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

Response example (405)

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

Response example (415)

{
    "ErrorMessage": "We currently don't support that format. Please check the format type defined in your request and try again. ",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (429)

{
    "ErrorMessage": "Looks like you've sent too many requests. Please wait a moment and try again later.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (500)

{
    "ErrorMessage": "Looks like something went wrong. Please try again when you're ready. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "TransactionId": "359681587523_SR-RMC-210729-11081",
    "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
    "TransactionTime": "2022-04-05T07:59:15.422Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-9999",
            "title": "Unknown error",
            "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials.",
            "detail": {
                "code": "KEY-9999",
                "title": "Unknown error",
                "description": "Additional information about error code."
            }
        },
        "doddFrank": "NO"
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (502)

{
    "ErrorMessage": "Looks like something went wrong. Please try again when you're ready. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "A connectivity error occurred with the downstream service (unexpected end of file at the target). Please check with your KeyBank Client Success Manager or email developers@keybank.com before trying the request again."
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (503)

{
    "ErrorMessage": "Looks like something went wrong. Please try again later. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "This service is currently unavailable(there are no active targets). Please check with your KeyBank Client Success Manager or email developers@keybank.com before trying the request again."
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (504)

{
    "ErrorMessage": "Your request took too long to process. Please try again. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Request could not be processed on time (gateway timeout). Please wait a moment and resubmit the request."
    }
}

post /rtp/v1/payment/validate

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

header FIELDTYPEDESCRIPTION
AcceptrequiredstringAcceptable media types for the response. Valid values: application/json, application/xml
Content-TyperequiredstringDefines the content type of the API. Common content types are application/json or application/x-www-form-urlencoded.
X-CorrelationIdoptionalstringA universal ID to trace the transaction across all systems involved, useful for system logging and identification.
KeyClientIdrequiredstringKeyClientId is provided by KeyBank. This is a 32-character string that identifies you as the client.
BODY FIELDTYPEDESCRIPTION
requestedServicerequiredstringThe type of payment transaction. The transaction request is valid only for the API products with granted access. Valid values: RTP, WIRE
requestReferenceoptionalstringA 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.
requestedValueDateoptionalstringDate (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.
ultimateDebitPartyoptionalObjectultParty
debitPartyoptionalObjectparty
debitPartyBankoptionalObjectparty
creditPartyBankoptionalObjectparty
creditPartyoptionalObjectparty
transferAmountrequirednumberAmount of money to transfer in the correct currency format.
transferCurrencyrequiredstringCurrency code for the transfer amount.
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.

Request example

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

Response example (200)

{
    "status": "VALID",
    "transactionId": "XZ23050714000000",
    "requestReference": "testWBB25889710252",
    "sendersReference": "INVC0012345",
    "receiversReference": "INVC0054321",
    "debitAccountNumber": "12345",
    "creditAccountNumber": "987654321",
    "transferAmount": 10,
    "transferCurrency": "USD"
}
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

Response example (400)

{
    "ErrorMessage": "Please make sure your request is correct and try again.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "US21052400000000",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "status": "FAILED",
        "transactionId": "rrt-770941720727587-2383364-1",
        "requestReference": "RR-220818-01",
        "sendersReference": "SR-220818-01",
        "valueDate": 1683676800,
        "error": {
            "code": "KEY-1006",
            "title": "Required field missing",
            "description": "The object creditPartyBank is required in the request.",
            "detail": {
                "code": "KEY-1006",
                "title": "Required field missing",
                "description": "The object creditPartyBank is required in the request."
            }
        }
    }
}
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

Response example (401)

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

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"
}
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

Response example (404)

{
    "ErrorMessage": "We can't seem to find what you're looking for. Please verify the resource and try again.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
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

Response example (405)

{
    "ErrorMessage": "Looks like something went wrong. Please check your request method and try again.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
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

Response example (415)

{
    "ErrorMessage": "We currently don't support that format. Please check the format type defined in your request and try again. ",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
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

Response example (429)

{
    "ErrorMessage": "Looks like you've sent too many requests. Please wait a moment and try again later.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
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

Response example (500)

{
    "ErrorMessage": "Looks like something went wrong. Please try again when you're ready.",
    "TransactionId": "359681587523_SR-RMC-210729-11081",
    "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
    "TransactionTime": "2022-04-05T07:59:15.422Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-9999",
            "title": "Unknown error",
            "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials.",
            "detail": {
                "code": "KEY-9999",
                "title": "Unknown error",
                "description": "Additional information about error code."
            }
        },
        "doddFrank": "NO"
    }
}
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

Response example (502)

{
    "ErrorMessage": "Looks like something went wrong. Submit your request again.",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (unexpected EOF at target). Please check with application support team before resubmitting the request"
    }
}
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

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."
    }
}
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

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
typeoptionalstringThe five-digit global routing code for a foreign financial institution.
idoptionalstringThe identification number associated with the foreign financial institution.
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
NAMETYPEDESCRIPTION
namerequiredstringName of the party. This can be an individual, a financial institution, or a beneficiary. The name cannot exceed 140 characters.
accountNumberoptionalstringAccount number of the party.
abaoptionalstringIf the party is a financial institution, this is the ABA number or routing number.
bicoptionalstringThe bank identifier code (BIC) for the party. This is a combination code that identifies the bank, country, location, and possibly the bank branch.
txidoptionalstringThe tax identification number for the party.
foreignBankSystemIdoptionalObjectforeignBankSystemType
adrLineoptionalarrayAn 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
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
paymentStatusoptionalstringThe status of the payment transaction. Valid values: IN PROCESS, COMPLETED, FAILED, RETURNED, ERROR, VALID
NAMETYPEDESCRIPTION
requestedServicerequiredstringThe type of payment transaction. The transaction request is valid only for the API products with granted access. Valid values: RTP, WIRE
requestReferenceoptionalstringA reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
typerequiredstringIndicate if the transaction type is a PAYMENT or a DRAFT.
requestedValueDateoptionalstringDate (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.
ultimateDebitPartyoptionalObjectultParty
debitPartyoptionalObjectparty
debitPartyBankoptionalObjectparty
creditPartyBankoptionalObjectparty
creditPartyoptionalObjectparty
transferAmountrequirednumberAmount of money to transfer in the correct currency format.
transferCurrencyrequiredstringCurrency code for the transfer amount.
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
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.
valueDateoptionalstringThe date (YYYY-MM-DD) the transferred occurred.
erroroptionalObjectpaymentError
doddFrankoptionalObjectnoYesType
NAMETYPEDESCRIPTION

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

For more information about errors, see Error handling.

API-specific error messages

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

KEYBANK CODES AND MESSAGES

CODE MESSAGE

KEY-0001

Not authorized

KEY-0002

Not authorized for requested action

KEY-0003

Request exceeds authorized limit

KEY-0004

Unauthorized for account

KEY-0005

Internal use only fields

KEY-0006

Not authorized for requested service

KEY-0008 NSF

KEY-1000

Transformation Error

KEY-1001

Invalid Data

KEY-1002

Invalid Bank Identifier

KEY-1003

Invalid or unknown template

KEY-1004

Invalid account

KEY-1005

Invalid Currency

KEY-1006

Required field missing

KEY-1007

Transaction Not Found

KEY-1008

Insufficient Funds

KEY-1009

Account has restrictions

KEY-1010

Duplicate Request

KEY-1011

Payor Account Restrictions

KEY-1012

Payee Account Restrictions

KEY-3001

Exceeds transaction limit for RTP transactions

KEY-3002

Field not usable for RTP transactions

KEY-3003

Payment network timeout. Please retry.

KEY-3004

Payment rejected by payment network

KEY-9997

Failed payment review

KEY-9998

Payment failed during processing

KEY-9999

Unknown error

 

 

 

 

 

API-specific error example

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

YAML file