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.

receiver

object

Required  

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

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.

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.

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

id

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

receiver

object

Receiver bank details

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.

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.

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

previous

object

Previous payment details

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.

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.

Back to top

Copy

Sample request

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

{
    "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

id

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.

Back to top

Copy

Sample request

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

{
  "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

id

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.

Back to top

Copy
Sample request
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

{
  "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

Back to top

Related topics

ACH overview

Error codes

Request and response codes

Tutorials

How to originate an ACH payment

How to originate and cancel ACH client batches

How to simulate ACH inbound payments

 

Back to top