Pagination

3-minute read Rel. 4.0.0 | updated Nov. 12, 2024

It's a real page-turner

Pagination keeps data manageable by breaking it into chunks, so systems handle large data requests without slowing down.

Row-based pagination: Use startRowIndex and endRowIndex to fetch rows by range.
Offset-based pagination: Set limit (items per page) and offset (start position).
Page size: Defines the number of items on each page and total count of records returned.

Common pagination controls

Row pagination

There are common pagination parameters like startRowIndex and endRowIndex that help retrieve and organize large data sets into separate, scrollable pages. This is commonly used with information reporting and transaction inquiry APIs. These are optional fields and not required for the request.

The startRowIndex query string parameter sets the first row of data of the response. The default value is 1.
The endRowIndex query string parameter sets the final row of data of the response. The default value is 1000 records and is also the maximum number of records allowed in a single transaction.
If the startRowIndex or endRowIndex parameters are blank, all the rows of data return up to the maximum limit of the endRowIndex value for transaction records.
In the response header of the API, an endpoint may return totalRows or retrievedRows. These parameters provide a summary of the total number of transactions that match the request criteria or were retrieved based on the request criteria.

Example

This is an example of a request with general pagination parameters applied in the query string for the Previous Day API:

POST /ddaReports/accounts/v1/transactions/list?startRowIndex=1&endRowIndex=20

In this example, the startRowIndex is 5 so the first row of data is the fifth row, skipping the first four rows of data. The endRowIndex is 20 so that there is only 20 records per page following the fifth row.

Offset pagination

The offset pagination parameters are limit and offset. These parameters tell the server how many records to search for at a time and what records to skip. This parameter is not reliant on the sort controls and is not a recommended parameter for very large sets of data. Offset pagination is available with the RTP Send Payment API and is required for the RTP list of participants endpoint.

The limit is a query string parameter field that tells the server what items to return during a search. The limit restricts how many rows are returned. There is no maximum limit to this parameter.
The offset is a query string parameter field that specifies which set of rows to return. You can use this field to set the starting row for the data that is returned, and control what rows of data to skip. The default value is zero (0).
Be cautious when you use these parameters because if the data set changes it can affect the result and may return an incorrect response.

Example

This is a request example with the offset pagination parameters applied in the query string for the RTP Send Payment API:

GET /rtp/v1/payment/rtp/participant?limit=15&offset=0

In this example, the offset is 0 so that no items are skipped, and the limit is 15 meaning the request will search 15 items at a time.

Page size

You can control how many pages and records are returned with page request parameters like pageSize and pageNumber

The pageNumber is a query string parameter the tells which page to start with the returned response set. Typically, this number is set to 1 at first until you get familiar with record sets based on common queries.
The pageSize is a query string parameter defines the total number of pages to return. This number must 1 or greater and cannot exceed 1000.

Example

This is a request example with the page size parameters applied in the query string for the ACH Inquiry API:

POST /accounts/transactions/v1/ach/list?pageNumber=1&pageSize=50

In this example, the pageNumber is 1 returning the first page of the result set and the pageSize is 50 meaning that only 50 pages from page 1 are returned.

Endpoints with Pagination

API	METHOD	ENDPOINT	PAGINATION PARAMETER
ACH Origination	POST	/ach/payments/v1/status/addenda	`pageSize`
ACH Inquiry	POST	/accounts/transactions/v1/ach/list	`pageNumber` `pageSize`
Wire Inquiry	POST	/wireInquiry/v1/transactions/details	`startRowIndex` `endRowIndex`
RTP Send Payment	GET	/rtp/v1/payment/rtp/participant	`limit` `offset`
RTP Inquiry	POST	/rtp/v1/transactions/list	`pageNumber` `pageSize`
Previous Day	POST	/ddaReports/accounts/v1/transactions/list	`startRowIndex` `endRowIndex`
Intraday	POST	/ddaReports/accounts/v1/transactions/intraday/list	`startRowIndex` `endRowIndex`

Webhooks

6-minute read 2.2.0 | updated Nov. 12, 2024

Timely and automated payment status notifications

Overview

KeyBank’s payment webhooks provide timely and automated payment status notifications without the need for constant API polling or manual checks.

We currently facilitate alerts for both ACH and wire transaction status changes. You get near real-time updates whenever a specific payment event occurs, like a posted ACH transaction or a completed wire transfer.

Requirements

To subscribe to webhook alert notifications for ACH, Wire, or RTP transactions, you must be a commercial customer or fintech partner of KeyBank. Only authorized API consumers can subscribe to this feature.

For existing clients, reach out to your Payments Advisor to start the subscription process.
For new clients, you will first need to onboard with KeyBank (see our Getting Started Guide for the basic process). In addition, you will be asked to provide a few more details like:
- Type of alert subscription (see alert codes)
- A decision if the pre-production and production subscriptions accounts will be the same or different
- Expected volumes per day/month/year

KeyBank recommends that destination application always have authentication. To reduce setup time for webhook subscriptions while maintaining system integrity and security, we recommend these guidelines:

Use Basic Authentication (BasicAuth) which involves providing KeyBank with a unique username and password for your application.
KeyBank will send a Base64 encoded version of the credential to Authorization header of your HTTP request.
Connect securely with a TLS connection for an encrypted, safe exchange of data.

If you have a specialized needs or circumstances that require secure alternatives rather than BasicAuth, speak with your KeyBank Payment Advisor. This may extend setup time.

Got you hooked?

Check out some more content about our webhooks:

Alert codes
Payment webhook specifications
Retry mechanism

Payment webhooks

Alert notifications are triggered by specific payment status events and are sent in the form of an HTTP POST request. KeyBank can send up to 100 alerts per API call. After receiving an alert notification, KeyBank expects you to send an HTTP 2XX status code in response within 10 seconds and the response needs to adhere to KeyBank's format for an alert response.

Payment webhook alert notifications

Each payment webhook alert notification has an alertNotification object that is made up of two parts:

alertHeader: The header information gives you basic information about the request like date and time sent, the alert code, and a unique notification identifier.
alertBody: The body information contains transaction details. Each of the fields will be present in the request even if there is no data retrieved for a particular field. Fields that have no data show the null value.

Both the alertHeader and alertBody can vary by event type, ACH or Wire/RTP. The alertHeader for Wire/RTP notification contains the payType field that specifies if is a wire or RTP alert while the ACH alert header does not have this field. The alertBody fields are also different based on each event type as defined by the alert code.

Alert codes

Each alert notification contains the alert code for the payment status event that occurred. There is an alert code for Wire/RTP and ACH to monitor all payment status events related to that transaction type.

Alert code types

Wire/RTP alert code = AL00901
ACH alert code = AL00906

Note, with a latest specification update, all ACH payment events are now managed with alert code AL00906. This one code consolidates the legacy ACH alert codes: AL00902 (ACH Collected), AL00903 (ACH Posted), AL00904 (ACH Returned), AL00905 (ACH Notification of Change).

Before you begin

All KeyBank APIs require certificates, user credentials, and certain permissions. Check out our Getting Started Guide to learn more.

ACH alert notifications

ACH Notification Request

HEADER FIELD	TYPE	DESCRIPTION
alertSentDateAndTime	string	Date and time the alert was sent. Format: (YYYY-MM-DD)T(HH:MM:SS)Z
alertCode	string	Alert code. Valid values: AL00906
eapAlertGUID	string	Unique alert notification identifier.

BODY FIELD	TYPE	DESCRIPTION
transactionStatus	string	The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumber	string	The unique number for the transaction provided by the originator.
parNumber	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionAmount	number	The dollar amount of the transaction.
collectionDate	string	Date the transaction was processed. Format: YYYY-MM-DD
settlementDate	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCode	string	Two-digit code identifying the account type at the receiving financial institution.
transactionDescription	string	Description about the purpose of the transaction.
authorizedCustomerName	string	Authorized customer name
standardEntryClassCode	string	Three-digit Standard Entry Class (SEC) code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEB
receivingAccountNumber	string	Account number of the person or institution receiving the funds.
receivingCustomerIdentificationNumber	string	The customer identification number for the person receiving the transaction.
receivingCompanyName	string	Company name of the institution getting the funds.
originatingAccountNumber	string	Account number of the ACH transaction originator.
originatingCustomerIdentificationNumber	string	Originating customer identification number
returnReasonCode	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescription	string	Description as to why the ACH transaction is returned.
returnDate	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
notificationOfChangeAddendaCount	string	Count of change notifications for addenda records.
internationalAddendaCount	string	Count of international addenda records.
addendaCount	string	Count of addenda records.

Request example (ACH)

{
"alertNotificationRequest": [  
	{  
	"alertNotification": {
	  "alertHeader": {
		"alertSentDateAndTime": "2024-07-07T16:25:08Z",
		"alertCode": "AL00906",
		"eapAlertGUID": "4g0fda4b-156f-483c-98ae-bd8ccab266h0"
		},
	"alertBody": {
		"transactionStatus": "COLLECTED",
		"traceNumber": "41033956478656",
		"parNumber": "22010008879477",
		"transactionAmount": "287.40",
		"collectionDate": "2024-01-12",
		"settlementDate": "2024-01-12",
		"transactionCode": "22",
		"transactionDescription": "PAYMENT",
		"authorizedCustomerName": "HIGHMARK INC.",
		"standardEntryClassCode": "CCD",
		"receivingAccountNumber": "00000000001000004133",
		"receivingCustomerIdentificationNumber": "65A658990",
		"receivingCompanyName": "LEHIGH GASTROENTEROLOG",
		"originatingAccountNumber": "00000000001000005244",
		"originatingCustomerIdentificationNumber": "7498659450",
		"originatingCompanyName": "HIGHMARK INC.",
		"returnReasonCode": "R29",
		"returnReasonDescription": "Corporate Customer Advises Not Authorized",
		"returnDate": "2024-01-03",
		"notificationOfChangeAddendaCount": "1",
		"internationalAddendaCount": "0",
		"addendaCount": "0"
		}
	  }
	}
  ]
}

Wire/RTP alert notifications

The Wire/RTP alertBody identifies the status of the payment event in the tranBusnStatusCode field.

Wire/RTP statuses

The Wire and RTP statuses listed show the final status values. You may get an intermittent status that is not list in this table. Go to Data values > Wire and RTP webhook statuses to view the full list.

STATUS	DESCRIPTION
Abandoned	Payment is manually forced to not complete payment processing. Payment will not complete workflow.
Cancelled	Payment was cancelled. Payment will not complete workflow.
Completed	Payment processed successfully and completes the workflow.
Fatal	A serious error has occurred. Payment will not complete workflow.
Future Warehouse Cancelled	Payment was cancelled from Future Warehouse queue. Payments enter the Future Warehouse queue if the payment missed the payment network cutoff time and moves to a future business date. When the future business date arrives, the payment network re-enters the payment in the workflow to reach Future Warehouse Cancelled.
Rejected	Payment was rejected by the network. Payment will not complete workflow.
Returned	Payment was returned by receiving bank.

Wire/RTP Notification Request

HEADER FIELD	TYPE	DESCRIPTION
alertSentDateAndTime	string	Date and time the alert was sent. Format: (YYYY-MM-DD)T(HH:MM:SS)Z
alertCode	string	Alert code. Valid values: AL00901
payType	string	Identifies if the payment type was a Wire or RTP transaction. Valid values: WIRE, RTP
eapAlertGUID	string	Unique alert notification identifier.

BODY FIELD	TYPE	DESCRIPTION
crOrDbCode	string	Identifies the transaction type as credit or debit. Valid values: C (credit), D (debit)
crArngNum	string	Account number of the credit account.
crArngTypeCode	string	Type code of the credit account.
crArngBankNum	string	Bank number of the credit account.
crTranCurrencyCode	string	Transaction currency code of the credit account.
dbArngTypeCode	string	Type code of the debit account
dbTranCurrencyCode	string	Transaction currency code of the debit account.
requestReferenceNumber	string	Unique identification number for an originating wire or RTP transaction. This number is limited to 32 characters.
crIpId	string	Customer number associated with the credit account.
crIpNm	string	Customer name associated with the credit account.
dbArngNum	string	Account number of the debit account.
dbArngBankNum	string	Bank number of the debit account.
dbIpId	string	Customer number associated with the debit account.
dbIpINm	string	Customer name associated with the debit account.
payNotifyTs	string	Timestamp of the payment event.
wireEventNm	string	Payment status code
tranAmt	string	Dollar amount of the transaction.
tranExecutedDt	string	Date the transaction is executed. Format: YYYYMMDD
federalReferNum	string	Federal reference number
sndngBankReferNum	string	Reference number attached to a wire, issued by the sending bank.
tranId	string	Unique transaction identifier
tranBusnStatusCode	string	Transaction business status code
wireDirectionCode	string	Indicates the direction of the transaction.
tranType	string	Type of transaction.
tranValueTypeCode	string	Identifies the value of a transaction.
wireProcessTypeCode	string	Wire processing type code
benefitAba	string	ABA routing number of the beneficiary.
benefitArngNum	string	Account number of the beneficiary.
benefitIpAddrLine	string	Address lines 1-7 (array) of the beneficiary.
benefitBicCode	string	BIC number of the beneficiary.
benefitBankAbaNum	string	ABA routing number of the beneficiary's bank.
benefitBankArngNum	string	Account number of the beneficiary's bank.
benefirBankAddrLine	string	Address lines 1-7 (array) of the beneficiary's bank.
benefitBankBicCode	string	BIC number of the beneficiary's bank.
benefitBankNm	string	Name of the beneficiary's bank.
intrmdryBankAbaNum1	string	ABA routing number of the intermediary bank 1.
intrmdryBNankAddrLine1	string	Address lines 1-7 (array) of the intermediary bank 1.
intrmdryBankNm1	string	Name of the intermediary bank 1.
intrmdryBicCode1	string	BIC number of the intermediary bank 1.
intrmdryBankAbaNum2	string	ABA routing number of the intermediary bank 2.
intramdryBankAddrLine2	string	Address lines 1-7 (array) of the intermediary bank 2.
intrmdryBankNm2	string	Name of the intermediary bank 2.
intrmdryBicCode2	string	BIC number of the intermediary bank 2.
intrmdryBankAbaNum3	string	ABA routing number of the intermediary bank 3.
intrmdryBankAddrLine3	string	Address lines 1-7 (array) of the intermediary bank 3.
intrmdryBankNm3	string	Name of the intermediary bank 3.
intrmdryBicCode3	string	BIC number of the intermediary bank 3.
orgntngBankAbaNum	string	ABA routing number of the wire originator's bank.
orgntngBankAddrLine	string	Address lines 1-7 (array) of the wire originator's bank.
orgntngBankBicCode	string	BIC number of the wire originator's bank.
orgntngBankNm	string	Name of the wire originator's bank.
orgntngAba1	string	ABA routing number of the originator 1.
orgntngArngNum1	string	Account number of the originator 1.
orgntngIpNm1	string	Name of the originator 1.
orgntngIpAddrLine1	string	Address lines 1-7 (array) of the originator 1.
orgntngAba2	string	ABA routing number of the originator 2.
orgntngArngNum2	string	Account number of the originator 2.
orgntngIpNm2	string	Name of the originator 2.
orgntngIpAddrLine2	string	Address lines 1-7 (array) of the originator 2.
orgntngAba3	string	ABA routing number of the originator 3.
orgntngArngNum3	string	Account number of the originator 3.
orgntngIpNm3	string	Name of the originator 3.
orgntngIpAddrLine3	string	Address lines 1-7 (array) of the originator 3.
crVirtualNum	string	Virtual account number of the credit account.
dbVirtualNum	string	Virtual account number of the debit account.

Request example (Wire/RTP)

{
  "alertNotificationRequest": [
  {
	"alertNotification": 
	  "alertHeader": {
		"alertSentDateAndTime": "2023-02-1159T10:20:56Z",
		"alertCode": "AL00901",
		"payType": "WIRE",
		"eapAlertGUID": "f4d88cd2-446c-3cc4-9330-aa123456789"
		},
	  "alertBody": {
		"crOrDbCode": "C",
		"crArngNum": "359123456789",
		"crArngTypeCode": "DDA",
		"crArngBankNum": "0101",
		"crTranCurrencyCode": "USD",
		"dbArngTypeCode": "DDA",
		"dbTranCurrencyCode": "USD",
		"requestReferenceNumber": "4630123-20240212161123",
		"crIpId": "999997",
		"crIpNm": "BANKOFTEST",
		"dbArngNum": "201907987654321",
		"dbArngBankNum": "0101",
		"dbIpId": "30472222",
		"dbIpNm": "Test Name",
		"payNotifyTs": "1673615327943",
		"wireEventNm": "WirePaymentTransactionEvent",
		"tranAmt": "12.79",
		"tranExecutedDt": "20240112",
		"federalReferNum": "null",
		"sndngBankReferNum": "null",
		"tranId": "US23010987654321",
		"tranBusnStatusCode": "RegulatoryFilter",
		"wireDirectionCode": "OUTBOUND",
		"tranType": "null",>
		"tranValueTypeCode": "N",
		"wireProcessTypeCode": "null",
		"benefitAba": "null",
		"benefitArngNum": "3435656765",
		"benefitIpAddrLine": "250 Delaware Ave St",
		"benefitBicCode": "KEYBUS33 XXX",
		"benefitBankAbaNum": "null",
		"benefitBankArngNum": "null",
		"benefitBankAddrLine": "250 Delaware Ave St",
		"benefitBankBicCode": "KEYBUS33 XXX",
		"benefitBankNm": "KeyBank National Association",
		"intrmdryBankAbaNum1": "null",
		"intrmdryBankAddrLine1": "null",
		"intrmdryBankNm1": "KeyBank National Association",
		"intrmdryBicCode1": "21300077",
		"intrmdryBankAbaNum2": "null",
		"intrmdryBankAddrLine2": "null",
		"intrmdryBankNm2": "BANKOFTEST",
		"intrmdryBicCode2": "KEYBUS33 XXX",
		"intrmdryBankAbaNum3": "null",
		"intrmdryBankAddrLine3": "null",
		"intrmdryBankNm3": "null",
		"intrmdryBicCode3": "null",
		"orgntngBankAbaNum": "null",
		"orgntngBankAddrLine": "null",
		"orgntngBankBicCode": "null",
		"orgntngBankNm": "null",
		"orgntngAba1": "null",
		"orgntngArngNum1": "123456789",
		"orgntngIpNm1": "TEST COMPANY 1, LLC",
		"orgntngIpAddrLine1": "127 Public Sq, Cleveland,OH 44114,US",
		"orgntngAba2": "null",
		"orgntngArngNum2": "null",
		"orgntngIpNm2": "null",
		"orgntngIpAddrLine2": "null",
		"orgntngAba3": "null",
		"orgntngArngNum3": "null",
		"orgntngIpNm3": "null",
		"orgntngIpAddrLine3": "null"
		"crVirtualNum": "953456789",
		"dbVirtualNum": "953654321"
		}
	  }
	}
  ]
}

Payment webhook response

The top level alertNotificationResponse object is an array of alertAcknowledgment objects. Because KeyBank can send up to 100 alerts per API call, each alert notification sent must be responded to with its own alertAcknowledgment object. The format of the response needs to adhere to the format specified here.

Response

FIELD	TYPE	DESCRIPTION
alertStatus	string	Status of the alert notification.
confirmationGUID	string	API customer unique ID for the alert notification.
alertRecievedDateAndTime	string	Date and time the alert was received. Format: (YYYY-MM-DD)T(HH:MM:SS)Z
eapAlertGUID	string	Unique alert notification identifier passed through from the request.
message	string	Free-form text field to describe the response.

Successful response

{
  "alertNotificationResponse": [
  {
    "alertAcknowledgment": {
    "alertStatus": "SUCCESS",
    "confirmationGUID": "5f0ada5b-056f-483c-98ae-ac6ccab269c1",
    "alertRecievedDateAndTime": "2021-11-19T10:31:12Z",
    "eapAlertGUID": "f4d88cd2-446c-3cc4-9330-aa123456789",
    "message": "Successfully submitted the request"
    }
  }
 ]
}

Unsuccessful response

{
  "alertNotificationResponse": [
  {
    "alertAcknowledgment": {
      "alertStatus": "FAILURE",
      "confirmationGUID": "5f0ada5b-056f-483c-98ae-ac6ccab269c1",
      "alertRecievedDateAndTime": "2021-11-19T10:31:12Z",
      "eapAlertGUID": "f4d88cd2-446c-3cc4-9330-aa123456789",
      "message": "Required parameter(s) not found: [fieldName(s)]"
    }
  }
]
}

