ACH APIs

The Cross River ACH API allows you to both originate and receive payments through the Federal Reserve ACH network.

ACH APIs are found in the ACH module of our COS sandbox.

Note

Get started with Cross River APIs.

This table presents ACH APIs we that describe in detail.

Action	API Call	Description
Originate an ACH payment	`POST /ach/v1/payments`	Sends a single payment using ACH
Originate ACH client batches	`POST /ach/v1/client-batches`	Originates several payments together in a batch
Cancel ACH client batches	`GET /ach/v1/client-batches/{id}/cancel`	Cancels any incomplete payments and stops further processing of any remaining payments in the batch

Originate an ACH payment

/ach/v1/payments

Originates an ACH payment.

Note

Use an ACH prenotification (prenote) to verify and validate account details. A prenote simply means originating a payment of $0.00. If you don't receive an error response, the details are correct.

Request attributes

accountNumber

string

Required

Account number for payment originator

originator

object

Conditional

Details about the entity sending the payment. If the account originating the payment is enabled to provide this information according to the supplied account number, all the values should be null. If these values are supplied in the request they override the originator profile defined for the account.

child attributes

name

string

Conditional

Name of the originator of the transaction. Nacha refers to this as Company Name . 35 character maximum unless the secCode is IAT. In that case the maximum is only 16 characters.

identification

string

Required

Originator Identification. Nacha refers to this as the Company Identification . 10 character maximum.

data

string

Optional

Originator Data. Nacha refers to this as Company Discretionary Data. 20 character maximum.

receiver

object

Required

In the case of Pull payments, this is the account the funds are being pulled from.

child attributes

routingNumber

string

Required

Federal routing number for the receiver bank

accountNumber

string

Required

Account number for the receiver. Must be 7 digits. For account numbers with 5 or 6 digits, add 0s to the beginning of the account number.

accountType

string

Required

Deposit account type: Checking, Savings, GeneralLedger, Loan

name

string

Required

Receiver name. Maximum 22 characters.

identification

string

Optional

Receiver Identification. Nacha refers to this as the Individual Identification Number. 22 character maximum.

secCode

string

Required

Standard Entry Class (SEC) codes required by Nacha for every ACH transaction. See values here.

description

string

Required

Description of the payment. Maximum 10 characters.

transactionType

string

Required

Sending or requesting funds:

Push (originator is sending funds—debit)
Pull (originator is receiving funds—credit)

amount

integer

Required

Dollar amount of payment in positive integral cents. For example, write $1.00 as 100.

serviceType

string

Required

When the payment completes:

Standard (Payment effective the following business day. International payments must use this service type.)
SameDay (Payment effective same day, subject to certain constraints. See ACH overview.)

extendedDetails

object

Conditional

ACH-specific details.

If the transactionType is pull and secCode is WEB you must include a paymentType value in this object.

If the secCode is POS you must include a cardTransactionType value.

Learn more on the Nacha site.

child attributes

authCode

string

cardAccountNumber

string

cardExpDate

"string

cardTransactionType

string

Conditional

Card transaction types are represented by specific codes that explain what kind of transaction took place at the point of sale

checkSerialNumber

string

docReferenceNumber

string

itemType

string

networkIdentification

string

paymentType

string

Conditional

Payment types are a single character, and are based on the authorization of the account holder to debit their account:

S for single
R for recurring

processControl

string

reference1

string

reference2

string

researchNumber

string

terminalIdentification

string

terminalLocation

string"

terminalCity

string

terminalState

string

transactionDate

string

transactionDesc

string

transactionSerial

string

transactionTime

string

iatDetails

object

Conditional

Required if the secCode is IAT. See here for more information about IAT.

Do not enter values for these attributes for any other secCode.

child attributes

originator

object

Conditional

Payment sender details

child attributes

address

string

Required

Street or post office box address. 35 characters maximum.

city

string

Required

City full name. 33 characters maximum.

state

string

Optional

State name. 33 characters maximum.

