RTP Send Payment

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

Transfer money immediately and at any time with RTP Send Payment. 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.

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 only required for POST requests to initiate or validate a payment.

Payment chain parties

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

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

 

RTP Payments API Endpoints

Summary Endpoint
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

Get a list of RTP participants

get /rtp/v1/payment/rtp/participant

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

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.

Request

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

Responses

Successful response

NAME TYPE DESCRIPTION
countrequired string The count of records that match the initial query.
limitrequired integer The maximum number of records returned in the response.
offsetrequired integer The number of records skipped before the response is returned.
partiesoptional Object party

Response example (200)

{
    "count": "65",
    "limit": 10,
    "offset": 0,
    "parties": {
        "name": "CITIZENS BANK, NA",
        "accountNumber": "102258001",
        "aba": "100001995",
        "bic": "CITZUSL2XXX",
        "txid": "fa1354bkg3153kj13b4h34",
        "foreignBankSystemId": {
            "type": "USABA"
        },
        "postalAddress": {
            "adrLine": [
                "BENEFICIARY ADDRESS LINE 1",
                "BENEFICIARY ADDRESS LINE 2"
            ]
        }
    }
}

Missing data

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

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

Access denied

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

Not found

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

Request method denied

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

Media type not supported

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

Too many requests

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

Internal server error

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

Bad gateway

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

Service unavailable

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

Gateway timeout

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 information about one RTP participant

get /rtp/v1/payment/rtp/participant/{routingNumber}

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

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.

Request

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
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'

Responses

Successful response

NAME TYPE DESCRIPTION
namerequired string Name of the party. This can be an individual, a financial institution, or a beneficiary. The name 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)

{
    "name": "KeyBank National Association",
    "accountNumber": "8756654",
    "aba": "125200879",
    "bic": "KEYUSL2XXX",
    "txid": "fa125da513hj135j42b5",
    "foreignBankSystemId": {
        "type": "USABA"
    },
    "postalAddress": {
        "adrLine": [
            "123 Keybank Street",
            "Cleveland, OH"
        ]
    }
}

Missing data

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

Unauthorized request

NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (401)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
    "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
    "TransactionTime": "2022-04-04T11:41:13.754Z",
    "ServiceError": {
        "status": "ERROR",
        "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"
    }
}

Access denied

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

Not found

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

Request method denied

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

Media type not supported

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

Too many requests

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

Internal server error

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": "RR-RMC-210720-0123458981",
        "sendersReference": "SR-RMC-210729-11081",
        "valueDate": 1654905600,
        "error": {
            "code": "KEY-9999",
            "title": "Unknown error",
            "description": "Payment Initiation ServiceException: AUTHENTICATION_FAILURE Unable to logon with the supplied credentials.",
            "detail": {
                "code": "KEY-9999",
                "title": "Unknown error",
                "description": "Additional information about error code."
            }
        },
        "doddFrank": "NO"
    }
}

Bad gateway

NAME TYPE DESCRIPTION
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"
    }
}

Service unavailable

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

Gateway timeout

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 the status with the transaction ID

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.

Request

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'

Responses

Successful response

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

Missing data

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

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

Access denied

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

Not found

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

Request method denied

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

Media type not supported

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

Too many requests

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

Internal server error

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

Bad gateway

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

Service unavailable

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

Gateway timeout

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 the status with the request reference number

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.

Request

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'

Responses

Successful response

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

Missing data

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

Unauthorized request

NAME TYPE DESCRIPTION
ErrorMessageoptional string A human-readable message that describes the type or source of the error.
TransactionIdoptional string A unique transaction ID returned with the response, useful for traceability.
TransactionTimeoptional string Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (401)

{
    "ErrorMessage": "Error received from backend service.",
    "TransactionId": "rrt-621075741872460927-c-gce-9129-15867185-4",
    "X-CorrelationId": "80457bcb-2c3b-8c55-8cd6-3520c3157e8f",
    "TransactionTime": "2022-04-04T11:41:13.754Z",
    "ServiceError": {
        "status": "ERROR",
        "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"
    }
}

Access denied

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

Not found

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

Request method denied

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

Media type not supported

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

Too many requests

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

Internal server error

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

Bad gateway

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

Service unavailable

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

Gateway timeout

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

Send a real-time payment

post /rtp/v1/payment/initiate

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

Request

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

Responses

Successful response

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

Missing data

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

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

Access denied

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

Not found

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

Request method denied

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

Media type not supported

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

Too many requests

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

Internal server error

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

Bad gateway

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

Service unavailable

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

Gateway timeout

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

Perform validation checks

post /rtp/v1/payment/validate

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

Request

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

Responses

Successful response

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

Missing data

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

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

Access denied

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

Not found

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

Request method denied

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

Media type not supported

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

Too many requests

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

Internal server error

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

Bad gateway

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

Service unavailable

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

Gateway timeout

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

Schemas

connectError

NAMETYPEDESCRIPTION
ConnectErroroptionalstringAPI connectivity error information, if available.

exception

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

foreignBankSystemType

NAMETYPEDESCRIPTION
typeoptionalstringThe five-digit global routing code for a foreign financial institution.
idoptionalstringThe identification number associated with the foreign financial institution.

noYesType

NAMETYPEDESCRIPTION
noYesTypeoptionalstringThis field indicates whether the transaction qualifies for Dodd-Frank.

participantListResponse

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

party

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.

paymentError

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

paymentStatus

NAMETYPEDESCRIPTION
paymentStatusoptionalstringThe status of the payment transaction. Valid values: IN PROCESS, COMPLETED, FAILED, RETURNED, ERROR, VALID

paymentTransactionRequestV1

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.

paymentTransactionResponse

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

serviceErrorData

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

ultParty

NAMETYPEDESCRIPTION

For more information about errors, see Error handling.

For RTP Send Payment API, custom messages can display with the HTTP 400, 401, 403, or 500 status codes. The message and details are in the error object. Errors can be about account restrictions, network timeout, invalid data in the request, etc.

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
YAML file