RTP Send Payment

clock 5-minute read calender 1.3.0 | updated Jun. 23, 2025

Make a payment immediately and at any time

What you can doEndpoint
Health checkget /rtp/v1/payment/healthCheck
Send a real-time paymentpost /rtp/v1/payment/initiate
Get a list of RTP participantsget /rtp/v1/payment/rtp/participant
Get information about one RTP participantget /rtp/v1/payment/rtp/participant/{routingNumber}
Perform validation checkspost /rtp/v1/payment/validate
 

Before you begin

All KeyBank APIs require certificates, user credentials, and certain permissions. 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 Transfer API.

Check out our Getting Started Guide to learn more.

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. This field is not the same as your client credentials (part of your API keys needed to obtain an access token).

The reference numbers reduces manuals processes or payment identification errors. It can also help the recipient auto-reconcile  incoming payment. 

requestReference: A unique identifier specific to this request. This is used for idempotency and deduplication. If you retry the same request due to network or system error, using the same requestReference makes sure the bank does not process it twice.

originatorReference: A reference number that represents the party that initiated the payment. This is usually your end customer or payment originator.

sendersReference: A unique reference identification generated by you - the API client or sender of the RTP request. Use this to track or identify the transaction with your system.

receiversReference: A reference value that the recipient of the payment can use to reconcile or track the payment on their side. This gives the payee an extra piece of information for their own system, like an order ID or case number that they can tie back to the payment.

How reference IDs work
REFERENCE FIELDWHO SETS ITWHAT IT TRACKSWHO SEES ITEXAMPLE
requestReferenceYou (API client)Unique API request identifier for idempotency and retries.Bank or RTP network (for deduplication)"req-20250617-001"
originatorReferencePayment originator (your customer or the system on their behalf)Their reason for the payment, like an invoice number they are paying.Recipient (payee)"INV-4567"
sendersReferenceYou (API client)Your internal transaction tracking number, like a PO number or system ID. You and the bank"ERP-PO-7890"
receiversReferenceYou (API client)Helps the recipient's system reconcile the payment, like a order or case number for their system.Recipient (payee)"SupplierOrder123"

The party object is required for any payment or validation request. The party object defines each participant in the payment chain, sender (debitParty, debitPartyBank) and receiver (creditParty, creditPartyBank). The receiver can be an individual, corporation, beneficiary, or financial institution.

Depending on the party type in the payment chain, there are certain details required about the person or entity sending a payment and the one receiving the payment. Define the following request fields to successfully send a payment from one account to another or validate a recent transaction.

Payment chain request objects
ORDERPAYMENT CHAIN ACTIVITYREQUEST FIELD/VAULES
1You send a payment as an individual or as a business.debitParty
Enter the name associated with the account (name) and your debit account number (accountNumber).
2Your bank transfers the funds.debitPartyBank
Enter the ABA or routing number (aba) for your bank. Usually, this is KeyBank.
3The recipient's bank receives the funds from your bank.

creditPartyBank
Enter the ABA number for the recipient's financial institution (aba) or the account number (accountNumber).

If the accountNumber is used for party identification, you also need the name and address for validation. A complete address can have either one address line (adrLine) or the town name (twnNm) and country (ctry).

4The person or business ("beneficiary party") you are sending money to receives the funds.

creditParty 
Enter the name associated with the account (name) and the account number (accountNumber) of the person or business to receive the funds.

If the accountNumber is used for party identification, you also need the name and address for validation. A complete address can have either one address line (adrLine) or the town name (twnNm) and country (ctry).

Use the right characters in ISO messages

Use only the supported characters in ISO messages. If you use a character that isn't supported, an error message returns. Review the entered values to make sure you did not use a restricted character (like the pipe delimiter).

ISO messages only support the following characters:

  • Alphabet characters, uppercase (A-Z) and lowercase (a-z)
  • Numeric characters (0-9)
  • Special characters limited to .,-()?+'=:?@-#{!"%&*;<>
  • Single space, carriage return, and line feed