postalCode

string

Optional

Postal code. Regular expression. 32 characters maximum.

countryCode

string

Required

2-letter ISO country code

receiver

object

Required

Payment receiver details

child attributes

address

string

Required

Street or post office box address. 35 characters maximum.

city

string

Required

City full name. 33 characters maximum.

state

string

Optional

State name. 33 characters maximum.

postalCode

string

Optional

Postal code. Regular expression. 32 characters maximum.

countryCode

string

Required

2-letter ISO country code

originatingBank

object

Optional

Details of financial institution originating the IAT

child attributes

name

string

Required

Name of financial institution. 35 characters maximum.

identification

string

Required

DFI Identification number, which is the first 8 digits of that financial institution's routing number

idQualifier

string

Required

Originating DFI Identification Number Qualifier:

01 (National Clearing System Number. For example, US Routing transit number)
02 BIC Code
03 IBAN

countryCode

string

Required

2-letter ISO country code

receivingBank

object

Required

Details of financial institution receiving the IAT

child attributes

name

string

Required

Name of financial institution. 35 characters maximum.

identification

string

Required

DFI Identification number, which is the first 8 digits of that financial institution's routing number

idQualifier

string

Required

Originating DFI Identification Number Qualifier:

01 (National Clearing System Number. For example, US Routing transit number)
02 BIC Code
03 IBAN

countryCode

string

Required

2-letter ISO country code

remittanceInfo1

string

Optional

Additional IAT information. 80 characters.

A second field is available as remittanceInfo2.

correspondentBank1

object

Optional

Details of a correspondent (intermediary) bank, if there is one.