Payment webhook errors

If your webhook receiver/handler encounters an error, KeyBank expects you to send one of the following HTTP status codes:

400 Invalid input
401 Authentication error
403 Authorization error
500 Internal error

Only the HTTP 500 error codes will prompt the retry mechanism. If you have one of the HTTP 400 error codes, you are expected to troubleshoot the issue. If you cannot find a resolution, please contact your Payments Advisor or Technical Account Manager.

Payment webhook alert retry mechanism

The retry mechanism is trigger for any backend error issues, typically associated with HTTP 500's status codes. With a unsuccessful HTTP 5XX response, the KeyBank retry mechanism will attempt to deliver a failed alert notification for 24 hours after the original failed notification. The retry attempts follow this schedule:

3 attempts, each attempt every 30 seconds
6 attempts, each attempt every 90 minutes
3 attempts, each attempt every 5 hours

Attempt number	Time between attempts	Time elapsed since first alert
1-3	30 seconds	30 seconds - 1.5 minutes
4-9	90 minutes	1.5 - 9 hours
10-12	5 hours	14 - 24 hours

After the 24-hour window, the notification fails and there are no more additional retry attempts. Notify your Payments Advisor if there is an outage for more than 24 hours or if you have an outage planned for your systems that extends past a 24-hour period. You can also notify us with our Support form.

To inquire about a payment event after 24 hours, you must use the ACH Inquiry or Wire Inquiry APIs.

Changelog

Release	API version	Change description	Impact
August 2024	2.2.0	We introduce the version 2 of our Webhooks. This API is sleek! For ACH alerts, the alert codes (AL00902, AL00903, AL00904, AL00905) have been consolidated into a single and new code, AL00906.	HIGH
April 2024	1.1.0	For Wire and RTP webhook alert notifications, `dbTranCurrencyCode` and `dbAngTypeCode` are in the alert body. Added the `requestReferenceNumber` to the alert body for Wire and RTP alert notification. If this parameter has a value, it will return in the alert body for RTP or Wire notifications.	MID
December 2023	1.1.0	Remove all leading zeros for the following account parameters: `crArngNum` `dbArngNum` `accountNumber`	LOW
August 2023	1.0.1	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

ACH Inquiry

4-minute read 1.2.1 | updated Oct. 15, 2024

Get the status for your ACH transactions

ACH Inquiry Endpoints

Summary	Endpoint
Health check	get /accounts/transactions/v1/healthCheck
Get details about an ACH transaction with a PAR number	get /accounts/transactions/v1/ach/detail/{parNumber}
Search for ACH transactions	post /accounts/transactions/v1/ach/list

Overview

You can use the ACH Inquiry API to get the status for ACH transactions as they are received and processed by KeyBank.

The consolidation settlement type affect what information is returned. The ACHStatus field defines the status of the transaction as in progress (COLLECTED), processed (SETTLED), or returned (RETURNED).

For clients with a non-consolidated settlement, you can receive information about collected, settled, and returned transactions.
For clients with a consolidated settlement, you will only receive collected and returned transactions. SETTLED is not an available status for consolidated settlement.

PAR-don me

ACH inquiries require a parNumber or traceNumber for inquiries. Learn more in our ACH APIs User Guide.

Health check

get /accounts/transactions/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	System producing the health response. Genesis of the response could either be just from “gateway” or “roundtrip” from the farthest possible system involved in generating this response.
Timestampoptional	string	Timestamp when the health response is being returned by this service.
ClientIpoptional	string	IP of the client from which this request for health check is received by the gateway.
X-Forwarded-Foroptional	string	Sequence of all the Ips of the 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]"
}

Get details about an ACH transaction with a PAR number

get /accounts/transactions/v1/ach/detail/{parNumber}

Use the PAR number to retrieve information about an ACH transaction.

Request

path FIELD	TYPE	DESCRIPTION
parNumberrequired	string	The unique PAR number assigned to the the transaction by the ACH product processor.

Responses

Successful response

NAME	TYPE	DESCRIPTION
parNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionStatusoptional	string	The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumberoptional	string	The unique number for the transaction provided by the originator.
transactionAmountoptional	number	The dollar amount of the transaction.
settlementDateoptional	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
transactionCodeDescriptionoptional	string	Description for the transaction code.
transactionDescriptionoptional	string	Description about the purpose of the transaction.
authorizedCustomerNameoptional	string	Authorized customer name
standardEntryClassCodeoptional	string	The three-digit Standard Entry Class code based on Nacha rules.
standardEntryClassDescriptionoptional	string	The description for the Nacha SEC code.
receivingAccountoptional	Object	AccountDetail
receivingPartyoptional	Object	PartyDetail
originatingAccountoptional	Object	AccountDetail
originatingPartyoptional	Object	PartyDetail
returnDateoptional	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCodeoptional	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescriptionoptional	string	Description as to why the ACH transaction is returned.
addendaCountoptional	integer	Count of addenda records.
notificationOfChangeAddendaCountoptional	integer	Count of change notifications for addenda records.
internationalAddendaCountoptional	integer	Count of international addenda records.
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.
checkSerialNumberoptional	string	Serial number for the check converted to an ACH transaction.
transactionDirectionoptional	string	Indicates the direction of the transaction. Valid values: ORIGINATING ITEM, RECEIVING ITEM
addendaoptional	array	Addendum
notificationOfChangeoptional	array	NotificationOfChange

Response example (200)

{
    "parNumber": "22018007665985",
    "transactionStatus": "COLLECTED",
    "traceNumber": "000000000000000",
    "transactionAmount": 10.01,
    "settlementDate": "2021-03-08",
    "transactionCode": "22",
    "transactionCodeDescription": "Automated Deposit",
    "transactionDescription": "DEPOSIT",
    "authorizedCustomerName": "TEST CUSTOMER1",
    "standardEntryClassCode": "CCD",
    "standardEntryClassDescription": "Cash Concentration or Disbursement",
    "receivingAccount": {
        "accountNumber": "123456789012",
        "bankNumber": "0000",
        "routingNumber": "1234567890"
    },
    "receivingParty": {
        "customerIdentificationNumber": "099999999",
        "companyName": "MERCHANT",
        "customerName": "TEST MERCHANT"
    },
    "originatingAccount": {
        "accountNumber": "123456789012",
        "bankNumber": "0000",
        "routingNumber": "1234567890"
    },
    "originatingParty": {
        "customerIdentificationNumber": "1234567",
        "companyName": "COMPANY NAME 1",
        "customerName": "CUSTOMER NAME 1"
    },
    "returnDate": "2024-02-01",
    "returnReasonCode": "R02",
    "returnReasonDescription": "Account Closed",
    "addendaCount": 1,
    "notificationOfChangeAddendaCount": 1,
    "internationalAddendaCount": 0,
    "customData": "merchant:status",
    "checkSerialNumber": "4345",
    "transactionDirection": "Receiving Item",
    "addenda": [
        {
            "sequenceNumber": 1,
            "entryDetailSequenceNumber": "188",
            "paymentRelatedInformation": "Addenda Record (Applies to CCD, CTX, PPD, and WEB entries)"
        }
    ],
    "notificationOfChange": [
        {
            "changeCode": "C02",
            "changeDescription": "Incorrect transit\/routing number",
            "correctedData": "1234567890"
        }
    ]
}

Successful response

NAME	TYPE	DESCRIPTION
parNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionStatusoptional	string	The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumberoptional	string	The unique number for the transaction provided by the originator.
transactionAmountoptional	number	The dollar amount of the transaction.
settlementDateoptional	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
transactionCodeDescriptionoptional	string	Description for the transaction code.
transactionDescriptionoptional	string	Description about the purpose of the transaction.
authorizedCustomerNameoptional	string	Authorized customer name
standardEntryClassCodeoptional	string	The three-digit Standard Entry Class code based on Nacha rules.
standardEntryClassDescriptionoptional	string	The description for the Nacha SEC code.
receivingAccountoptional	Object	AccountDetail
receivingPartyoptional	Object	PartyDetail
originatingAccountoptional	Object	AccountDetail
originatingPartyoptional	Object	PartyDetail
returnDateoptional	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCodeoptional	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescriptionoptional	string	Description as to why the ACH transaction is returned.
addendaCountoptional	integer	Count of addenda records.
notificationOfChangeAddendaCountoptional	integer	Count of change notifications for addenda records.
internationalAddendaCountoptional	integer	Count of international addenda records.
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.
checkSerialNumberoptional	string	Serial number for the check converted to an ACH transaction.
transactionDirectionoptional	string	Indicates the direction of the transaction. Valid values: ORIGINATING ITEM, RECEIVING ITEM
addendaoptional	array	Addendum
notificationOfChangeoptional	array	NotificationOfChange

Response example (200)

{
    "parNumber": "22018007665985",
    "transactionStatus": "COLLECTED",
    "traceNumber": "000000000000000",
    "transactionAmount": 10.01,
    "settlementDate": "2021-03-08",
    "transactionCode": "22",
    "transactionCodeDescription": "Automated Deposit",
    "transactionDescription": "DEPOSIT",
    "authorizedCustomerName": "TEST CUSTOMER1",
    "standardEntryClassCode": "CCD",
    "standardEntryClassDescription": "Cash Concentration or Disbursement",
    "receivingAccount": {
        "accountNumber": "123456789012",
        "bankNumber": "0000",
        "routingNumber": "1234567890"
    },
    "receivingParty": {
        "customerIdentificationNumber": "099999999",
        "companyName": "MERCHANT",
        "customerName": "TEST MERCHANT"
    },
    "originatingAccount": {
        "accountNumber": "123456789012",
        "bankNumber": "0000",
        "routingNumber": "1234567890"
    },
    "originatingParty": {
        "customerIdentificationNumber": "1234567",
        "companyName": "COMPANY NAME 1",
        "customerName": "CUSTOMER NAME 1"
    },
    "returnDate": "2024-02-01",
    "returnReasonCode": "R02",
    "returnReasonDescription": "Account Closed",
    "addendaCount": 1,
    "notificationOfChangeAddendaCount": 1,
    "internationalAddendaCount": 0,
    "customData": "merchant:status",
    "checkSerialNumber": "4345",
    "transactionDirection": "Receiving Item",
    "addenda": [
        {
            "sequenceNumber": 1,
            "entryDetailSequenceNumber": "188",
            "paymentRelatedInformation": "Addenda Record (Applies to CCD, CTX, PPD, and WEB entries)"
        }
    ],
    "notificationOfChange": [
        {
            "changeCode": "C02",
            "changeDescription": "Incorrect transit\/routing number",
            "correctedData": "1234567890"
        }
    ]
}

Advanced search for ACH transactions

post /accounts/transactions/v1/ach/list

Search for ACH transactions by passing certain search parameters. With ACH transactions, each status point has a start and end date. If you search using the fromDate and toDate parameters, use the dateSearchType to identify if it is the start and end date for when the transaction was collected, returned, or settled. If you leave the dateSearchType field blank, the request only searches the date range for collected transactions.

Request

NAME	TYPE	DESCRIPTION
accountNumberrequired	string	The bank account number. This field cannot exceed 16 characters.
dateSearchTypeoptional	string	Each ACH transaction status has an associated date range. Indicate the specific transaction date set to search. If left blank, the search defaults to collected transaction dates. Valid values: COLLECTED, RETURNED, SETTLED
fromDateoptional	string	Start date for the date range. This date must be the current date or prior to the current date. Transaction data can be recalled within 180 days of the current date. Format: YYYY-MM-DD
toDateoptional	string	End date for the date range. This date can be the current day or a later date from the start date (fromDate). The date range should 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.
traceNumberoptional	string	The unique number for the transaction provided by the originator.
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",
  "dateSearchType": "COLLECTED",
  "fromDate": 1706745600,
  "toDate": 1706745600,
  "minimumAmount": 100,
  "maximumAmount": 75020.5,
  "traceNumber": "041001030016002",
  "pageNumber": 1,
  "pageSize": 150
 }

Responses

Successful response

NAME	TYPE	DESCRIPTION
transactionsoptional	string	AchListTransaction
metadataoptional	string	Metadata

Response example (200)

{
  "transactions": [{
    "parNumber": "22018007665985",
    "transactionStatus": "COLLECTED",
    "traceNumber": "000000000000000",
    "transactionAmount": 10.01,
    "settlementDate": "2021-03-08",
    "transactionCode": "22",
    "authorizedCustomerName": "TEST CUSTOMER1",
    "standardEntryClassCode": "CCD",
    "receivingAccount": {
      "accountNumber": "123456789012"
      },    
    "receivingParty": {
      "customerIdentificationNumber": "099999999",
      "companyName": "MERCHANT"
      },
    "originatingAccount": {
      "accountNumber": "123456789012"
      },
    "originatingParty": {
      "customerIdentificationNumber": "1234567",
      "companyName": "COMPANY NAME 1"
      },
    "returnDate": "2024-02-01",
    "returnReasonCode": "R02",
    "returnReasonDescription": "Account Closed",
    "addendaCount": 1,
    "notificationOfChangeAddendaCount": 1,
    "internationalAddendaCount": 0
    }
  ],
    "metadata": {
      "messages": [{
        "code": "099",
        "message": "Search results match the criteria"
          }    
    ],
    "page": {
    "pageNumber": 1,
    "pageSize": 10,
    "totalPages": 10,
    "totalRecords": 28,
    "lastPage": true
    }
    }    
    }

Bad input parameter

NAME	TYPE	DESCRIPTION
metadataoptional	string	Metadata

Response example (400)

{
  "metadata": {
    "messages": [{
      "code": "001",
      "message": "There are no transactions that match the parNumber."
     }  
  ],
  "page": {
    "pageNumber": 1,
    "pageSize": 1,
    "totalPages": 1,
    "totalRecords": 0,
    "lastPage": false
   }
  }
 }

Schemas

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

serviceErrorData

NAME	TYPE	DESCRIPTION
ServiceErrorDataoptional	oneOf	returnACHtransactionslistResponse achCollectedTransactionsResponse achPostedTransactionsResponse achStatusInquiryResponse

connectError

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

returnACHtransactionslistResponse

NAME	TYPE	DESCRIPTION
getACHReturnTransactionsResponseoptional	Object	achReturnTransactionsResponse

ACHReturnTransaction

NAME	TYPE	DESCRIPTION
returnTransactionParNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
sourceBankNumberoptional	string	Originating entry bank number
sourceAccountNumberoptional	string	Originating account number
sourceTransactionRecordNumberoptional	string	Originating record number for the transaction
sourceSysCodeoptional	string	Do not use. This field is for internal purpose only.
sourceSysOfRecordCodeoptional	string	Do not use. This field is for internal purpose only.
snapshotDateoptional	string	This field is for internal purpose only.
originalACHTransactionParNumberoptional	string	The assigned PAR number for the original ACH transaction.
originalTransactionProcessDateoptional	string	Date the transaction is processed. Format: YYYY-MM-DD
originalTransactionProcessTimeoptional	string	Time the transaction is processed in 24-hour time. Format: HHMMSS
originalTransactionProcessTimestampoptional	string	The date and time the transaction is processed. Format: YYYY-MM-DD HH:MM:SS
originatingReceiverCodeoptional	string	Two-character code that identifies the transaction type as originating (O) or receiving (R) and if the transaction is incoming (I) or outgoing (O). Codes can be OI, OO, RI, or RO.
originatingReceiverDescriptionoptional	string	Description for the returned originating receiver code.
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
transactionCodeDescriptionoptional	string	Description for the transaction code.
transactionFlowTypeCodeoptional	string	Identifies if transaction is intrabank (within a single financial institution) or interbank (between two or more banks). Valid values: INTRA, INTER
transactionFlowTypeDescriptionoptional	string	Description for the transaction flow type code.
transactionAmountoptional	string	The dollar amount of the transaction.
transactionDescription1optional	string	A free form text field that provides the receiver with a description about the purpose of the transaction.
transactionDescription2optional	string	Additional transaction description information.
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
sourceTransactionCreatedDateoptional	string	Date when the user created the ACH transaction. Format: YYYY-MM-DD
sourceTransactionCreatedTimeoptional	string	Time when the user created the ACH transaction. The time format uses the 24-hour clock. Format: HHMM
sourceTransactionCreatedTimestampoptional	string	The date and time that the ACH transaction was created. Format: YYYY-MM-DD HH:MM:SS
sourceTransactionProcessDateoptional	string	Date when the transaction was collected by the ACH product processor. Format: YYYY-MM-DD
sourceTransactionProcessTimeoptional	string	Time when the transaction was collected by the ACH product processor. The time format uses the 24-hour clock. Format: HHMMSS
sourceTransactionProcessTimestampoptional	string	The date and time the ACH transaction was collected by the ACH product processor. Format: YYYY-MM-DD HH:MM:SS
inboundCollectionWindowoptional	string	The time window when the transaction collection is processed. The time format uses the 24-hour clock. Format: HHMM
outboundCollectionWindowoptional	string	The outbound processing window for the transaction collection. The time format uses the 24-hour clock. Format: HHMM
sourceTransactionSettledDateoptional	string	Date when the transaction is settled. Format: YYYY-MM-DD
sourceTransactionSettledTimeoptional	string	The time window when the transaction is settled. The time format uses the 24-hour clock. Format: HHMM
sourceTransactionSettledTimestampoptional	string	The date and time the ACH transaction is settled. Format: YYYY-MM-DD HH:MM:SS
receivingAccountNumberoptional	string	Account number of the person or institution receiving the funds.
receivingCustIdentificationNumberoptional	string	The customer identification number for the person receiving the transaction.
receivingCustomerNameoptional	string	Customer name of the person receiving the funds.
receivingCompanyNameoptional	string	Company name of the institution getting the funds.
receivingFIBankNumberoptional	string	Bank number for the financial institution receiving the funds.
receivingFIRoutingNumberoptional	string	Routing number for the receiving financial institution.
originatingAccountNumberoptional	string	Account number of the ACH transaction originator.
originatingCustIdentificationNumberoptional	string	Originating customer identification number
originatingCustomerNameoptional	string	Originating customer name
originatingCompanyNameoptional	string	Originating company name
originatingFIBankNumberoptional	string	Originating financial institution bank number
originatingFIRoutingNumberoptional	string	Originating financial institution routing number
authorizedCustomerNameoptional	string	Authorized customer name
immediateDestinationIDoptional	string	The ID indicates the next location of the file once it leaves KeyBank.
returnReleaseDateoptional	string	Release date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCodeoptional	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescriptionoptional	string	Description as to why the ACH transaction is returned.
checkSerialNumberoptional	string	Serial number for the check converted to an ACH transaction.
nachaBatchNumberoptional	string	The sequential number of the Nacha batch job.
nachaFileHeadRefererenceNumberoptional	string	The Nacha transaction file reference number.
nachaSecondarySecCodeoptional	string	The secondary Nacha standard entry class (SEC) code for the transaction, if applicable. Valid values: CCD, CTX, PPD, TEL, WEB.
nachaSecondarySecDescriptionoptional	string	The description for the secondary Nacha SEC code.
traceIdoptional	string	The trace ID number from the source application.
postCompanyCostcontrolNumberoptional	string	Do not use. This field is for internal purpose only.
glAccountNumberoptional	string	Do not use. This field is for internal purpose only.
collectionPointoptional	string	Transaction collection point
collectionApplicationTypeCodeoptional	string	Do not use. This field is for internal purpose only.
collectionApplicationTypeDescriptionoptional	string	Do not use. This field is for internal purpose only.
batchIDoptional	string	The identification number for the batch job.
customDataoptional	string	Custom data from the originating payment request.

businessFault

NAME	TYPE	DESCRIPTION
errorCodeoptional	string	Business error code
errorDescriptionoptional	string	Business error description

achReturnTransactionsResponse

NAME	TYPE	DESCRIPTION
responseHeaderrequired	Object	responseHeader
ACHReturnTransactionoptional	array	ACHReturnTransaction
errorResponseoptional	Object	errorResponse

systemFault

NAME	TYPE	DESCRIPTION
errorCodeoptional	string	System error code
errorDescriptionoptional	string	System error description

achReturnTransactionsRequest

NAME	TYPE	DESCRIPTION
getACHReturnTransactionsRequestoptional	Object	getACHReturnTransactionsRequest