All payments go through two levels of checks to avoid duplicate transactions. You will receive an error if the transaction is not unique.

Level 1: We look at the requestReference field defined in the request. This must be a unique number for the originated transaction. This ID stays with the transaction and helps prevent duplicate transactions. 

Level 2: Check additional fields in the request to make sure the transaction is not a duplicate.

  • debitParty > accountNumber
  • creditPartyBank > aba
  • creditParty > accountNumber
  • requestedValueDate
  • transferAmount
  • receiversReference  (This is a critical field if you may be sending similar, almost identical payments.)

 

get /rtp/v1/payment/healthCheck

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

 
NAMETYPEDESCRIPTION
StatusstringThe status of the health check response.
SourcestringThe 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.
TimestampstringThe date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIpstringThe client IP address the gateway receives from the request.
X-Forwarded-ForstringThe 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]"
}

post /rtp/v1/payment/initiate

Initiate a RTP payment. Use the requestedService parameter to define the transaction as RTP or Wire.

Review the request requirements to get a better understanding about request identifiers and the party object.

header FIELDTYPEDESCRIPTION
KeyClientIdrequiredstringThis value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions.
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 32 characters.
typerequiredstringFor RTP, the type can show if the transaction is a PAYMENT or a DRAFT. For Wire transfers, the type is always 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 32 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. This cannot exceed 140 characters.
ultimateDebitPartyoptionalObjectultParty
debitPartyrequiredObjectparty
debitPartyBankoptionalObjectparty
intermediaryBank1optionalObjectparty
intermediaryBank2optionalObjectparty
intermediaryBank3optionalObjectparty
creditPartyBankrequiredObjectparty
creditPartyrequiredObjectparty
transferAmountrequirednumberAmount of money to transfer in the correct currency format.
transferCurrencyrequiredstringCurrency code for the transfer amount.
externalTemplateNameoptionalstringName of the external template. Text cannot exceed 2048 characters.
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",
    "sendersReference": "INVC0012345",
    "receiversReference": "INVC0054321",
    "requestedValueDate": 1621814400,
    "debitParty": {
        "name": "CLARK GABLE",
        "accountNumber": "001122334455"
    },
    "creditPartyBank": {
        "name": "CLARK GABLE",
        "aba": "123456789"
    },
    "creditParty": {
        "name": "CLARK GABLE",
        "accountNumber": "987654321",
        "postalAddress": {
            "adrTp": "HOME",
            "dept": "Test Dept",
            "subDept": "Test Sub Dept",
            "strtNm": "123 Main Street",
            "bldgNb": 10,
            "pstCd": 12345,
            "twnNm": "Central Town",
            "ctrySubDvsn": "Test Sub Division",
            "ctry": "US",
            "adrLine": [
                "123 Main Street",
                "Central Town, US"
            ]
        }
    },
    "transferAmount": 10,
    "transferCurrency": "USD"
}
NAMETYPEDESCRIPTION
statusrequiredObjectpaymentStatus
transactionIdstringThe unique ID number associated with the original payment request.
requestReferencestringA reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferencestringA reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 32 characters.
receiversReferencestringA reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberstringDebit account number. This cannot exceed 34 digits.
creditAccountNumberstringCredit account number. This cannot exceed 34 digits.
valueDatestringThe date (YYYY-MM-DD) the transfer occurred.
transferAmountintegerAmount of money to transfer in the correct currency format.
transferCurrencystringCurrency code for the transfer amount.
errorObjectpaymentError
doddFrankObjectnoYesType
clearingSystemReferencestringA 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"
}
NAMETYPEDESCRIPTION
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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"
    }
}
NAMETYPEDESCRIPTION
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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/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.