You can have up to 5 correspondent banks: (correspondentBank1, correspondentBank2, correspondentBank3, correspondentBank4, correspondentBank5 , each with the same child attributes.

child attributes

name

string

Required

Name of financial institution. 35 characters maximum.

identification

string

Required

DFI Identification number, which is the first 8 digits of that financial institution's routing number

idQualifier

string

Required

Originating DFI Identification Number Qualifier:

01 (National Clearing System Number. For example, US Routing transit number)
02 BIC Code
03 IBAN

countryCode

string

Required

2-letter ISO country code

transactionTypeCode

string

Required

Part of the addenda record. An additional way to explain the purpose of the IAT. See values here.

originatingCurrency

string

Optional

An ISO three-character code to identify the originating currency

destinationCurrency

string

Optional

An ISO three-character code to identify the receiving currency

addenda

string

Optional

Additional transaction-related information

purpose

string

Optional

Reason for the ACH transfer. For internal use only. The data is not included with the outgoing ACH batch file.

clientIdentifier

string

Optional

Use this attribute to add your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes.

Response attributes

string

Payment ID. This ID first appears as the value for this attribute in the response to the originate a payment call. This ID is in the GUID format.

accountNumber

string

Originator account number. In CR, depending on the account type, the number of digits will vary. The first digit indicates the kind of account.

referenceId

string

Unique CR reference ID for the payment. The reference ID always begins with the first letter of the rail. For ACH the reference ID starts with 'A'.

paymentType

string

Type of payment being sent. See values here.

direction

string

The payment direction, which includes:

Inbound: payment received by a CR account from another bank
Outbound: a payment sent from a CR account to another bank

status

string

The status of the payment

source

string

Source of the activity: Api, PartnerPortal, OpsPortal, File

postingType

string

Individual or Aggregate

clientBatchId

string

Unique identifier for a batch (GUID) if you originate the client batch

clientBatchSequence

integer

Sequence number of the payment in the batch, if you originate the client batch

fedBatchId

string

Unique ID for the batch sent to or received from the Fed

fedBatchSequence

integer

Sequence of the payment inside of the batch sent to or received from the Fed

coreTransactionId

string

Internal CR unique ID for the transaction

memoPostId

string

For outbound push payments, ID of the original authorization on the account for the amount of the payment request

postingCode

string

The related CR system transaction status. When you originate a payment, the system initially returns OK. If the payment fails or is declined, the value changes to a CR system-generated code.

posting

string

Posting status: Pending, Posted, Failed, Canceled, Authorized, Processing

rejectionReason

string

OfacUnableToDetermine, OfacConfirmed, OfacUnconfirmed, Other

blockedReason

string

Ofac, Other

originator

object

Originator bank details

child attributes

routingNumber

string

Financial institution federal routing number

accountNumber

string

Account number for payment originator

accountType

string

Deposit account type:

Checking
Savings
GeneralLedger
Loan

name

string

Name of the originator of the transaction. Nacha refers to this as Company Name . 35 character maximum unless the secCode is IAT. In that case the maximum is only 16 characters.

identification

string

Originator Identification. Nacha refers to this as the Company Identification . 10 character maximum.

data

string

Originator Data. Nacha refers to this as Company Discretionary Data. 20 character maximum.

receiver

object

Receiver bank details

child attributes

routingNumber

string

Financial institution federal routing number

accountNumber

string

Account number for the receiver

accountType

string

Deposit account type:

Checking
Savings
GeneralLedger
Loan

name

string

Receiver name as it appears on the receiver account. Nacha refers to this as the Individual Name.

identification

string

Receiver Identification. Nacha refers to this as the Individual Identification Number. 22 character maximum.

data

string

Receiver data. Nacha refers to this as Discretionary Data.

secCode

string

Standard Entry Class (SEC) codes required by Nacha for every ACH transaction. See values here.

description

string

Description of the payment. 10 character limit.

transactionType

string

Sending or requesting funds:

Push (originator is sending funds—debit)
Pull (originator is receiving funds—credit)

amount

integer

Dollar amount of payment in positive integral cents. For example, write $1.00 as 100.

serviceType

string

When the payment completes:

Standard (Payment effective the following business day. International payments must use this service type.)
SameDay (Payment effective same day, subject to certain constraints. See ACH overview.)

extendedDetails

object

ACH-specific fields. Learn more on the Nacha site.

child attributes

authCode

string

cardAccountNumber

string

cardExpDate

"string

cardTransactionType

string

Card transaction types are represented by specific codes that explain what kind of transaction took place at the point of sale

checkSerialNumber

string

docReferenceNumber

string

itemType

string

networkIdentification

string

paymentType

string

Payment types are a single character, and are based on the authorization of the account holder to debit their account:

S for single
R for recurring

processControl

string

reference1

string

reference2

string

researchNumber

string

terminalIdentification

string

terminalLocation

string"

terminalCity

string

terminalState

string

transactionDate

string

transactionDesc

string

transactionSerial

string

transactionTime

string

iatDetails

object

Required if the SEC code is IAT. See here for more information about IAT.

Do not enter values for these attributes for any other SEC code.

child attributes

originator

object

Payment sender details

child attributes

address

string

Street or post office box address. 35 characters maximum.

city

string

City full name. 33 characters maximum.

state

string

State name. 33 characters maximum.

postalCode

string

Postal code. Regular expression. 30 characters maximum.

countryCode

string

2-letter ISO country code

receiver

object

Payment receiver details

child attributes

address

string

Street or post office box address. 35 characters maximum.

city

string

City full name. 33 characters maximum.

state

string

State name. 33 characters maximum.

postalCode

string

Postal code. Regular expression. 30 characters maximum.

countryCode

string

2-letter ISO country code

originatingBank

object

Details of financial institution originating the IAT

child attributes

name

string

Name of financial institution. 35 characters maximum.

identification

string

DFI Identification number, which is the first 8 digits of its routing number.

idQualifier

string

Originating DFI Identification Number Qualifier:

01 National Clearing System Number
02 BIC Coder
03 IBAN

countryCode

string

2-letter ISO country code

receivingBank

object

Required

Details of financial institution receiving the IAT

child attributes

name

string

Name of financial institution. 35 characters maximum.

identification

string

DFI Identification number, which is the first 8 digits of its routing number.

idQualifier

string

Originating DFI Identification Number Qualifier:

01 National Clearing System Number
02 BIC Coder
03 IBAN

countryCode

string

2-letter ISO country code

remittanceInfo1

string

Optional

Additional IAT information. 80 characters.

A second field is available as remittanceInfo2.

correspondentBank1

object

Details of a correspondent (intermediary) bank, if there is one.

You can have up to 5 correspondent banks: (correspondentBank1, correspondentBank2, correspondentBank3, correspondentBank4, correspondentBank5, each with the same child attributes.

child attributes

name

string

Name of financial institution. 35 characters maximum.

identification

string

DFI Identification number, which is the first 8 digits of its routing number.

idQualifier

string

Originating DFI Identification Number Qualifier:

01 National Clearing System Number
02 BIC Coder
03 IBAN

countryCode

string

2-letter ISO country code

transactionTypeCode

string

Part of the addenda record. An additional way to explain the purpose of the IAT. See values here.

originatingCurrency

string

An ISO three-character code to identify the originating currency

destinationCurrency

string

An ISO three-character code to identify the receiving currency

addenda

string

Additional transaction-related information

effectiveDate

string

Effective entry date

reasonCode

string

Nacha return code. See values here.

reasonData

string

Data supporting the Nacha reason code

traceNumber

string

Unique ACH trace number for the transaction

settlementDate

string

Date payment will settle in the receiver's account

wasReturned

boolean

True if payment was returned, otherwise false.

wasCorrected

boolean

True if a payment is sent with bad info but the receiving FI fixes it and sends back the information (NOC), otherwise false.

holdDays

integer

For ACH pulls, allows defining a number of days to delay credit of funds to an account to mitigate fraud and NSF scenarios

object

Previous payment details

child attributes

paymentId

string

Payment ID for an original payment if the payment is returned or the system sends a NOC

reasonCode

string

Reason code for an original payment if the payment is returned or the system sends a NOC

traceNumber

string

Trace number for an original payment if the payment is returned or the system sends a NOC

settlementDate

string

Settlement date for an original payment if the payment is returned or the system sends a NOC

reasonData

string

Supporting data for the reason code for an original payment if the payment is returned or the system sends a NOC

original

object

Original payment details when a payment was returned or a NOC was sent.

Resending a payment after failure as a completely new request. The new payment cannot be linked to the failed payment.

child attributes

paymentId

string

Payment ID for an original payment

reasonCode

string

Reason code for an original payment

traceNumber

string

Trace number for an original payment

settlementDate

string

Settlement date for an original payment

reasonData

string

Supporting data for the reason code for an original payment

createdAt

string

Date and time the payment was created in the system. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

canceledAt

string

Date and time the payment was canceled. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

rejectedAt

string

Date and time the payment was rejected. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

blockedAt

string

Date and time the payment was blocked by BSA/AML. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

processedAt

string

Date and time the payment was processed by CR. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

completedAt

string

Date and time the payment was systemically completed. This can only occur after the payment has successfully posted to the account.. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

postedAt

string

Date and time the payment was posted to the CR account. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

partnerId

string

Your ID in the CR system. This ID is in GUID format.

productId

string

ID in GUID format of your specific product type on which the account is based. Provided by CR. In this case, the CR account involved in the payment.

lastModifiedAt

string

Internal CR value. Date and time the database entry was last modified.

purpose

string

Reason for the ACH transfer. For internal use only. The data is not included with the outgoing ACH batch file.

clientIdentifier

string

Use this attribute to add your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes.

Copy

Sample request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
curl -X POST
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
-d '{
  "accountNumber": "2151546989",
  "receiver": {
    "routingNumber": "021200339",
    "accountNumber": "6546543213",
    "accountType": "Checking",
    "name": "Glenn Quagmire",
    "identification": "XYZ123"
  },
  "secCode": "WEB",
  "description": "JulyFees",
  "transactionType": "Pull",
  "amount": 1,
  "serviceType": "SameDay",
  "extendedDetails": {
      "paymentType": "S"
  },
  "purpose": "sample payment"
}

Copy

Sample response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
    "id": "d2216084-4e30-4620-bcad-b0ca0126a228",
    "accountNumber": "2151546989",
    "referenceId": "A3343EHA7357",
    "paymentType": "Origination",
    "direction": "Outbound",
    "status": "Created",
    "source": "Api",
    "postingType": "Aggregate",
    "postingCode": "OK",
    "posting": "Authorized",
    "originator": {
        "routingNumber": "021214891",
        "accountNumber": "2151546989",
        "accountType": "Checking",
        "name": "Cross River Bank",
        "identification": "021214891"
    },
    "receiver": {
        "routingNumber": "021200339",
        "accountNumber": "6546543213",
        "accountType": "Checking",
        "name": "Glenn Quagmire",
        "identification": "XYZ123"
    },
    "secCode": "WEB",
    "description": "JulyFees",
    "transactionType": "Pull",
    "amount": 1,
    "serviceType": "SameDay",
    "extendedDetails": {
        "paymentType": "S"
    },
    "effectiveDate": "231130",
    "traceNumber": "021214892564114",
    "wasReturned": false,
    "wasCorrected": false,
    "holdDays": 0,
    "original": {
        "paymentId": "d2216084-4e30-4620-bcad-b0ca0126a228"
    },
    "createdAt": "2023-11-30T12:52:43.649396-05:00",
    "partnerId": "1e5d3f04-ae24-4af6-9e30-aecf012b99dd",
    "productId": "cc62e17f-5912-483e-9e42-aed30112fbb6",
    "lastModifiedAt": "2023-11-30T12:52:43.649396-05:00",
    "purpose": "sample payment"
}

