Wire Inquiry | API Documentation

Use the Wire Inquiry API to get wire transaction details and its status.

Before you begin

All KeyBank APIs require certificates, user credentials, and certain permissions. Before you begin, see Key concepts to learn more about these fundamental elements as well as other recommended best practices.

Custom data fields

Responses to inquiries about wire transactions include the customData defined in the original request. Custom data is client-specific metadata that you can use to append certain information or use as an identifier for filtering certain types of transactions. The customData field returns any custom fields that were part of the payment request stored for recall after a successful Wire transaction completes. The request uses the traceId to retrieve the custom data. The custom data included in the request remains with the transaction and is not stored in any KeyBank database.

Wire Inquiry Endpoints

Summary	Endpoint
Get wire transaction details	post /wireInquiry/v1/transactions/details

Get wire transaction details

post /wireInquiry/v1/transactions/details

Get the details about a wire transaction and its status. Wire transaction data can be recalled from the previous 24 months. When setting the date range (fromDate and toDate), the date range specified cannot exceed more than one year.

Request

header FIELD	TYPE	DESCRIPTION
X-CorrelationIdoptional	string	A universal ID to trace the transaction across all the systems involved, useful for system logging and identification.

BODY FIELD	TYPE	DESCRIPTION
getWireInquiryRequestrequired	Object	getWireInquiryRequest

Request example