getACHReturnTransactionsRequest

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 than 16 characters.
fromDaterequired	string	The start date of a date range for submitted transactions. This date should be less than or equal to the current date. Date range cannot exceed more than one year. Format: YYYY-MM-DD
toDaterequired	string	The end date of a date range for the submitted transactions. The date must be later than the start date (fromDate). Date range cannot exceed more than one year. Format: YYYY-MM-DD
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
fromAmountoptional	string	Transaction amount lower limit value to be searched.
toAmountoptional	string	Transaction amount upper limit value to be searched.
parNumberoptional	string	The PAR (Payment Assigned Reference) number is a unique identifier assigned by the ACH Product Processor. Use a comma to separate multiple PAR numbers.
detailsFlagrequired	string	Return a detailed response (Y) or a brief response (N). Valid values: Y, N
receivingCustIdentificationNumberoptional	string	The unique ID number associated with the payment recipient. This number is defined in the originating payment request.
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.

responseHeader

NAME	TYPE	DESCRIPTION
statusrequired	string	Indicates whether the result was successful or not. Valid values: accepted, failure
statusDescriptionrequired	string	Description of the status
retrivedRowsoptional	string	Total number of transactions retrieved.
totalRowsoptional	string	Total number of transactions matching the requested criteria.
dataLoadDateoptional	string	Indicates the date that the requested data was loaded. Format: YYYY-MM-DD

errorResponse

NAME	TYPE	DESCRIPTION
businessFaultoptional	array	businessFault
systemFaultoptional	array	systemFault

achCollectedTransactionsRequest

NAME	TYPE	DESCRIPTION
getACHCollectedTransactionsRequestoptional	Object	getACHCollectedTransactionsRequest

getACHCollectedTransactionsRequest

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 than 16 characters.
fromDaterequired	string	The start date of a date range for submitted transactions. This date should be less than or equal to the current date. Date range cannot exceed more than one year. Format: YYYY-MM-DD
toDaterequired	string	The end date of a date range for the submitted transactions. The date must be later than the start date (fromDate). Date range cannot exceed more than one year. Format: YYYY-MM-DD
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
fromAmountoptional	string	Transaction amount lower limit value to be searched.
toAmountoptional	string	Transaction amount upper limit value to be searched.
addendaFlagrequired	string	Retrieves addenda information if set to Y for yes. Valid values: Y, N
secCodeoptional	string	The three-digit Standard Entry Class code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEB
traceNumberoptional	string	The unique number for the transaction provided by the originator. Multiple trace numbers can be comma separated.
parNumberoptional	string	The PAR (Payment Assigned Reference) number is a unique identifier assigned by the ACH Product Processor. Use a comma to separate multiple PAR numbers.
detailsFlagrequired	string	Return a detailed response (Y) or a brief response (N). Valid values: Y, N
receivingCustIdentificationNumberoptional	string	The unique ID number associated with the payment recipient. This number is defined in the originating payment request.
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.

achStatusInquiryParRequest

NAME	TYPE	DESCRIPTION
getACHStatusInquiryRequestoptional	Object	getACHStatusInquiryParRequest

achStatusInquiryTraceNumberRequest

NAME	TYPE	DESCRIPTION
getACHStatusInquiryRequestoptional	Object	getACHStatusInquiryTraceNumberRequest

getACHStatusInquiryParRequest

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 than 16 characters.
parNumberrequired	array	The PAR (Payment Assigned Reference) number is a unique identifier assigned by the ACH Product Processor. Use a comma to separate multiple PAR numbers.
traceNumberoptional	array	The unique number for the transaction provided by the originator. Multiple trace numbers can be comma separated.
receivingCustIdentificationNumberoptional	string	The unique ID number associated with the payment recipient. This number is defined in the originating payment request.
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.

getACHStatusInquiryTraceNumberRequest

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 than 16 characters.
traceNumberrequired	array	The unique number for the transaction provided by the originator. Multiple trace numbers can be comma separated.
parNumberoptional	array	The PAR (Payment Assigned Reference) number is a unique identifier assigned by the ACH Product Processor. Use a comma to separate multiple PAR numbers.
receivingCustIdentificationNumberoptional	string	The unique ID number associated with the payment recipient. This number is defined in the originating payment request.
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	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.

achPostedTransactionsRequest

NAME	TYPE	DESCRIPTION
getACHPostedTransactionsRequestoptional	Object	getACHPostedTransactionsRequest

getACHPostedTransactionsRequest

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 than 16 characters.
fromDaterequired	string	The start date of a date range for submitted transactions. This date should be less than or equal to the current date. Date range cannot exceed more than one year. Format: YYYY-MM-DD
toDaterequired	string	The end date of a date range for the submitted transactions. The date must be later than the start date (fromDate). Date range cannot exceed more than one year. Format: YYYY-MM-DD
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
fromAmountoptional	string	Transaction amount lower limit value to be searched.
toAmountoptional	string	Transaction amount upper limit value to be searched.
parNumberoptional	string	The PAR (Payment Assigned Reference) number is a unique identifier assigned by the ACH Product Processor. Use a comma to separate multiple PAR numbers.
receivingCustIdentificationNumberoptional	string	The unique ID number associated with the payment recipient. This number is defined in the originating payment request.
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.

achCollectedTransactionsResponse

NAME	TYPE	DESCRIPTION
getACHCollectedTransactionsResponserequired	Object	getACHCollectedTransactionsResponse

getACHCollectedTransactionsResponse

NAME	TYPE	DESCRIPTION
responseHeaderrequired	Object	responseHeader
ACHCollectedTransactionoptional	array	achCollectedTransactionsResult
errorResponseoptional	Object	errorResponse

achCollectedTransactionsResult

NAME	TYPE	DESCRIPTION
transactionParNumberoptional	string	The unique PAR number assigned to the transaction by the ACH product processor.
sourceBankNumberoptional	string	Originating entry bank number
sourceAccountNumberoptional	string	Originating account number.
origAcctSuffixoptional	string	Do not use. This field is for internal purpose only.
sourceSysCodeoptional	string	Do not use. This field is for internal purpose only.
sourceSysOfRecordCodeoptional	string	Do not use. This field is for internal purpose only.
snapshotDateoptional	string	This field is for internal purpose only.
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
transactionCodeDescriptionoptional	string	Description for the transaction code.
transactionFlowTypeCodeoptional	string	Identifies if transaction is intrabank (within a single financial institution) or interbank (between two or more banks). Valid values: INTRA, INTER
transactionFlowTypeDescriptionoptional	string	Description for the transaction flow type code.
originatingReceiverCodeoptional	string	Two-character code that identifies the transaction type as originating (O) or receiving (R) and if the transaction is incoming (I) or outgoing (O). Codes can be OI, OO, RI, or RO.
transactionAmountoptional	string	The dollar amount of the transaction.
transactionDescriptionoptional	string	A free form text field that provides the receiver with a description about the purpose of the transaction.
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
inboundCollectionWindowoptional	string	The time window when the transaction collection is processed. The time format uses the 24-hour clock. Format: HHMM
sourceTransactionProcessDateoptional	string	Date when the transaction was collected by the ACH product processor. Format: YYYY-MM-DD
sourceTransactionProcessTimeoptional	string	Time when the transaction was collected by the ACH product processor. The time format uses the 24-hour clock. Format: HHMMSS
sourceTransactionProcessTimestampoptional	string	The date and time the ACH transaction was collected by the ACH product processor. Format: YYYY-MM-DD HH:MM:SS
sourceTransactionSettledDateoptional	string	Date when the transaction is settled. Format: YYYY-MM-DD
sourceTransactionSettledTimeoptional	string	The time window when the transaction is settled. The time format uses the 24-hour clock. Format: HHMM
sourceTransactionSettledTimestampoptional	string	The date and time the ACH transaction is settled. Format: YYYY-MM-DD HH:MM:SS
sourceTransactionPostDateoptional	string	Date the ACH transaction is posted. Format: YYYY-MM-DD
sourceTransactionPostTimeoptional	string	Time the ACH transaction is posted. The time format uses the 24-hour clock. Format: HHMMSS
sourceTransactionPostTimestampoptional	string	The date and time the transaction is posted. Format: YYYY-MM-DD HH:MM:SS
deliveryStatusCodeoptional	string	The code abbreviation for the delivery status of the ACH transaction.
deliveryStatusDescriptionoptional	string	The delivery status description for the abbreviated code.
receivingAccountNumberoptional	string	Account number of the person or institution receiving the funds.
receivingFIBankNumberoptional	string	Bank number for the financial institution receiving the funds.
receivingFIRoutingNumberoptional	string	Routing number for the receiving financial institution.
receivingCustIdentificationNumberoptional	string	The customer identification number for the person receiving the transaction.
receivingCustomerNameoptional	string	Customer name of the person receiving the funds.
receivingCompanyNameoptional	string	Company name of the institution getting the funds.
originatingAccountNumberoptional	string	Account number of the ACH transaction originator.
originatingFIBankNumberoptional	string	Originating financial institution bank number
originatingFIRoutingNumberoptional	string	Originating financial institution routing number
originatingCustIdentificationNumberoptional	string	Originating customer identification number
originatingCompanyNameoptional	string	Originating company name
originatingCustomerNameoptional	string	Originating customer name
checkSerialNumberoptional	string	Serial number for the check converted to an ACH transaction.
nachaBatchNumberoptional	string	The sequential number of the Nacha batch job.
nachaFileHeadRefererenceNumberoptional	string	The Nacha transaction file reference number.
nachaSecCodeoptional	string	The Nacha standard entry class (SEC) code for the transaction. Valid values: CCD, CTX, PPD, TEL WEB
nachaSecDescriptionoptional	string	The description for the Nacha SEC code.
traceNumberoptional	string	The unique number for the transaction provided by the originator. Multiple trace numbers can be comma separated.
postCompanyCostcontrolNumberoptional	string	Do not use. This field is for internal purpose only.
glAccountNumberoptional	string	Do not use. This field is for internal purpose only.
addendaPresentFlagoptional	string	Indicates if there are addenda records or not.
addendaRecordNumberoptional	string	Number of addenda records.
originatingReceiverDescriptionoptional	string	Description for the collected originating receiver code.
goRoutingNumberoptional	string	Gateway operator routing number for international transactions.
authorizedCustomerNameoptional	string	Authorized customer name
iatFlagoptional	string	International transaction identifier
collectionPointoptional	string	Transaction collection point
batchIdoptional	string	The identification number for the batch job.
transactionTraceIdoptional	string	The trace ID number from the source application.
addendaInformationoptional	Object	addendaInformation
customDataoptional	string	Custom data from the originating payment request.

achPostedTransactionsResponse

NAME	TYPE	DESCRIPTION
getACHPostedTransactionsResponserequired	Object	getACHPostedTransactionsResponse

getACHPostedTransactionsResponse

NAME	TYPE	DESCRIPTION
responseHeaderrequired	Object	responseHeader
ACHPostedTransactionoptional	array	achPostedTransactionsResult
errorResponseoptional	Object	errorResponse

achPostedTransactionsResult

NAME	TYPE	DESCRIPTION
snapshotDateoptional	string	Do not use. This field is for internal purpose only.
processDateoptional	string	Date the transaction was processed. Format: YYYY-MM-DD
sourceBankNumberoptional	string	Originating entry bank number
sourceAccountNumberoptional	string	Originating account number
transactionParNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionAmountoptional	string	The dollar amount of the transaction.
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
hoganTransactionCodeoptional	string	The KeyBank Hogan code for the transaction.
baiCodeoptional	string	The three-digit BAI (Bank Administration Institute) code for the transaction.
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
regulationDescription1optional	string	Regulation description for the transaction.
regulationDescription2optional	string	Additional regulation information for the transaction.
regulationDescription3optional	string	Additional regulation information for the transaction.
regulationDescription4optional	string	Additional regulation information for the transaction.
postingWindowoptional	string	The time window when the transaction collection is posted. The time format uses the 24-hour clock. Format: HHMM
batchIDoptional	string	The identification number for the batch job.
customDataoptional	string	Custom data from the originating payment request.

achStatusInquiryResponse

NAME	TYPE	DESCRIPTION
responseHeaderrequired	Object	responseHeader
ACHTransactionStatusoptional	array	achStatusInquiryResult
errorResponseoptional	Object	errorResponse

achStatusInquiryResult

NAME	TYPE	DESCRIPTION
ACHStatusoptional	string	The status informs you if the ACH transaction has been collected or returned. Valid values: COLLECTED or RETURNED
ACHCollectedTransactionoptional	Object	achCollectedTransactionsStatusResult
ACHPostedTransactionoptional	Object	achPostedTransactionsStatusResult
ACHReturnTransactionoptional	Object	achReturnTransactionsStatusResult

achCollectedTransactionsStatusResult

NAME	TYPE	DESCRIPTION
transactionParNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
sourceBankNumberoptional	string	Originating entry bank number
sourceAccountNumberoptional	string	Originating account number.
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
transactionAmountoptional	string	The dollar amount of the transaction.
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
sourceTransactionProcessDateoptional	string	Date when the transaction was collected by the ACH product processor. Format: YYYY-MM-DD
sourceTransactionProcessTimeoptional	string	Time when the transaction was collected by the ACH product processor. The time format uses the 24-hour clock. Format: HHMMSS
sourceTransactionProcessTimestampoptional	string	The date and time the ACH transaction was collected by the ACH product processor. Format: YYYY-MM-DD HH:MM:SS
sourceTransactionSettledDateoptional	string	Date when the transaction is settled. Format: YYYY-MM-DD
sourceTransactionSettledTimeoptional	string	The time window when the transaction is settled. The time format uses the 24-hour clock. Format: HHMM
sourceTransactionSettledTimestampoptional	string	The date and time the ACH transaction is settled. Format: YYYY-MM-DD HH:MM:SS
sourceTransactionPostDateoptional	string	Date the ACH transaction is posted. Format: YYYY-MM-DD
sourceTransactionPostTimeoptional	string	Time the ACH transaction is posted. The time format uses the 24-hour clock. Format: HHMMSS
sourceTransactionPostTimestampoptional	string	The date and time the transaction is posted. Format: YYYY-MM-DD HH:MM:SS
receivingCustomerNameoptional	string	Customer name of the person receiving the funds.
receivingCompanyNameoptional	string	Company name of the institution getting the funds.
originatingCompanyNameoptional	string	Originating company name
originatingCustomerNameoptional	string	Originating customer name
nachaSecCodeoptional	string	The Nacha standard entry class (SEC) code for the transaction. Valid values: CCD, CTX, PPD, TEL, WEB
traceNumberoptional	string	The unique number for the transaction provided by the originator. Multiple trace numbers can be comma separated.
transactionDescriptionoptional	string	A free form text field that provides the receiver with a description about the purpose of the transaction.
receivingCustIdentificationNumberrequired	string	The unique ID number associated with the payment recipient. This number is defined in the originating payment request.

achPostedTransactionsStatusResult

NAME	TYPE	DESCRIPTION
processDateoptional	string	Date the transaction was processed. Format: YYYY-MM-DD
transactionParNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionAmountoptional	string	The dollar amount of the transaction.
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
baiCodeoptional	string	The three-digit BAI (Bank Administration Institute) code for the transaction.
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
regulationDescription1optional	string	Regulation description for the transaction.
regulationDescription2optional	string	Additional regulation information for the transaction.
regulationDescription3optional	string	Additional regulation information for the transaction.
regulationDescription4optional	string	Additional regulation information for the transaction.
postingWindowoptional	string	The time window when the transaction collection is posted. The time format uses the 24-hour clock. Format: HHMM

achReturnTransactionsStatusResult

NAME	TYPE	DESCRIPTION
transactionParNumberoptional	string	The unique PAR number assigned to the transaction by the ACH product processor.
transactionCodeoptional	string	Two digit code identifying the account type at the receiving financial institution.
transactionCodeDescriptionoptional	string	Description for the transaction code.
transactionAmountoptional	string	The dollar amount of the transaction.
transactionDescription1optional	string	A free form text field that provides the receiver with a description about the purpose of the transaction.
transactionDescription2optional	string	Additional transaction description information.
creditOrDebitCodeoptional	string	Identifies the transaction type as credit or debit. To get both credit and debit transactions, leave this parameter blank. Valid values: C, D.
returnReleaseDateoptional	string	Release date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCodeoptional	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescriptionoptional	string	Description as to why the ACH transaction is returned.

addendaInformation

NAME	TYPE	DESCRIPTION
iatAddendumoptional	Object	iatAddendum
nonIatAddendumoptional	Object	nonIatAddendum
nocAddendumoptional	Object	nocAddendum

iatAddendum

NAME	TYPE	DESCRIPTION
addendaParNumberoptional	string	The unique PAR number assigned to the addendum by the ACH product processor.
snapshotDateoptional	string	Do not use. This field is for internal purpose only.
transactionParNumberoptional	string	The unique PAR number assigned to the transaction by the ACH product processor.
payInformationoptional	string	Additional information about the remittance payment.
addendaTypeCodeoptional	string	Two-digit code identifying the type of information.
addendaTypeDescriptionoptional	string	Description of the addenda type associated with the code.
transactionTypeCodeoptional	string	This field contains a three-character code used to identify the type of transaction.
transactionTypeDescroptional	string	This field contains description of the the transaction type code
originatingFiIdentificationNumberCodeoptional	string	Originating financial institution code
originatingFiNameoptional	string	Originating financial institution name
originatingFiIdentificationNumberoptional	string	Originating financial institution identification number
originatingFiBranchCountryCodeoptional	string	Originating company country branch code
originatingCompanyNameoptional	string	Originating company name
originatingCompanyAddress1optional	string	Originating bank physical street address, line 1
originatingCompanyAddress2optional	string	Originating bank physical street address, line 2
originatingCompanyCityStateProvinceoptional	string	Originator city and state
originatingCompanyCountryPostalCodeoptional	string	Originator country and postal code
receivingFiNameoptional	string	Receiving financial institution name
receivingFiIdentificationNumberoptional	string	Receiving financial institution identification number
receivingFiIdentificationNumberCodeoptional	string	Receiving financial institution code
receivingFiBranchCountryCodeoptional	string	Receiving company country branch code
receivingCustomerNameoptional	string	Receiving customer name
receivingCompanyNameoptional	string	Receiving company name
receivingCompanyNumberoptional	string	Receiving company number
receivingCompanyAddress1optional	string	Receiving company physical address, line 1
receivingCompanyAddress2optional	string	Receiving company physical address, line 2
receivingCompanyCityStateProvinceoptional	string	Receiving company city and state
receivingCompanyCountryPostalCodeoptional	string	Receiving company country and postal code
foreignCorrespondentFiIdNumberCodeoptional	string	Foreign correspondent bank identification number qualifier
foreignCorrespondentFiNameoptional	string	Correspondent bank name
foreignCorrespondentFiBRCountryCodeoptional	string	Correspondent bank country code
foreignCorrespondentBankIdNumberoptional	string	Correspondent bank identifier
foreignOriginatingAmountoptional	string	Foreign payment amount
foreignOriginatingCurrencyCodeoptional	string	Foreign currency code
foreignTraceNumberoptional	string	Identifier number of the foreign transaction.
addendaSequenceNumberoptional	string	The sequence number of the addenda. The number cannot exceed 4 digits.
entryDetailSequenceNumberoptional	string	Sequence number of the entry detail
operatorCommandFlagoptional	string	Operator command flag

nonIatAddendum

NAME	TYPE	DESCRIPTION
addendaParNumberoptional	string	The unique PAR number assigned to the addendum by the ACH product processor.
snapshotDateoptional	string	Do not use. This field is for internal purpose only.
transactionParNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionSerialNumberoptional	string	Serial number for the transaction
transactionDescriptionoptional	string	A free form text field that provides the receiver with a description about the purpose of the transaction.
sourceTransactionCreatedDateoptional	string	Date when the user created the ACH transaction. Format: YYYY-MM-DD
sourceTransactionCreatedTimeoptional	string	Time when the user created the ACH transaction. The time format uses the 24-hour clock. Format: HHMM
payInformationoptional	string	Additional information associated with the payment transaction.
addendaTypeCodeoptional	string	Two-digit code identifying the type of information.
addendaTypeDescriptionoptional	string	Description of the addenda type associated with the code.
entryDetailSequenceNumberoptional	string	Sequence number of the entry detail
referenceInformation1optional	string	Free form text field with additional reference information.
referenceInformtion2optional	string	Free form text field with additional reference information.
networkIdentificationCodeoptional	string	Network identification code (NIC)
terminalIdentificationCodeoptional	string	Terminal identification code
terminalCityoptional	string	City location of the terminal
terminalStateoptional	string	State location of the terminal
keyBankTransactionReferenceNumberoptional	string	Unique ACH transaction identifier created by KeyBank.
operatorCommandFlagoptional	string	Operator command flag

