Search

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.

The effective date on the transaction is the day the first leg of the transaction will start, this is not a required field and should only be set if you want the transaction to take place in the future. If you do not set it we will automatically set it to the next available business day.

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); //note that if this is not set we will automatically set it
	// to next available effective date, to initiate the transaction.
	

    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.
XS_BAT_TYPE_CANCEL	Indicates that a transaction should be canceled. The original transaction ID should be set on the BankAccountTransaction object, and the original transaction must be in the CREATED status.
XS_BAT_TYPE_REVERSAL	Indicates that a transaction should be reversed. The original transaction ID should be set on the BankAccountTransaction object, and the original transaction must be in the SETTLED status. This will create a transaction to move the money in the reverse direction of the original transaction.

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.