ACH Connect Overview

ACH Connect is a RESTful API which allows ACH transactions to be submitted and received, without the complexity of a full NACHA file.

Note that while the ACH Connect API should be suitable for most transactions, if a greater level of control is required, a NACHA file should be used. The API is designed to be easy and effective for the majority of transactions, however there are limitations compared to the full NACHA spec.

ACH Connect Features

  • Support for CCD, PPD, IAT, and WEB standard entry class codes.
  • Streamlined API hides the complexity of the NACHA spec into a unified set of RESTful API calls.
  • Support for returns and notifications of change.
  • Receive inbound payments from other financial institutions.
  • Maintains a complete history of events for each transaction for at least 7 years.

ACH Connect Workflow

The general workflow for ACH Connect is to submit new transactions using the originate transaction endpoint. Those transactions are batched according to client specific settings, and when a certain threshold is met, a NACHA file is generated and released containing those batched transactions. Once a transaction is released it is considered complete. You will receive no further confirmations regarding the transaction. However, a transaction can be returned at a later point for a number of reasons.

Transactions and events can also come from the Federal Reserve or another financial institution. To receive these notifications, it is recommended that the events endpoint be polled periodically throughout the day. Generally new events will come in several times throughout the day, so checking every few hours is usually acceptable. It is not recommended to poll for events on a continual basis.

If a new event is received, no action is required unless a return or correction is needed. Otherwise the event information can be used at the client’s discretion to ultimately process the transaction outside of the context of ACH Connect.

ACH Connect API Endpoints

ACH Connect exposes the following API endpoints via HTTPS:

  • Authorization
  • Transactions
    • Get Events
    • Get Transaction
    • Originate Transaction
    • Correct Transaction
    • Return Transaction
    • Recall Event

With these endpoints, you can view transaction history, submit new transactions, or return transactions previously received from another financial institution.

Authorization

ACH Connect uses the client credentials type of authorization grant, as defined in the OAuth 2.0 specification. To communicate with the API, you must first obtain an OAuth access token.

OAuth Endpoint


POST {auth server url}/connect/token

The client credentials you post must be Base64 encoded. For example, if the user credentials were username and password, they would be encoded from username:password to jXNlcm5hbWU6cGFzc3dvcmQ=.

Place the encoded string in the header, as in the following example:


Content-Type: application/x-www-form-urlencoded
Authorization: Basic jXNlcm5hbWU6cGFzc3dvcmQ=

Then include the following in the body:


grant_type=client_credentials&scope=crbapi

Upon success, expect the following response:


{
"access_token": "8t9dxjkd3...", "expires_in": 3600, "token_type": "Bearer"
}

Finally, include the authorization token in the header of all subsequent calls to the ACH Connect API:


"Authorization:Bearer 8t9dxjkd3..."

Get Events

ACH Connect uses the concept of transaction events to track the history of a given transaction. For example, when a new transaction is submitted, an origination event is automatically created for that transaction. If the transaction were to be returned by the receiving institution, a return event would be added to the transaction object.

The events endpoint will return an array of events that occurred on a given date. Filters for the event type, status, and direction of the transaction are also available.

Events Endpoint


GET {base_URL}/api/transaction/event?date=9/1/2015&eventType=Originati on&status=Released&direction=ToFed

Event Filters

Date Timestamp of Events
eventType Origination – new transaction

Return – returned by the receiving institution

Correction – receiving institution sent a notification of change
Status Pending – awaiting release to the Federal Reserve
Released – released to the Federal Reserve for processing or released to the ACH client depending on the direction of the transaction
Transmitted – transmitted to the Federal Reserve for processing. Applies to direction “ToFed” only
Rejected – Operations team was unable to process this transaction for compliance reasons
Recalled – transaction was recalled at client’s request
Direction ToFed – to be sent to the Federal Reserve
FromFed – received from the Federal Reserve

Get Transaction

Retrieves a full transaction record, containing all origination details and complete event history.

Transaction Endpoint


GET {base_URL}/api/transaction/{:transactionID}

Originate Transaction

Submits a new transaction destined to the Federal Reserve and ultimately another financial institution. Any standard entry class code can be originated from this endpoint. Certain codes require additional information. In those cases, a sub-detail json object is added to the request specific to the given code. For example, IAT transactions will require an “IATDetails” object to be included with the request.

Originate Transaction Endpoint


POST {base_URL}/api/transaction

A Transaction Proposal object should be submitted in the body of the request.


{
StandardEntryClassCode: "CCD",
TransactionType: "push",
FromRouting: "021214862",
FromName: "Business Inc.",
FromIdentification: "934534",
ToRouting: "099999999",
ToAccount: "999999999",
ToAccountType: "checking",
ToName: "Corporation Inc.",
Description: "Loan Payment",
Amount: 5000.25,
SameDay: false
}

