RTP Inquiry

clock 2-minute read calender 1.2.0 | updated Apr. 22, 2025

Search and query real-time payments transactions

RTP INQUIRY ENDPOINTS

What can you doEndpoint
Health checkget /rtp/v1/healthCheck
Search real time payment transactionspost /rtp/v1/transactions/list
Get a real time payment transaction by its transaction IDget /rtp/v1/transactions/detail/{transactionId}

Key notes

Before you begin

All KeyBank APIs require certificates, user credentials, and certain permissions. Details about what is required to become an API partner with KeyBank are in the Get Started Guide to learn more. 

Before using any endpoint, make sure you understand the required parameters and conditions for a valid request.

Account number

When retrieving a list of wire transactions, you need a valid (16-character) accountNumber. This account number pulls all related transactions within the specified date range of the request. 

Date range

Use the fromDate and toDate in the request to specify the date range for settled transactions for the account number provided. 

The start date (fromDate) must be within 100 days of the current day. This date has to occur before the end date (toDate). The end date cannot be a future date. Date formats are in YYYY-MM-DD.

Transaction ID

If you are looking for details about a specific transaction, you must specify the transactionId in the detail request. The transactionId is the unique ID number associated with the original payment request. The maximum amount of characters for a transactionId is 100, but typically they are around 16 characters in length. 

How do I get the transaction ID? 

The transactionId is returned in the response for the list API. Use this ID returned in your detail request to return additional information about an RTP transaction. 

Search real time payment transactions

post /rtp/v1/transactions/list

Based on search criteria provided, get a list of RTP transactions. The account number and date range are required for every request.

Request

NAMETYPEDESCRIPTION
accountNumberrequiredstringThe bank account number. This field cannot exceed 16 characters.
fromDaterequiredstringStart date for the date range. This date can be the current day or within 100 days prior to the current date. To search for a single date, this value will be the same as the toDate. Format: YYYY-MM-DD
toDaterequiredstringEnd date for the date range. This date must be the same or later than the start date (fromDate). To search for a single date, this value will be the same as the fromDate. To search for a range of dates, make sure the date range does not exceed 31 days. Format: YYYY-MM-DD
minimumAmountstringThe minimum dollar amount of the transaction. This amount must be less than or equal to the maximum amount. Leave blank or enter zero for no minimum amount.
maximumAmountstringThe maximum dollar amount of the transaction. This amount must be greater than or equal to the minimum amount. Leave blank to retrieve all amounts. This amount cannot exceed one billion dollars.
requestReferencestringA reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
pageNumberstringThe number of the page being viewed. This number must be greater than or equal to 1.
pageSizestringThe total number of pages returned. This number must be greater than or equal to 1 and cannot exceed 1000.

Request example

copylink
{
  "accountNumber": "3123456789",
  "fromDate": "2024-02-01",
  "toDate": "2024-02-01",
  "minimumAmount": "100.00",
  "maximumAmount": "75020.5",
  "requestReference": "USt41001030ii016002",
  "pageNumber": "1",
  "pageSize": "500"
}

Responses

NAMETYPEDESCRIPTION
transactionsarrayRtpListTransaction
metadataObjectMetadata

Response example (200)

copylink
{
    "transactions": [
        {
            "transactionId": "US99999000999999",
            "transactionStatus": "COMPLETED",
            "transactionDate": "2024-02-01",
            "transactionAmount": 32772.63,
            "requestReference": "1122334455",
            "sendersReference": "US99999000999999",
            "creditor": {
                "name": "Global Markets LLC"
            },
            "creditorAccount": {
                "accountNumber": "987654321"
            },
            "debtor": {
                "name": "Paul Wilson"
            },
            "debtorAccount": {
                "accountNumber": "123456789"
            }
        }
    ],
    "metadata": {
        "page": {
            "pageNumber": 1,
            "pageSize": 25,
            "totalPages": 3,
            "totalRecords": 75,
            "lastPage": true
        }
    }
}

Bad input parameter

NAMETYPEDESCRIPTION
metadataobjectMetadata

Response example (400)

copylink
{
    "metadata": {
        "messages": [
            {
                "code": "RTP-List-400-bad-input",
                "message": "Bad input parameter"
            }
        ]
    }
}

View the details of a RTP transaction by its ID

get /rtp/v1/transactions/detail/{transactionId}

Provide the transaction ID to retrieve all available fields for that single real time payment transaction.

Request

path FIELDTYPEDESCRIPTION
transactionIdrequiredstringThe unique ID number associated with the original payment request.
 

Responses

A RTP transaction matches the provided transactionId

