openapi: 3.1.0
info:
#---------------------------------------------------
# Information to contact the API provider
#---------------------------------------------------
title: RTP Inquiry API
version: 1.2.3
description: Retrieve the status and details of a real-time payments transactions
contact:
name: KeyBank Developer Support
email: embedded_banking_support@keybank.com
servers:
#---------------------------------------------------
# List of Environments for the API
#---------------------------------------------------
- url: https://partner-api-qv.key.com
description: Non-Production environment (QV)
- url: https://partner-api.key.com
description: Production and Simulator environment
tags:
- name: HealthCheck
description: Verify you can connect to the API service.
- name: RTP
description: RTP functions to list and retrieve real-time payment details
security:
- bearerAuth: []
paths:
#---------------------------------------------------
# List of API flows
#---------------------------------------------------
/rtp/v1/healthCheck:
get:
tags:
- HealthCheck
summary: Health check
description: Verify you can connect to the API service. A bearer token is required.
operationId: healthCheck
security:
- bearerAuth: []
responses:
'200':
description: Successful response
headers:
X-CorrelationId:
description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/HealthResponse'
example:
Status: Ok
Source: Roundtrip
Timestamp: '2022-09-15T04:49:03'
ClientIp: 192.0.2.1
X-Forwarded-For: '[192.0.2.1]'
/rtp/v1/transactions/list:
post:
tags:
- RTP
summary: Search real time payment transactions
operationId: searchRtpTransactions
description: Based on search criteria provided, get a list of RTP transactions. The account number and date range are required for every request.
security:
- bearerAuth: []
parameters:
- name: X-CorrelationId
in: header
schema:
type: string
required: false
description: Universal ID to trace the transaction across all systems involved.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- accountNumber
- fromDate
- toDate
properties:
accountNumber:
type: string
description: The bank account number. This number cannot exceed 16 characters.
minLength: 1
maxLength: 16
pattern: '^\d+$'
examples:
- '3123456789'
fromDate:
type: string
format: date
description: 'Start date for the date range. This date can be the current day or within 180 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'
examples:
- '2024-02-01'
toDate:
type: string
format: date
description: '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'
examples:
- '2024-02-01'
minimumAmount:
allOf:
- $ref: '#/components/schemas/Amount0To1B'
description: 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.
examples:
- 0.5
- 100
- 75.1
- 83838.23
- '0.50'
- '75,020.52'
- '74333.22'
maximumAmount:
allOf:
- $ref: '#/components/schemas/Amount0To1B'
description: 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.
examples:
- 100
- 75.1
- 83838.23
- '75,020.52'
- '74333.22'
requestReference:
type: string
description: A reference value for the original request that is useful for traceability and reporting. The ID cannot exceed 32 characters.
maxLength: 32
examples:
- '1122334455'
pageNumber:
type: integer
format: int32
minimum: 1
description: The number of the page being viewed. This number must be greater than or equal to 1.
examples:
- 1
pageSize:
type: integer
format: int32
minimum: 1
maximum: 1000
description: The number of records per page. This number must be greater than or equal to 1 and cannot exceed 1000.
examples:
- 500
responses:
'200':
description: Search results match the criteria
headers:
X-CorrelationId:
description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. The ID is unique to each request.
schema:
type: string
content:
application/json:
schema:
type: object
properties:
transactions:
type: array
maxItems: 1000
items:
$ref: '#/components/schemas/RTPListTransaction'
metadata:
$ref: '#/components/schemas/PageMetadata'
example:
transactions:
- transactionId: US99999000999999
transactionStatus: COMPLETED
transactionStatusTimestamp: '2026-01-12T12:18:01'
transactionDate: '2026-01-12'
transactionAmount: 32772.63
requestReference: '1122334455'
sendersReference: US99999000999999
creditor:
name: Global Markets LLC
creditorAccount:
accountNumber: '987654321'
debtor:
name: Paul Wilson
debtorAccount:
accountNumber: '123456789'
originator:
name: VAM TEST BANK
beneficiary:
name: MARKET CAPITAL
metadata:
page:
pageNumber: 1
pageSize: 25
totalPages: 3
totalRecords: 75
lastPage: false
'400':
description: Bad input parameter
headers:
X-CorrelationId:
description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations. The ID is unique to each request.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Exception'
example:
ErrorMessage: Error received from backend service
TransactionId: 84293235-5d2c-42ba-afc3-a5d4afc5f88e27097
X-CorrelationId: 929618f2-6163-bf73-51b0-6c54a8533c74
TransactionTime: '2021-06-11T16:31:34.041Z'
Api-Url: https://partner-api-qv.key.com/rtp/v1/transactions/list
ServiceError:
metadata:
messages:
- code: RTP-List-400-toDate
message: toDate format must be YYYY-MM-DD
'401':
description: Unauthorized request
headers:
X-CorrelationId:
description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Exception'
example:
ErrorMessage: Received request is unauthorized, please provide valid credentials
TransactionId: 0635f201-8fbb-418f-b93a-138d5103e2b91348
X-CorrelationId: 929618f2-6163-bf73-51b0-6c54a8533c74
TransactionTime: '2021-06-11T16:31:34.041Z'
Api-Url: https://partner-api-qv.key.com/rtp/v1/transactions/list
'403':
description: Entitlements validation failed
headers:
X-CorrelationId:
description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Exception'
example:
ErrorMessage: Error received from backend service
TransactionId: 84293235-5d2c-42ba-afc3-a5d4afc5f88e27097
X-CorrelationId: 929618f2-6163-bf73-51b0-6c54a8533c74
TransactionTime: '2021-06-11T16:31:34.041Z'
Api-Url: https://partner-api-qv.key.com/rtp/v1/transactions/list
ServiceError:
metadata:
messages:
- code: 403-Forbidden
message: Entitlements Validation Failed
'408':
description: Request timeout error
headers:
X-CorrelationId:
description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Exception'
example:
ErrorMessage: Error received from backend service
TransactionId: 84293235-5d2c-42ba-afc3-a5d4afc5f88e27097
X-CorrelationId: 929618f2-6163-bf73-51b0-6c54a8533c74
TransactionTime: '2021-06-11T16:31:34.041Z'
Api-Url: https://partner-api-qv.key.com/rtp/v1/transactions/list
ServiceError:
metadata:
messages:
- code: RTP-List-408-timeout
message: The request exceeded the timeout limit. Please adjust your request parameters and try again.
'500':
description: Unexpected server error
headers:
X-CorrelationId:
schema:
type: string
description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
content:
application/json:
schema:
$ref: '#/components/schemas/Exception'
example:
ErrorMessage: Error received from backend
TransactionId: 84293235-5d2c-42ba-afc3-a5d4afc5f88e27097
TransactionTime: '2021-06-11T16:31:34.041Z'
X-CorrelationId: 929618f2-6163-bf73-51b0-6c54a8533c74
Api-Url: https://partner-api-qv.key.com/rtp/v1/transactions/list
ServiceError:
metadata:
messages:
- code: 500-InternalServerError
message: An unexpected error occurred. Please try again later or contact support if the problem persists.
/rtp/v1/transactions/detail/{transactionId}:
get:
tags:
- RTP
summary: View the details of a RTP transaction by its ID
operationId: searchRtpTransaction
description: Provide the transaction ID to retrieve all available fields for that single real time payment transaction.
security:
- bearerAuth: []
parameters:
- name: X-CorrelationId
in: header
schema:
type: string
required: false
description: Universal ID to trace the transaction across all systems involved.
- name: transactionId
in: path
required: true
description: The unique ID number associated with the original payment request.
schema:
maxLength: 100
type: string
example: US99999000999999
responses:
'200':
description: A RTP transaction matches the provided transactionId
headers:
X-CorrelationId:
description: A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/RtpDetailTransaction'
example:
transactionId: US99999000999999
transactionStatus: COMPLETED
transactionStatusTimestamp: '2026-01-12T12:18:01'
transactionDate: '2026-01-12'
transactionAmount: 32772.63
transactionDirection: INBOUND
requestReference: '1122334455'
sendersReference: US99999000999999
clearingReferenceNumber: '20209999MMZZZZZD099999'
remittanceInformation: Payment 01/12/2026_Invoice 123456789 Cust
bankToBankInstructions: Final Payment
customData: USER ID 1
creditor:
name: Global Markets LLC
postalAddress:
type: Office
department: Financial
subDepartment: Sub financial
street: Columbus pike
buildingNumber: '123'
postalCode: '43240'
city: Columbus
region: OH
countryCode: US
addressLine: 123 SIM ST,STE W123 |SIMCITY OH 12345|I/US
creditorAccount:
accountNumber: '987654321'
virtualAccountNumber: '95312346654532'
debtor:
name: Paul Wilson
postalAddress:
type: Office
department: Financial
subDepartment: Sub financial
street: Columbus pike
buildingNumber: '123'
postalCode: '43240'
city: Columbus
region: OH
countryCode: US
addressLine: 123 SIM ST,STE W123 |SIMCITY OH 12345|I/US
debtorAccount:
accountNumber: '123456789'
virtualAccountNumber: '95312346654532'
originator:
name: VAM TEST BANK NA
originalName: Raul Wilson
postalAddress:
type: Office
department: Financial
subDepartment: Sub financial
street: Columbus pike
buildingNumber: '123'
postalCode: '43240'
city: Columbus
region: OH
countryCode: US
addressLine: 123 SIM ST,STE W123 |SIMCITY OH 12345|I/US
beneficiary:
name: SIM IV INC
ultimateName: Saul Wilson
postalAddress:
type: Office
department: Mortgage
subDepartment: Housing
street: 123 BNFW1 ST
buildingNumber: '123'
postalCode: '12334'
city: BNFCITY
region: OH
countryCode: US
addressLine: 123 BNFW1 SIM ST,BNFW1 123 |BNFCITY OH 12334|I/US
beneficiaryAccount:
accountNumber: '9350371100'
originatorAccount:
accountNumber: '9350371111'
ultimateCreditor:
name: ULTCR Party1
postalAddress:
type: Office
department: dept
subDepartment: subDept
street: Oak Point Rd
buildingNumber: '100'
postalCode: '12335'
city: Amherst
region: NY
countryCode: US
addressLine: dept subDept 100 Oak Point Rd Amherst NY pstC44001d
ultimateCreditorAccount:
accountNumber: '1234321'
ultimateDebtor:
name: ULTDB Party
postalAddress:
type: Office
department: dept
subDepartment: subDept
street: Oak Point Rd
buildingNumber: '100'
postalCode: '12335'
city: Amherst
region: NY
countryCode: US
addressLine: dept subDept 100 Oak Point Rd Amherst NY pstC44001d
ultimateDebtorAccount:
accountNumber: '567651'
intermediaryBank1:
name: SIMW1 BANK
aba: '012345678'
bic: SIMWUS01
addressLine: 0123 INT2W1 ST|NEW YORK 01234 US
intermediaryBank2:
name: SIMWINT2 BANK
aba: '112345555'
bic: SIMWUS22
addressLine: 0123 INT2W1 ST|NEW YORK 01235 US
intermediaryBank3:
name: SIMINTW3 CANADA BANK
aba: '112346666'
bic: SIMINT3W1
addressLine: 0123 INT2W1 ST|NEW YORK 01238 US
beneficiaryBank:
aba: '021007821'
bic: SIMCRKEYBUS21
originatorBank:
aba: '011007822'
bic: SIMDBKEYBUS22
failureReasons:
initiatingFailureReasonCode: 'KEY-9998'
initiatingFailureReasonTitle: 'Unauthorized for account'
networkFailureReasonCode: '123'
networkFailureReasonTitle: 'Network Failure'
'401':
description: Unauthorized request
headers:
X-CorrelationId:
description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Exception'
example:
ErrorMessage: Received request is unauthorized, please provide valid
credentials
TransactionId: 0635f201-8fbb-418f-b93a-138d5103e2b91348
X-CorrelationId: 929618f2-6163-bf73-51b0-6c54a8533c74
TransactionTime: '2021-06-11T16:31:34.041Z'
Api-Url: https://partner-api-qv.key.com/rtp/v1/transactions/detail/US99999000999999
'404':
description: No RTP transaction was found with the provided transactionId
headers:
X-CorrelationId:
description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Exception'
example:
ErrorMessage: Error received from backend service
TransactionId: 84293235-5d2c-42ba-afc3-a5d4afc5f88e27097
X-CorrelationId: 929618f2-6163-bf73-51b0-6c54a8533c74
TransactionTime: '2021-06-11T16:31:34.041Z'
Api-Url: https://partner-api-qv.key.com/rtp/v1/transactions/detail/US99999000999999
ServiceError:
metadata:
messages:
- code: RTP-Detail-404-no-records
message: Record Not Found
'500':
description: Unexpected server error
headers:
X-CorrelationId:
schema:
type: string
description: A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
content:
application/json:
schema:
$ref: '#/components/schemas/Exception'
example:
ErrorMessage: Error received from backend
TransactionId: 84293235-5d2c-42ba-afc3-a5d4afc5f88e27097
TransactionTime: '2021-06-11T16:31:34.041Z'
X-CorrelationId: 929618f2-6163-bf73-51b0-6c54a8533c74
Api-Url: https://partner-api-qv.key.com/rtp/v1/transactions/detail/US99999000999999
ServiceError:
metadata:
messages:
- code: 500-InternalServerError
message: An unexpected error occurred. Please try again later or contact support if the problem persists.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Access token supplied in the `Authorization` header using the `Bearer` scheme (e.g. `Authorization: Bearer {token}`).'
schemas:
RtpDetailTransaction:
type: object
description: Contains the response payload with details about an RTP transaction.
properties:
transactionId:
type: string
description: The unique ID number associated with the original payment request.
maxLength: 100
examples:
- US99999000999999
transactionStatus:
type: string
enum:
- CANCELLED
- COMPLETED
- FAILED
- IN PROCESS
- IN REVIEW
- RETURNED
description: 'The status of the RTP payment. Valid values: CANCELLED, COMPLETED, FAILED, IN PROCESS, IN REVIEW, RETURNED'
maxLength: 50
transactionStatusTimestamp:
description: Timestamp for the most recent status change on the transaction.
type: string
pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$'
examples:
- '2026-01-12T12:18:01'
transactionDate:
description: 'Date the transfer occurred. Format: YYYY-MM-DD'
type: string
format: date
examples:
- '2024-01-12'
transactionAmount:
description: The dollar amount of the transaction.
type: number
format: double
examples:
- 32772.63
- 32.1
transactionDirection:
type: string
enum:
- OUTBOUND
- INBOUND
- BOOK
description: RTP Transaction Direction
maxLength: 50
examples:
- OUTBOUND
requestReference:
type: string
description: A reference value for the original request that is useful for traceability and reporting. The ID cannot
exceed 32 characters.
maxLength: 32
examples:
- '1122334455'
sendersReference:
type: string
description: 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.
maxLength: 35
examples:
- US99999000999999
clearingReferenceNumber:
type: string
description: Messages or instructions shared from one bank to another. Data retrieved if part of the original wire transfer.
maxLength: 100
examples:
- 20209999MMZZZZZD099999
creditor:
$ref: '#/components/schemas/PartyDetail'
creditorAccount:
$ref: '#/components/schemas/AccountExtended'
debtor:
$ref: '#/components/schemas/PartyDetail'
debtorAccount:
$ref: '#/components/schemas/AccountExtended'
originator:
$ref: '#/components/schemas/OriginatorPartyDetail'
originatorAccount:
$ref: '#/components/schemas/Account'
beneficiary:
$ref: '#/components/schemas/BeneficiaryPartyDetail'
beneficiaryAccount:
$ref: '#/components/schemas/Account'
ultimateCreditor:
$ref: '#/components/schemas/PartyDetail'
ultimateCreditorAccount:
$ref: '#/components/schemas/Account'
ultimateDebtor:
$ref: '#/components/schemas/PartyDetail'
ultimateDebtorAccount:
$ref: '#/components/schemas/Account'
remittanceInformation:
type: string
description: Information that stays with a payment as it is transferred from one party to another. This field only displays if there is remittance information for the transaction. Message length cannot exceed 256 characters.
maxLength: 1024
examples:
- Payment 01/12/2026_Invoice 123456789 Cust
bankToBankInstructions:
type: string
description: Messages or instructions shared from one bank to another.
maxLength: 2048
examples:
- Final Payment
customData:
type: string
description: A client-defined free-form text field (up to 500 alphanumeric characters) that remains associated with the transaction throughout its lifecycle in the KeyBank network.
minLength: 0
maxLength: 500
examples:
- custom data
intermediaryBank1:
$ref: '#/components/schemas/IntermediaryBank'
intermediaryBank2:
$ref: '#/components/schemas/IntermediaryBank'
intermediaryBank3:
$ref: '#/components/schemas/IntermediaryBank'
beneficiaryBank:
$ref: '#/components/schemas/Bank'
originatorBank:
$ref: '#/components/schemas/Bank'
failureReasons:
$ref: '#/components/schemas/FailureReasons'
RTPListTransaction:
type: object
description: Contains the response payload for RTP inquiries.
properties:
transactionId:
type: string
description: The unique ID number associated with the original payment request
maxLength: 100
examples:
- US99999000999999
transactionStatus:
type: string
enum:
- CANCELLED
- COMPLETED
- FAILED
- IN PROCESS
- IN REVIEW
- RETURNED
description: 'The status of the RTP transfer. Valid values: CANCELLED, COMPLETED, FAILED, IN PROCESS, IN REVIEW, RETURNED'
maxLength: 50
transactionStatusTimestamp:
type: string
pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$'
description: Timestamp for the most recent status change on the transaction.
examples:
- '2026-01-12T12:18:01'
transactionDate:
type: string
format: date
description: 'Date the transfer occurred. Format: YYYY-MM-DD'
examples:
- '2026-01-12'
transactionAmount:
type: number
format: double
description: The dollar amount of the transaction.
examples:
- 32772.63
- 32.1
requestReference:
type: string
description: A reference value for the original request that is useful for traceability and reporting. The ID cannot
exceed 32 characters.
maxLength: 32
examples:
- '1122334455'
sendersReference:
type: string
description: 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.
maxLength: 35
examples:
- US99999000999999
creditor:
$ref: '#/components/schemas/PartySummary'
creditorAccount:
$ref: '#/components/schemas/Account'
debtor:
$ref: '#/components/schemas/PartySummary'
debtorAccount:
$ref: '#/components/schemas/Account'
originator:
$ref: '#/components/schemas/PartySummary'
beneficiary:
$ref: '#/components/schemas/PartySummary'
HealthResponse:
type: object
title: healthResponse
properties:
Status:
type: string
description: Status of the health check response.
examples:
- Ok
Source:
type: string
description: Origin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved.
examples:
- Gateway
- Roundtrip
Timestamp:
type: string
description: Date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$'
examples:
- '2022-09-15T04:49:03'
ClientIp:
type: string
description: Client IP address the gateway receives from the request.
examples:
- 192.0.2.1
X-Forwarded-For:
type: string
description: Sequence of IP addresses for systems between the client and the gateway.
examples:
- '[192.0.2.1]'
Amount0To1B:
description: Amount between 0 and 1,000,000,000 inclusive. Accepts a JSON number or a string. If a string is used, commas
are allowed as thousands separators. Decimal precision must be at most 2 decimal places.
oneOf:
- title: AmountAsNumber
type: number
format: double
minimum: 0
maximum: 1000000000
multipleOf: 0.01
description: Amount between 0 and 1 billion. Decimals are optional. If present, must contain 1 or 2 digits (e.g., 2433.0, 3939.2, 100.25).
- title: AmountAsString
type: string
description: 'String amount may include commas. If commas are used, they must be valid thousands separators (e.g., 1,234,567).
Must be 0..1,000,000,000 inclusive. Decimals are optional; if present,
must be 1 or 2 digits (e.g., 2433.0, 3939.2, 100.25). Note: 1,000,000,000 may only be whole dollars or with a
decimal value of .0/.00.'
pattern: '^(?:(?:1(?:,000){3}|1000000000)(?:\.0{1,2})?|(?:0|[1-9]\d{0,8}|[1-9]\d{0,2}(?:,\d{3}){1,2})(?:\.\d{1,2})?|\.\d{1,2})$'
examples:
- 0.25
- 100
- 100.0
- 2433.0
- 3939.2
- '.25'
- '100'
- '100.0'
- '100.25'
- '75,020.52'
- '1,000,000,000'
- '1,000,000,
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/keycorp/refs/heads/main/openapi/keycorp-rtp-inquiry-openapi.yml