nocAddendum

NAME	TYPE	DESCRIPTION
addendaParNumberoptional	string	The unique PAR number assigned to the addendum by the ACH product processor.
snapshotDateoptional	string	Do not use. This field is for internal purpose only.
transactionParNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
addendaTypeCodeoptional	string	Two-digit code identifying the type of information.
addendaTypeDescriptionoptional	string	Description of the addenda type associated with the code.
changeCodeoptional	string	The three-character change code begins with the letter 'C'. This code is applied to all NOCs to indicate the information that is being changed.
changeDescriptionoptional	string	The description associated with the change code.
receivingFiIdentificationNumberoptional	string	Receiving financial institution identification number
correctedDataoptional	string	The corrected data per the correction change code.
externalFiTransactionIdentificationNumberoptional	string	The number used by an external financial institution to identify the transaction.
keyBankTransactionReferenceNumberoptional	string	Unique ACH transaction identifier created by KeyBank.
operatorCommandFlagoptional	string	Operator command flag.

AccountList

NAME	TYPE	DESCRIPTION
accountNumberoptional	string	Bank account number.

AccountDetail

NAME	TYPE	DESCRIPTION
accountNumberoptional	string	Bank account number of the ACH originator or receiver.
bankNumberoptional	string	Bank number associated with the account number.
routingNumberoptional	string	Nine-digit routing number for the account provided in the original request.

AchDetailTransaction

NAME	TYPE	DESCRIPTION
parNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionStatusoptional	string	The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumberoptional	string	The unique number for the transaction provided by the originator.
transactionAmountoptional	number	The dollar amount of the transaction.
settlementDateoptional	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
transactionCodeDescriptionoptional	string	Description for the transaction code.
transactionDescriptionoptional	string	Description about the purpose of the transaction.
authorizedCustomerNameoptional	string	Authorized customer name
standardEntryClassCodeoptional	string	The three-digit Standard Entry Class code based on Nacha rules.
standardEntryClassDescriptionoptional	string	The description for the Nacha SEC code.
receivingAccountoptional	Object	AccountDetail
receivingPartyoptional	Object	PartyDetail
originatingAccountoptional	Object	AccountDetail
originatingPartyoptional	Object	PartyDetail
returnDateoptional	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCodeoptional	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescriptionoptional	string	Description as to why the ACH transaction is returned.
addendaCountoptional	integer	Count of addenda records.
notificationOfChangeAddendaCountoptional	integer	Count of change notifications for addenda records.
internationalAddendaCountoptional	integer	Count of international addenda records.
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.
checkSerialNumberoptional	string	Serial number for the check converted to an ACH transaction.
transactionDirectionoptional	string	Indicates the direction of the transaction. Valid values: ORIGINATING ITEM, RECEIVING ITEM
addendaoptional	array	Addendum
notificationOfChangeoptional	array	NotificationOfChange

AchListTransaction

NAME	TYPE	DESCRIPTION
parNumberoptional	string	The unique PAR number assigned to the the transaction by the ACH product processor.
transactionStatusoptional	string	The status of the ACH transaction. Valid values: COLLECTED, RETURNED, SETTLED
traceNumberoptional	string	The unique number for the transaction provided by the originator.
transactionAmountoptional	number	The dollar amount of the transaction.
settlementDateoptional	string	The date the transaction settlement occurred. Format: YYYY-MM-DD
transactionCodeoptional	string	Two-digit code identifying the account type at the receiving financial institution.
authorizedCustomerNameoptional	string	Authorized customer name
standardEntryClassCodeoptional	string	The three-digit Standard Entry Class code based on Nacha rules.
receivingAccountoptional	Object	AccountList
receivingPartyoptional	Object	PartyList
originatingAccountoptional	Object	AccountList
originatingPartyoptional	Object	PartyList
returnDateoptional	string	Date of the returned transaction to the ACH system. Format: YYYY-MM-DD
returnReasonCodeoptional	string	The code associated with the reason for returning the ACH transaction. The code is the letter 'R' for reason followed by a two-digit numeric code. Format: R00
returnReasonDescriptionoptional	string	Description as to why the ACH transaction is returned.
addendaCountoptional	integer	Count of addenda records.
notificationOfChangeAddendaCountoptional	integer	Count of change notifications for addenda records.
internationalAddendaCountoptional	integer	Count of international addenda records.

Addendum

NAME	TYPE	DESCRIPTION
sequenceNumberoptional	integer	The addenda record item number in order of sequence. Number cannot exceed 4 digits.
entryDetailSequenceNumberoptional	string	The entry number in order of sequence. Number cannot exceed 7 digits.
paymentRelatedInformationoptional	string	The related payment information from the addenda records. The maximum character limit is 255.

Message

NAME	TYPE	DESCRIPTION
codeoptional	string	Code for the related message.
messageoptional	string	Message associated with the code.

Page

NAME	TYPE	DESCRIPTION
pageNumberoptional	integer	The number of the page being viewed.
pageSizeoptional	integer	The number of records per page.
totalPagesoptional	integer	The number of pages there are in total.
totalRecordsoptional	integer	The total number of transactions available in the result set.
lastPageoptional	boolean	Indicates if the current page (page number) is the last page of the result set. Valid values: true, false

Metadata

NAME	TYPE	DESCRIPTION
messagesoptional	array	Message
pageoptional	Object	Page

PartyList

NAME	TYPE	DESCRIPTION
customerIdentificationNumberoptional	string	The unique identification number associated with the customer.
companyNameoptional	string	The name of the corporation or institution making the request.

PartyDetail

NAME	TYPE	DESCRIPTION
customerIdentificationNumberoptional	string	The unique identification number associated with the customer.
companyNameoptional	string	The name of the corporation or institution making the request.
customerNameoptional	string	The name of the customer.

NotificationOfChange

NAME	TYPE	DESCRIPTION
changeCodeoptional	string	The three-character change code begins with the letter 'C'. This code is applied to all NOCs to indicate the information that is being changed.
changeDescriptionoptional	string	The description associated with the change code.
correctedDataoptional	string	The corrected data per the correction change code.

Errors

For more information about general errors, see Error handling.

API-specific KeyBank error codes and details are in the ServiceError or errorResponse object with additional information specific to the API. The KeyBank error codes start with ECA-W with a three-digit number that follows. The number increases by one digit for each error message. For example, 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.

API specific KeyBank codes and messages

HTTP
STATUS CODE CUSTOM
STATUS CODE DESCRIPTION

299

ECA-W-001 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-001 Request Validation failed.

There is missing mandatory information like accountNumber, fromDate, or toDate. Review values for mandatory request fields.

400

ECA-W-002 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.

Changelog

Release	API version	Change description	Impact
October 2024	1.2.1	Date parameters adjusted to support the maximum date range search limit of 180 days. Do not enter a `fromDate` and `toDate` date range that goes beyond 31 days.	LOW
May 2024	1.2.0	Two new endpoints available in all environments, including the API simulator! We have added: `GET /accounts/transactions/v1/ach-transactions/{parNumber}` `POST /accounts/transactions/v1/ach-transactions`	MID
December 2023	1.1.6	Deprecated the `mdmID` field. Backend services and processes have been enhanced to authenticate client API calls without the need for an MDM ID. Removed the POSTED status from the list of valid values for the `ACHStatus` field in the `achStatusInquiryResult` object. Valid values for this field now only include COLLECTED or RETURNED.	MID
September 2023	1.1.5	The `mdmId` description has been updated to communicate that this field will soon deprecate in an upcoming release.	LOW
August 2023	1.1.4	Modified the format for date parameters to match with KeyBank API standard date format of YYYY-MM-DD. `fromDate` and `toDate` were updated to recall transaction data from the previous 24 months.	LOW
July 2023	1.1.3	Added the `settlementDate` field in the response to provide you the ability to filter by date in response. MDM ID (`mdmId`) is no longer a required field, it is now optional.	LOW
May 2023	1.1.2	Added `customData` to the following objects: `achCollectedTransactionsResult` `achPostedTransactionsResult` `ACHReturnTransaction` Added `receivingCustIdentificationNumber` to the request payloads. In the `achCollectedTransactionsResult` response, we added an example for the `nonIatAddendum` schema.	MID
December 2022	1.0.0	Released 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

ACH Origination

8-minute read 1.3.2 | updated Oct. 15, 2024

Send or collect an ACH transaction, report on the status, or undo a payment

ACH Origination Endpoints

What you can do	Endpoint
Health check	get /ach/payments/v1/healthCheck
Check the status of a payment request	post /ach/payments/v1/status
Check the status of addenda records	post /ach/payments/v1/status/addenda
Send or collect a payment	post /ach/payments/v1/ccd
Make or collect payments to or from a corporate account with attached records	post /ach/payments/v1/ctx
Make deposits and withdrawals to or from consumer accounts	post /ach/payments/v1/ppd
Authorize a payment over the phone	post /ach/payments/v1/tel
Send an online payment	post /ach/payments/v1/web
Undo a payment request	post /ach/payments/v1/undo
Send additional addenda information	post /ach/payments/v1/addenda

Before you begin

All KeyBank APIs require certificates, user credentials, and certain permissions. Check out our Getting Started Guide to learn more.

Sometimes it's the details

You can add details to your transaction. Use custom data feature when you send or validate a payment. Define the customData in the request payload. Learn more about our custom data feature here.

Overview

ACH stands for Automated Clearing House. ACH payments are electronic funds transfers (EFTs), a type of electronic payment that transfers funds between bank accounts within the United States. ACH payments are often less expensive than wire transfers, with lower or no transaction fees. Most commonly, ACH payments are used for direct deposit of payroll, recurring bill payments, online purchases, and person-to-person transfers.

How does it work?

The ACH Origination process starts with a payment or collection request made by a financial institution or client (business or individual). In the request, the payment method (SEC code) and transaction type (credit or debit) must be defined. The API automatically assigns the effective date and other data, like the trace number.

You get a trace number after you initiate an ACH transaction. The trace number is a unique identifier for an ACH transaction generated by the API. The trace number is useful for transaction inquiries and traceability. Save this trace number if you intend to check on the progress of the ACH transaction. For multiple payment requests, the trace number may not be in sequential order.

A request generates a batch response that includes the status and payment details by SEC code. For the consolidation, we store records from the batch, detail, and addenda schemas. You can include up to ten accounts with each request. For each submitted request, you can check on the status and progress of the payment or addenda report.

Except for TEL type transaction, all the SEC code types can include addenda information with the response. If an addenda item returns a large set of records (common with CTX), it initiates the addenda request. This request adds additional addenda records to a detail item. Currently, only details that are associated to a batch having a CTX SEC code can have additional addenda records added.

API requirements

UUID: UUID stands for Universally Unique Identifier. This is a useful attribute to recall a transaction before the next batch cycle runs. Since the UUID field is required to undo an ACH payment request, KeyBank strongly encourages the UUID is included with all ACH Origination calls.

The batch and the individual UUID can be the same, but KeyBank recommends that you use different UUID values.

Client information values: After you have completed the onboarding process with KeyBank, KeyBank provides the client (point) and client account (collectionApplicationId, collectionApplicationType) information via secure email. These fields are required for any ACH Origination call with a SEC code.

SEC code: In the request payload, you must specify the Standard Entry Class (SEC) code for the transaction. The ACH Origination API supports these SEC codes: CCD, CTX, PPD, TEL, WEB. Review the details on SEC codes in our user guide.

Health check

get /ach/payments/v1/healthCheck

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

Responses

Successful response

NAME	TYPE	DESCRIPTION
Statusoptional	string	The 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 response from the API service.
ClientIpoptional	string	The client IP address the gateway receives from the request.
X-Forwarded-Foroptional	string	The sequence of the IP addresses for systems 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]"
}

Check the status of a payment request

post /ach/payments/v1/status

Check the return status of one or more transactions. Use this request to see if the originated item failed, was accepted, is waiting for one or more addenda items, or is being processed.

Request

BODY FIELD	TYPE	DESCRIPTION
detailStatusoptional	array	paymentInquiryDetailRequest

Request example

{
    "detailStatus": [
        {
            "uuid": "qas220602x-49eb-47664-b94rhd1-e52e2re11001"
        }
    ]
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
detailsoptional	array	detailStatusResponse

Missing mandatory information

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "Runtime error occurred in the service, please check with application support team before resubmitting the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
    }
}

Unavailable service

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Check the status of addenda records

post /ach/payments/v1/status/addenda

Check the return status of one or more addenda records

Request

BODY FIELD	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
pageSizeoptional	string	The number of records to be returned in the pagination search.
startAddendaSequenceNumberoptional	string	The starting number for the addenda record sequence.

Request example

{
    "uuid": "qas220517x-49eb-47664-b94rhd1-e52e2re13001",
    "pageSize": "10",
    "startAddendaSequenceNumber": "0001"
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
uuidoptional	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusoptional	string	The status of the batch can be accepted or rejected.
errorMessagesoptional	array	detailMessage
traceNumberoptional	string	The unique number for the ACH transaction. Record this number for possible ACH inquiry requests.
informationMessagesoptional	array	detailMessage
addendaoptional	array	baseAddendaDetailResponse

Response example (200)

{
    "uuid": "qas220517x-49eb-47664-b94rhd1-e52e2re13001",
    "status": "accepted",
    "traceNumber": "041001030009004",
    "informationMessages": [
        {
            "code": "1002040-50I",
            "moreInfo": "All addenda have been received."
        }
    ],
    "errorMessages": [],
    "addenda": [
        {
            "addendaTypeCode": "05",
            "addendaSequenceNumber": "0001",
            "paymentRelatedInformation": "Undo WEB PAYMENT GOOD ITEM"
        }
    ]
}

Missing mandatory information

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "Runtime error occurred in the service, please check with application support team before resubmitting the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
    }
}

Unavailable service

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Send or collect a payment

post /ach/payments/v1/ccd

Make or collect payments to a corporate account. This call originates an ACH transaction for SEC code CCD (Corporate Credit or Debit). Use this request to send or collect cash, debit, or credit transactions between the buyer and seller financial institution accounts. This can also be used by companies to move funds and deposit to a central bank account.

Request

BODY FIELD	TYPE	DESCRIPTION
batchrequired	Object	batchRequestCCDDetailRequest
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.

Request example

{
    "batch": {
        "collectionApplicationId": "TEST",
        "point": "APITEST1",
        "secCode": "CCD",
        "uuid": "daily001-qas230109-010300-005",
        "collectionApplicationType": "",
        "effectiveDate": "230211",
        "companyDescriptiveDate": "230211",
        "companyEntryDescription": "Payroll",
        "details": [
            {
                "DFIAccountNumber": "123456",
                "accountType": "C",
                "amount": "0.01",
                "checkDigit": "9",
                "creditDebitCode": "C",
                "receivingCompanyName": "ProdTest001",
                "receivingDFIId": "04100103",
                "transactionType": "L",
                "uuid": "daily001-qas230109-010301-0026",
                "identificationNumber": "099999999a",
                "discretionaryData": "AB",
                "addenda": [
                    {
                        "paymentRelatedInformation": "DAILYTEST0103A"
                    }
                ]
            }
        ]
    }
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
batchrequired	Object	acceptedBatchResponseAcceptedDetailResponse

Response example (200)

{
    "batch": {
        "uuid": "daily001-qas230109-010300-005",
        "status": "accepted",
        "requestAcceptedUTCTime": "2023-05-03T17:04:03Z",
        "effectiveDate": "230211",
        "informationMessages": [
            {
                "code": "1006040-65I",
                "moreInfo": "Effective date assigned 230211."
            }
        ],
        "errorMessages": [],
        "details": [
            {
                "uuid": "daily001-qas230109-010301-0026",
                "status": "accepted",
                "errorMessages": [],
                "informationMessages": [],
                "traceNumber": "041001030013025",
                "requestAcceptedUTCTime": "2023-05-03T17:04:03Z"
            }
        ]
    }
}

Missing mandatory information

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "Runtime error occurred in the service, please check with application support team before resubmitting the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
    }
}

Unavailable service

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Make or collect payments to or from a corporate account with attached records

post /ach/payments/v1/ctx

Submit or collect a payment from one business/entity to another. This call originates an ACH transaction for SEC code CTX (Corporate Trade Exchange). Use this request to send or collect an electronic payment with remittance information.

Request

BODY FIELD	TYPE	DESCRIPTION
batchrequired	Object	batchRequestCTXDetailRequest
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.

Request example

{
    "batch": {
        "collectionApplicationId": "TEST2",
        "point": "APITEST1",
        "secCode": "CTX",
        "uuid": "test3c377-bat338-ctxf-bcd6fehdd0-031103",
        "collectionApplicationType": "",
        "effectiveDate": "230411",
        "companyDescriptiveDate": "230411",
        "companyEntryDescription": "Payroll",
        "details": [
            {
                "DFIAccountNumber": "111011",
                "accountType": "S",
                "checkDigit": "0",
                "creditDebitCode": "C",
                "numberOfAddendaRecords": "1",
                "receivingCompanyNameIDNumber": "YourTest301",
                "receivingDFIId": "06100001",
                "totalAmount": "1.31",
                "transactionType": "L",
                "uuid": "test3c377-det338-ctxf-dcd6fehdd0-030104",
                "identificationNumber": "099999999",
                "discretionaryData": "AK",
                "addenda": [
                    {
                        "paymentRelatedInformation": "YourTest03.01"
                    }
                ]
            }
        ]
    }
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
batchrequired	Object	acceptedBatchResponseAcceptedDetailResponse

Response example (200)

{
    "batch": {
        "uuid": "test3c377-bat338-ctxf-bcd6fehdd0-031103",
        "status": "accepted",
        "requestAcceptedUTCTime": "2023-05-03T17:06:02Z",
        "effectiveDate": "230411",
        "informationMessages": [
            {
                "code": "1006040-65I",
                "moreInfo": "Effective date assigned 230411."
            }
        ],
        "errorMessages": [],
        "details": [
            {
                "uuid": "test3c377-det338-ctxf-dcd6fehdd0-030104",
                "status": "accepted",
                "errorMessages": [],
                "informationMessages": [],
                "traceNumber": "041001030013026",
                "requestAcceptedUTCTime": "2023-05-03T17:06:02Z"
            }
        ]
    }
}

Missing mandatory information

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "Runtime error occurred in the service, please check with application support team before resubmitting the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
    }
}

Unavailable service

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Make deposits and withdrawals to or from consumer accounts

post /ach/payments/v1/ppd

Submit or collect a payment based on consumer authorization and terms of service. This call originates an ACH transaction for SEC code PPD (Prearranged Payments and Debits). Use this request to send or collect a routine electronic payment, like a subscription or monthly payment plan.

Request

BODY FIELD	TYPE	DESCRIPTION
batchrequired	Object	batchRequestPPDDetailRequest
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.

Request example