header FIELDTYPEDESCRIPTION
KeyClientIdrequiredstringThis value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions.
query FIELDTYPEDESCRIPTION
limitrequiredintegerPagination parameter that indicates the maximum number of records to return in the response.
offsetrequiredintegerPagination 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 'KeyClientId: testwUhSQADUD4DwYyZz2hZkwLqsoFGK'
--header 'Accept: application/json'
--header 'Bearer testZcKJDWnwDWmmf9qah6PJvPy8'
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.
partiesObjectparty

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"
            ]
        }
    }
}
NAMETYPEDESCRIPTION
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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"
    }
}
NAMETYPEDESCRIPTION
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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.

header FIELDTYPEDESCRIPTION
KeyClientIdrequiredstringThis value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions.
path FIELDTYPEDESCRIPTION
routingNumberrequiredstringRouting number of the participating RTP bank.

Request example

curl --location: 'https://partner-api-qv.keybank.com/rtp/v1/payment/rtp/participant/12345678
--header 'KeyClientId: testwUhSQADUD4DwYyZz2hZkwLqsoFGK'
--header 'Accept: application/json'
--header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8'
NAMETYPEDESCRIPTION
namerequiredstringName of the party. This can be an individual, a financial institution, or a beneficiary. The name is required for the creditParty. This cannot exceed 140 characters.
accountNumberstringAccount number of the party. If this is a wire transfer, you must provide the name and address with the account number for all parties, except debitParty and debitPartyBank. This cannot exceed 34 digits.
abastringThe ABA or routing number of the financial institution. If this is a wire transfer, you do not need to provide other account information like address or name, unless it is for debitParty or debitPartyBank. This cannot exceed 9 digits.
bicstringThe bank identifier code (BIC) for the party. This is a combination code that identifies the bank, country, location, and possibly the bank branch.
txidstringThe tax identification number for the party.
foreignBankSystemIdObjectforeignBankSystemType
adrTpstringAddress type for the party that specifies if it is a home, business, or mailing address. Valid values: ADDR, PBOX, HOME, BIZZ, MLTO, DLVY
deptstringDepartment of the party for the mailing address, if applicable. This field cannot exceed 70 characters.
subDeptstringSub-department of the party, if applicable. This field cannot exceed 70 characters.
strtNmstringStreet address for the party. This field cannot exceed 70 characters.
bldgNbstringBuilding number. This field cannot exceed 16 characters.
pstCdstringThe postal code or zip code for the address. This field cannot exceed 16 characters.
twnNmstringName of the town. This field cannot exceed 35 characters.
ctrySubDvsnstringName of subdivision of a country like a state, region, or county. This field cannot exceed 35 characters.
ctrystringCountry name or abbreviation.
adrLineoptionalarrayAn unstructured address line. You can have up to three lines of text. Each line can be 70 characters or less.

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"
        ]
    }
}
NAMETYPEDESCRIPTION
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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"
    }
}
NAMETYPEDESCRIPTION
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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.

Review the request requirements to get a better understanding about request identifiers and the party object.