Originate ACH client batches

/ach/v1/client-batches

Submits 2 or more payments as a batch. Note that each batch payment must be originated from the same CR account number. If originating from multiple CR accounts, the payments from each account must be submitted as separate batches. For each payment, include the request attributes in the payments object of the request as shown in the code snippet.

Request attributes

clientIdentifier

string

Optional

Use this attribute to add your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes.

Use this field to enter a clientIdentifier for the entire batch. You can also add a separate clientIdentifier for each payment.

payments

object

Required

The information for each payment in the batch.

Response attributes

string

Unique ID for the client batch request. This ID is in the GUID format.

referenceId

string

Unique CR reference ID for the payment. The reference ID always begins with the first letter of the rail. For ACH the reference ID starts with 'A'.

status

string

Status of the transaction:

Processing
Imported
Canceling

accountNumber

string

The account number from which the batch payments originate

paymentCount

integer

The number of unique payments in the batch (up to 5000)

debitTotal

integer

The total amount to be credited to the originator account

creditTotal

integer

The total amount to be debited from the originator account

importCount

integer

Indicates how many payments have been processed at the time of the response

productId

string

ID in GUID format of your specific product type on which the account is based. Provided by CR. In this case, the CR account involved in the batch payment. See also here.

partnerId

string

Your ID in the CR system. This ID is in GUID format.