{
    "batch": {
        "collectionApplicationId": "TEST",
        "point": "APITEST1",
        "secCode": "PPD",
        "uuid": "qas22517-4d3338-4c6f-bcd6fehdd0-1234360",
        "collectionApplicationType": "",
        "effectiveDate": "230211",
        "companyDescriptiveDate": "230211",
        "companyEntryDescription": "Payroll",
        "details": [
            {
                "DFIAccountNumber": "123456789",
                "accountType": "S",
                "amount": "520.25",
                "checkDigit": "9",
                "creditDebitCode": "C",
                "individualName": "QASTest005",
                "receivingDFIId": "04100103",
                "transactionType": "L",
                "uuid": "qas220330A-49eb-47664-b94rhd1-12361",
                "individualIdentificationNumber": "099999999a",
                "discretionaryData": "AB",
                "addenda": [
                    {
                        "paymentRelatedInformation": "QASTest02.02A"
                    }
                ]
            },
            {
                "DFIAccountNumber": "234567891",
                "accountType": "S",
                "amount": "0.00",
                "checkDigit": "2",
                "creditDebitCode": "C",
                "individualName": "QASTest006",
                "receivingDFIId": "24107121",
                "transactionType": "P",
                "uuid": "qas220330A-49eb-47664-b94rhd1-12362",
                "individualIdentificationNumber": "099999999b",
                "discretionaryData": "BC"
            },
            {
                "DFIAccountNumber": "345678912",
                "accountType": "S",
                "amount": "1794.91",
                "checkDigit": "2",
                "creditDebitCode": "D",
                "individualName": "QASTest006",
                "receivingDFIId": "24107121",
                "transactionType": "L",
                "uuid": "qas220330A-49eb-47664-b94rhd1-12363",
                "individualIdentificationNumber": "099999999c",
                "discretionaryData": "BC",
                "addenda": [
                    {
                        "paymentRelatedInformation": "QASTest02.02C"
                    }
                ]
            }
        ]
    }
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
batchrequired	Object	acceptedBatchResponseAcceptedDetailResponse

Response example (200)

{
    "batch": {
        "uuid": "qas22517-4d3338-4c6f-bcd6fehdd0-1234360",
        "status": "accepted",
        "requestAcceptedUTCTime": "2023-05-03T17:08:45Z",
        "effectiveDate": "230211",
        "informationMessages": [
            {
                "code": "1006040-65I",
                "moreInfo": "Effective date assigned 230211."
            }
        ],
        "errorMessages": [],
        "details": [
            {
                "uuid": "qas220330A-49eb-47664-b94rhd1-12361",
                "status": "accepted",
                "errorMessages": [],
                "informationMessages": [],
                "traceNumber": "041001030012784",
                "requestAcceptedUTCTime": "2023-05-03T17:08:45Z"
            },
            {
                "uuid": "qas220330A-49eb-47664-b94rhd1-12362",
                "status": "accepted",
                "errorMessages": [],
                "informationMessages": [],
                "traceNumber": "041001030012785",
                "requestAcceptedUTCTime": "2023-05-03T17:08:45Z"
            },
            {
                "uuid": "qas220330A-49eb-47664-b94rhd1-12363",
                "status": "accepted",
                "errorMessages": [],
                "informationMessages": [],
                "traceNumber": "041001030012786",
                "requestAcceptedUTCTime": "2023-05-03T17:08:45Z"
            }
        ]
    }
}

Missing mandatory information

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "Runtime error occurred in the service, please check with application support team before resubmitting the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
    }
}

Unavailable service

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Send a payment over the phone

post /ach/payments/v1/tel

Authorize and submit a payment by the phone.

Request

BODY FIELD	TYPE	DESCRIPTION
batchrequired	Object	batchRequestTELDetailRequest
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.

Request example

{
    "batch": {
        "collectionApplicationId": "TEST",
        "point": "APITEST1",
        "secCode": "TEL",
        "uuid": "qas22523-4d3338-4c6f-bcd6fehdd0-12349",
        "collectionApplicationType": "",
        "effectiveDate": "230211",
        "companyDescriptiveDate": "230211",
        "companyEntryDescription": "Payroll",
        "details": [
            {
                "DFIAccountNumber": "1234567890123452",
                "accountType": "C",
                "amount": "5963.88",
                "checkDigit": "0",
                "creditDebitCode": "D",
                "individualName": "QASTest014",
                "receivingDFIId": "06100001",
                "transactionType": "L",
                "uuid": "qas22523-f76-44eb-a7014041047",
                "individualIdentificationNumber": "099999999",
                "paymentTypeCode": "R"
            }
        ]
    }
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
batchrequired	Object	acceptedBatchResponseAcceptedDetailResponse

Response example (200)

{
    "batch": {
        "uuid": "qas22523-4d3338-4c6f-bcd6fehdd0-12349",
        "status": "accepted",
        "requestAcceptedUTCTime": "2023-05-03T17:10:58Z",
        "effectiveDate": "230211",
        "informationMessages": [
            {
                "code": "1006040-65I",
                "moreInfo": "Effective date assigned 230211."
            }
        ],
        "errorMessages": [],
        "details": [
            {
                "uuid": "qas22523-f76-44eb-a7014041047",
                "status": "accepted",
                "errorMessages": [],
                "informationMessages": [],
                "traceNumber": "041001030013030",
                "requestAcceptedUTCTime": "2023-05-03T17:10:58Z"
            }
        ]
    }
}

Missing mandatory information

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "Runtime error occurred in the service, please check with application support team before resubmitting the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
    }
}

Unavailable service

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Send an online payment

post /ach/payments/v1/web

Authorize and submit a payment on a website.

Request

BODY FIELD	TYPE	DESCRIPTION
batchrequired	Object	batchRequestWEBDetailRequest
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.

Request example

{
    "batch": {
        "collectionApplicationId": "TEST",
        "point": "APITEST1",
        "secCode": "WEB",
        "uuid": "qas22523-4d3338-4c6f-bcd6fehdd0-41033",
        "collectionApplicationType": "",
        "effectiveDate": "230211",
        "companyDescriptiveDate": "",
        "companyEntryDescription": "Payroll",
        "details": [
            {
                "DFIAccountNumber": "123546789",
                "accountType": "C",
                "amount": "0.00",
                "checkDigit": "0",
                "creditDebitCode": "D",
                "individualName": "QASTest014",
                "receivingDFIId": "06100001",
                "transactionType": "P",
                "uuid": "qas22523-f76-44eb-a7014041034",
                "individualIdentificationNumber": "099999999",
                "paymentTypeCode": "R",
                "addenda": [
                    {
                        "paymentRelatedInformation": "DAILYTEST0103A"
                    }
                ]
            }
        ]
    }
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
batchrequired	Object	acceptedBatchResponseAcceptedDetailResponse

Response example (200)

{
    "batch": {
        "uuid": "qas22523-4d3338-4c6f-bcd6fehdd0-41033",
        "status": "accepted",
        "requestAcceptedUTCTime": "2023-05-03T17:13:45Z",
        "effectiveDate": "230211",
        "informationMessages": [
            {
                "code": "1006040-65I",
                "moreInfo": "Effective date assigned 230211."
            }
        ],
        "errorMessages": [],
        "details": [
            {
                "uuid": "qas22523-f76-44eb-a7014041034",
                "status": "accepted",
                "errorMessages": [],
                "informationMessages": [],
                "traceNumber": "041001030012787",
                "requestAcceptedUTCTime": "2023-05-03T17:13:45Z"
            }
        ]
    }
}

Missing mandatory information

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "Runtime error occurred in the service, please check with application support team before resubmitting the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
    }
}

Unavailable service

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Undo a payment request

post /ach/payments/v1/undo

Reverse a payment request before it enters consolidation.

Request

BODY FIELD	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.

Request example

{
    "uuid": "qas220517x-49eb-47664-b94rhd1-e52e2re13001"
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusoptional	string	The status of a batch record can be accepted or rejected. The status of a detailed record can be deleted, accepted, rejected, notFound, or waitingForAddenda.
errorMessagesoptional	array	detailMessage
informationMessagesoptional	array	detailMessage
traceNumberoptional	string	The unique number for the ACH transaction. Record this number for possible ACH inquiry requests.

Response example (200)

{
    "uuid": "qas220517x-49eb-47664-b94rhd1-e52e2re13001",
    "status": "accepted",
    "errorMessages": [
        {
            "code": "1006040-651"
        },
        {
            "moreInfo": "Effective date assigned 220411"
        }
    ],
    "informationMessages": [
        {
            "code": "1006040-651"
        },
        {
            "moreInfo": "Effective date assigned 220411"
        }
    ],
    "traceNumber": "041001030008013"
}

Missing mandatory information

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "Runtime error occurred in the service, please check with application support team before resubmitting the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
    }
}

Unavailable service

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Send additional addenda information

post /ach/payments/v1/addenda

Add records to an existing ACH transaction.

Request

BODY FIELD	TYPE	DESCRIPTION
addendarequired	array	addendaRequest
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.

Request example

{
    "addenda": [
        {
            "paymentRelatedInformation": "0410*820412***PER*AP*QAS TESTING*IT*N1*PR*THE QAS COMPANY*         0",
            "addendaSequenceNumber": "002"
        },
        {
            "paymentRelatedInformation": "3*ROUTE 1234*BOX 1234\\N5*TESTING*",
            "addendaSequenceNumber": "003"
        },
        {
            "paymentRelatedInformation": "TM*003*820311\\RMT*IV*0302892**252640\\DTM*003*820315\\RMT*IV*0302960**593835\\",
            "addendaSequenceNumber": "004"
        }
    ],
    "uuid": "qas220517x-49eb-47664-b94rhd1-e52e2re13001"
}

Responses

Successfully staged ACH file data into ACH Origination API.

NAME	TYPE	DESCRIPTION
uuidoptional	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusoptional	string	The overall status of the addenda request can be accepted or rejected.
traceNumberoptional	string	The unique number for the ACH transaction. Record this number for possible ACH inquiry requests.
informationMessagesoptional	array	detailMessage
errorMessagesoptional	array	detailMessage
addendaoptional	array	addendaResponse
requestAcceptedUTCTimeoptional	string	The date and time the request was accepted in UTC time. Format: YYYY-MM-DDTHH:MM:SSZ

Response example (200)

{
    "uuid": "qas220517x-49eb-47664-b94rhd1-e52e2re13001",
    "status": "accepted",
    "traceNumber": "41001030008011",
    "informationMessages": [
        {
            "code": "1002040-50II",
            "moreInfo": "All addenda have been received."
        }
    ],
    "errorMessages": [],
    "addenda": [
        {
            "status": "accepted",
            "errorMessages": [],
            "informationMessages": []
        }
    ],
    "requestAcceptedUTCTime": "2022-05-25T16:33:46Z"
}

Missing mandatory information

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unauthorized 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource not found

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request timeout

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown error

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (500)

{
    "ErrorMessage": "Runtime error occurred in the service, please check with application support team before resubmitting the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Bad gateway

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "ServiceError": {
        "ConnectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with application support team before resubmitting the request"
    }
}

Unavailable service

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "ConnectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Schemas

healthResponse

NAME	TYPE	DESCRIPTION
Statusoptional	string	The 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 response from the API service.
ClientIpoptional	string	The client IP address the gateway receives from the request.
X-Forwarded-Foroptional	string	The sequence of the IP addresses for systems between the client and the gateway.

exception

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Time of the occurrence of the error of the message.
ServiceErroroptional	oneOf	detailMessage connectError

connectError

NAME	TYPE	DESCRIPTION
ConnectErroroptional	string	Error information of the connectivity with downstream service.

acceptedAddendaResponseEnvelope

NAME	TYPE	DESCRIPTION
uuidoptional	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusoptional	string	The overall status of the addenda request can be accepted or rejected.
traceNumberoptional	string	The unique number for the ACH transaction. Record this number for possible ACH inquiry requests.
informationMessagesoptional	array	detailMessage
errorMessagesoptional	array	detailMessage
addendaoptional	array	addendaResponse
requestAcceptedUTCTimeoptional	string	The date and time the request was accepted in UTC time. Format: YYYY-MM-DDTHH:MM:SSZ

acceptedBatchResponseAcceptedDetailResponse

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusrequired	string	The status of the batch can be accepted or rejected.
requestAcceptedUTCTimeoptional	string	The date and time the request was accepted in UTC time. Format: YYYY-MM-DDTHH:MM:SSZ
effectiveDateoptional	string	The date the transaction is posted. This date must be within 31 days of the current date. Format: YYMMDD
informationMessagesoptional	array	detailMessage
errorMessagesoptional	array	detailMessage
detailsoptional	array	acceptedDetailResponse

acceptedDetailResponse

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusoptional	string	The overall status of the addenda can be accepted or rejected.
errorMessagesoptional	array	detailMessage
informationMessagesoptional	array	detailMessage
traceNumberoptional	string	The unique number for the ACH transaction. Record this number for possible ACH inquiry requests.
requestAcceptedUTCTimeoptional	string	The date and time the request was accepted in UTC time. Format: YYYY-MM-DDTHH:MM:SSZ

addendaRequest

NAME	TYPE	DESCRIPTION
paymentRelatedInformationrequired	string	The related payment information for the addenda records. The limit is 80 characters.
addendaSequenceNumberrequired	string	The sequence number of the addenda. The number cannot exceed 4 digits.

addendaRequestEnvelope

NAME	TYPE	DESCRIPTION
addendarequired	array	addendaRequest
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.

addendaResponse

NAME	TYPE	DESCRIPTION
statusoptional	string	The overall status of the addenda request can be accepted or rejected.
errorMessagesoptional	array	detailMessage
informationMessagesoptional	array	detailMessage

addendaStatusRequestEnvelope

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
pageSizeoptional	string	The number of records to be returned in the pagination search.
startAddendaSequenceNumberoptional	string	The starting number for the addenda record sequence.

addendaStatusResponseEnvelope

NAME	TYPE	DESCRIPTION
uuidoptional	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusoptional	string	The status of the batch can be accepted or rejected.
errorMessagesoptional	array	detailMessage
traceNumberoptional	string	The unique number for the ACH transaction. Record this number for possible ACH inquiry requests.
informationMessagesoptional	array	detailMessage
addendaoptional	array	baseAddendaDetailResponse

baseAddendaDetailResponse

NAME	TYPE	DESCRIPTION
addendaTypeCodeoptional	string	The type code for the addenda. The value is '05'.
addendaSequenceNumberoptional	string	The sequence number of the addenda. The number cannot exceed 4 digits.
paymentRelatedInformationoptional	string	The related payment information from the addenda records. The maximum character limit is 80.

baseAddendaRequest

NAME	TYPE	DESCRIPTION
paymentRelatedInformationrequired	string	The related payment information for the addenda records. The limit is 80 characters.

baseDetailResponse

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusoptional	string	The status of a batch record can be accepted or rejected. The status of a detailed record can be deleted, accepted, rejected, notFound, or waitingForAddenda.
errorMessagesoptional	array	detailMessage
informationMessagesoptional	array	detailMessage
traceNumberoptional	string	The unique number for the ACH transaction. Record this number for possible ACH inquiry requests.

batchRequestCCDDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
pointrequired	string	A short name specific to your company provided by KeyBank. This is included in the file name and improves security for file transfers.
collectionApplicationIdrequired	string	This ID is provided by KeyBank and cannot exceed the maximum of 9 alphanumeric characters.
collectionApplicationTypeoptional	string	A subset of the collection application parameters. This is not commonly used and by default, left blank. If there is a collection application type, the value is provided by KeyBank during onboarding and cannot exceed 6 characters.
secCoderequired	string	The three-digit Standard Entry Class code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEB.
effectiveDateoptional	string	The date the transaction is posted. This date must be within 31 days of the current date. Format: YYMMDD
companyDescriptiveDateoptional	string	Company descriptive date. Format: YYMMDD
companyEntryDescriptionrequired	string	Provides the receiver a description of the payment purpose. The value cannot exceed 10 characters and cannot be blank. Possible values: 'REVERSAL', 'RETURN FEE', 'RECLAIM', 'REDEPCHECK' for RCK entries, 'HCCLAIMPMT' for Health Care EFTs, or 'ACCTVERIFY' for clients sending in a micro-entry as a type of ACH entry.
detailsoptional	array	cCDDetailRequest

batchRequestCTXDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
pointrequired	string	A short name specific to your company provided by KeyBank. This is included in the file name and improves security for file transfers.
collectionApplicationIdrequired	string	This ID is provided by KeyBank and cannot exceed the maximum of 9 alphanumeric characters.
collectionApplicationTypeoptional	string	A subset of the collection application parameters. This is not commonly used and by default, left blank. If there is a collection application type, the value is provided by KeyBank during onboarding and cannot exceed 6 characters.
secCoderequired	string	The three-digit Standard Entry Class code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEB.
effectiveDateoptional	string	The date the transaction is posted. This date must be within 31 days of the current date. Format: YYMMDD
companyDescriptiveDateoptional	string	Company descriptive date. Format: YYMMDD
companyEntryDescriptionrequired	string	Provides the receiver a description of the payment purpose. The value cannot exceed 10 characters and cannot be blank. Possible values: 'REVERSAL', 'RETURN FEE', 'RECLAIM', 'REDEPCHECK' for RCK entries, 'HCCLAIMPMT' for Health Care EFTs, or 'ACCTVERIFY' for clients sending in a micro-entry as a type of ACH entry.
detailsoptional	array	cTXDetailRequest

batchRequestEnvelopeBatchRequestCCDDetailRequest

NAME	TYPE	DESCRIPTION
batchrequired	Object	batchRequestCCDDetailRequest
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.

batchRequestEnvelopeBatchRequestCTXDetailRequest

NAME	TYPE	DESCRIPTION
batchrequired	Object	batchRequestCTXDetailRequest
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.

batchRequestEnvelopeBatchRequestPPDDetailRequest

NAME	TYPE	DESCRIPTION
batchrequired	Object	batchRequestPPDDetailRequest
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.

batchRequestEnvelopeBatchRequestTELDetailRequest

NAME	TYPE	DESCRIPTION
batchrequired	Object	batchRequestTELDetailRequest
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.

batchRequestEnvelopeBatchRequestWEBDetailRequest

NAME	TYPE	DESCRIPTION
batchrequired	Object	batchRequestWEBDetailRequest
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.

batchRequestPPDDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
pointrequired	string	A short name specific to your company provided by KeyBank. This is included in the file name and improves security for file transfers.
collectionApplicationIdrequired	string	This ID is provided by KeyBank and cannot exceed the maximum of 9 alphanumeric characters.
collectionApplicationTypeoptional	string	A subset of the collection application parameters. This is not commonly used and by default, left blank. If there is a collection application type, the value is provided by KeyBank during onboarding and cannot exceed 6 characters.
secCoderequired	string	The three-digit Standard Entry Class code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEB.
effectiveDateoptional	string	The date the transaction is posted. This date must be within 31 days of the current date. Format: YYMMDD
companyDescriptiveDateoptional	string	Company descriptive date. Format: YYMMDD
companyEntryDescriptionrequired	string	Provides the receiver a description of the payment purpose. The value cannot exceed 10 characters and cannot be blank. Possible values: 'REVERSAL', 'RETURN FEE', 'RECLAIM', 'REDEPCHECK' for RCK entries, 'HCCLAIMPMT' for Health Care EFTs, or 'ACCTVERIFY' for clients sending in a micro-entry as a type of ACH entry.
detailsoptional	array	pPDDetailRequest

batchRequestTELDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
pointrequired	string	A short name specific to your company provided by KeyBank. This is included in the file name and improves security for file transfers.
collectionApplicationIdrequired	string	This ID is provided by KeyBank and cannot exceed the maximum of 9 alphanumeric characters.
collectionApplicationTypeoptional	string	A subset of the collection application parameters. This is not commonly used and by default, left blank. If there is a collection application type, the value is provided by KeyBank during onboarding and cannot exceed 6 characters.
secCoderequired	string	Standard Entry Class Code. Length must be exactly 3 alphabetical characters and adhere to Nacha rules.
effectiveDateoptional	string	The date the transaction is posted. This date must be within 31 days of the current date. Format: YYMMDD
companyDescriptiveDateoptional	string	Company descriptive date. Format: YYMMDD
companyEntryDescriptionrequired	string	Provides the receiver a description of the payment purpose. The value cannot exceed 10 characters and cannot be blank. Possible values: 'REVERSAL', 'RETURN FEE', 'RECLAIM', 'REDEPCHECK' for RCK entries, 'HCCLAIMPMT' for Health Care EFTs, or 'ACCTVERIFY' for clients sending in a micro-entry as a type of ACH entry.
detailsoptional	array	telDetailRequest

batchRequestWEBDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
pointrequired	string	A short name specific to your company provided by KeyBank. This is included in the file name and improves security for file transfers.
collectionApplicationIdrequired	string	This ID is provided by KeyBank and cannot exceed the maximum of 9 alphanumeric characters.
collectionApplicationTypeoptional	string	A subset of the collection application parameters. This is not commonly used and by default, left blank. If there is a collection application type, the value is provided by KeyBank during onboarding and cannot exceed 6 characters.
secCoderequired	string	The three-digit Standard Entry Class code based on Nacha rules. Valid values: CCD, CTX, PPD, TEL, WEB.
effectiveDateoptional	string	The date the transaction is posted. This date must be within 31 days of the current date. Format: YYMMDD
companyDescriptiveDateoptional	string	Company descriptive date. Format: YYMMDD
companyEntryDescriptionrequired	string	Provides the receiver a description of the payment purpose. The value cannot exceed 10 characters and cannot be blank. Possible values: 'REVERSAL', 'RETURN FEE', 'RECLAIM', 'REDEPCHECK' for RCK entries, 'HCCLAIMPMT' for Health Care EFTs, or 'ACCTVERIFY' for clients sending in a micro-entry as a type of ACH entry.
detailsoptional	array	webDetailRequest

batchResponseEnvelopeAccepted

NAME	TYPE	DESCRIPTION
batchrequired	Object	acceptedBatchResponseAcceptedDetailResponse

cCDDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
accountTyperequired	string	The account type can be checking (C) or savings (S). Valid values: C, S.
creditDebitCoderequired	string	One-character field indicates if the ACH transaction is a credit (C) or debit (D). Valid values: C, D.
transactionTyperequired	string	Nacha-defined transaction types can be live (L), prenote (P), or zero (Z). Valid values: L, P, Z.
receivingDFIIdrequired	string	The bank routing number (ABA number) of the receiving designated financial institution. The number can be a maximum of 8 digits.
checkDigitrequired	string	The final character of a routing number that can be used to validate a specific routing number. This is a single digit.
DFIAccountNumberrequired	string	The recipient account number at the designated financial institution. The account number can be a maximum of 17 characters.
amountrequired	string	The transaction amount in valid currency format. The amount can have up to 8 digits before the decimal and 2 digits after the decimal.
identificationNumberoptional	string	Identification number for the detail record. The number cannot exceed 15 characters.
receivingCompanyNamerequired	string	The name of the receiving company. The name cannot exceed a maximum of 22 characters.
discretionaryDataoptional	string	Further identification of the company or used to describe the type of entries being processed. The ID can be a maximum of 2 characters.
addendaoptional	array	baseAddendaRequest

cTXDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
accountTyperequired	string	The account type can be checking (C) or savings (S). Valid values: C, S.
creditDebitCoderequired	string	One-character field indicates if the ACH transaction is a credit (C) or debit (D). Valid values: C, D
transactionTyperequired	string	Nacha-defined transaction types can be live (L), prenote (P), or zero (Z). Valid values: L, P, Z
receivingDFIIdrequired	string	The bank routing number (ABA number) of the receiving designated financial institution. The number can be a maximum of 8 digits.
checkDigitrequired	string	The final character of a routing number that can be used to validate a specific routing number. This is a single digit.
DFIAccountNumberrequired	string	The recipient account number at the designated financial institution. The account number can be a maximum of 17 characters.
totalAmountrequired	string	The total amount of the transactions in valid currency format. The amount can have up to 8 digits before the decimal and 2 digits after the decimal.
identificationNumberoptional	string	Identification number for the detail record. The number cannot exceed 15 characters.
numberOfAddendaRecordsrequired	string	Count of addenda records. This cannot exceed 4 digits.
receivingCompanyNameIDNumberrequired	string	The name and ID of the receiving company. This field cannot exceed 16 characters.
discretionaryDataoptional	string	Further identification of the company or used to describe the type of entries being processed. The ID can be a maximum of 2 characters.
addendaoptional	array	baseAddendaRequest

detailMessage

NAME	TYPE	DESCRIPTION
codeoptional	string	A static status code assigned by the network or payment system.
moreInfooptional	string	Detailed descriptive message.

detailStatusRequestEnvelopePaymentInquiryDetailRequest

NAME	TYPE	DESCRIPTION
detailStatusoptional	array	paymentInquiryDetailRequest

detailStatusResponse

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
statusoptional	string	The status of the batch tells if data is valid, contains errors, or has been received by the ACH core processing system. Valid values: accepted, rejected, extracted
errorMessagesoptional	array	detailMessage
informationMessagesoptional	array	detailMessage
traceNumberoptional	string	The unique number for the ACH transaction. Record this number for possible ACH inquiry requests.
requestAcceptedUTCTimeoptional	string	The date and time the request was accepted in UTC time. Format: YYYY-MM-DDTHH:MM:SSZ
requestDeletedUTCTimeoptional	string	The date and time the request was deleted in UTC time. Format: YYYY-MM-DDTHH:MM:SSZ
requestLastUpdatedUTCTimeoptional	string	The date and time the request was updated in UTC time. Format: YYYY-MM-DDTHH:MM:SSZ
pointoptional	string	A short name specific to your company provided by KeyBank. This is included in the file name and improves security for file transfers.
collectionApplicationIdoptional	string	This ID is provided by KeyBank and cannot exceed the maximum of 9 alphanumeric characters.
collectionApplicationTypeoptional	string	A subset of the collection application parameters. This is not commonly used and by default, left blank. If there is a collection application type, the value is provided by KeyBank during onboarding and cannot exceed 6 characters.
secCodeoptional	string	The three-digit Standard Entry Class code based on Nacha rules. Valid values: CCD, CTX, IAT, PPD, TEL, WEB.
effectiveDateoptional	string	The date the transaction is posted. This date must be within 31 days of the current date. Format: YYMMDD
companyDescriptiveDateoptional	string	Company descriptive date. Format: YYMMDD
batchNumberoptional	string	The number associated with the batch. It can be a maximum of 7 digits.
companyNameoptional	string	The name of the corporation or institution making the request. The name cannot exceed 16 characters or have spaces.
companyDiscretionaryDataoptional	string	Discretionary data for the company.
companyIdentificationoptional	string	The identification number of the company. This cannot exceed 15 digits.
companyEntryDescriptionoptional	string	Provides the receiver a description of the payment purpose. The value cannot exceed 10 characters and cannot be blank. Possible values: 'REVERSAL', 'RETURN FEE', 'RECLAIM', 'REDEPCHECK' for RCK entries, 'HCCLAIMPMT' for Health Care EFTs, or 'ACCTVERIFY' for clients sending in a micro-entry as a type of ACH entry.
originatingDFIIdoptional	string	The bank routing number (ABA number) of the originating designated financial institution. The number can be a maximum of 8 digits.
accountTypeoptional	string	The account type can be checking (C) or savings (S). Valid values: C, S.
creditDebitCodeoptional	string	One-character field indicates if the ACH transaction is a credit (C) or debit (D). Valid values: C, D.
transactionTypeoptional	string	Nacha-defined transaction types can be live (L), prenote (P), or zero (Z). Valid values: L, P, Z
transactionCodeoptional	string	A two-character field that specifies the billing credit transaction code.
receivingDFIIdoptional	string	The bank routing number (ABA number) of the receiving designated financial institution. The number can be a maximum of 8 digits.
checkDigitoptional	string	The final character of a routing number that can be used to validate a specific routing number. This is a single digit.
dfiAccountNumberoptional	string	The recipient account number at the recipient's bank.
amountoptional	string	The transaction amount in valid currency format. The amount can have up to 8 digits before the decimal and 2 digits after the decimal.
identificationNumberoptional	string	Identification number for the detail record. The number cannot exceed 15 characters.
receivingCompanyNameoptional	string	The name of the receiving company. The name cannot exceed a maximum of 22 characters.
discretionaryDataoptional	string	Further identification of the company or used to describe the type of entries being processed. The ID cannot exceed the maximum of 20 characters.
totalAmountoptional	string	The total amount of the transactions in valid currency format. The amount can have up to 8 digits before the decimal and 2 digits after the decimal.
receivingCompanyNameIDNumberoptional	string	The name and ID of the receiving company. This field cannot exceed 16 characters.
individualIdentificationNumberoptional	string	The ID number for the individual. This cannot exceed 15 characters.
individualNameoptional	string	The name of the individual. This cannot exceed 22 characters.
paymentTypeCodeoptional	string	The code is a maximum of four characters. This field returns two empty spaces if the code is not provided by the client.
numberOfAddendaRecordsoptional	string	Count of addenda records. This cannot exceed 4 digits.
numberOfAddendaReceivedoptional	string	Count of addenda records received.
addendaoptional	array	baseAddendaDetailResponse
fileCreationDateoptional	string	The date the file was created. Format: YYMMDD
fileCreationTimeoptional	string	The time the file was created.
fileIdModifieroptional	string	The file ID modifier to control the totals with a single alphanumeric value.

detailStatusResponseEnvelopeDetailStatusResponse

NAME	TYPE	DESCRIPTION
detailsoptional	array	detailStatusResponse

detailUndoRequestEnvelope

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.

pPDDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
accountTyperequired	string	The account type can be checking (C) or savings (S). Valid values: C, S.
creditDebitCoderequired	string	One-character field indicates if the ACH transaction is a credit (C) or debit (D). Valid values: C, D.
transactionTyperequired	string	Nacha-defined transaction types can be live (L), prenote (P), or zero (Z). Valid values: L, P, Z.
receivingDFIIdrequired	string	The bank routing number (ABA number) of the receiving designated financial institution. The number can be a maximum of 8 digits.
checkDigitrequired	string	The final character of a routing number that can be used to validate a specific routing number. This is a single digit.
DFIAccountNumberrequired	string	The recipient account number at the designated financial institution. The account number can be a maximum of 17 characters.
amountrequired	string	The transaction amount in valid currency format. The amount can have up to 8 digits before the decimal and 2 digits after the decimal.
individualNamerequired	string	The name of the individual. This cannot exceed 22 characters.
individualIdentificationNumberoptional	string	The ID number for the individual. This cannot exceed 15 characters.
discretionaryDataoptional	string	Further identification of the company or used to describe the type of entries being processed. The ID can be a maximum of 2 characters.
addendaoptional	array	baseAddendaRequest

paymentInquiryDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.

telDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
accountTyperequired	string	The account type can be checking (C) or savings (S). Valid values: C, S.
creditDebitCoderequired	string	One-character field indicates if the ACH transaction is a credit (C) or debit (D). Valid values: C, D.
transactionTyperequired	string	Nacha-defined transaction types can be live (L), prenote (P), or zero (Z). Valid values: L, P, Z.
receivingDFIIdrequired	string	The bank routing number (ABA number) of the receiving designated financial institution. The number can be a maximum of 8 digits.
checkDigitrequired	string	The final character of a routing number that can be used to validate a specific routing number. This is a single digit.
DFIAccountNumberrequired	string	The recipient account number at the designated financial institution. The account number can be a maximum of 17 characters.
amountrequired	string	The transaction amount in valid currency format. The amount can have up to 8 digits before the decimal and 2 digits after the decimal.
individualIdentificationNumberoptional	string	The ID number for the individual. This cannot exceed 15 characters.
individualNamerequired	string	The name of the individual. This cannot exceed 22 characters.
paymentTypeCodeoptional	string	The code is a maximum of two characters. The code is two empty spaces if the code is not provided by the client.

webDetailRequest

NAME	TYPE	DESCRIPTION
uuidrequired	string	A custom value used to identify each transaction. It is required to undo a payment. The ID must not exceed 45 alphanumeric characters.
accountTyperequired	string	The account type can be checking (C) or savings (S). Valid values: C, S
creditDebitCoderequired	string	One-character field indicates if the ACH transaction is a credit (C) or debit (D). Valid values: C, D
transactionTyperequired	string	Nacha-defined transaction types can be live (L), prenote (P), or zero (Z). Valid values: L, P, Z
receivingDFIIdrequired	string	The bank routing number (ABA number) of the receiving designated financial institution. The number can be a maximum of 8 digits.
checkDigitrequired	string	The final character of a routing number that can be used to validate a specific routing number. This is a single digit.
DFIAccountNumberrequired	string	The recipient account number at the designated financial institution. The account number can be a maximum of 17 characters.
amountrequired	string	The transaction amount in valid currency format. The amount can have up to 8 digits before the decimal and 2 digits after the decimal.
individualIdentificationNumberoptional	string	The ID number for the individual. This cannot exceed 15 characters.
individualNamerequired	string	The name of the individual. This cannot exceed 22 characters.
paymentTypeCodeoptional	string	The code is a maximum of two characters. The code is two empty spaces if the code is not provided by the client.
addendaoptional	array	baseAddendaRequest

Errors

For more information about errors, see Error handling.

Changelog

Release	API version	Change description	Impact
October 2024	1.3.2	Updated `companyEntryDescription` to include possible values like 'REVERSAL', 'RETURN FEE', 'RECLAIM', 'REDEPCHECK' for RCK entries, and 'HCCLAIMPMT' for health care EFTs, or 'ACCTVERIFY' for clients sending in micro-entry as a type of ACH entry.	LOW
May 2024	1.3.1	Changed the `effectiveDate` range for ACH payments from 90 days to 31 days. `X-CorrelationId` has been removed as a request header field for all endpoints. The parameter is no longer in the request body, but still remains in the code. The system assigns a unique ID when you submit a request and returns the value in the response.	MID
April 2024	1.3.0	Removed `X-Point` from all endpoints. This is an internal field and is not required for API requests.	LOW
September 2023	1.2.0	Added `customData` field to each of the SEC payment endpoints. You can enter up to 500 alphanumeric characters that will stay with the transaction through its lifecycle. Removed unused objects: `batchResponseEnvelopeRejected` `successSearchResponseNotificationEventResponse` `successResponseString` `successMetaResponse` `sortControl` `notifcationEventResponse` `messageResponse` `baseDataObject` `rejectedBatchResponseBaseDetailResponse` The `traceNumber` was updated to remove a reference to an internal database table, TBDACHDETAIL. `DFIAccountNumber` was updated to clarify that this is the recipient account number at the recipient’s bank. `receivingDFIID` was updated to clarify that this is the ABA of the recipient’s bank.	MID
May 2023	1.1.6	Added the require `companyEntryDescription` for each of the SEC payment endpoints. ACH requests will no longer have a default description. You can set the description for each transaction. This field returns in the ACH status response payload.	MID
December 2022	1.1.5	Released 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

Getting Started Guide

clock 8-minute read calender Rel. 4.0.0 | updated Nov. 12, 2024

We've created this simple, user-friendly developer portal with you in mind. Here's a few good things to know first.

Key takeaways

You need to be an authenticated and authorized user with our developer portal to use our APIs. To get started, see our overview of the onboarding process.
After you onboard, you get your own private API keys and can access our test environment.
Get an access token to connect to your APIs and start building.

Want in?

Contact a Payments Advisor to learn more about the KeyBank API developer portal and we'll have someone contact you with more information!
Contact us

Quick overview of the onboarding process

01 Contact and consult

If you are interested in a particular API product or a group of APIs, sign up for our waitlist. KeyBank will follow-up with you to help get you started.

To work with KeyBank APIs, there needs to be an established agreement between the service provider (KeyBank) and the client (you). This agreement details the API services you want, its services, and settings. It also gathers important system information needed for the KeyBank onboarding team to configure and secure the provisioned app.

02 Determine API needs

Determine which APIs are needed, define the frequency of use, and the transaction activity timeframe. Some APIs require specific configurations and may have a certain object to include in the call. Also, be mindful of our rate limiting.

For each API, provide the following information:

General details like transaction volume
Call frequency (number of calls per second, number of calls per minute, etc.)
Call timeframe (e.g., 24 hours a day or only during business hours)

The KeyBank onboarding team will reach out via email communication for additional details, if necessary.

03 Set up security

It is essential to have a secure connection before we start exchanging data, especially data as sensitive as financial data. For us to trust one another and verify that our pathways are safe, private, and guarded, we need to know your IP address and exchange certificates.

A digital certificate verifies your identity and keeps your data safe. Think of it like a virtual ID card for a website, or in this case the developer portal. When you connect to the site, the certificate legitimizes your identity. Then, when making API requests and transferring data on a cloud network, the certificate helps encrypt the data.

We use a mTLS authentication mechanism. This means when you request a mTLS certificate, you will get a public certificate chain and a private key. On your end, configure your application with the private key and certificate. You do not need to share your private key with KeyBank. After we exchange certificates, you will use the private key to encrypt the exchange and KeyBank uses the public certificate chain to verify it.

Certificate requirements:

Must have a CSR and private key. Do not share the private key.
Must include the root, intermediate, and leaf.
File format can be *.pem, *.crt, or *.cer.
Certificates cannot be self-signed.
Issued by a trusted certificate authority organization like DigiCert.
Only one certificate is required for all APIs.

04 Grant access

KeyBank sets up your account entitlements. Entitlements authenticate your identity and contain the authorization rules for the APIs you have permission to access. Part of the account entitlements are the API keys.

You need API keys to create an access token required to make an API call. There are application credentials that authorize which API products you can access, and there are client credentials that authenticate you as a client partnering with KeyBank. We share this information with your privately and securely during our onboarding procedures.

KeyBank will set you up a test environment. You can use the test environment to get a better idea of how the API functions and how to integrate with your application. We share the environment details with you once setup is complete.

Common terms

Access token: A temporary token to that gives you permission to use the API. Use your API keys to generate the token. This is also known as a bearer token.
API consumer:: An authenticated developer portal user that has completed the onboarding process, has access to API services and possibly the KeyBank test environment.
API keys:: There are two sets of API keys that we privately share with you to authenticate and authorize your ability to use and access our API products. Can’t turn that engine without a key.
Authentication:: A method of identifying you and your application as a trusted and accepted source to exchange data. With authentication, we use your KeyBank client credentials (part of your API keys) to identify you.
Authorization:: A method of permitting access to certain APIs and services.
Certificates:: A digital exchange of several encrypted codes that verify your ability to connect with our API products safely, securely, and cautiously. These certificates typically expire annually.
CSR:: Certificate signing request is an encoded message that contains the information needed by the Certificate Authority (CA) to create your certificate. This can include your name, domain, organization information, or location.
Domain:: A human-readable name for an application or web address that identifies the name of the online application. Domain names are used to help set up web servers, communication, and other online services.
IP address:: The internet protocol address is a numerical label assigned to each device or application connected to the internet. Addresses can uniquely identify devices and route data to its intended destination.
mTLS:: Mutual Transport Layer Security is mechanism for the mutual authentication between the service provider and the client. No catfishing here. Digital certificates are exchanged and signed with the PKI framework.
Onboarding:: The process of helping KeyBank partners and API consumers get familiar with our suite of API products. This can include assessment, setup, and environment access.
PKI:: A public key infrastructure is a system to create, store, and distributes digital certificates. This framework matches the public keys to digital entities to authenticate the identity of users, devices, and services.
Pre-production:: A test environment that allows you try the API product using sample data.
Production:: KeyBank’s live environment that exchanges real proprietary data between your application and our API products.
Service agreement:: A contract between KeyBank and financial businesses and applications that intend to use and integrate with KeyBank’s suite of APIs. The service agreement identifies the API products allowed, data volume, and other specifics require to ensure a proper configuration of services.

Using our APIs

Health checks

We recommend that you always start your API builds with a health check. To perform a health check, you must have valid certificates exchanged with KeyBank and API keys to request an access token.

Rate limiting

To ensure efficient and consistent API performance, we've placed a limit of 5 transactions per second (TPS) across all KeyBank APIs. API requests that exceed the rate limit receive an HTTP 429 response status code. If you've exceeded this limit, wait for at least 2 minutes before making another API call.

While we established the 5 TPS threshold to maximize stability and performance, we understand that your consumption needs might not fit within those limits. To request an increased rate limit, contact your KeyBank Client Success Manager.

X-CorrelationId

The X-CorrelationId is a unique 36-digit alphanumeric identification code generated automatically for each API transaction. This field helps support teams at KeyBank quickly track down an inquiry or issue. The ID stays with the transaction so we can trace the chain of API operations in the event logs. If you see different X-CorrelationId values for the same transaction, this could indicate that duplicate requests.

Request an access token

KeyBank requires an OAuth 2.0 access token to authorize API calls. To make a call for a token, you must have access to our environments, your certificates, private key, and API keys.

Copy and modify the cURL command template. Be sure to replace the curly brackets {{xxxx}} with your specific information.

For line 1, identify the certificates.
- For client.crt, enter the location of your certificate signing request (CSR). The file must be in one of these formats *.pem, *.crt, or *.cer.
- For client.key, enter the name of your certificate’s private key file.
- For ca.crt, enter the name of your certificate authority (CA) certificate.
For line 2, identify the host. Enter the URL address for the KeyBank environment. Make sure to add scope=rs-read as a path parameter in the URL.
For line 3, enter your application credentials (consumer_key and consumer_secret) API keys in Base64 encoded format. Use a trusted site to generate an encoded string for your consumer key and secret.
For line 6, enter your client credentials from KeyBank. For client id enter your client_id API key and for client password, enter the client_secret API key from KeyBank.

cURL command template

curl -X POST --cert {{client.crt}} --key {{client.key}} --cacert {{ca.crt}} \
  ‘{{host}}/oauth/v1/token?scope=rs-read'
  -H 'Authorization: Basic {{base64 encoded consumer key and secret}}'
  -H 'Content-type: application/x-www-form-urlencoded'
  -H 'Accept: application/json'
  -d 'Id={{client id}}&Key={{client password}}&grant_type=client_credentials'

Request and response example

The response contains a field named access_token. Use this access token in the Authorization header when you call the API over a secure mTLS connection.
If you are unable to retrieve an access code, reassess your setup, review your API keys, and make sure you are properly connected to the environment before you try again.