header FIELDTYPEDESCRIPTION
KeyClientIdrequiredstringThis value is provided by KeyBank during onboarding and is different from your client credentials. This is required for each call for RTP or Wire transactions.
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 32 characters.
typerequiredstringFor RTP, the type can show if the transaction is a PAYMENT or a DRAFT. For Wire transfers, the type is always 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 32 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. This cannot exceed 140 characters.
ultimateDebitPartyoptionalObjectultParty
debitPartyrequiredObjectparty
debitPartyBankoptionalObjectparty
intermediaryBank1optionalObjectparty
intermediaryBank2optionalObjectparty
intermediaryBank3optionalObjectparty
creditPartyBankrequiredObjectparty
creditPartyrequiredObjectparty
transferAmountrequirednumberAmount of money to transfer in the correct currency format.
transferCurrencyrequiredstringCurrency code for the transfer amount.
externalTemplateNameoptionalstringName of the external template. Text cannot exceed 2048 characters.
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": "CLARK GABLE"
    },
    "debitParty": {
        "name": "CLARK GABLE",
        "accountNumber": "001122334455"
    },
    "creditPartyBank": {
        "name": "CLARK GABLE",
        "aba": "123456789"
    },
    "creditParty": {
        "name": "CLARK GABLE",
        "accountNumber": "987654321",
        "postalAddress": {
            "adrTp": "HOME",
            "dept": "Test Dept",
            "subDept": "Test Sub Dept",
            "strtNm": "123 Main Street",
            "bldgNb": 10,
            "pstCd": 12345,
            "twnNm": "Central Town",
            "ctrySubDvsn": "Test Sub Division",
            "ctry": "US"
        }
    },
    "transferAmount": 10,
    "transferCurrency": "USD",
    "customData": ""
}
NAMETYPEDESCRIPTION
statusrequiredObjectpaymentStatus
transactionIdstringThe unique ID number associated with the original payment request.
requestReferencestringA reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferencestringA reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 32 characters.
receiversReferencestringA reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberstringDebit account number. This cannot exceed 34 digits.
creditAccountNumberstringCredit account number. This cannot exceed 34 digits.
valueDatestringThe date (YYYY-MM-DD) the transfer occurred.
transferAmountintegerAmount of money to transfer in the correct currency format.
transferCurrencystringCurrency code for the transfer amount.
errorObjectpaymentError
doddFrankObjectnoYesType
clearingSystemReferencestringA 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData 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
StatusstringThe status of the health check response.
SourcestringThe 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.
TimestampstringThe date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIpstringThe client IP address the gateway receives from the request.
X-Forwarded-ForstringThe sequence of the IP addresses for systems between the client and the gateway. Addresses are separated by a comma.
NAMETYPEDESCRIPTION
ErrorMessagestringA human-readable message that describes the type or source of the error.
TransactionIdstringA unique transaction ID returned with the response, useful for traceability.
TransactionTimestringDate (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroneOfserviceErrorData connectError
NAMETYPEDESCRIPTION
statusrequiredObjectpaymentStatus
transactionIdstringThe unique ID number associated with the original payment request.
requestReferencestringA reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferencestringA reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 35 characters.
receiversReferencestringThe sender reference value from the original request. This is useful for traceability and reporting.
debitAccountNumberstringThe sender reference value from the original request. This is useful for traceability and reporting.
creditAccountNumberstringThe sender reference value from the original request. This is useful for traceability and reporting.
valueDatestringThe date (YYYY-MM-DD) the transferred occurred.
errorObjectpaymentError
doddFrankObjectnoYesType
NAMETYPEDESCRIPTION
ConnectErrorstringAPI connectivity error information, if available.
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 32 characters.
typerequiredstringFor RTP, the type can show if the transaction is a PAYMENT or a DRAFT. For Wire transfers, the type is always DRAFT.
requestedValueDaterequiredstringDate (YYYY-MM-DD) the transfer will occur.
originatorReferencestringAn 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 32 characters.
receiversReferencestringA reference value for the beneficiary. This value cannot exceed 140 characters.
bankToBankInstructionsstringArea to share messages or instructions from one bank to another bank. This cannot exceed 140 characters.
ultimateDebitPartyObjectultParty
debitPartyrequiredObjectparty
debitPartyBankObjectparty
intermediaryBank1Objectparty
intermediaryBank2Objectparty
intermediaryBank3Objectparty
creditPartyBankrequiredObjectparty
creditPartyrequiredObjectparty
transferAmountrequirednumberAmount of money to transfer in the correct currency format.
transferCurrencyrequiredstringCurrency code for the transfer amount.
externalTemplateNamestringName of the external template. Text cannot exceed 2048 characters.
customDatastringThe 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
namerequiredstringName of the party. This can be an individual, a financial institution, or a beneficiary. The name is required for the creditParty. This cannot exceed 140 characters.
accountNumberstringAccount number of the party. If this is a wire transfer, you must provide the name and address with the account number for all parties, except debitParty and debitPartyBank. This cannot exceed 34 digits.
abastringThe ABA or routing number of the financial institution. If this is a wire transfer, you do not need to provide other account information like address or name, unless it is for debitParty or debitPartyBank. This cannot exceed 9 digits.
bicstringThe bank identifier code (BIC) for the party. This is a combination code that identifies the bank, country, location, and possibly the bank branch.
txidstringThe tax identification number for the party.
foreignBankSystemIdObjectforeignBankSystemType
adrTpstringAddress type for the party that specifies if it is a home, business, or mailing address. Valid values: ADDR, PBOX, HOME, BIZZ, MLTO, DLVY
deptstringDepartment of the party for the mailing address, if applicable. This field cannot exceed 70 characters.
subDeptstringSub-department of the party, if applicable. This field cannot exceed 70 characters.
strtNmstringStreet address for the party. This field cannot exceed 70 characters.
bldgNbstringBuilding number. This field cannot exceed 16 characters.
pstCdstringThe postal code or zip code for the address. This field cannot exceed 16 characters.
twnNmstringName of the town. This field cannot exceed 35 characters.
ctrySubDvsnstringName of subdivision of a country like a state, region, or county. This field cannot exceed 35 characters.
ctrystringCountry name or abbreviation.
adrLineoptionalarrayAn unstructured address line. You can have up to three lines of text. Each line can be 70 characters or less.
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.
partiesObjectparty
NAMETYPEDESCRIPTION
typestringThe five-digit global routing code for a foreign financial institution.
idstringThe identification number associated with the foreign financial institution.
NAMETYPEDESCRIPTION
statusrequiredObjectpaymentStatus
transactionIdstringThe unique ID number associated with the original payment request.
requestReferencestringA reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReferencestringA reference value provided by the sender. For outbound payments, this value is the same as the transaction ID. The ID cannot exceed 32 characters.
receiversReferencestringA reference value for the beneficiary. This value cannot exceed 140 characters.
debitAccountNumberstringDebit account number. This cannot exceed 34 digits.
creditAccountNumberstringCredit account number. This cannot exceed 34 digits.
valueDatestringThe date (YYYY-MM-DD) the transfer occurred.
transferAmountintegerAmount of money to transfer in the correct currency format.
transferCurrencystringCurrency code for the transfer amount.
errorObjectpaymentError
doddFrankObjectnoYesType
clearingSystemReferencestringA reference value for the beneficiary. This value cannot exceed 140 characters.
NAMETYPEDESCRIPTION
paymentStatusoptionalstringThe status of the payment transaction. Valid values: IN_PROCESS, IN_REVIEW, COMPLETED, FAILED, RETURNED, ERROR, VALID
NAMETYPEDESCRIPTION
coderequiredstringStatus code assigned to each error type.
titlerequiredstringBrief title about the error associated with the status code.
descriptionstringDescription of the error.
codestringA static code assigned by the network or payment system.
titlestringBrief title about the error associated with the status code.
descriptionstringDescription of the error
NAMETYPEDESCRIPTION
noYesTypeoptionalstringThis field indicates whether the transaction qualifies for Dodd-Frank.
NAMETYPEDESCRIPTION
namestringTypically this is the name of the party that instructed the debit party to initiate a payment. This applies only to RTP transactions and the 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. For more information about our standard HTTP errors, see Error handling.

KeyBank may include additional information about the error in API-specific error messages. The 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.

CODEMESSAGE
KEY-0001Not authorized
KEY-0002Not authorized for requested action
KEY-0003Request exceeds authorized limit
KEY-0004Unauthorized for account
KEY-0005Internal use only fields
KEY-0006Not authorized for requested service
KEY-1000Transformation Error
KEY-1001Invalid Data
KEY-1002Invalid Bank Identifier
KEY-1003Invalid or unknown template
KEY-1004Invalid account
KEY-1005Invalid Currency
KEY-1006Required field missing
KEY-1007Transaction Not Found
KEY-1008Insufficient Funds
KEY-1009Account has restrictions
KEY-1010Duplicate Request
KEY-1011Payor Account Restrictions
KEY-1012Payee Account Restrictions
KEY-2101Unable to construct wire from template
KEY-3001Exceeds transaction limit for RTP transactions
KEY-3002Field not usable for RTP transactions
KEY-3003Payment network timeout. Please retry.
KEY-3004Payment rejected by payment network
KEY-9997Failed payment review
KEY-9998Payment failed during processing
KEY-9999Unknown 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" 
      } 
  }