{
    "getWireInquiryRequest": {
        "accountNumber": [
            "123456789"
        ],
        "transactionType": null,
        "paymentStatus": null,
        "fromDate": 1669852800,
        "toDate": 1669852800,
        "fromTransmitDate": null,
        "toTransmitDate": null,
        "fromAmount": null,
        "toAmount": null,
        "traceID": null,
        "keyBankTransactionReference": null,
        "sourceChannel": null,
        "mdmId": null,
        "startRowIndex": "1",
        "endRowIndex": "1000"
    }
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
getWireInquiryResponserequired	Object	getWireInquiryResponse

Response example (200)

{
    "getWireInquiryResponse": {
        "responseHeader": {
            "status": "Success",
            "statusDescription": "Successfully returned results for the requested range 1 to 1",
            "retreivedRows": "1",
            "totalRows": "1"
        },
        "WireInquiryResult": [
            {
                "amount": "6400",
                "debitCurrencyCode": "USD",
                "transactionType": "INBOUND FED PAYMENT",
                "creditAccountNumber": "987654321",
                "wireEventName": "PaymentWaitForOFCResponse",
                "clearingBankNumber": "21300077",
                "creditAccountBankBranch": "US",
                "creditAccountCurrencyCode": "USD",
                "creditAccountCustomerNumber": "987654321",
                "creditAccountCustomerName": "TEST COMPANY 1, LLC",
                "creditAccountCountry": "US",
                "creditAccountCustomerType": "CORP",
                "wireTransactionDirection": "INBOUND",
                "transactionValueIdentifier": "HVC",
                "creditTransactionCurrency": "USD",
                "settlementPaymentType": "CRD",
                "incomingReferenceNumber": "INVC0012345",
                "paymentEventType": "CRD",
                "sendingBankReferenceNumber": "KTT00049210303842R",
                "initiatingPartyName": "TEST BANK, USA",
                "initiatingPartyPostalAddressLine1": "127 Public Sq, Cleveland",
                "initiatingPartyPostalAddressLine2": "OH 44114",
                "initiatingParty2Name": "TEST COMPANY 2, LLC",
                "initiatingParty2AccountNumber": "123456789",
                "initiatingParty2PostalAddressLine1": "726 Exchange Street,Suite 900,",
                "initiatingParty2PostalAddressLine2": "Buffalo, NY 14210",
                "transactionDetailDocument": "Receivers Reference Information",
                "traceID": "01239240303842R",
                "keybankTransactionReference": "US2201100012345",
                "transmittedDate": "2022-01-10T00:00:00.000-0500",
                "federalClearingReferenceNumber": "20220110B1QDRCQR012345",
                "enteredDate": "2022-01-10T11:38:05.000-0500",
                "creditorAgentBankName": "KeyBank National Association",
                "creditorAgentBankPostalAddressLine1": "250 Delaware Ave Ste",
                "creditorAgentBankPostalAddressLine2": "Buffalo,NY 14202",
                "beneficiaryName": "TEST COMPANY 1, LLC",
                "beneficiaryAccountNumber": "987654321",
                "beneficiaryCreditorPostalAddressLine1": "726 Exchange Street,Suite 900,",
                "beneficiaryCreditorPostalAddressLine2": "Buffalo, NY 14210",
                "sourceChannel": "FRB INITIATED",
                "paymentStatus": "Active",
                "transactionBusinessStatusCode": "Regulatory Filter"
            }
        ]
    }
}

Missing data

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

Response example (400)

{
    "ErrorMessage": "Please make sure your request is correct and try again.",
    "TransactionId": "rrt-770941720727587-2383364-1",
    "X-CorrelationId": "2ebd0e8d5a70-e91",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized request

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

Response example (401)

{
    "ErrorMessage": "Please make sure you're using the correct credentials. Then log in again.",
    "TransactionId": "rrt-770941720727587-2383364-1",
    "X-CorrelationId": "2ebd0e8d5a70-e91",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Access denied

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

Response example (403)

{
    "ErrorMessage": "You don't have access to this resource. Contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "TransactionId": "rrt-770941720727587-2383364-1",
    "X-CorrelationId": "2ebd0e8d5a70-e91",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Not found

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

Response example (404)

{
    "ErrorMessage": "We can't seem to find what you're looking for. Please verify the resource and try again.",
    "TransactionId": "rrt-770941720727587-2383364-1",
    "X-CorrelationId": "2ebd0e8d5a70-e91",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Requested method denied

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

Response example (405)

{
    "ErrorMessage": "Looks like something went wrong. Please check your request method and try again.\"",
    "TransactionId": "rrt-770941720727587-2383364-1",
    "X-CorrelationId": "2ebd0e8d5a70-e91",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Media type not supported

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

Response example (415)

{
    "ErrorMessage": "We currently don't support that format. Please check the format type defined in your request and try again. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "TransactionId": "rrt-770941720727587-2383364-1",
    "X-CorrelationId": "2ebd0e8d5a70-e91",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Too many requests

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

Response example (429)

{
    "ErrorMessage": "Looks like you've sent too many requests. Please wait a moment and try again later.",
    "TransactionId": "rrt-770941720727587-2383364-1",
    "X-CorrelationId": "2ebd0e8d5a70-e91",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Internal server error

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

Response example (500)

{
    "ErrorMessage": "Looks like something went wrong. Please try again when you're ready. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "TransactionId": "rrt-770941720727587-2383364-1",
    "X-CorrelationId": "2ebd0e8d5a70-e91",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

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

Response example (502)

{
    "ErrorMessage": "Looks like something went wrong. Please try again when you're ready. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution. ",
    "TransactionId": "rrt-770941720727587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "2ebd0e8d5a70-e91",
    "ServiceError": {
        "ConnectError": "A connectivity error occurred with the downstream service(unexpected end of file at the target). Please check with your KeyBank Client Success Manager or email developers@keybank.com before trying the request again."
    }
}

Service unavailable

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

Response example (503)

{
    "ErrorMessage": "Looks like something went wrong. Please try again later. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "TransactionId": "rrt-770941720727587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "This service is currently unavailable(there are no active targets). Please check with your KeyBank Client Success Manager or email developers@keybank.com before trying the request again."
    }
}

Gateway timeout

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

Response example (504)

{
    "ErrorMessage": "Your request took too long to process. Please try again. If you experience more issues, contact your KeyBank Client Success Manager or email developers@keybank.com for help with a resolution.",
    "TransactionId": "rrt-770941720727587-2383364-1",
    "X-CorrelationId": "2ebd0e8d5a70-e91",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "The request could not be processed on time (gateway timeout). Please wait a moment and try again later."
    }
}

Schemas

businessFault

NAME	TYPE	DESCRIPTION
errorCodeoptional	string	Business error code
errorDescriptionoptional	string	A human-readable message that describes the type or source of the business error.

connectError

NAME	TYPE	DESCRIPTION
ConnectErroroptional	string	API connectivity error information, if available.

errorResponse

NAME	TYPE	DESCRIPTION
businessFaultoptional	array	businessFault
systemFaultoptional	array	systemFault

exception

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

getWireInquiryRequest

NAME	TYPE	DESCRIPTION
accountNumberrequired	array	One or more bank account numbers. To look up multiple accounts, separate the account numbers with a comma. This field cannot exceed 16 characters.
transactionTypeoptional	array	Indicates the type of transaction. Valid values: INBOUND FED PAYMENT, OUTBOUND SWIFT PAYMENT, OUTBOUND FED PAYMENT, INBOUND SWIFT PAYMENT, INTERNAL, OTHER
paymentStatusoptional	array	Indicates the status of payment. Valid values: Active, Returned, Cancelled, Success, PendingUserAction
fromDaterequired	string	The starting date range for the originating wire transactions returned. The date must be less than or equal to the current date. Transaction data can be recalled from the previous 24 months. Date range cannot exceed more than one year. Format: YYYY-MM-DD
toDaterequired	string	The ending date range for the originating wire transactions returned. The date must be be less than or equal to the current date. Transaction data can be recalled from the previous 24 months. Date range cannot exceed more than one year. Format: YYYY-MM-DD
fromTransmitDateoptional	string	The starting date range for transmitted or settled wire transactions that are returned. The date must be less than or equal to the current date. Transaction data can be recalled from the previous 24 months. Date range cannot exceed more than one year. Format: YYYY-MM-DD
toTransmitDateoptional	string	The ending date range for transmitted or settled wire transactions that are returned. Should be less than or equal to the current date. Transaction data can be recalled from the previous 24 months. Date range cannot exceed more than one year. Format: YYYY-MM-DD
fromAmountoptional	string	Transaction amount lower limit value to be searched.
toAmountoptional	string	Transaction amount upper limit value to be searched.
traceIDoptional	string	Source transaction identifier for a specific transaction.
keyBankTransactionReferenceoptional	string	Unique wire transaction identifier created by KeyBank.
sourceChanneloptional	array	Source channel that created the given transaction. Denotes where the request is from within a KeyBank application or through API.
mdmIdoptional	string	The MDM ID will soon deprecate. This is an ID number that can associate with a single account or many accounts for verification and data retrieval.
startRowIndexoptional	string	Pagination parameter that indicates the starting count available for the records. If this parameter is not provided, value will default to 1.
endRowIndexoptional	string	Pagination parameter that indicates the last count available for the records. If this parameter is not provided, value will default to 1000. The request can't exceed more than 1000 records from the startRowIndex.

getWireInquiryResponse

NAME	TYPE	DESCRIPTION
responseHeaderrequired	Object	responseHeader
WireInquiryResultoptional	array	getWireInquiryResult
errorResponseoptional	Object	errorResponse

getWireInquiryResult

NAME	TYPE	DESCRIPTION
amountoptional	string	Transaction amount
debitCurrencyCodeoptional	string	Debit currency code
transactionTypeoptional	string	Indicates the type of transaction. Valid values: INBOUND FED PAYMENT, OUTBOUND SWIFT PAYMENT, OUTBOUND FED PAYMENT, INBOUND SWIFT PAYMENT, INTERNAL, OTHER
debitAccountNumberoptional	string	Debit account number
creditAccountNumberoptional	string	Credit account number
wireEventNameoptional	string	Payment status code
clearingBankNumberoptional	string	Bank number of the clearing bank.
creditAccountBankBranchoptional	string	Bank branch holding the credit account.
creditAccountCurrencyCodeoptional	string	Transaction currency code of the credit account.
creditAccountCustomerNumberoptional	string	Customer number associated with the credit account.
creditAccountCustomerNameoptional	string	Customer name associated with the credit account.
creditAccountCountryoptional	string	Country of the credit account.
creditAccountCustomerTypeoptional	string	Customer type associated with the credit account.
debitAccountTypeoptional	string	Debit account type
debitAccountBankNumberoptional	string	Bank number holding the debit account.
debitAccountBankBranchoptional	string	Bank branch holding the debit account.
debitAccountCurrencyCodeoptional	string	Transaction currency code associated with the debit account.
debitAccountCustomerNumberoptional	string	Customer number associated with the debit account.
debitAccountCustomerNameoptional	string	Customer name associated with the debit account.
cancelCommentoptional	string	Message provided by the operator who canceled a transaction.
wireTransactionDirectionoptional	string	Indicates the direction of the transaction. Valid values: UNKNOWN, INBOUND, OUTBOUND, BOOK
transactionValueIdentifieroptional	string	Indicates the value of the transaction. Valid values: HVC, HVB, LVC
paymentClearingStateoptional	string	Payment clearing status of the wire transaction.
creditTransactionCurrencyoptional	string	Currency of the amount credited.
settlementPaymentTypeoptional	string	The mechanism or method by which settlement occurs.
incomingReferenceNumberoptional	string	The incoming reference number, which is provided by the sending bank.
executionDateoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the transaction is executed.
paymentEventTypeoptional	string	Payment type of PEN message.
transactionTypeCodeoptional	string	Type of wire transaction code.
sendingBankReferenceNumberoptional	string	Reference number issued by the sending bank.
bankToBankMemooptional	string	Free-form text transmitted between the banks.
initiatingPartyNameoptional	string	Initiating party name
initiatingPartyAccountNumberoptional	string	Initiating party account number
initiatingPartyPostalAddressLine1optional	string	Initiating party address line 1
initiatingPartyPostalAddressLine2optional	string	Initiating party address line 2
initiatingParty2Nameoptional	string	Initiating party 2 name
initiatingParty2AccountNumberoptional	string	Initiating party 2 account number
initiatingParty2PostalAddressLine1optional	string	Initiating party 2 address line 1
initiatingParty2PostalAddressLine2optional	string	Initiating party 2 address line 2
transactionDetailDocumentoptional	string	Detail document or related reference
traceIDoptional	string	Source transaction identifier
keybankTransactionReferenceoptional	string	Unique wire transaction identifier created by KeyBank.
transmittedDateoptional	string	Transaction settled date
federalClearingReferenceNumberoptional	string	Federal reference number
exchangeRateoptional	string	Exchange rate
enteredDateoptional	string	Entered date
creditorAgentBankNameoptional	string	Creditor agent bank name
creditorAgentBankABAoptional	string	Creditor agent bank ABA
creditorAgentBICoptional	string	Creditor agent BIC (business identifier code)
creditorAgentBankPostalAddressLine1optional	string	Creditor agent bank postal address line 1
creditorAgentBankPostalAddressLine2optional	string	Creditor agent bank postal address line 2
beneficiaryNameoptional	string	Beneficiary name
beneficiaryAccountNumberoptional	string	Beneficiary account number
beneficiaryCreditorPostalAddressLine1optional	string	Beneficiary postal address line 1
beneficiaryCreditorPostalAddressLine2optional	string	Beneficiary postal address line 2
sourceChanneloptional	string	Source channel that created the given transaction. Denotes where the request is from within a KeyBank application or through API.
paymentStatusoptional	string	Indicates the status of payment. Valid values: Active, Returned, Cancelled, Success, PendingUserAction
transactionBusinessStatusCodeoptional	string	Transaction business status code
paySubTypeoptional	string	A four-digit code that identifies the type of the wire transaction and if it is a drawdown request (1031), drawdown funds (1032) or drawdown refusal (1033). Valid values: 1031, 1032, 1033
sourceSubTypeoptional	string	Three-character code that defines the source of the paySubType.
correlationIdoptional	string	A universal ID to trace the transaction.
channelCodeoptional	string	Three-character code for the wire channel.
channelModeoptional	string	The mode of the wire transfer.
relatedReferenceIdoptional	string	Reference identification for the wire transaction.
creditVirtualAccountoptional	string	The VAM credit account number. VAM account numbers are 15 digits and start with 953.
debitVirtualAccountoptional	string	The VAM debit account number. VAM account numbers are 15 digits and start with 953.
customDataoptional	string	The values for custom data is defined by the client. This free-form text field can contain up to 500 alphanumeric characters. Custom information stays with the transaction through its lifecycle.

responseHeader

NAME	TYPE	DESCRIPTION
statusrequired	string	Indicates whether the result was successfully retrieved.
statusDescriptionrequired	string	Description of the status
retreivedRowsoptional	string	Total number of transactions retrieved
totalRowsoptional	string	Total number of transactions matching the requested criteria

serviceErrorData

NAME	TYPE	DESCRIPTION
getWireInquiryResponseoptional	Object	getWireInquiryResponse

systemFault

NAME	TYPE	DESCRIPTION
errorCodeoptional	string	System error code
errorDescriptionoptional	string	A human-readable message that describes the type or source of the system error.

transactionDetailsRequest

NAME	TYPE	DESCRIPTION
getWireInquiryRequestrequired	Object	getWireInquiryRequest

transactionDetailsResponse

NAME	TYPE	DESCRIPTION
getWireInquiryResponserequired	Object	getWireInquiryResponse

Errors

For more information about errors, see Error handling.

Error codes and messages

Standard errors use the typical HTTP status codes. Messages specific to KeyBank have an asterisk (*) after the message code number. The ServiceError or errorResponse object with additional information specific to the API.

KeyBank error codes start with ECA-W with a three-digit number that follows. The number increases by one digit for each error message. If you have an issue with your request that generates two error messages specific to the API, the codes will be ECA-W-001 and ECA-W-002.

HTTP STATUS CODE	CUSTOM STATUS CODE	DESCRIPTION
200*	S	`Transaction not found.` The request was received, but there is no result for the requested criteria.
299*	W	`Request processing completed with warnings.` This message occurs when multiple request parameters are provided, and some of the data are not available as part of response.
400*	ECA-W-001F	`Request Validation failed.` There is missing mandatory information like accountNumber, fromDate, or toDate. Review values for mandatory request fields.
400*	ECA-W-001F	`Requested records range is greater than the allowed limit - 1000` Response goes beyond 1000 transactions for the requested account. Change the request criteria to help limit returned transactions to the allowed amount.

YAML file