ACH

Configuration

Reference for ACH configuration within the Twisp ACH Processor

The Basics

ACH configurations define the operational parameters for processing ACH transactions. Each configuration specifies the accounts, webhook endpoints, file header information, and timezone settings required for both originating (ODFI) and receiving (RDFI) ACH operations.

Configurations in Twisp...

  • Connect settlement, suspense, exception, and fee accounts
  • Define ODFI header information for NACHA file generation
  • Reference webhook endpoints for transaction decisioning
  • Specify journal for posting all ACH transactions
  • Declare a direction (RDFI, ODFI, or BOTH) that restricts which file types the configuration may process
  • Optionally enable auto-pending mode, which receives RDFI entries without sending webhooks: forward entries post to a pending account and matched dishonored returns post there on the settled layer

Components of ACH Configuration

There are 7 primary components which define an ACH configuration:

  1. Accounts: Settlement, suspense, and exception accounts are always required. The fee account is required unless the configuration is RDFI-only. Auto-pending configurations additionally require a pending account.
  2. Webhook Endpoint: Receives decisioning requests during file processing, allowing custom business logic for transaction acceptance or rejection. It is optional and unused when auto-pending is enabled.
  3. ODFI Header Configuration: Company and bank information used when generating NACHA-formatted files for transmission.
  4. Journal: The ledger journal where all ACH transaction entries are posted.
  5. Timezone: IANA timezone identifier for date/time operations and effective date calculations.
  6. Direction: Whether the configuration processes RDFI files, ODFI files, or BOTH (the default).
  7. Auto Pending: When enabled, RDFI processing sends no webhooks. Forward entries post as pending to the configured pending account, and matched dishonored returns post there on the settled layer.

Optional components may also be configured:

  • Trace Number Configuration: A reserved range of trace numbers Twisp generates from when originating files.
  • File Modifier Configuration: A reserved range of file ID modifiers Twisp assigns to the files it generates each day, or an instruction to take the modifier from the caller instead.

In addition, configurations have common properties:

  • Config ID: a universally unique identifier (UUID) for the configuration.
  • Version: configurations are versioned, allowing tracking of changes over time and ensuring file processing references the correct configuration version.
  • Created & Modified Timestamps: when the configuration was created and last updated.

Required Accounts

Settlement Account

The settlement account is the central hub for ACH fund flows. All incoming and outgoing ACH transactions post to this account during processing phases.

Characteristics:

  • Normal balance type: DEBIT (typically holds positive balance from incoming credits)
  • enableConcurrentPosting: true (supports high transaction volumes)
  • Debited for ODFI PULL transactions, credited for ODFI PUSH transactions
  • Credited for RDFI inbound credits, debited for RDFI inbound debits

Suspense Account

Suspense account receives transactions where the destination account cannot be located, commonly when routing number and account number combinations don't match existing accounts.

Characteristics:

  • enableConcurrentPosting: true (may receive high transaction volumes)
  • Requires manual review to determine correct account or return to originator
  • Funds held pending investigation or return processing

Exception Account

The exception account receives transactions that cannot be applied automatically. This includes transactions that fail processing due to velocity controls, locked accounts, or other business rule violations, as well as inbound returns with no eligible originated workflow. A return has no eligible workflow when its original trace number has no match or all matching workflows have already returned.

Characteristics:

  • enableConcurrentPosting: true (supports parallel processing)
  • Unmatched returns post with transaction code SYS_ACH_UNKNOWN_RETURN_CR or SYS_ACH_UNKNOWN_RETURN_DR, based on the return entry's transaction code
  • Processing an unmatched return sets hasExceptions on the inbound file
  • The transaction and entry metadata contain the parsed RDFI workflow entry for investigation
  • Requires manual review to return rejected forward entries or reconcile unmatched inbound returns

Fee Account

Fee account collects ACH processing fees charged per transaction. It is required unless the configuration's direction is RDFI (fees are only charged on ODFI operations).

Characteristics:

  • Normal balance type: CREDIT (accumulates fee income)
  • enableConcurrentPosting: true (supports high transaction volumes)
  • Credited when fees charged, debited when fees reimbursed (on returns/cancellations)

Pending Account (auto-pending only)

The pending account receives every forward RDFI entry and the settled posting for every matched dishonored return when the configuration has auto-pending enabled. It is required when autoPending: true and unused otherwise.

Characteristics:

  • Holds encumbered funds until each entry is manually settled or returned
  • enableConcurrentPosting: true recommended (receives every entry in a file)
  • See Auto Pending Mode below

Direction

The direction field declares which side of ACH processing a configuration handles:

  • BOTH (default): Processes RDFI and ODFI files. Existing configurations created before this field existed behave as BOTH.
  • RDFI: Receives incoming files only. Mutation.ach.processFile() rejects ODFI file types (ODFI_RETURN, ODFI_PREPROCESS_RETURN, ODFI_PROCESSED) with a BadRequest. The fee account becomes optional.
  • ODFI: Originates outgoing files only. processFile rejects RDFI file types. Auto-pending cannot be enabled.