ReleaseAPI versionChange descriptionImpact
June 20251.3.0
  • Deprecated the status endpoints with the recent RTP and Wire Inquiry API enhancements. We recommend you use the /list or /detail paths to get an accurate status report on your transactions. 

    The following endpoints were deprecated:
    • /rtp/v1/payment/status/debitAccount/{debitAccount}/reference/{reference}
    • /rtp/v1/payment/status/transactionId/{transactionId}
MID
April 20251.2.6
  • Added details to the party object for accountNumber and aba parameters. This applies to all party object except for debitParty and debitPartyBank as it pertains to wire transmissions.
  • Added Duplicate checks content to describe how the API checks for duplicate entries. We also identify what parameters must be unique to help prevent duplication issues.
LOW
December 20241.2.5
  • Enhanced the requirements and responses for party addresses.
  • has been replaced by the postalAddress object.
    • Added the following fields to postalAddress nested in the party object: adrTp, dept, subDept, strtNm, bldgNb, pstCd, twnNm, ctrySubDvsn, ctry.
    • For requests, you are required to complete the postalAddress fields for both the debitParty and creditParty.
    • Address information returns in the response if available.
  • Foreign payments are possible for RTP transactions. You can use the foreignBankSystemID to specify the type (five-digit routing code) and the id (ID number).