createdAt

string

When the client batch was created after the request was received

importedAt

string

The time when the import count matches the total number of payments in the batch

lastModifiedAt

string

Internal CR value. Date and time the database entry was last modified.

paymentIdentifiers

array

Unique identifier for each payment in the batch, in GUID format.

Copy

Sample request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
curl -X POST
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
-d '{ \
  "payments": [
{
      "accountNumber": "2207975570",
      "receiver": {
        "routingNumber": "021000021",
        "accountNumber": "12345678",
        "accountType": "Checking",
        "name": "John Wick"
      },
      "secCode": "PPD",
      "description": "string",
      "transactionType": "Push",
      "amount": 113,
      "serviceType": "SameDay"
    },
{
      "accountNumber": "2207975570",
      "receiver": {
        "routingNumber": "021000021",
        "accountNumber": "2342123458",
        "accountType": "Checking",
        "name": "Cleveland Brown"
      },
      "secCode": "PPD",
      "description": "string",
      "transactionType": "Pull",
      "amount": 243591,
      "serviceType": "Standard"
    }
  ]
} 'https://sandbox.crbcos.com/ACH/v1/client-batches'

Copy

Sample response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "id": "fcb7188f-e051-4f5b-addd-afaa00eadb3a",
  "referenceId": "CB0461724AAWT",
  "status": "Processing",
  "accountNumber": "2207975570",
  "paymentCount": 5,
  "debitTotal": 258641,
  "creditTotal": 2863,
  "importCount": 0,
  "productId": "cc62e17f-5912-483e-9e42-aed30112fbb6",
  "partnerId": "1e5d3f04-ae24-4af6-9e30-aecf012b99dd",
  "createdAt": "2023-02-15T09:15:05.1486312-05:00",
  "lastModifiedAt": "2023-02-15T09:15:05.1486312-05:00",
  "paymentIdentifiers": [
    "f04793f3-13d9-4d52-b57e-afaa00eb6c74",
    "dbe36253-06d1-462a-9117-afaa00eb6c74"
    ]
}

