RTP Send Payment

clock 5-minute read calender 1.2.2 | updated Apr. 24, 2024

Transfer money immediately and at any time

What you can do Endpoint
Health check get /rtp/v1/payment/healthCheck
Get a list of RTP participants get /rtp/v1/payment/rtp/participant
Get information about one RTP participant get /rtp/v1/payment/rtp/participant/{routingNumber}
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 real-time payment 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.

You can initiate a real-time payment, check on its status, and get information about participating parties.

RTP stands for Real-Time Payment. It is a modern payment system that enables immediate and real-time fund transfers between financial institution or individuals. RTP transactions use the clearing house’s RTP network, which operates 24/7, allowing for instant payment settlement. RTP payments are often used for person-to person transfers, bill payments, and business-to-business transactions.

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.

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).


get /rtp/v1/payment/healthCheck

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

header FIELDTYPEDESCRIPTION
X-CorrelationIdoptionalstringA unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
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)

copylink
{
    "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/rtp/participant

Retrieve a list of active, online RTP banks. Use the limit and offset fields to control how many records to return and what records to skip.

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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
KeyClientIdoptional string KeyClientId is provided by KeyBank. This is a 32-character string that identifies you as the client.
query FIELD TYPE DESCRIPTION
limitrequired integer Pagination parameter that indicates the maximum number of records to return in the response.
offsetrequired integer Pagination parameter that indicates the number of records skipped before generating the output.

Request example

curl --location: 'https://partner-api-qv.keybank.com/rtp/v1/payment/rtp/participant?limit=15&offset=0'
--header 'X-CorrelationId: test987654'
--header 'KeyClientId: testwUhSQADUD4DwYyZz2hZkwLqsoFGK'
--header 'Accept: application/json'
--header 'Bearer testZcKJDWnwDWmmf9qah6PJvPy8'
NAME TYPE DESCRIPTION
countrequired string The count of records that match the initial query.
limitrequired integer The maximum number of records returned in the response.
offsetrequired integer The number of records skipped before the response is returned.
partiesoptional Object party

Response example (200)

copylink
{
    "count": "65",
    "limit": 10,
    "offset": 0,
    "parties": {
        "name": "CITIZENS BANK, NA",
        "accountNumber": "102258001",
        "aba": "100001995",
        "bic": "CITZUSL2XXX",
        "txid": "fa1354bkg3153kj13b4h34",
        "foreignBankSystemId": {
            "type": "USABA"
        },
        "postalAddress": {
            "adrLine": [
                "BENEFICIARY ADDRESS LINE 1",
                "BENEFICIARY ADDRESS LINE 2"
            ]
        }
    }
}
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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "359681587523_SR-RMC-210729-11081",
    "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
    "TransactionTime": "2022-04-05T07:59:15.422Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "RR-RMC-210720-0123458981",
        "sendersReference": "SR-RMC-210729-11081",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-9999",
            "title": "Unknown error",
            "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials.",
            "detail": {
                "code": "KEY-9999",
                "title": "Unknown error",
                "description": "Additional information about error code."
            }
        },
        "doddFrank": "NO"
    }
}
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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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/rtp/participant/{routingNumber}

This call returns information about a single RTP participant. Use the routing number of the financial institution to search for the RTP participant.

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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
KeyClientIdoptional string KeyClientId is provided by KeyBank. This is a 32-character string that identifies you as the client.
path FIELD TYPE DESCRIPTION
routingNumberrequired string Routing number of the participating RTP bank.

Request example

curl --location: 'https://partner-api-qv.keybank.com/rtp/v1/payment/rtp/participant/12345678
--header 'X-CorrelationId: test987654'
--header 'KeyClientId: testwUhSQADUD4DwYyZz2hZkwLqsoFGK'
--header 'Accept: application/json'
--header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8'
NAME TYPE DESCRIPTION
namerequired string Name of the party. This can be an individual, a financial institution, or a beneficiary. The name cannot exceed 140 characters.
accountNumberoptional string Account number of the party.
abaoptional string If the party is a financial institution, this is the ABA number or routing number.
bicoptional string The bank identifier code (BIC) for the party. This is a combination code that identifies the bank, country, location, and possibly the bank branch.
txidoptional string The tax identification number for the party.
foreignBankSystemIdoptional Object foreignBankSystemType
adrLineoptional array An unstructured address line. You can have up to three lines of text.

