Wire Inquiry

13 minute read 1.1.0 | updated Feb. 13, 2023

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

KeyBank has some common prerequisites and best practices. All KeyBank APIs require certifications, user credentials, and certain permissions. Make sure to satisfy all prerequisites before building your API.

Follow these steps to prepare for operations:

  1. Have valid certificates for a secure connection.

  2. Make sure you have the API keys needed for basic authentication and API access.

  3. Request a bearer token before you start.

  4. Check the health of the API.

  5. Know your MDM ID.

Certificates are a digital authentication method we use to encrypt the information exchanged between KeyBank and your app or service. To access KeyBank environments, you must exchange valid certificates with KeyBank. These certificates must be properly installed on your system before you start to send API calls.

You need API keys to get a bearer token and to grant access to the APIs and the Pre-Production or Production environments. These API keys are created only for authenticated users that have partnered with KeyBank. For more information, see API security or sign up to become a KeyBank API consumer.

Get a bearer token before you start. Only authenticated users with client credentials can request a bearer token. For more information, see API security or sign up to become a KeyBank API consumer.

Before you start building your API, perform a quick health check. A health check verifies that the API is operational and responding correctly with your system. A bearer token is required to perform a health check. For more information, see Health check.

KeyBank assigns a Master Data Management (MDM) ID to each client. The MDM ID is used for account entitlement. This ID needs to be part of the API request to authorize the account’s data retrieval. The MDM ID can associate an ID with a single account or many accounts for verification and data retrieval. The MDM ID is shared via secure email..

Endpoint Result Description
post /wireInquiry/v1/transactions/details Get wire transaction details Get the details about a wire transaction and its status.

post /wireInquiry/v1/transactions/details

Check on a wire transaction to get its status and details. This call uses the transactionDetailsRequest object for the body of the request payload.

Required parameters: Content-Type, accountNumber, fromDate, toDate, mdmId

HEADER FIELD TYPE DESCRIPTION
X-CorrelationIdoptional string Universal id to trace the transaction across all the systems involved.CorrelationId is unique per request.
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"
    }
}
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"
            }
        ]
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message related to system generating this error.
TransactionIdoptional string Unique functional identifier from the data to identify a message.
TransactionTimeoptional string Time of the occurrence of the error of the message.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data 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"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message related to system generating this error.
TransactionIdoptional string Unique functional identifier from the data to identify a message.
TransactionTimeoptional string Time of the occurrence of the error of the message.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (401)