Auto Pending Mode

Auto-pending is a hands-off RDFI ingest mode. When autoPending: true, RDFI processing sends no webhooks. Forward entries are automatically posted as PENDING to the configured pending account, where they wait for you to settle or return them. Matched dishonored returns post to the same account on the settled layer.

Requirements:

  • pendingAccountId is required, must reference an existing account, and must differ from the settlement, suspense, and exception accounts
  • direction must be RDFI or BOTH — enabling auto-pending on an ODFI configuration is a validation error
  • endpointId becomes optional. Auto-pending sends no webhooks, even when an endpoint is configured.

Behavior:

  • Entries post to the pending account's encumbrance layer, exactly as if a decisioning webhook had responded PENDING with that account
  • A matched dishonored return posts on the pending account's settled layer and remains at DISHONOR until you move or contest it with workflow.executeTask
  • The file transitions PROCESSING → PENDING and remains there until every entry reaches a terminal state, then transitions to COMPLETED (it skips PROCESSED, since no webhooks are ever sent)
  • Resolve each entry by executing a SETTLE or RETURN task on its workflow execution, the same as resolving a webhook-pended entry

See the RDFI reference for the end-to-end flow.

ODFI Header Configuration

ODFI header configuration contains NACHA file header information required when generating ACH files.

Components:

  • Immediate Destination: Routing number of receiving institution (ODFI or Federal Reserve)
  • Immediate Destination Name: Name of receiving institution (max 23 characters)
  • Immediate Origin: Your Federal Tax ID or routing number (10 characters)
  • Immediate Origin Name: Your company name as it appears in ACH files (max 23 characters)

These values populate the File Header Record (Record Type Code 1) in generated NACHA files.

Webhook Endpoint

The webhook endpoint receives POST requests during ACH file processing for transaction decisioning. The endpoint must be of type ACH_PROCESSOR. It is required unless the configuration has auto-pending enabled, and it is not used at all while auto-pending is enabled.

Request Format: Webhook receives transaction details including amount, account identifiers, and entry metadata when processing files via Mutation.ach.processFile().

Response Format: Webhook responds with settlement instructions specifying which account to credit/debit, or directing transaction to suspense/exception accounts.

Timeout: Webhook must respond within configured timeout period to avoid transaction failure.

See the RDFI reference for detailed webhook payload and response specifications.

Timezone

IANA timezone identifier determines date/time interpretation for:

  • Effective dates for ACH transactions
  • Settlement window calculations
  • Batch header dates in NACHA files
  • Processing cutoff time interpretation

Common values: America/New_York, America/Chicago, America/Denver, America/Los_Angeles, America/Phoenix

Use the timezone where primary ACH operations occur, typically matching ODFI timezone or business headquarters location.

Trace Number Configuration

Every entry in a NACHA file carries a 15-character trace number: an 8-character ODFI routing prefix followed by a 7-digit sequence number. Twisp assigns the sequence number whenever it originates a file — including return and NOC (notification of change) files generated for RDFI operations.

If your program originates its own forward files outside of Twisp, those files draw sequence numbers from the same 7-digit space, and trace numbers could collide with the ones Twisp generates. To prevent this, reserve a block of trace numbers for Twisp:

  • Min Trace Number: The lowest sequence number Twisp will generate. Must be greater than or equal to 1.
  • Max Trace Number: The highest sequence number Twisp will generate. Must be greater than the min and less than or equal to 9999999.

When configured, all trace numbers Twisp generates for this configuration fall within the reserved range, wrapping back to the min after the max is used. When omitted, Twisp generates from the full range of 1 to 9999999.

Range size and file generation:

  • Return and NOC files contain at most as many entries as the range holds. If more entries are queued than fit, the file is generated with a full range of entries and the remainder automatically carries over to the next file generation.
  • Twisp-originated forward files fail with an error if a single file would contain more entries than the range holds. Size the reserved range comfortably above your expected per-file entry counts.

The trace number configuration can be set at creation via Mutation.ach.createConfiguration() or added later via Mutation.ach.updateConfiguration(). If the range is changed while the current trace position lies outside the new range, generation restarts from the new min.

File Modifier Configuration