LOW
August 20241.2.4
  • Added clarification to type parameter. For RTP the type can be PAYMENT or DRAFT. For wire transfers, the type will always be DRAFT.
MID
May 20241.2.3
  • KeyClientId is required for all endpoints, including GET calls.
MID
March 20241.2.1
  • Added 'IN_REVIEW' as a valid value for status in the paymentStatus object.
  • Added new parameters to paymentTransactionRequestV1:
    • bankToBankInstructions
    • debitPartyInstructions
    • intermediaryBank1
    • intermediaryBank2
    • intermediaryBank3
    • externalTemplateName
  • Added the clearingSystemReference in the paymentTransactionResponse object.
  • Added the following parameter to serviceErrorData:
    • receiversReference
    • debitAccountNumber
    • creditAccountNumber
  • Changed min/max limits for the following parameters:
    • requestReference and sendersReference changed from maxLength 35 to 32 with a minLength of 1.
    • Added parameter limits for originatorReference with a minLength of 1 and a maxLength of 35.
    • Added parameter limit for transferAmount with a maximum of 18 digits (which is like quintillion).
    • Added parameter limit for accountNumber in the party to a minLength of 1.
    • Added parameter limit for aba to a maxLength of 9 digits.
    • Added parameter limit for debitAccountNumber to a maxLength 34 characters.
HIGH
September 20231.1.5
  • Parameter description updates. This change is for technical content only. The code and operations of the API remain the same.
  • Clarified the transactionId for RTP payments is the clearing system reference number.
LOW
December 20221.1.3
  • Released on the Developer Portal.
 

Impact levels

  • LOW: This is a minor change or enhancement that does not alter the operations of the API. Upgrading to the latest specifications is preferable but not required.
  • MID: The previous API version is valid and operates, but does not contain latest enhancements. You need to update your specifications to get these enhancements.
  • HIGH: The previous API version is no longer operable. You must upgrade to the latest specifications to access and use this API product.

YAML file download