{
    "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": ""
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message related to system generating this error.
TransactionIdoptional string Unique functional identifier from the data to identify a message.
TransactionTimeoptional string Time of the occurrence of the error of the message.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (403)

{
    "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"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message related to system generating this error.
TransactionIdoptional string Unique functional identifier from the data to identify a message.
TransactionTimeoptional string Time of the occurrence of the error of the message.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (404)

{
    "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"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message related to system generating this error.
TransactionIdoptional string Unique functional identifier from the data to identify a message.
TransactionTimeoptional string Time of the occurrence of the error of the message.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (405)

{
    "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"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message related to system generating this error.
TransactionIdoptional string Unique functional identifier from the data to identify a message.
TransactionTimeoptional string Time of the occurrence of the error of the message.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (415)

{
    "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"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message related to system generating this error.
TransactionIdoptional string Unique functional identifier from the data to identify a message.
TransactionTimeoptional string Time of the occurrence of the error of the message.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (429)

{
    "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"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message related to system generating this error.
TransactionIdoptional string Unique functional identifier from the data to identify a message.
TransactionTimeoptional string Time of the occurrence of the error of the message.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (500)

{
    "ErrorMessage": "Runtime error occured in the service, please check with appplication support team before resubmitting the request",
    "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message related to system generating this error.
TransactionIdoptional string Unique functional identifier from the data to identify a message.
TransactionTimeoptional string Time of the occurrence of the error of the message.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (502)

{
    "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 occured with the downstream service(Unexpected EOF at target), please check with appplication support team before resubmitting the request"
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message related to system generating this error.
TransactionIdoptional string Unique functional identifier from the data to identify a message.
TransactionTimeoptional string Time of the occurrence of the error of the message.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (503)

{
    "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 appplication support before resubmitting the request."
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message related to system generating this error.
TransactionIdoptional string Unique functional identifier from the data to identify a message.
TransactionTimeoptional string Time of the occurrence of the error of the message.
ServiceErroroptional oneOf serviceErrorData connectError

Response example (504)

{
    "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(GatewayTimeout), please wait a moment and resubmit the request."
    }
}
NAME TYPE DESCRIPTION
ErrorMessageoptional string Error message related to system generating this error.
TransactionIdoptional string Unique functional identifier from the data to identify a message.
TransactionTimeoptional string Time of the occurrence of the error of the message.
ServiceErroroptional oneOf serviceErrorData connectError
NAME TYPE DESCRIPTION
getWireInquiryResponseoptional Object getWireInquiryResponse
NAME TYPE DESCRIPTION
ConnectErroroptional string Error information of the connectivity with downstream service.
NAME TYPE DESCRIPTION
responseHeaderrequired Object responseHeader
WireInquiryResultoptional array getWireInquiryResult
errorResponseoptional Object errorResponse
NAME TYPE DESCRIPTION
amountoptional string Transaction amount for the given transaction.
debitCurrencyCodeoptional string Debit currency code for the given transaction.
transactionTypeoptional string Transaction type for the given transaction.
debitAccountNumberoptional string Debit account number for the given transaction.
creditAccountNumberoptional string Credit account number for the given transaction.
wireEventNameoptional string Payment status code for the given transaction.
clearingBankNumberoptional string Bank Number holding the credit account.
creditAccountBankBranchoptional string Bank Branch holding the credit account.
creditAccountCurrencyCodeoptional string Transaction currency of Credit account.
creditAccountCustomerNumberoptional string Customer Number associated to the Credit account.
creditAccountCustomerNameoptional string Customer Name associated to the Credit account.
creditAccountCountryoptional string Country of the credit account.
creditAccountCustomerTypeoptional string Customer Type associated to the credit accout.
debitAccountTypeoptional string Type of the Debit Account.
debitAccountBankNumberoptional string Bank Number holding the debit account.
debitAccountBankBranchoptional string Bank Branch holding the debit account.
debitAccountCurrencyCodeoptional string Transaction currency of debit account.
debitAccountCustomerNumberoptional string Customer Number associated to the debit account.
debitAccountCustomerNameoptional string Customer Name associated to the debit account.
cancelCommentoptional string This field indicates the Text entered by the operator who canceled the message.
wireTransactionDirectionoptional string Direction of transaction.
transactionValueIdentifieroptional string Identifies the value of a transaction.
paymentClearingStateoptional string Payment Clearing Status.
creditTransactionCurrencyoptional string Currency of the amount credited.
settlementPaymentTypeoptional string The mechanism or method by which settlement occurs.
incomingReferenceNumberoptional string Incoming Reference number, which is populated by the sending bank.
executionDateoptional string Date 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 that can be transmitted between the banks.
initiatingPartyNameoptional string Initiating Party Name for the given transaction.
initiatingPartyAccountNumberoptional string Initiating Party Account Number for the given transaction.
initiatingPartyPostalAddressLine1optional string Initiating Party Addr Line 1 for the given transaction.
initiatingPartyPostalAddressLine2optional string Initiating Party Addr Line 2 for the given transaction.
initiatingParty2Nameoptional string Initiating Party2 Name for the given transaction.
initiatingParty2AccountNumberoptional string Initiating Party2 Account Number for the given transaction.
initiatingParty2PostalAddressLine1optional string Initiating Party2 Addr Line 1 for the given transaction.
initiatingParty2PostalAddressLine2optional string Initiating Party2 Addr Line 2 for the given transaction.
transactionDetailDocumentoptional string Detail Document/Related Reference for the given transaction.
traceIDoptional string Source transaction identified for the given transaction.
keybankTransactionReferenceoptional string Unique wire transaction identifier created by Keybank inhouse application.
transmittedDateoptional string Transaction settled date for the given transaction.
federalClearingReferenceNumberoptional string Federal Clearing Reference Number for the given transaction.
exchangeRateoptional string Exchange rate for the given transaction
enteredDateoptional string Entered date for a given transaction.
creditorAgentBankNameoptional string Creditor Agent Bank Name for a given transaction.
creditorAgentBankABAoptional string Creditor Agent Bank ABA for a given transaction.
creditorAgentBICoptional string Creditor Agent BIC for a given transaction.
creditorAgentBankPostalAddressLine1optional string Creditor Agent Bank Postal Address Line 1 for a given transaction.
creditorAgentBankPostalAddressLine2optional string Creditor Agent Bank Postal Address Line 2 for a given transaction.
beneficiaryNameoptional string Beneficiary Name for the given transaction.
beneficiaryAccountNumberoptional string Beneficiary account number for the given transaction.
beneficiaryCreditorPostalAddressLine1optional string Beneficiary postal Addr line 1 for the given transaction.
beneficiaryCreditorPostalAddressLine2optional string Beneficiary postal Addr line 2 for the given transaction.
sourceChanneloptional string Source channel that created the given transaction.
paymentStatusoptional string Payment status code for the given transaction.
transactionBusinessStatusCodeoptional string Transaction business status code for the given transaction.
placeHolderoptional string Meta-data information that denotes creator/approver/other useful info associated to the given transaction
NAME TYPE DESCRIPTION
getWireInquiryResponserequired Object getWireInquiryResponse
NAME TYPE DESCRIPTION
errorCodeoptional string Business error code.
errorDescriptionoptional string Business error description .
NAME TYPE DESCRIPTION
getWireInquiryRequestrequired Object getWireInquiryRequest
NAME TYPE DESCRIPTION
errorCodeoptional string System error code.
errorDescriptionoptional string System description.
NAME TYPE DESCRIPTION
accountNumberrequired array Enter the account number or numbers for your request. To display multiple accounts, separate the account number with a comma. The account number cannot be more than 16-digits in length.
transactionTypeoptional array Indicates the type of transaction. Valid values are INBOUND FED PAYMENT, OUTBOUND SWIFT PAYMENT, OUTBOUND FED PAYMENT, INBOUND SWIFT PAYMENT, INTERNAL, OTHER.
paymentStatusoptional array Indicates the status of payment. Valid values are Active, Returned, Cancelled, Success, PendingUserAction.
fromDaterequired string Corresponds to the wire origination date. Indicates the starting date range for transactions returned. Should be <=current date. YYYY-MM-DD format Date range cannot exceed more than a year.
toDaterequired string Corresponds to the wire origination date. Indicates the ending date range for transactions returned. Should be <=current date. YYYY-MM-DD format Date range cannot exceed more than a year.
fromTransmitDateoptional string Corresponds to the wire transmitted/settled date. Indicates the starting date range for transactions returned. Should be <=current date. YYYY-MM-DD format Date range cannot exceed more than a year.
toTransmitDateoptional string Corresponds to the wire transmitted/settled date. Indicates the ending date range for transactions returned.Should be <=current date. YYYY-MM-DD format Date range cannot exceed more than a year.
fromAmountoptional string Transaction amount lower limit value to be searched.
toAmountoptional string Transaction amount upper limit value to be searched.
traceIDoptional string Indicates sender's/source transaction identifier for a specific Transaction.
keyBankTransactionReferenceoptional string Indicates unique wire transaction identifier created by KeyBank.
sourceChanneloptional array Indicates source channel that created the given transaction. Denotes where the request is from within a KeyBank application or through API.
mdmIdrequired string Enter KeyBank provided MDM ID during client onboarding.
startRowIndexoptional string This is a pagination field. It indicates the starting count available for the records. If the field is not provided, value will default to 1.
endRowIndexoptional string This is a pagination field. It indicates the last count available for the records. If the field is not provided, value will default to 1000. The request can't exceed more than 1000 records from the startRowIndex.
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.
NAME TYPE DESCRIPTION
businessFaultoptional array businessFault
systemFaultoptional array systemFault

An error can indicate a problem with the request, the network, or the API itself. Use the error handling information to get a better understanding of what went wrong and possible corrective actions.

Some APIs contain status messages in the responseHeader object of the response payload. The status field returns the status code S, W, or F. Successful responses return the status code S with an HTTP 200 status code. Responses that were not processed as expected or failed to be processed at all return the status code W for warning or F for failure. Warning messages are associated with HTTP 299 status code. A warning message means the request was successfully received, but there was a minor issue that requires your attention. Failure messages are associated with the HTTP 400 or 500 status codes. Additional information is shared in the statusDescription field.

An erroneous response returns the HTTP code number with the content of the exception schema. Additional information in this schema like the transaction ID and transaction time can help you diagnose the issue.

The schema includes the X-CorrelationId field to help with traceability.

Custom messages are used for API-related functional business messages or faults. Each API can contain custom messages specific to KeyBank operations or the API. These messages can be part of the exception schema or a separate object.

For errors specific to the API, we use the ServiceError object in the exception schema or errorResponse object in the request payload.

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, toDate, or mdmID. Review values for mandatory request fields.
400* ECA-W-001F Error occurred while validating account association.

The MDM ID provided in the request is invalid or empty.
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.
400   Missing data in the request.

Mandatory data not provided, please verify the data and resubmit the request.
401   Received request is unauthorized.

Received request is unauthorized, please provide valid credentials.
403   Request is forbidden to access the resource.

Access to requested resource is forbidden.
404   Request resource is not found.

Requested resource is not found, please verify the resource and resubmit the request.
405   Request method is not allowed.

Requested method is not allow, please verify the method and resubmit the request.
415   Requested unsupported media type.

Requested media type is not allowed, please verify the media type and resubmit the request.
429   Too many request received.

Number requests threshold reached, please resubmit the request after sometime.
500   Internal server error.

Unknown error occurred, please resubmit the request.
502   Bad Gateway.

Bad Gateway, please resubmit the request
503   Service Unavailable.

Service is currently unavailable, please resubmit the request.
504   Gateway timeout.

Request could not be processed on time, please resubmit the request.
YAML file