Cancel ACH client batches

/ach/v1/client-batches/{id}/cancel

Cancels any incomplete payments and stops further processing of any remaining payments in the batch. If you need to cancel many payments in a client batch, it's most efficient to cancel a client batch before all the payments have imported rather than try to cancel a large number of payments individually.

Path parameters

string

Required

The unique ID of the batch payment, received in the batch origination response as the id attribute. This ID is in GUID format.

Response attributes

The response attributes for this call are the same as for Originate ACH client batches.

Copy

Sample request

1
2
3
4
5
curl -X POST
--header 'Accept: application/json'
--header 'Authorization: Bearer '<token>'

https://sandbox.crbcos.com/ACH/v1/client-batches/fcb7188f-e051-4f5b-addd-afaa00eadb3a/cancel'

Copy

Sample response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "id": "fc0d501d-c36b-45b4-a0d5-afaa00eb6c74",
  "referenceId": "CB0460UJR6DNA",
  "status": "Canceling",
  "accountNumber": "2207975570",
  "paymentCount": 5,
  "debitTotal": 258641,
  "creditTotal": 2863,
  "importCount": 5,
  "productId": "cc62e17f-5912-483e-9e42-aed30112fbb6",
  "partnerId": "1e5d3f04-ae24-4af6-9e30-aecf012b99dd",
  "createdAt": "2023-02-15T09:17:09.077-05:00",
  "importedAt": "2023-02-15T09:17:19.123-05:00",
  "lastModifiedAt": "2023-02-15T09:17:26.8406542-05:00",
  "paymentIdentifiers": [
    "6ed9ea59-2522-4550-8e5d-afaa00eb6c74",
    "dbe36253-06d1-462a-9117-afaa00eb6c74"
  ]
}

Associated webhook events

Event Name	Description
Ach.Batch.Canceled	Any pending or on-hold payments in an ACH client batch canceled
Ach.Batch.Imported	Entire ACH client batch import process into the CR system complete
Ach.Payment.Canceled	ACH payment canceled at partner request
Ach.Payment.Rejected	ACH payment rejected due to a compliance failure or fail to fund
Ach.Payment.Sent	ACH payment sent to the Federal Reserve
Ach.Payment.Received	ACH inbound payment received
Ach.Payment.ReceivedEarly	ACH early direct deposit payment received
Ach.Return.Received	ACH payment was returned from the receiving bank and has been marked as received
Ach.Noc.Received	A Notification of Change was sent from the receiving bank regarding a previous origination
Ach.Hold.Escalated	ACH inbound or outbound payment is on hold and it's status was escalated. This is often used to indicate that additional actions are needed

ACH APIs

Originate an ACH payment

Originate ACH client batches

Cancel ACH client batches

Associated webhook events

Related topics

Tutorials