NAMETYPEDESCRIPTION
transactionIdstringThe unique ID number associated with the original payment request.
transactionDatestringDate the transfer occurred. Format: YYYY-MM-DD
transactionAmountnumberThe dollar amount of the transaction.
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.
creditorObjectPartyList
creditorAccountObjectAccountList
debtorObjectPartyList
debtorAccountObjectAccountList
remittanceInformationstringSpecific details associated with a transaction like an invoice number or customer details that provide a reason for the payment.
originatorObjectPartyList
originatorAccountObjectAccountList
beneficiaryObjectPartyList
beneficiaryAccountObjectAccountList
ultimateCreditorObjectPartyList
ultimateCreditorAccountObjectAccountList
ultimateDebtorObjectPartyList
ultimateDebtorAccountObjectAccountList

Response example (200)

copylink
{
    "transactionId": "US99999000999999",
    "transactionStatus": "COMPLETED",
    "transactionDate": "2024-02-01",
    "transactionAmount": 32772.63,
    "requestReference": "1122334455",
    "sendersReference": "US99999000999999",
    "creditor": {
        "name": "Global Markets LLC"
    },
    "creditorAccount": {
        "accountNumber": "987654321"
    },
    "debtor": {
        "name": "Paul Wilson"
    },
    "debtorAccount": {
        "accountNumber": "123456789"
    },
    "remittanceInformation": "Payment 02\/01\/2024_Invoice - 123456789 Cust",
    "originator": {
        "name": "Global Markets"
    },
    "originatorAccount": {
        "accountNumber": 987654321,
        "virtualAccountNumber": 400100225000
    },
    "beneficiary": {
        "name": "Wilson"
    },
    "beneficiaryAccount": {
        "accountNumber": 123456789,
        "virtualAccountNumber": 400100338001
    }
}

Requested resource is not found

NAMETYPEDESCRIPTION
metadataobjectMetadata

Response example (404)

copylink
{
    "metadata": {
        "messages": [
            {
                "code": "RTP-Detail-404-no-records",
                "message": "Record Not Found"
            }
        ]
    }
}

Schemas

RtpDetailTransaction

NAMETYPEDESCRIPTION
transactionIdstringThe unique ID number associated with the original payment request.
transactionDatestringDate the transfer occurred. Format: YYYY-MM-DD
transactionAmountnumberThe dollar amount of the transaction.
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.
creditorObjectPartyList
creditorAccountObjectAccountList
debtorObjectPartyList
debtorAccountObjectAccountList
remittanceInformationstringSpecific details associated with a transaction like an invoice number or customer details that provide a reason for the payment.
originatorObjectPartyList
originatorAccountObjectAccountList
beneficiaryObjectPartyList
beneficiaryAccountObjectAccountList
ultimateCreditorObjectPartyList
ultimateCreditorAccountObjectAccountList
ultimateDebtorObjectPartyList
ultimateDebtorAccountObjectAccountList

RtpListTransaction

NAMETYPEDESCRIPTION
transactionIdstringThe unique ID number associated with the original payment request
transactionDatestringDate the transfer occurred. Format: YYYY-MM-DD
transactionAmountnumberThe dollar amount of the transaction.
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.
creditorObjectPartyList
creditorAccountObjectAccountList
debtorObjectPartyList
debtorAccountObjectAccountList
originatorObjectPartyList
beneficiaryObjectPartyList

healthResponse

NAMETYPEDESCRIPTION
StatusstringStatus of the health check response.
SourcestringThe origin of the system 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 the response from the API service.
ClientIpstringThe client IP address the gateway gets from the request.
X-Forwarded-ForstringThe sequence of all the IP addresses for systems involved between the client and the gateway.

AccountList

NAMETYPEDESCRIPTION
accountNumberstringAccount number of the party.
virtualAccountNumberstringAccount number of the virtual account (VAM).

PartyList

NAMETYPEDESCRIPTION
namestringContains the customer identification number and the company name.

Message

NAMETYPEDESCRIPTION
codestringStatic code assigned by the network or payment system.
messagestringA human-readable message associated with the code.

Page

NAMETYPEDESCRIPTION
pageNumberintegerThe number of the page being viewed.
pageSizeintegerThe number of records per page.
totalPagesintegerThe total number of pages available.
totalRecordsintegerThe total number of the transactions (records) available in the result set.
lastPagebooleanIndicates the last page of the total pages.

Metadata

NAMETYPEDESCRIPTION
messagesoptionalarrayMessage
pageObjectPage

For more information about general errors, see Error handling.

ReleaseAPI versionChange descriptionImpact
April 20251.2.0
  • Added the following parameters to the RtpListTransaction object:
    • originator
    • originatorAccount
    • beneficiary
    • beneficiaryAccount
  • In the AccountList object, added the virtualAccountNumber field to return VAM account information, if applicable.
MID
February 20251.1.0
  • Added requestReference to the /list endpoint. You can now recall a RTP transaction by the request reference ID.
LOW
November 20241.0.0
  • Published 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