Menu

ACH Processing

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

Processing an ACH Debit Transaction

	BankAccountTransaction o_ach_transaction = new BankAccountTransaction();
    o_ach_transaction.setType(BankAccountTransaction.XS_BAT_TYPE_DEBIT);
    o_ach_transaction.setMethod(BankAccountTransaction.XS_BAT_METHOD_CCD);
    o_ach_transaction.setRoutingNumber("021000021");
    o_ach_transaction.setAmount(10.18);
    o_ach_transaction.setAccountType(BankAccountTransaction.XS_BAT_ACCOUNT_TYPE_CHECKING);
    o_ach_transaction.setAccountName("Sample ACH Transaction");
    o_ach_transaction.setAccountNumber("12345");

    Calendar o_calendar = new GregorianCalendar( Locale.US );
    o_calendar.set(Calendar.DAY_OF_YEAR, o_calendar.get(Calendar.DAY_OF_YEAR) + 3);
    Date o_effective_date = o_calendar.getTime();
    o_ach_transaction.setEffectiveDate(o_effective_date);

    BaseCommerceClient o_client = new BaseCommerceClient( s_username, s_password, s_key );
    o_client.setSandbox(true);
    o_ach_transaction = o_client.processBankAccountTransaction(o_ach_transaction);

    if ( o_ach_transaction.isStatus(BankAccountTransaction.XS_BAT_STATUS_FAILED) ) {
        // Transaction failed, look at messages for reasons why
        System.out.println( o_ach_transaction.getMessages() );
     } else if ( o_ach_transaction.isStatus(BankAccountTransaction.XS_BAT_STATUS_CREATED) ) {
        // Transaction successful
        System.out.println( o_ach_transaction.getBankAccountTransactionId() );
    }                               

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:

Transaction Type Description
XS_BAT_TYPE_CREDIT Indicates that a CREDIT type transaction should be created. This will result in money being withdrawn from the Merchant's 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:

Transaction Method Description
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 does not allow 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:

Transaction Status Description
XS_BAT_STATUS_CREATED Transactions in the created status have successfully been added to the system for processing. The transaction will be included in the merchant's next batch the banking day before effective date of the transaction.
XS_BAT_STATUS_BATCHED Transactions in the batched status means they have been put into a batch for that merchant and will go out in the next file to the Federal Reserve.
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, so long as the transaction has not returned, the transaction will automatically move to the Settled status, indicating that the second half of the transaction has went into a file to the Federal Reserve.
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_CANCELED Indicates that this transaction has been canceled. Transactions can only be canceled while they are in the CREATED 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 perform a transaction type out of sequence.