Request

Response

curl -X POST --cert client.crt --key client.key --cacert ca.crt \ 
  'https://partner-api.keybank.com/oauth/v1/token’
  -H 'Authorization: Basic KFddrcHQwQ3JDGQTamdqRUI0bEFHVVlHQcg'
  -H 'Content-type: application/x-www-form-urlencoded'
  -H 'Accept: application/json'
  -d 'Id=b1194a183b8e01&Key=165a15dfanqf1d60&grant_type=client_credentials'

curl -X POST --cert {{client.crt}} --key {{client.key}} --cacert {{ca.crt}} \
  {
   "refresh_token_expires_in": "0",
   "api_product_list": "[API 1, API 2, API 3]",
   "api_product_list_json": [
      "API Inquiry",
      "API test product",
     ],
   "organization_name": "keybank-non-prod",
   "developer.email": "yourEmail",
   "token_type": "BearerToken",
   "issued_at": "2255448892",
   "client_id": "KBConsumerKey”,
   "access_token": "gPd4ZXMi927aoWhvmc",
   "application_name": "9IIa42-134320dk32s",
   "scope": "apiauth-read apiauth-write rs-create rs-delete rs-oauth rs-read rs-update rs-write",
   "Id": "KBClientId",
   "expires_in": "86399",
   "refresh_count": "0",
   "status": "approved"
  }

What to expect

You get a response with access token and information about which API products you can use, the refresh token time cycle, expiration time, etc.
Select and copy the access_token value to use with your API requests.
The access token remains valid for 24 hours. If it expires, try the refresh token to receive a new access token and pass in the API request.

What's next?

If this all sounds nice to you, sign up to speak with a Payments Advisor. Our people will reach out to your people.
Read our API documentation to learn more about KeyBank’s API products. Or if you prefer to look under the hood, download an API specification file in YAML format.

Check Image Retrieval

2-minute read 1.2.5 | updated Nov. 19, 2024

See and verify checks paid

Use the Check Image Retrieval API to retrieve images of every check deposited and cleared.

Check Image Retrieval Endpoints

What you can do	Endpoint
Health check	get /cmi/v1/healthCheck
Retrieve a check image	post /cmi/v1/checkList

Before you begin

All KeyBank APIs require certificates, user credentials, and certain permissions. Check out our Getting Started Guide to learn more.

Overview

Use the Check Image Retrieval API to retrieve images of every check deposited and cleared. A successful request returns details of the requested check image (if attachImages is set to TRUE).

API requirements

Username and password: Your assigned username and password for the API is required in the defaultCheckRequest object of the request body. These credentials are provided by KeyBank after the onboarding process is complete. This information is shared with you via secure email.

Health check

get /cmi/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	Origin of the system response can be 'Gateway' or 'Roundtrip'. Roundtrip returns a response from the farthest system involved.
Timestampoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) of response from the API service.
ClientIpoptional	string	Client IP address the gateway receives from the request.
X-Forwarded-Foroptional	string	Sequence of IP addresses for systems 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]"
}

Retrieve a check image

post /cmi/v1/checkList

Get a single check image associated with the requested check and account information.

Request

BODY FIELD	TYPE	DESCRIPTION
attachImagesrequired	boolean	Indicates if the check image needs to be attached to the response. If set to true, images are rendered in response.
defaultChecksRequestrequired	Object	defaultChecksRequest
featuresoptional	Object	features
limitrequired	integer	The number of checks returned. Because this endpoint returns a single check image, limit must be set to 1.
startoptional	integer	Start index of the check range to be retrieved

Request example

{
    "attachImages": true,
    "defaultChecksRequest": {
        "applicationGroupId": "CPCCHECKS",
        "applicationId": "CPC-CHECKS",
        "criterias": [
            {
                "documentIndex": "Account Number",
                "highValue": "",
                "lowValue": "1234567890",
                "operator": "eq"
            },
            {
                "documentIndex": "Check Number",
                "highValue": "",
                "lowValue": "14704523",
                "operator": "eq"
            },
            {
                "documentIndex": "Amount",
                "highValue": "",
                "lowValue": "85.95",
                "operator": "eq"
            },
            {
                "documentIndex": "Check Process Date",
                "highValue": "",
                "lowValue": "09\/22\/2021",
                "operator": "eq"
            }
        ],
        "password": "testuser",
        "userName": "abc$123#scsf"
    },
    "features": {
        "outputFormat": "TIF",
        "compresstoZip": true,
        "scale": ""
    },
    "limit": 1,
    "start": 0
}

Responses

Successful response

NAME	TYPE	DESCRIPTION
getChecksListResponserequired	array	getChecksListResponse
messagerequired	string	A human-readable message that describes the response status.
totalNoOfChecksrequired	string	Indicates the total number of checks retrieved.

Response example (200)

{
    "getChecksListResponse": [
        {
            "accountNumber": "1234567890",
            "amount": "85.95",
            "checkProcessDate": "09\/22\/2021",
            "checkNumber": "14704523  ",
            "sequenceNumber": "38581847",
            "transactionType": "DEBIT",
            "checkRoutingNumber": "04120704",
            "checkFrontImage": "lUwXMGBwTm4dy\/5pe8GwlRZULmMfPkzL8yZKfDxRTU7HFMW\/b7DYqjBq0vyC85PxMObQ2UxtcbVe78MWsdgIBkKY7pCB4eE7GQr9QOcFRW2O7FQshj8ExEy0bmCV8cQFyxzKh04XPWIDxp71PIw\/BFWy2GG+R3b1SFP\/Mbj0Hdppoxn+rUxAz7Red+39BodSSz1xZteU8hu6fYvvNmbqasZmkVAEE6hS2H+3uVKqaMmnpHJ2oIie0rtowueFradOWhNGvV5pRuEhEd6j93X\/7mt=",
            "checkRearImage": "73mfoZbjXF4Gr9XuIYSieWR0o3NV2bvMcwiurzvU8Dyvy2CG+1DYdw3IyHHZRdY6CKiarVFK7mG+IgJKVaDwqA2Ma7YxopwgEIJ5oc8gS\/O8BzX7zms\/6hmRn9wrcZj3ZhaSUmAdOtSc3qOzp6JPLoYyJg2hQwnEtJyormF8GT5ajF8ADV6XQD+d3Ym8bKsR6rHWwGB0bmiKu+9r+33mR8QZmzmmCPIUZXzj6CXaLr0dNA4+xXszgMbWAHI00ZGhTsSfzyWp8FHYZx24fbEOkS9ApuVBRihL+Eb14ldJayOgAXI3OjLJgo2pB4EUvbQmhwu="
        }
    ],
    "message": "Successfully retrieved",
    "totalNoOfChecks": "1"
}

Missing mandatory information

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (400)