Response example (200)

copylink
{
    "name": "KeyBank National Association",
    "accountNumber": "8756654",
    "aba": "125200879",
    "bic": "KEYUSL2XXX",
    "txid": "fa125da513hj135j42b5",
    "foreignBankSystemId": {
        "type": "USABA"
    },
    "postalAddress": {
        "adrLine": [
            "123 Keybank Street",
            "Cleveland, OH"
        ]
    }
}
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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

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

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

Get the status of a RTP payment or 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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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

Initiate a RTP payment. Use the requestedService parameter to define the transaction as RTP or 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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
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

copylink
{
    "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"
}
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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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)

copylink
{
    "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 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 unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
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
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.

Request example

copylink
{
    "requestedService": "RTP",
    "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": ""
}
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.

Response example (200)

copylink
{
    "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)

copylink
{
    "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."
        }
    }
}
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)

copylink
{
    "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"
    }
}
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)

copylink
{
    "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)

copylink
{
    "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"
}
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)

copylink
{
    "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"
}
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)

copylink
{
    "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"
}
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)

copylink
{
    "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"
}
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)

copylink
{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "359681587523_SR-RMC-210729-11081",
    "X-CorrelationId": "7ad7fdfb-2ade-a3ab-b97c-523dc5312688",
    "TransactionTime": "2022-04-05T07:59:15.422Z",
    "ServiceError": {
        "status": "ERROR",
        "transactionId": "rrt-621075741872460927",
        "requestReference": "REQUEST-REF-220314.1",
        "sendersReference": "SENDER-REF-220314.1",
        "valueDate": "06-10-2023",
        "error": {
            "code": "KEY-9999",
            "title": "Unknown error",
            "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials.",
            "detail": {
                "code": "KEY-1005",
                "title": "Error",
                "description": "Additional information about error code."
            }
        },
        "doddFrank": "NO"
    }
}
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)

copylink
{
    "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"
    }
}
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)

copylink
{
    "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)

copylink
{
    "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.
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
NAMETYPEDESCRIPTION
typeoptionalstringThe five-digit global routing code for a foreign financial institution.
idoptionalstringThe identification number associated with the foreign financial institution.
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
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.
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
paymentStatusoptionalstringThe status of the payment transaction. Valid values: IN_PROCESS, IN_REVIEW, 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
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
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 or FAILED. 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 signify a failed payment that could have been caused by account restrictions, network timeout, or invalid data in the request.

CODE MESSAGE

KEY-0001

Not authorized

KEY-0002

Not authorized for requested action

KEY-0003

Request exceeds authorized limit

KEY-0004

Unauthorized for account

KEY-0005

Internal use only fields

KEY-0006

Not authorized for requested service

KEY-1000

Transformation Error

KEY-1001

Invalid Data

KEY-1002

Invalid Bank Identifier

KEY-1003

Invalid or unknown template

KEY-1004

Invalid account

KEY-1005

Invalid Currency

KEY-1006

Required field missing

KEY-1007

Transaction Not Found

KEY-1008

Insufficient Funds

KEY-1009

Account has restrictions

KEY-1010

Duplicate Request

KEY-1011

Payor Account Restrictions

KEY-1012

Payee Account Restrictions

KEY-3001

Exceeds transaction limit for RTP transactions

KEY-3002

Field not usable for RTP transactions

KEY-3003

Payment network timeout. Please retry.

KEY-3004

Payment rejected by payment network

KEY-9997

Failed payment review

KEY-9998

Payment failed during processing

KEY-9999

Unknown error

 

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 download