Every NACHA file header carries a single-character file ID modifier that distinguishes files created on the same day with the same origin and destination. Modifiers must be unique per day, so Twisp records the ones each day has used (in the configuration's timezone) and assigns each file the first modifier of the sequence A through Z, then 0 through 9, that the day has not used yet. The first file of a day therefore takes A, and generation fails once the day has used every modifier of the sequence.

If your program originates files outside of Twisp with the same origin and destination, those files draw modifiers from the same per-day space and could collide with the ones Twisp assigns. The file modifier configuration prevents this in one of two ways: reserve a range of modifiers for Twisp, or supply the modifier of each file yourself.

The configuration can be set at creation via Mutation.ach.createConfiguration() or added later via Mutation.ach.updateConfiguration(). Set a range or userSupplied, never both. Configuring the full range — start A, end 9 — resets the configuration to Twisp's default: it is stored as no file modifier configuration at all, which is how a range or userSupplied is cleared once set.

Reserved Range

  • Start File ID Modifier: The first modifier Twisp assigns each day. A single character from A-Z or 0-9.
  • End File ID Modifier: The last modifier Twisp assigns each day. Must not come before the start in the sequence A-Z then 0-9. A range with the same start and end reserves a single modifier, which allows one file per day.

When configured, each file takes the first modifier of the range the day has not used yet. The first file of the day therefore takes the start modifier, and generation fails once the range holds no unused modifier. When omitted, Twisp assigns from the full sequence of A through 9 — up to 36 files per day.

The range may be changed during the day. Twisp tracks the modifiers the day has already used rather than a position in the sequence, so a moved range picks up its first unused modifier and never reissues one. A range narrowed and widened again the same day fills the gaps it left behind, which can hand out a modifier below the day's last one.

Caller-Supplied Modifiers

Set User Supplied (userSupplied: true) to assign the modifier of every file yourself. Twisp then assigns no modifiers of its own, and options.fileModifier becomes a required argument of Mutation.ach.generateFile(). Generation fails with a bad request error when the modifier is missing, when it is not a single character from A-Z or 0-9, or when a modifier is supplied to a configuration that reserves a range instead.

Use this when the modifier of each file has to match an assignment your own systems already make. Twisp writes the supplied character to the file header as given, and enforces no sequence of its own: any unused modifier is accepted, in any order. See Supplying the File ID Modifier for the generation option.

Modifiers stay unique per day whoever chooses them. Supplied modifiers join the day's used modifiers, so a modifier the day has already written to a file is refused rather than reissued, and the two modes are safe to alternate: a configuration switched between userSupplied and a reserved range on the same day never repeats a modifier in either direction.

Generation is not a repeatable operation — it drains the queued entries into the file it creates — so a refused repeat costs you nothing: the file that already carries the modifier remains available from File Download.

Offset Configuration (Balanced Files)

By default, Twisp originates unbalanced files: batches contain only the forward entries, so the file's total credits and total debits differ. Some ODFIs require balanced files, where each batch carries an offset entry drawn on the originator's settlement account at the ODFI so credits equal debits.

Setting offsetConfiguration opts a configuration into balanced origination files:

  • Account Number: The account offset entries are drawn on (required, max 17 characters).
  • Account Type: CHECKING or SAVINGS (required).
  • Routing Number: The routing number offset entries are drawn on. When omitted, offsets are drawn on the configuration's Immediate Origin, which must then be a valid ABA routing number.
  • Description: Optional discretionary data carried on offset entries (max 2 characters).
  • Enable Balanced Return/NOCs (enableBalancedReturnNOCs): When true, generated return and NOC files are balanced as well. Defaults to false — only originated forward files are balanced.

Balanced forward file behavior:

  • Each batch in a generated forward file ends with a single offset entry whose amount equals the sum of the batch's entries, posted with the opposite transaction code and the individual name OFFSET.
  • Batches with offsets use service class code 200 (mixed debits and credits), and file/batch control totals include the offset amounts — total credits always equal total debits.
  • Forward entries may not use the individual name OFFSET; it is reserved for generated offset entries.

Balanced return/NOC file behavior (when enableBalancedReturnNOCs is set):

  • Return batches cannot carry a forward offset entry directly (NACHA parsers reject forward entries mixed into a return batch), so the offsets are collected into a single trailing forward batch — service class code 200, company entry description OFFSET — holding one offset entry per unbalanced batch. File control totals balance; individual return batches are unchanged.
  • NOC entries carry zero amounts, so NOC batches need no offset and are untouched; a pure NOC file has no offset batch.

Shared behavior:

  • Offset entries consume trace numbers from the same sequence as regular entries, reserved exactly — one per offset entry, determined after batch consolidation — so the sequence carries no gaps. All trace numbers within a file must be distinct, so a reserved trace range must hold the file's entries plus its offset entries; return files cap their entry count at half the range so the worst case always fits.
  • Offsets only affect generated files. Ledger postings are unchanged: settlement is already modeled by the configuration's settlement account.

Forward-file offsets apply to configurations with direction ODFI or BOTH; an RDFI-only configuration may use offsetConfiguration when enableBalancedReturnNOCs is set, since it generates only return and NOC files. Remove the configuration by passing clearOffsetConfiguration: true to Mutation.ach.updateConfiguration().

Configuration Versioning

Configurations use optimistic locking with version numbers. Each update via Mutation.ach.updateConfiguration() increments the version field. File processing records reference the specific configuration version used, ensuring immutability and audit trail consistency.

When files are processed via Mutation.ach.processFile(), the configVersion field on AchFileInfo captures which configuration version applied, allowing historical analysis even after configuration updates.

Configuration Operations

Use GraphQL to create, update, and query ACH configurations:

Further Reading

To learn how to set up ACH configuration from scratch, see the tutorial on Setting Up ACH Processing.

For step-by-step configuration with real APIs, see the how-to guide on Processing ACH Payments.

For complete GraphQL type definitions, see:

Previous
ACH
Next
File Operations