{
    "ErrorMessage": "Mandatory data not provided, please verify the data and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (401)

{
    "ErrorMessage": "Received request is unauthorized, please provide valid credentials",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Forbidden request access

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (403)

{
    "ErrorMessage": "Access to requested resource is forbidden",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Resource 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (404)

{
    "ErrorMessage": "Requested resource is not found, please verify the resource then resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request method

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (405)

{
    "ErrorMessage": "Requested method is not allowed, please verify the method and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Invalid request type

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (415)

{
    "ErrorMessage": "Requested media type is not allowed, please verify the media type and resubmit the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Request 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (429)

{
    "ErrorMessage": "Number requests threshold reached, please resubmit the request after sometime",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z"
}

Unknown 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (500)

{
    "ErrorMessage": "Runtime error occurred in the service, please check with application support team before resubmitting the request",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (502)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "ServiceError": {
        "connectError": "Connectivity error occurred with the downstream service (Unexpected EOF at target), please check with appplication support team before resubmitting the request"
    }
}

Unavailable service

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (503)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "TransactionTime": "2021-06-11T16:31:34.041Z",
    "ServiceError": {
        "connectError": "Service is currently unavailable (NoActiveTargets), please check with application support before resubmitting the request."
    }
}

Unable to process 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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

Response example (504)

{
    "ErrorMessage": "Error received from backend",
    "TransactionId": "rrt-7709400285867417207-b-gce-27587-2383364-1",
    "X-CorrelationId": "929618f2-6163-bf73-51b0-6c54a8533c74",
    "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."
    }
}

Schemas

criteria

NAME	TYPE	DESCRIPTION
documentIndexrequired	string	Required parameters to retrieve a check image. A total of four criteria objects should be included in the request - one for each of the four values required to retrieve a check image. Valid values: Account Number, Check Number, Check Amount, Check Process Date
highValueoptional	string	Indicates the high range of the criteria. Reserved for future use, should be left blank.
lowValuerequired	string	Indicates the starting range of the criteria.
operatorrequired	string	Indicates the operation type. Must be set to "eq".

defaultChecksRequest

NAME	TYPE	DESCRIPTION
applicationGroupIdrequired	string	Indicates the application group ID for check images. Must be set to "CPCCHECKS".
applicationIdrequired	string	Indicates the application ID for check images. Must be set to "CPC-CHECKS".
criteriasrequired	array	criteria
userNamerequired	string	Username provided by KeyBank during client onboarding.
passwordrequired	string	Encrypted password provided by KeyBank during client onboarding.

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.
X-CorrelationIdoptional	string	A unique identifier generated for each transaction that remains with the transaction through the chain of API operations.
TransactionTimeoptional	string	Date (YYYY-MM-DD) and time (HH:MM:SS) the error occurred.
ServiceErroroptional	oneOf	serviceErrorData connectError

connectError

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

features

NAME	TYPE	DESCRIPTION
outputFormatrequired	string	Indicates the output format of the check images. Valid values: TIF, TIFG4
compresstoZipoptional	boolean	Reserved for future use. Please leave this field blank.
scaleoptional	string	Reserved for future use. Please leave this field blank.

getCheckListRequest

NAME	TYPE	DESCRIPTION
attachImagesrequired	boolean	Indicates if the check image needs to be attached to the response. If set to true, images are rendered in response.
defaultChecksRequestrequired	Object	defaultChecksRequest
featuresoptional	Object	features
limitrequired	integer	The number of checks returned. Because this endpoint returns a single check image, limit must be set to 1.
startoptional	integer	Start index of the check range to be retrieved

getCheckListBean

NAME	TYPE	DESCRIPTION
getChecksListResponserequired	array	getChecksListResponse
messagerequired	string	A human-readable message that describes the response status.
totalNoOfChecksrequired	string	Indicates the total number of checks retrieved.

getChecksListResponse

NAME	TYPE	DESCRIPTION
accountNumberoptional	string	Account number of the check image
amountoptional	string	Amount of the check
checkProcessDateoptional	string	Check processed date (MM-DD-YYYY)
checkNumberoptional	string	Check number
sequenceNumberoptional	string	Sequence number of the check
transactionTypeoptional	string	Transaction type of the check
checkRoutingNumberoptional	string	Routing number of the check
checkFrontImageoptional	string	The Base64 encoded string for the front image of the check.
checkRearImageoptional	string	The Base64 encoded string for the back image of the check.

serviceErrorData

NAME	TYPE	DESCRIPTION
ErrorDetailsoptional	string	Additional error details about the failed transaction.

Errors

For more information about general errors, see Error handling.

The message field in the getCheckListResponse tells you if the check was "Successfully retrieved" or "Failed". It is possible to receive a HTTP 200 response and have a failure message to resolve. This means that your transaction was successfully received but there was an issue with the request data. Look at the API-specific KeyBank error codes and details are in the serviceErrorData object of the exception schema.

HTTP STATUS CODE	Message status	DESCRIPTION
200	`Successfully retrieved`	`Specified checks not found.` There is invalid data in the request payload. Make sure mandatory fields are complete and field entries are in the correct format.
200	`Successfully retrieved`	`checkFrontImage and checkRearImage are blank.` The Boolean value for the `attachImages` field is set to False in the request and you will not receive check images.
200	`Failed`	`Error received from backend service.` `Missing or invalid field – Check Date` You are missing mandatory information in your request. Enter the starting check date in MMDDYYYY format in the `criterias` object > `lowValue` field.
200	`Failed`	`Error received from backend service.` `This Application is not configured for CMI transaction.` You are missing some mandatory information in the `defaultsCheckRequest` object. Make sure you have the correct information in the `applicationGroupId` field.
200	`Failed`	`Error received from backend service.` `500 – Internal Server Error` You are missing mandatory information or have an invalid value in the `criterias` object. Review the request to make sure that all requirements are met before retrying the call.
200	`Failed`	`Unknown error occured(Expected STRING or NUMBER or OBJECT or ARRAY at line 2), please check and resubmit the request` Make sure that the Boolean value for the `attachImages` field is set to True to receive check images.

Changelog

Release	API version	Change description	Impact
November 2024	1.2.5	Modified the front and back image description to clarify that it is a Base64 encoded string and not an actual image file.	LOW
May 2024	1.2.4	Parameter description updates. This change is for technical content only. The code and operations of the API remain the same. Updated the `getChecksListResponse` object with improved error messaging. `X-CorrelationId` has been removed as a request header field for all endpoints. The parameter is no longer in the request body, but still remains in the code. The system assigns a unique ID when you submit a request and returns the value in the response.	MID
December 2022	1.1.7	Released 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

ACH APIs User Guide

clock 31-minute read calender | updated Sep. 15, 2024

Tips and tricks to leverage the suite of ACH API’s quickly and efficiently

Key takeaways

TL;DR so here are the hits:

Use our ACH Origination API to make or collect authorized payments. You can also inquire on the transactions before they are officially submitted for processing.
Sometimes we make mistakes. With ACH you can undo a payment typically within a period of 10 minutes from origination.
Inquiring minds want to know? Monitor and report on ACH transactions at any point in the payment process.
Look at our Webhooks specs to learn more about automatic push notifications for ACH transactions.

Try it out!

Wanna check out our ACH APIs? You first need to complete the KeyBank onboarding process.

Check out our Getting Started Guide or contact a KeyBank Payment Advisor to learn more.

ACH Origination API

With the ACH Origination API, you can originate a credit or debit transaction to an authorized receiver.

See the specs

It’s cool if you take my money

To make or collect a payment there has to be an authorized agreement between the originator and the receiver. An authorized agreement means that the payee has an agreement with their financial institution or commercial entity that funds can be exchanged between the originator and the receiver.

Submit an ACH request

The ACH Origination API uses only POST methods to generate new ACH transactions. In the request, you indicate if you are pushing or pulling funds and the method of authorization to transfer funds.

The creditDebitCode defines the action of the request, if you are taking funds (debit) or receiving funds (credit).
The secCode defines the authorized method to transfer funds, like from a corporate account, online account, by phone, etc. There is a path for each SEC code. Use the correct endpoint path and identify the secCode in the request.

Some more details about SEC codes

All ACH payments, credit or debit, must include a SEC code. The code is implicit in how payment authorization is arranged (by standing, written, oral, online, etc.). A SEC code also helps determine the rules and requirements that apply to the transaction, including timing of settlement and eligibility for same-day processing.

KeyBank allows ACH origination payment types for the following SEC codes: CCD, CTX, PPD, TEL, and WEB.

SEC Codes

CCD	Corporate Credit or Debit	Deposits and withdrawals to corporate accounts. Does not require individual consumer authorization for each payment. Remittance information available with the transaction as an addendum record.
CTX	Corporate Trade Exchange	One business pays another for goods or services. An electronic payment that includes an invoice (addenda) intended for the receiving financial institution.
PPD	Prearranged Payments and Deposits	Specify a certain amount to be transferred from one financial account to another. Requires consumer authorization or prearrangement for the payment or deposit to occur. Some examples are direct deposit of payroll, pension, and dividends, or payment of utility bills, mortgages, rent, membership dues, loans and other recurring payments.
TEL	Telephone	Send a payment via the telephone. Must provide verbal consent during the phone call to initiate the payment transaction.
WEB	Online	Initiate a transaction through the web or online banking. Requires consumer authorization for the payment or deposit to occur.

Nacha business, not your problem

With ACH, transaction processing happens in real-time while the file processing for Nacha occurs behind the scenes. We follow Nacha standards and recommend there are no more than 100 transactions per request.

The Nacha file format is the standard file format used for ACH electronic fund transfers (EFT) in the United States. Nacha stands for National Automated Clearing House Association, the organization responsible for managing the rules and regulations governing the ACH network in the US. The Nacha file format is used to create batch files that contain multiple transactions, like direct deposits, bill payments, and other types of electronic payments. These files are commonly used by businesses, financial institutions, and other organizations to initiate and process ACH transactions.

Addenda records

An addendum is an ACH record type that carries supplemental data like remittance information. This data may be needed to identify an electronic payment to the receiving financial institution and the payee, or it may contain additional information relating to the prior entry detail record.

This addenda record is optional. It is primarily used for business-to-business transactions, like CCD and CTX.

Addenda record settings and limitations:

CCD, PPD, and WEB payment transactions can have one addenda record. The addenda record displays as one line, not to exceed the 88-character limit.
A CTX payment transaction can have multiple addenda records, up to 9,999 records to be exact.
KeyBank does not allow more than 20 addenda records per request.
If you need additional records, there is a different request available to add addenda records and that endpoint is limited to 100 records per request.

To manage the status of the addenda records, our system tracks it for the entire business day. The status changes from Waiting to Completed, indicating that the addenda records were successfully received, and the ACH transaction is ready to be processed.

Same-day ACH funds

Same-day ACH transactions are when the receiving depository financial institution (RDFI) posts the credit or debit to the payee account on the same day the transaction originated. Same-day ACH transactions cannot exceed a set maximum dollar amount per day. Typically, the total same-day ACH transactions cannot exceed $100,000 in a single business day.

This is an automatic setting for our clients. If you do not want the default option of same-day ACH transactions, you can choose to opt out. There is a surcharge for same-day transactions.

For the ACH Origination API, there are cutoff times for the ACH transaction to be posted the same day it originated:

Same-day Time Schedule

SAME-DAY FLOW	Window 1	Window 2	Window 3
Client cutoff	09:15 a.m. (EST)	11:15 a.m. (EST)	03:00 p.m. (EST)
File sent from KeyBank to the ACH operator	09:30 a.m. (EST)	11:30 a.m. (EST)	03:45 p.m. (EST)
ACH transaction to RDFI	12:00 p.m. (EST)	04:00 p.m. (EST)	05:30 p.m. (EST)
Posted to payee account	01:30 p.m. (local)	05:00 p.m. (local)	RDFI end of day

Did you know?

With the ACH Origination API, you can inquire on the transactions before they are officially submitted for processing. The status endpoint tells you if the transaction was accepted (transaction request data is valid), rejected (there is missing or erroneous data in the request), or extracted (transaction received by the ACH core processing system).

Common terms

ACH operator: The central clearing facility managed by the Federal Reserve Bank.
ACH processor: The ACH core processing system takes the incoming transactions from the originating financial institution, which are then sorted, batched, and verified. After the transaction is legitimized, the funds are forwarded to the receiver’s financial institution.
Collected: The status when the originating transaction is received by the ACH processor.
Credit: To push funds to other accounts.
Debit: To pull funds from an account.
ODFI: Originating Depository Financial Institution is the financial institution of the originator. This ODFI has an active relationship with ACH services and sends transactions to the ACH network on behalf of the originator.
Originator: The company or business that initiates a transaction to the receiver (payee). Before a transaction can be sent, the originator has authorized the receiver to credit or debit their account.
PAR number: Payment Assigned Reference number is a unique identifier assigned by the ACH processor used to identify the transaction without exposing any sensitive consumer identification information. When you submit a request with the ACH Origination API, it creates a PAR number and returns the value in the response.
Posted: The status when a transaction is received by the ACH processor, reviewed by the ACH operator, and currently with core banking applications to secure and transfer funds. It could also indicate that the funds have been completely settled between originator and receiver.
RDFI: Receiving Depository Financial Institution is the financial institution of the receiver. The ACH operator processes the transactions and sends the funds to the financial institution before the money is posted to the receiver's account.
Receiver: The individual or company that receives the funds. Before a transaction can be received, the receiver has authorized the originator to credit or debit their account. The receiver may also be referred to as the payee.
Returned: The status when a transaction is reviewed by the ACH operator and the transaction is not cleared for transfer for reasons like insufficient funds or erroneous data.
Reversal: Request to cancel a payment after it has posted. Reversals are not guaranteed.
Trace number: The trace number is a unique identifier for an ACH transaction generated by the ACH Origination API. Use this number for your ACH Inquiry API requests.
Undo: Stop a transaction before it is received by the ACH processor. This window is typically 10 minutes in length.

ACH Inquiry API

With the ACH Inquiry API, you can check on the progress of a payment transaction after the ACH processor receives them.

See the specs

Important identifiers that are good to know

Use the account number, PAR number, or trace number from the ACH Origination transaction request to inquire about the status or get additional details of a transaction.

Account number

Use the KeyBank originator account number associated with ACH transaction to inquire about transactions that are posted. With the ACH List inquiry, all you need is an account number to look up ACH transactions.

PAR number

The PAR (Payment Assigned Reference) number is a unique identifier assigned by the ACH processor after you submit a request with the ACH Origination API. This is used to identify the transaction without exposing any sensitive consumer identification information.

In the ACH Inquiry API request, use the PAR number (parNumber) in the ACH Detail request to inquire about an account with this unique identifier.

Trace number

When you submit a request with the ACH Origination API, the ACH processor immediately creates a trace number unique to that transaction (traceNumber). Save this trace number if you intend to check on the progress of the ACH transaction or to use it for verification.

Identifier by inquiry endpoint

In the table below we associate each endpoint in the ACH Inquiry API, including legacy endpoints, with the key identifiers you can use to request the status of an ACH transaction.

ENDPOINT		IDENTIFIER EXAMPLE
ACH List	/accounts/transactions/v1/ach/list	`accountNumber: 222333448`
ACH Detail	/accounts/transactions/v1/ach/detail/{parNumber}	`parNumber: 1234567891113`

A good reminder...

We recommend that you check on the status after 06:00 a.m. EST the following business day. By this time, the ACH processor has run the batch and consolidation processes.

ACH List

The ACH List endpoint is a comprehensive search of all ACH transactions with a single account number. Use the date parameters or identify the ACH transaction status to better define the response.

Request and response example

If you want to search with a date range, make sure to include the fromDate and toDate. You can search up to two years of past records. We recommend that you limit the date range to 31 days for a more efficient response.
If you are want to inquire about only a certain status of ACH transaction, use the dateSearchType parameter. You can filter the results by Collected, Returned, or Settled transactions.

Request

{
  "accountNumber": "3123456789",
  "dateSearchType": "COLLECTED",
  "fromDate": "2024-02-01T00:00:00.000Z",
  "toDate": "2024-02-01T00:00:00.000Z",  
  "minimumAmount": 100,
  "maximumAmount": 75020.5,
  "traceNumber": "041001030016002",
  "pageNumber": 1,
  "pageSize": 150  
}

Response

{
  "parNumber": "22018007665985",
  "transactionStatus": "COLLECTED",
  "traceNumber": "000000000000000",
  "transactionAmount": 10.01,
  "settlementDate": "2021-03-08",
  "transactionCode": "22",
  "transactionCodeDescription": "Automated Deposit",
  "transactionDescription": "DEPOSIT",
  "authorizedCustomerName": "TEST CUSTOMER1",
  "standardEntryClassCode": "CCD",
  "standardEntryClassDescription": "Cash Concentration or Disbursement",
  "receivingAccount": {
    "accountNumber": "123456789012",
    "bankNumber": "0000",
    "routingNumber": "1234567890"
    },
  "receivingParty": {
    "customerIdentificationNumber": "099999999",
    "companyName": "MERCHANT",
    "customerName": "TEST MERCHANT"
  },
  "originatingAccount": {
     "accountNumber": "123456789012",
    "bankNumber": "0000",
    "routingNumber": "1234567890"
   },
  "originatingParty": {
    "customerIdentificationNumber": "1234567",
    "companyName": "COMPANY NAME 1",
    "customerName": "CUSTOMER NAME 1"
  },
  "returnDate": "2024-02-01",
  "returnReasonCode": "R02",
  "returnReasonDescription": "Account Closed",
  "addendaCount": 1,
  "notificationOfChangeAddendaCount": 1,
  "internationalAddendaCount": 0,
  "customData": "merchant:status",
  "checkSerialNumber": "4345",
  "transactionDirection": "Receiving Item",
  "addenda": [{
    "sequenceNumber": 1,
    "entryDetailSequenceNumber": "188",
    "paymentRelatedInformation": "Addenda Record (Applies to CCD, CTX, PPD, and WEB entries)"
    }
  ],
  "notificationOfChange": [{  
  "changeCode": "C02",
  "changeDescription": "Incorrect transit/routing number",
  "correctedData": "1234567890"
   }
 ]
}

What to expect

In the transactions response, you can expect to see the status, general transaction information, identification for the originating and receiving parties involved, return reason if applicable, and addenda counts.
A metadata object is part of the response that gives details about the inquiry results and size of response.

ACH Detail

The ACH Detail endpoint retrieves details about an ACH transaction with a single PAR number.

Details returned include transaction IDs, originating parties, receiving parties, return reasons, transaction status, and Nacha SEC data.

Request and response example

Use the parNumber from the originating transaction to get additional details about the transaction.

Request

curl --location: '{host}/v1/ach/detail/22018007665985'
--header 'Accept: application/json'
--header 'Authorization: Bearer testZcKJDWnwDWmmf9qah6PJvPy8'

Response

{
  "parNumber": "22018007665985",
  "transactionStatus": "COLLECTED",
  "traceNumber": "000000000000000",
  "transactionAmount": 10.01,
  "settlementDate": "2021-03-08",
  "transactionCode": "22",
  "transactionCodeDescription": "Automated Deposit",
  "transactionDescription": "DEPOSIT",
  "authorizedCustomerName": "TEST CUSTOMER1",
  "standardEntryClassCode": "CCD",
  "standardEntryClassDescription": "Cash Concentration or Disbursement",
  "receivingAccount": {
    "accountNumber": "123456789012",
    "bankNumber": "0000",
    "routingNumber": "1234567890"
    },
  "receivingParty": {
    "customerIdentificationNumber": "099999999",
    "companyName": "MERCHANT",
    "customerName": "TEST MERCHANT"
  },
  "originatingAccount": {
    "accountNumber": "123456789012",
    "bankNumber": "0000",
    "routingNumber": "1234567890"
    },
  "originatingParty": {
    "customerIdentificationNumber": "1234567",
    "companyName": "COMPANY NAME 1",
    "customerName": "CUSTOMER NAME 1"
   },
  "returnDate": "2024-02-01",
  "returnReasonCode": "R02",
  "returnReasonDescription": "Account Closed",
  "addendaCount": 1,
  "notificationOfChangeAddendaCount": 1,
  "internationalAddendaCount": 0,
  "customData": "merchant:status",
  "checkSerialNumber": "4345",
  "transactionDirection": "Receiving Item",
  "addenda": [{
    "sequenceNumber": 1,
    "entryDetailSequenceNumber": "188",
    "paymentRelatedInformation": "Addenda Record (Applies to CCD, CTX, PPD, and WEB entries)"
    }                                                        ],
  "notificationOfChange": [{
    "changeCode": "C02",
    "changeDescription": "Incorrect transit\/routing number",
    "correctedData": "1234567890"
    }
  ]
 }

What to expect

You receive a detailed response for the transaction associated with the provided PAR number. Details include information about the parties involved. the identification and account associated with the PAR number, and additional transaction information in addenda records.

Moonwalk back those transactions

We all make mistakes. Sometimes we need to pull things back before we can move forward. KeyBank understands and our API Origination API has a few ways to do that.

Undo a payment

You can undo a payment before it is collected by the ACH processor. Use the undo endpoint to stop the transaction before it is received by the ACH processor. The time window to undo is dependent upon the collection windows. The typical window to undo a payment is about 10 minutes but it can be more depending on when the payment is submitted and the collection schedule.

Reverse a payment

If the payment was collected and you still need to delete the payment, you can reverse the transaction within five banking days from the original effective date. When you reverse the transaction, it generates a reversal to the receiver’s account to pull back payments that were originated erroneously. While reversals are not a guaranteed success, it is an option to undo the original payment submitted after collection.

To reverse a payment, you have one of two options. You cannot do both of these options if one does not work.

Option 1: Submit the file maintenance form for a payment reversal.

Option 2: Use ACH Direct to reverse a payment. You can search for the transaction by batch or account. Reversals are available within 5 banking days of the effective date for the current transactions. After you submit this request, the status for the transaction will be pending until it is fully processed as reversed.

Option 3: Complete an ACH Originate API request with the opposite credit or debit indicator in the creditDebitCode field of the request body. Update the companyEntryDescription in the request body to reflect REVERSAL.

Returned transactions

A payment can be returned for various reasons like insufficient funds, unable to verify accounts, incorrect data in the request, or a security concern.

KeyBank recommends that you inquire about returns daily with the ACH Inquiry API. Here’s how:

To inquire about one or more transactions, use the account number and date fields to look up information.
To look up a specific returned transaction, use the PAR number. The PAR number is generated by the API and provided in the response. It is a unique identifier that matches the returned transaction to the original transaction.

Unauthorized returns

Unauthorized returns apply mainly to disputed transactions where the person or company being charged does not consent to the funds transfer. There are different return time frames by SEC code so consider the exposure to unauthorized returns when you originate a payment with a certain SEC code.

Unauthorized Return Windows

	Consumer transactions	Commercial transactions
SEC code	PPD, TEL, WEB	CCD, CTX
Unauthorized returns window	up to 60 calendar days	24 hours (two banking days)

Gets the facts with FAQs

Does ACH stand for Actual Common Help? It sure doesn’t, but we can answer some questions for you!

Where is my transaction? How can I get more information?

You submitted a request with the ACH Origination API to send or get money. Get the traceNumber or parNumber from the ACH Origination API response and use that identifier with the ACH Inquiry API request to track the status of the ACH transaction (or batch of transactions).

See our information on the ACH Inquiry API to learn more.

I got an error. What went wrong?

Everything went wrong. And you forgot to send that birthday card too!

OK, it’s not that serious. We can’t fix the birthday card situation, but we can help with that API error.

Check out more information in the Errors section of the API documentation for the ACH Origination API or the ACH Inquiry API.

What’s the difference between undo, reversal, and returned?

When you undo a transaction, you stop the ACH processor from receiving the request before the collection window.

For example, let’s say there is a 10-minute window to undo a payment before it is received by the ACH processor. You submit a transaction with the API at 08:15 a.m. EST. You have until 08:25 a.m. EST to undo this transaction before the ACH processor begins to process the transaction.

When you reverse a transaction, you missed the window to undo a request and now need to either submit the file maintenance form for a payment reversal, use ACH Direct, or attempt to reverse it with another transaction.

When a transaction is returned, it means that something was not right when going through core banking applications for review and settlement. The transaction is returned to the originator without ever being posted.

CCD and PPD seem similar. What is the difference?

PPD transactions are typically from a corporate account to an individual account. Like if you are sending payroll to your employees, you are sending money from a corporate account to a personal account of the employee.

CCD transactions are usually from one commercial or business account to another. It could also be an individual account sending money to a vendor account. One example could be a renter (individual account) sending their rent check to the property management office (business account).

Is there a way to input a value in the request that I recall when using the ACH Inquiry API?

There are two fields available to attached additional information to a transaction.

The entry description (companyEntryDescripiton) describes the purpose of the payment as defined by you. This is required for reporting and helps identify any differences between the transactions. This information is visible to the originator and the receiver.
Use the custom data (customData) field to append specific information to a payment transaction. This information is only visible to the originator and can be recalled by the originator after a payment is collected.
The custom data does not transmit with the payment as it is processed. The custom data is safely stored in KeyBank’s database. The traceNumber links the incoming collected or posted payment to the custom data, recalled from the request input.

What is the timing with payments?

ACH transactions are collected/distributed several times throughout the day. KeyBank’s final cutoff time for clients to send us an ACH file is 10:30 p.m. EST. The schedule is as follows:

ACH collection/distribution schedule

Collection only, 05:00 a.m. EST
Collection and distribution, 06:00 a.m. EST
Collection and distribution, 09:30 a.m. EST
Collection and distribution, 11:30 a.m. EST
Collection and distribution, 01:30 p.m. EST
Collection and distribution, 03:30 p.m. EST
Collection and distribution, 07:00 p.m. EST
Collection and distribution, 09:30 p.m. EST
Collection and distribution, 10:30 p.m. EST

Can I do same-day payment?

For an additional fee, you can make same-day payments until approximately 03:00 p.m. EST. Funds are withdrawn the date the payment is processed and delivered by the following business day. The account’s available balance is updated when the payment is processed. The account ledger is updated the day after the payment is sent.

What about future date payments?

You can future date a transaction. The payment transaction is processed as normal and collected, but the payment does not post to the bank until the date specified.

Use effectiveDate in the request to specify when a collected transaction is posted. The effective date can be up to 30 days in the future. Typically, the funds will be distributed to the receiver 1-2 days prior to the effective date that was provided during origination. When setting the effective date, consider the schedule for collection windows and supporting processes.

Is there a limit to how many transactions I can send in a single request?

The ACH Origination API request is limited to 100 transactions per request for each of KeyBank’s clients. For each of the requests submitted, the clients will receive a message acknowledging either a successful transaction or a transaction error.

Is there a limit to how much money I can send in a same-day transaction?

Total same-day ACH payments cannot exceed $100,000 in a single business day.

Are there client requirements I should know about?

There are some required fields to initiate an ACH transaction. After you complete the KeyBank onboarding process, we will assign you values for point and collection application ID parameters that map to a legitimate bank account.

Point (point) is a short name specific to your company that’s assigned by KeyBank. The point name is nine characters long, but KeyBank limits the assigned name to eight characters. One character is used to match the input data of the request associated with this point value to the shared services payment system before batch processing. The point value is included in the file name and improves security for file transfers.
Collection application ID (collectionApplicationId) is a sub-level to the point value assigned by KeyBank. Every point requires at least one collection application identifier. The ID must not exceed 9 characters. If you have different settlement accounts, you'll need multiple collection application IDs, each connected to a specific settlement account.

There is another important parameter that is not required, but strongly encouraged. The universal unique identifier (uuid) is a custom value used to identify each transaction created by you. The UUID is required to undo a payment. The ID must not exceed 45 alphanumeric characters. The UUID is only part of the ACH Originate API and is not used to trace a transaction across its lifecycle, meaning it cannot be used as a lookup field in the ACH Inquiry API. The UUID is at the transaction level and provides the status of a specific transaction as Accepted, Waiting for Addenda, Consolidated, or Failed.

How do I send a prenote versus a live transaction?

A prenote (or as my grandfather calls it formerly - the prenotification entry) is a non-monetary entry submitted by an originator to a RDFI before sending a credit or debit entry to the receiver’s account with the RDFI.

A live transaction is a monetary entry submitted by an originator to a RDFI to send a credit or debit to the receiver’s account with the RDFI.

Word soup, right? Basically, a prenote is a notification the tells the RDFI to verify the account information. A live transaction is an actual payment.

In the request, define if the transaction is a prenote (P) or a live (L) transaction with the transactionType field.

What's next

Look at our API reference and specs to get the details about how our API is structured and any API requirements.
If you want to use our APIs, you need to be an authenticated and authorized user with our developer portal. Check out our Getting Started Guide.

Custom data

3-minute read Rel. 4.0.0 | updated Apr. 24, 2024

Add data or tags specific to your application or use case

If you send or validate a payment with the ACH Origination API or the Wire Transfer API, you can add information to the customData in the request payload.

Custom data is client-specific metadata that you can:

Use to append certain information or details
Use as an identifier to filter certain types of transactions

The customData information is not transmitted with the payment or stored in any KeyBank database. This information is only visible to you, the originator, with the ACH Inquiry API or the Wire Inquiry API. In the inquiry response, the customData field returns any custom values that were part of the payment request stored for recall after a successful ACH or wire transaction completes. This information is not visible to the recipient or any of the participating parties.

Here's how it works

Define the customData in the request payload. It is a free-form text field that can contain up to 500 alphanumeric characters that you can use however you like - for invoice number, product number, customer number, date/time stamp, etc.
Custom data examples
KeyBank recommends the common custom data format of name-value pairs. You can list multiple name-value pairs in the custom data field within the 500-character limit. The custom data fields will return exactly what is sent; it does not parse name-value pairs within the API response. The custom data should not contain any personal identifiable information (PII).
Example of name:value pairs
```
"customData": "Type:DD; Status:Submitted; POnumber:12556"
```
Example of regular text
```
"customData": "General products"
```
Example of timestamp
```
"customData": "05-MAR-2023:12:19:53EST"
```
As the originator, you can use the ACH Inquiry API or Wire Inquiry API to retrieve the custom data information.
Review the response for the customData field.
- If there is custom data, it returns any custom values that were part of the payment request stored for recall after a successful ACH or wire transaction completes.
- If no custom data is defined, the response returns an empty field.

Available for these APIs

Error handling

5-minute read Rel. 4.0.0 | updated Mar. 13, 2024

Is it you? Is it me? Is it us? Let's figure it out.

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.

HTTP status codes

Each error response returns the standard HTTP code number with the exception schema. KeyBank utilized the standard HTTP messaging so nothing too fancy.

Code	Status	Description
200	OK; Successful	The action was successful. No additional actions are needed.
400	Missing mandatory information	Request is missing required information.
401	Unauthorized request	Invalid credentials for the request.
403	Forbidden request access	You do not have permission to complete the request.
404	Resource not found	The resource for the request cannot be found.
405	Invalid request method	The wrong request method was used.
415	Invalid request type	The wrong media type submitted with the request.
429	Request timeout	There are too many requests to the API and a timeout goes into effect.
500	Unknown error	There was an unknown error with the server.
502	Bad gateway	The servers cannot talk to each other or there is a miscommunication.
503	Unavailable service	The service is temporarily down.
504	Unable to process request	Request needs more time to be processed.

Standard error message format

The exception schema includes the error message, your unique X-CorrelationId, and additional information like TransactionId and TransactionTime. The transaction ID and timestamp are helpful in diagnosing the issue. The X-CorrelationId is helpful for transaction traceability and may help determine where did the error occurred.

The exception schema may also contain the ServiceError field for API-specific errors or problems with backend services. This object can contain a few different values, depending on the API or circumstance:

connectError - error information of the connectivity with downstream service.
detailMessage - an error code with a detailed message.
serviceErrorData - API-specific error details about the failed transaction.
variable field based on API - custom messages about API-related functional business messages or faults.

Standard error format

{
  "ErrorMessage": string,
  "X-CorrelationId": string,
  "TransactionId": string,
  "TransactionTime": string,
  "ServiceError": object
}

Response header status messages

Some APIs contain status messages in the responseHeader object of the response payload. Review the status field to see if the transaction was successful (S), was successful but has a warning (W), or failed (F). Additional information is shared in the statusDescription field.

S: A successful response. (HTTP 200)
W: The transaction was not not processed as expected. A warning message means the request was successfully received, but there was a minor issue that requires your attention. (HTTP 299)
F: The transaction was not processed. (HTTP 400s/500s)

API-specific status messages are explained in depth on the API doc pages where applicable.

Status message example

{
  "responseHeader": {
     "status": "S",
     "statusDescription": "Successfully returned results for the requested range 1 to 1",
     "retrivedRows": "1",
     "totalRows": "1",
     "dataLoadDate": "2022-07-13"
     },
}

KeyVAM

clock 1-minute read calender Rel. 4.0.0 | updated May. 29, 2024

Make managing multiple accounts as easy as managing just one

Key takeaways

There are many benefits to virtual account management at KeyBank. With KeyVAM, you can:

Send and receive ACH, RTP, and Wire transactions on behalf of the parent account.
Instant opening and closed of sub-accounts for an individual or business.
View transaction and reconciliation data for each virtual sub-account while the total funds settle in one parent account with advance reporting.

Virtually amazing

Check it out yourself. There is a lot of great information on the Key Virtual Account Management site.

If you are ready to get started or have any questions, reach out to a Payments Advisor.

What is VAM?

Key Virtual Account Management (KeyVAM) is an embedded service of the KeyNavigator platform. KeyVAM enhances how you manage money by linking a set of a set of virtual accounts (sub-accounts) to a single, physical account (parent). You can create and manage virtual sub-accounts in real-time. This is a great option if you need to open and close high-value virtual sub-accounts common in industries like technology, property management, or corporate cost centers.

KeyVAM APIs

Integrate your application with APIs. KeyVAM APIs are available to further develop your virtual account management experience with task automation for common activities like creating accounts, transferring funds, or reports. View the Key Virtual Account Management API Documentation to see what is possible.

Subscribe to