Base Commerce Technical Documentation

ACH Processing

ACH Transactions are processed on the Base Commerce Platform using the BankAccountTransaction object to encapsulate all of the account data and details about the transaction and the BaseCommercePayClient processBankAccountTransaction() method. This section details the types of transactions that can be preformed on the platform, required and optional parameters, and the statuses you can expect back from each type of request.

BankAccountTransaction Types

Every BankAccountTransaction request requires a transaction type be set prior to executing processBankAccountTransaction(). The transaction type is set by invoking the setType( ) method on the BankAccountTransaction object with one of the following :

XS_BAT_TYPE_CREDIT – Indicates that a CREDIT type transaction should be created. This will result in money being withdrawn from the merchants bank account and deposited to the account specified in the BankAccountTransaction details.

XS_BAT_TYPE_DEBIT – Indicates that a DEBIT type transaction should be created. This will result in money being withdrawn from the account specified in the BankAccountTransaction object and deposited to the merchants bank account.

BankAccountTransaction Methods

Every BankAccountTransaction request requires a transaction method be set prior to executing processBankAccountTransaction(). The transaction method defines how the transaction originated and is set by invoking the setMethod( ) method on the BankAccountTransaction object with one of the following :

XS_BAT_METHOD_CCD - Corporate credit or debit. Primarily used for business-to-business transactions.

XS_BAT_METHOD_PPD - Prearranged payment and deposits. Used to credit or debit a consumer account. Popularly used for payroll direct deposits and preauthorized bill payments.

XS_BAT_METHOD_TEL - Telephone-initiated entry. Oral authorization by telephone to issue an ACH entry such as checks by phone. (TEL code allowed for inbound telephone orders only. NACHA disallows the use of this code for outbound telephone solicitations unless a prior business arrangement with the customer has been established.)

XS_BAT_METHOD_WEB - Web-initiated entry. Electronic authorization through the Internet to create an ACH entry.

BankAccountTransaction Statuses

Every BankAccountTransaction that is processed with valid credentials will have a status that should be checked to determine the results of the transaction. The status can be obtained from a BankAccountTransaction object by executing the getStatus() or isStatus() methods. The status values are as follows:

XS_BAT_STATUS_NEW - Transactions in the new status have successfully been added to the system for processing. They will be included in the next batch that is uploaded to the Federal Reserve for processing.

XS_BAT_STATUS_INITIATED – For merchants that have a settlement delay, this indicates that the first half of the transaction has been initiated and has been sent to the federal reserve for processing. After the settlement delay has been met, as long as the transaction has not returned, the transaction will automatically move to the pending settlement status indicating that the second half of the transaction will be processed.

XS_BAT_STATUS_SETTLED – Indicates that the transaction has completed the settlement process and that both parts of the transaction have processed. A transaction that is in the settled state can still be returned if there is a unauthorized transaction or a ACH reject.

XS_BAT_STATUS_RETURNED - Indicates that the transaction has been returned by the bank, check the return code on the BankAccountTransaction using the getReturnCode() method to determine the reason for the return.

XS_BAT_STATUS_PENDING_SETTLEMENT – Indicates that the second half of the transaction will be included in the next settlement batch.

XS_BAT_STATUS_CANCELED – Indicates that this transaction has been canceled, transactions can only be canceled while they are in the NEW status before any processing has taken place on it.

XS_BAT_STATUS_FAILED - Indicates that the transaction has failed as a result of our platforms integrity checks. See getResponseMessage() on the BankAccountTransaction object for the reason why. This status should not appear in production environments and is used as a way to assist the developer if they are missing data or trying to preform a transaction type out of sequence.

BankAccountTransaction Response Codes

Code
Reason
Description
R01
Insufficient funds
Available balance is not sufficient to cover the dollar amount of the debit entry
R02
Account closed
A previously open account is now closed
R03
No account or unable to locate account
The account number does not correspond to the individual identified in the entry or a valid account.
R04
Invalid account number
The account number fails the check digit validation or may contain an incorrect number of digits
R05
Unauthorized debit to consumer account
A business debit entry was transmitted to a members consumer account, and the member had not authorized the entry
R06
Returned per ODFI's request
The ODFI has requested that the RDFI return the entry
R07
Authorization revoked by customer
Member who previously authorized an entry has revoked authorization with the Originator
R08
Payment stopped or stop payment on item
Member had previously requested a stop payment of a single or recurring entry
R09
Uncollected funds
Available balance is sufficient, but collected balance is not sufficient to cover the entry
R10
Customer advises not authorized
Member advises not authorized, notice not provided, improper source document, or amount of entry not accurately obtained from source document
R11
Uncollected funds
To be used when returning a check truncation entry
R12
Branch sold to another DFI
RDFI unable to post entry destined for a bank account maintained at a branch sold to another financial institution
R13
Invalid ACH routing number
Financial institution does not receive commercial ACH entries
R14
Representment payee deceased or unable to continue in that capacity
Representative payee is deceased or unable to continue in that capacity, beneficiary is not deceasedn
R15
Beneficiary of account holder deceased
Beneficiary or Account Holder Deceased
R16
Account frozen
Access to account is restricted due to specific action taken by the RDFI or by legal action
R17
File record edit criteria
Fields rejected by RDFI processing (identified in return addenda)
R18
Improper effective entry date
Entries have been presented prior to the first available processing window for the effective date.
R19
Amount field error
Improper formatting of the amount field
R20
Nontransaction account
Policies or regulations (such as Regulation D) prohibit or limit activity to the account indicated
R21
Invalid company identification
The company ID information not valid (normally CIE entries)
R22
Invalid individual ID number
Individual id used by receiver is incorrect (CIE entries)
R23
Credit entry refused by receiver
Receiver returned entry because minimum or exact amount not remitted, bank account is subject to litigation, or payment represents an overpayment, originator is not known to receiver or receiver has not authorized this credit entry to this bank account
R24
Duplicate entry
RDFI has received a duplicate entry
R25
Addenda error
Improper formatting of the addenda record information
R26
Mandatory field error
Improper information in one of the mandatory fields
R27
Trace number error
Original entry trace number is not valid for return entry; or addenda trace numbers do not correspond with entry detail record
R28
Routing number or check digit error
Check digit for the transit routing number is incorrect
R29
Corporate customer advises not authorized
RDFI has been notified by business account holder that a specific transaction is unauthorized
R30
RDFI not participant in check truncation program
Financial institution not participating in automated check safekeeping application
R31
Permissible return entry
RDFI has been notified by business account holder that a specific transaction is unauthorized
R32
RDFI nonsettlement
RDFI is not able to settle the entry
R33
Return of XCK entry
RDFI determines at its sole discretion to return an XCK entry; an XCK return entry may be initiated by midnight of the sixtieth day following the settlement date if the XCK entry
R34
Limited participation DFI
RDFI participation has been limited by a federal or state supervisor
R35
Return of improper debit entry
ACH debit not permitted for use with the CIE standard entry class code (except for reversals)
R36
Return of improper credit entry
R37
Source Document Presented for Payment
Check used for an ARC, BOC or POP entry has also been presented for payment
R38
Stop payment on source document
Stop payment has been placed on a check used for an ARC entry