The following is a description of fields in the transaction proposal object.

Field Type Description
TransactionID String (optional) GUID to uniquely identify this transaction. If omitted, one will be generated automatically
StandardEntryClassCode String Classification of transaction. Expected values: CCD, PPD, IAT, or WEB
TransactionType String Type of transaction being actioned against the receiving institution. Expected values: pull (debits) or push (credits)
FromRouting String Routing number transaction is being originated from. Usually set to Cross River Bank’s routing number
FromName String Name of the business or individual originating this transaction
FromIdentification String Identifier for business or individual originating this transaction. For example, an invoice number or payment ID
ToRouting String Routing number of financial institution receiving this transaction
ToAccount String Account number of business or individual at the receiving institution
ToAccountType String Type of account at receiving institution. Expected values: checking, savings, or GL
ToName String Name of the business or individual at the receiving institution
ToIdentification String Identifier for business or individual receiving this transaction
Description String Brief description of the transaction, that may appear on the receiving entity’s bank statement
Amount Decimal Dollar amount of the transaction
SameDay Bool When set to true this indicates the transaction should be processed same day if possible. Note that the API account must be opted in to use this feature and additional fees will apply. Starting September 23rd 2016 this applies to PUSH transactions only. PULL transactions will be supported starting in 2017. Same Day processing is not available to IAT’s and dollar amounts over $25,000.
IATDetails Object (optional) Additional information required to complete an IAT transaction
WebDetails Object (optional) Additional information required to complete a WEB transaction

Sample IATDetails object:


IATDetails:
{
FromAddress: "123 Maple Street", FromCity: "Anytown",
FromState: "NY",
FromPostalCode: "07302", FromCountryCode: "US", FromBankName: "Cross River Bank", FromIdentificationQualifier: "01", FromBankCountryCode: "US", ToAddress: "456 Main Street",
ToCity: "New York",
ToState: "NY",
ToPostalCode: "11201",
ToCountryCode: "US",
ToBankName: "Chase Bank",
ToIdentificationQualifier: "01",
ToBankCountryCode: "US",
UltimateReceiverName: "John Brit",
UltimateReceiverAddress: "12 Queens Way",
UltimateReceiverCity: "London",
UltimateReceiverState: "Essex",
UltimateReceiverPostalCode: "GX1234",
UltimateReceiverCountryCode: "GB",
FCBName: "Some Foreign Bank",
FCBIdentification: "XYZ234",
FCBIdentificationQualifier: "02",
FCBCountryCode: "GB"
}

Sample WEBDetails object:


WEBDetails:
{
PaymentType: single
}

Correct Transaction

If a new transaction is received from another financial institution, you may wish to correct certain data associated with that transaction. An example, would be if they sent the wrong account number, and even though you were able to locate the account through other means, you still wish to notify them of the error. This is possible using the Correct Transaction endpoint.

Correct Transaction Endpoint


POST {base_URL}/api/transaction/{:transactionID}/corrections

Sample correct transaction request:


{
ReplyToEventId: "E9FBDEF4-7A2D-4637-AAE4-7F7094520CAA", ChangeCode: "C01",
CorrectedData: “123456789”
}

The following is a description of the fields in the Correction object:

Field Type Description
ReplyToEventId String ID of the transaction event the correction is associated with. Usually this will be the origination event from the Federal Reserve
ChangeCode String NACHA change code associated with the correction. For a full listing of codes, see the official NACHA documentation
CorrectedData String Context specific data relating to the correction. For example, if the change code indicated an incorrect account number, then the corrected data would be an account number

Return Transaction

If a new transaction is received from another financial institution, you may wish to return it for a variety of reasons. An example, would be if the account referenced could not be located by any means. This is possible using the Return Transaction endpoint.

Return Transaction Endpoint


POST {base_URL}/api/transaction/{:transactionID}/returns

Sample return transaction request:


{
ReplyToEventId: "E9FBDEF4-7A2D-4637-AAE4-7F7094520CAA", ReturnCode: "R01"
}
Field Type Description
ReplyToEventId String ID of the transaction event the return is associated with. Usually this will be the origination event from the Federal Reserve
ReturnCode String NACHA return code associated with the return. For a full listing of codes, see the official NACHA documentation

Recall Event

It is possible to recall (i.e. delete) an origination, return, or notification event before it has been released. Use the following endpoint to recall any pending event. Note that the request must be sent using the DELETE verb.

Recall Event Endpoint


DELETE {base_URL}/api/transaction/{:transactionID}/events/{:eventID}

Field Type Description
TransactionID String ID of transaction being recalled
EventID String ID of event being recalled