Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ecrypt.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers ACH payment processing through the ECRYPT API. It explains how bank account data is represented, how ACH transactions are submitted and settled, and what actions you can take after a transaction is created.

​
How ACH Works

ACH (Automated Clearing House) is a bank-to-bank payment network operated by Nacha that moves funds electronically between U.S. financial institutions. Unlike card transactions, ACH payments are not authorized in real time. Transactions are submitted in batches throughout the day, processed overnight by the ACH network, and settled within 1-3 business days. ACH supports two directions of money movement:
  • Debit: Funds are pulled from a customer’s bank account into your merchant account. This is the most common flow for collecting payments.
  • Credit: Funds are pushed from your merchant account into a recipient’s bank account. Typically used for refunds, payouts, or disbursements.

​
Bank Account Data

Two fields are required to tokenize a bank account. Additional fields can be included for record-keeping and statement clarity.

​
Required

accountNumber: The number that identifies the specific account at the financial institution. Raw account numbers should never be stored in your system. Use tokenization instead. routingNumber: A 9-digit number that identifies the financial institution. Routing numbers appear at the bottom-left of a paper check.

​
Optional

name: The name of the individual or business that owns the account. Included in the ACH transaction record transmitted to the network. accountType: Indicates whether the account is checking (0) or savings (1). checkNumber: The check number associated with the transaction, if applicable.

​
Tokenization

Before initiating an ACH transaction, tokenize the bank account details. Tokenization replaces the routing number and account number with a non-sensitive token that is safe to store and reuse. To tokenize a bank account, send the account details to POST /v1/tokens using the check object. Only accountNumber and routingNumber are required: 
curl --request POST \
     --url https://api.ecrypt.com/v1/tokens \
     --header 'X-Api-Key: {{api_key}}' \
     --header 'content-type: application/json' \
     --data '
{
  "check": {
    "account_number": "123123123",
    "routing_number": "123123123",
    "name": "Jane Smith",
    "check_number": "001",
    "account_type": "Checking"
  }
}
'

{
  "token": "200625bb-7c38-40af-b3cf-4b9d4304d80c",
  "metadata": {
    "accountNumber": "1*****3123"
  },
  "requestId": "0HNK1A7BLRLH00000005E"
}
The token string is what you pass in all subsequent transaction requests. The raw account number is never stored or returned after this point.

​
Transaction Lifecycle

ACH transactions do not use an authorization and capture model. There is no real-time approval step and no hold placed on funds. When you submit an ACH transaction, it is queued for processing and settlement begins asynchronously.

​
Submitting a Transaction

To initiate an ACH transaction, send a request to POST /v1/transactions/sale with the token from the tokenization step and the desired amount. 
curl --request POST \
     --url https://api.ecrypt.com/v1/transactions/sale \
     --header 'X-Api-Key: {{api_key}}' \
     --header 'content-type: application/json' \
     --data '
{
  "payment": {
    "token": "200625bb-7c38-40af-b3cf-4b9d4304d80c"
  },
  "amount": {
    "value": 100
  }
}
'
A successful submission returns a transactionId that you use for all subsequent operations (void, refund, etc.).

​
Pending

Once submitted, the transaction enters a pending state. ECRYPT batches ACH transactions and submits them to the ACH network on a regular processing schedule.

​
Settlement

After the batch is submitted to the network, settlement typically completes within 1-3 business days depending on the receiving bank and the time of submission. The transaction status changes from pending to settled once funds have transferred. Because there is no real-time authorization, a submitted transaction does not guarantee that funds are available. Insufficient funds, closed accounts, and invalid account data are discovered only during settlement or in the form of a return.

​
Returns

A return occurs when the receiving bank rejects the transaction after it has been submitted. Returns are identified by a standardized R-code. Common return reasons include:
Return CodeDescription
R01Insufficient funds
R02Account closed
R03No account or unable to locate
R04Invalid account number
R10Customer advises not authorized
R29Corporate customer advises not authorized
Returns can arrive up to 2 banking days after settlement for most codes. Unauthorized transaction claims (R05, R07, R10, R29) have an extended return window of up to 60 days for consumers. ECRYPT delivers return notifications via webhook. See Event Types for the relevant event payload. For a complete list of ACH return codes, see ACH Response Codes.

​
Managing Transactions

Once a transaction exists, the actions available to you depend on whether it has settled. All actions reference the transactionId returned at submission.

​
Pre-Settlement

Void: Cancels the transaction before it settles. No funds are transferred. 
curl --request POST \
     --url https://api.ecrypt.com/v1/transactions/void \
     --header 'X-Api-Key: {{api_key}}' \
     --header 'content-type: application/json' \
     --data '
{
  "transaction_id": "{{transaction_id}}"
}
'

​
Post-Settlement

Refund: Returns funds to the originating account after settlement has completed. A refund initiates a new ACH credit in the opposite direction of the original debit. 
curl --request POST \
     --url https://api.ecrypt.com/v1/transactions/refund \
     --header 'X-Api-Key: {{api_key}}' \
     --header 'content-type: application/json' \
     --data '
{
  "transaction_id": "{{transaction_id}}",
  "amount": 100
}
'
Partial refunds are supported. You can issue multiple partial refunds against a single settled transaction as long as the total refunded amount does not exceed the original transaction amount.
TimingActionFunds Move?
Pre-settlementVoidNo
Post-settlementRefund (full or partial)Yes (returned)

​
Next Steps