RTP Inquiry | API Documentation

Search and query real-time payments transactions

RTP Inquiry API Endpoints

Summary	Endpoint
Health check	get /rtp/v1/healthCheck
Search real time payment transactions	post /rtp/v1/transactions/list
Get a real time payment transaction by its transaction ID	get /rtp/v1/transactions/detail/{transactionId}

Health check

get /rtp/v1/healthCheck

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

Responses

Successful response

NAME	TYPE	DESCRIPTION
Statusoptional	string	Status of the health check response.
Sourceoptional	string	The origin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved.
Timestampoptional	string	The date (YYYY-MM-DD) and time (HH:MM:SS) of the response from the API service.
ClientIpoptional	string	The client IP address the gateway gets from the request.
X-Forwarded-Foroptional	string	The sequence of all the IP addresses for systems involved between the client and the gateway.

Response example (200)

{
  "Status": "Ok",
  "Source": "Roundtrip",
  "Timestamp": "2022-09-15T04:49:03",
  "ClientIp": "156.77.111.28",
  "X-Forwarded-For": "[156.77.111.28]"
}

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

NAME	TYPE	DESCRIPTION
accountNumberrequired	string	The bank account number. This field cannot exceed 16 characters.
fromDaterequired	string	Start 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
toDaterequired	string	End 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
minimumAmountoptional	string	The 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.
maximumAmountoptional	string	The 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.
requestReference	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
pageNumberoptional	string	The number of the page being viewed. This number must be greater than or equal to 1.
pageSizeoptional	string	The total number of pages returned. This number must be greater than or equal to 1 and cannot exceed 1000.

Request example

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

Responses

Search results match the criteria

NAME	TYPE	DESCRIPTION
transactions	array	RtpListTransaction
metadata	Object	Metadata

Response example (200)

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

NAME	TYPE	DESCRIPTION
messagesoptional	array	Message
page	Object	Page

Response example (400)

{
    "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 FIELD	TYPE	DESCRIPTION
transactionIdrequired	string	The unique ID number associated with the original payment request.

Request example

curl --location: 'https://partner-api.keybank.com/rtp/v1/transactions/detail/US99999000999999'
--header 'KeyClientId: testwUhSQADUD4DwYyZz2hZkwLqsoFGK'
--header 'Accept: application/json'
--header 'Bearer testZcKJDWnwDWmmf9qah6PJvPy8'

Responses

A RTP transaction matches the provided transactionId

NAME	TYPE	DESCRIPTION
transactionId	string	The unique ID number associated with the original payment request.
transactionStatus	enum	The status of the RTP payment. Valid values: CANCELLED, COMPLETED, FAILED, IN PROCESS, IN REVIEW, RETURNED
transactionDate	string	Date the transfer occurred. Format: YYYY-MM-DD
transactionAmount	number	The dollar amount of the transaction.
requestReference	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReference	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.
creditor	object	PartyList
creditorAccount	object	AccountList
debtor	object	PartyList
debtorAccount	object	AccountList
remittanceInformation	string	Specific details associated with a transaction like an invoice number or customer details that provide a reason for the payment.
originator	object	PartyList
originatorAccount	object	AccountList
beneficiary	object	PartyList
beneficiaryAccount	object	AccountList
ultimateCreditor	object	PartyList
ultimateCreditorAccount	object	AccountList
ultimateDebtor	object	PartyList
ultimateDebtorAccount	object	AccountList

Response example (200)

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

NAME	TYPE	DESCRIPTION
messagesoptional	array	Message
page	object	Page

Response example (404)

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

Schemas

AccountList

NAME	TYPE	DESCRIPTION
accountNumber	string	Account number of the party.
virtualAccountNumber	string	Account number of the virtual account (VAM).

Message

NAME	TYPE	DESCRIPTION
code	string	Static code assigned by the network or payment system.
message	string	A human-readable message associated with the code.

Metadata

NAME	TYPE	DESCRIPTION
messagesoptional	array	Message
page	Object	Page

Page

NAME	TYPE	DESCRIPTION
pageNumber	integer	The number of the page being viewed.
pageSize	integer	The number of records per page.
totalPages	integer	The total number of pages available.
totalRecords	integer	The total number of the transactions (records) available in the result set.
lastPage	boolean	Indicates the last page of the total pages.

PartyList

NAME	TYPE	DESCRIPTION
name	string	Contains the customer identification number and the company name.

RtpDetailTransaction

NAME	TYPE	DESCRIPTION
transactionId	string	The unique ID number associated with the original payment request.
transactionDate	string	Date the transfer occurred. Format: YYYY-MM-DD
transactionAmount	number	The dollar amount of the transaction.
requestReference	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReference	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.
creditor	Object	PartyList
creditorAccount	Object	AccountList
debtor	Object	PartyList
debtorAccount	Object	AccountList
remittanceInformation	string	Specific details associated with a transaction like an invoice number or customer details that provide a reason for the payment.
originator	Object	PartyList
originatorAccount	Object	AccountList
beneficiary	Object	PartyList
beneficiaryAccount	Object	AccountList
ultimateCreditor	Object	PartyList
ultimateCreditorAccount	Object	AccountList
ultimateDebtor	Object	PartyList
ultimateDebtorAccount	Object	AccountList

RtpListTransaction

NAME	TYPE	DESCRIPTION
transactionId	string	The unique ID number associated with the original payment request
transactionDate	string	Date the transfer occurred. Format: YYYY-MM-DD
transactionAmount	number	The dollar amount of the transaction.
requestReference	string	A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 35 characters.
sendersReference	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.
creditor	Object	PartyList
creditorAccount	Object	AccountList
debtor	Object	PartyList
debtorAccount	Object	AccountList
originator	Object	PartyList
beneficiary	Object	PartyList

Errors

For more information about general errors, see Error handling.

Changelog

Release	API version	Change description	Impact
April 2025	1.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 2025	1.1.0	Added `requestReference` to the /list endpoint. You can now recall a RTP transaction by the request reference ID.	LOW
November 2024	1.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