Menu

Recurring Transactions

Recurring Transactions are processed on the Base Commerce Platform using the RecurringTransaction object to encapsulate all of the data that is needed. It is processed using the BaseCommercePayClient processRecurringTransaction() method. This section details how to process a Recurring Transaction and how to cancel a Recurring Transaction.

Process a Recurring Transaction

Field Method on RecurringTransaction

Description

BankCard setBankCard( BankCard vo_bank_card ) Only one BankCard or BankAccount should be set on the RecurringTransaction, not both. If it is desired to use a BankCard that is stored in the vault, the getBankCard( String vs_token ) method can be used to grab the BankCard and set on the RecurringTransaction.
BankAccount setBankAccount( BankAccount vo_bank_account ) Only one BankCard or BankAccount should be set on the RecurringTransaction, not both. If it is desired to use a BankAccount that is stored in the vault, the getBankAccount( String vs_token ) method can be used to grab the BankAccount and set on the RecurringTransaction.

Frequency

setFrequency( String vs_frequency ) Sets the frequency that the Recurring Transactions will be run. Use one of the listed frequencies below.
Start Date setStartDate( Date vo_start_date ) Sets the RecurringTransactions start date. The Recurring Transactions will be run at whatever frequency interval based off of this date.
End Date setEndDate( Date vo_end_date ) Sets the RecurringTransactions end date, the date that Recurring Transactions will stop running. This is optional, and if no end date is set, the number of transactions will be set to 2999, and depending on the frequency, it will auto set the end date 2999 intervals from the start date.
Amount setAmount( double vd_amount ) The amount the RecurringTransaction is for.
Messages getMessages() Used on the response of processing a RecurringTransaction. If there were errors creating the RecurringTransaction, this method will show the errors. If there were no errors, this will be empty.
Status getStatus() Returns the Status of the Recurring Transaction, which can be any of the Statuses that are listed below.
Method setMethod( String vs_method ) Sets the Method of the RecurringTransaction. This is only used for ACH RecurringTransactions. It can be any of the Methods that are listed in the table below.
Type setType( String vs_type )

Sets the Type of the RecurringTransaction. This is only used for ACH RecurringTransactions. It can be either XS_BAT_TYPE_CREDIT or XS_BAT_TYPE_DEBIT, and should be pulled from the BankAccountTransaction object's static variable.

Example: BankAccountTransaction.XS_BAT_TYPE_CREDIT

RecurringTransactionID getRecurringTransactionID() Returns the ID of the RecurringTransaction. This is the value thats used for canceling RecurringTransactions.

Frequencies

These static Strings are on the RecurringTransaction object and should be used for when setting the frequency of a RecurringTransaction.

Frequency Type Description
XS_FREQUENCY_ANNUALLY Annually, once a year, the transaction will be run.
XS_FREQUENCY_QUARTERLY Quarterly, January 1st, April 1st, July 1st, and October 1st, the transactions will be run.
XS_FREQUENCY_MONTHLY Monthly, every month, the transaction will be run.
XS_FREQUENCY_BIWEEKLY Bi-Weekly, every 14 days, the transaction will be run.
XS_FREQUENCY_WEEKLY Weekly, every 7 days, the transaction will be run.
XS_FREQUENCY_DAILY Daily, every day, the transaction will be run.

Statuses

These are the Statuses that a RecurringTransaction can be in.

Status Type Description
XS_RECURRING_STATUS_ENABLED The RecurringTransaction is enabled.
XS_RECURRING_STATUS_FAILED The RecurringTransaction failed, check getMessages() function to see why it failed.
XS_RECURRING_STATUS_DISABLED The RecurringTransaction is disabled.

Example Process RecurringTransaction

		RecurringTransaction o_recurring_transaction = new RecurringTransaction();
        o_recurring_transaction.setAmount(19.99);
        o_recurring_transaction.setFrequency( RecurringTransaction.XS_FREQUENCY_MONTHLY );
        o_recurring_transaction.setType( BankAccountTransaction.XS_BAT_TYPE_CREDIT );
        o_recurring_transaction.setMethod( BankAccountTransaction.XS_BAT_METHOD_CCD );
        
        SimpleDateFormat o_sdf = new SimpleDateFormat("MM/dd/yyyy");
        try {
            o_recurring_transaction.setStartDate( o_sdf.parse("10/10/2015") );
            o_recurring_transaction.setEndDate( o_sdf.parse("11/12/2019") );
        } catch(ParseException e) {
            System.out.println("Error occured :" + e.getMessage());
        }
        
        BankAccount o_bank_account = new BankAccount();
        Address o_address = new Address(Address.XS_ADDRESS_NAME_BILLING);
        o_address.setLine1("1239 test lane");
        o_address.setZipcode("12345");
        o_address.setCity("looney town");
        o_address.setState("az");
        o_address.setCountry("us");
        //Create a new BankAccount object
        o_bank_account.setBillingAddress( o_address );
        o_bank_account.setName( "Test Name" );
        o_bank_account.setAccountNumber( "123123123" );
        o_bank_account.setType( BankAccount.XS_BA_TYPE_CHECKING );
        o_bank_account.setRoutingNumber( "111000025" ); 
        
        o_bank_account.setBillingAddress(o_address);
        o_recurring_transaction.setBankAccount( o_bank_account );

        BaseCommerceClient o_client = new BaseCommerceClient(XS_USERNAME, XS_PASSWORD, XS_KEY);
        o_client.setSandbox(true);

        o_recurring_transaction = o_client.processRecurringTransaction(o_recurring_transaction);

        if ( RecurringTransaction.XS_RECURRING_STATUS_FAILED.equals( o_recurring_transaction.getStatus() ) ) {
            // RecurringTransaction failed, look at messages for reason why
            System.out.println("failed: " + o_recurring_transaction.getMessages() );
        } else if (RecurringTransaction.XS_RECURRING_STATUS_ENABLED.equals( o_recurring_transaction.getStatus() ) ) {
            // RecurringTransaction Successful
            System.out.println("Process successful; Recurring transaction enabled with transaction ID:" + o_recurring_transaction.getRecurringTransactionID() );
        } else if ( RecurringTransaction.XS_RECURRING_STATUS_DISABLED.equals(o_recurring_transaction.getStatus())) {
            // RecurringTransaction disabled
            System.out.println("disabled");
        }

Cancel RecurringTransaction

To cancel a RecurringTransaction, all that is needed is the RecurringTransaction's ID, which can be obtained by the getRecurringTransactionID() method. That ID is passed into the cancelRecurringTransaction( int n_id ) method and that is all that is needed.

The user is able to Cancel/Disable only those Recurring Transaction which are in Active/Completed status. No failed transaction could be cancelled.

Example Cancel RecurringTransaction

		RecurringTransaction o_recurring_transaction = new RecurringTransaction();
        int n_recurring_transaction_id = 22;
        BaseCommerceClient o_client = new BaseCommerceClient(XS_USERNAME, XS_PASSWORD, XS_KEY);
        o_client.setSandbox(true);
        
        o_recurring_transaction = o_client.cancelRecurringTransaction( n_recurring_transaction_id );

        if ( RecurringTransaction.XS_RECURRING_STATUS_DISABLED.equals( o_recurring_transaction.getStatus() ) ) {
            // RecurringTransaction Successful
            System.out.println("Cancellation Successful for transaction ID :" + o_recurring_transaction.getRecurringTransactionID() );
        } else {
            System.out.println("Cancellation failed: " + o_recurring_transaction.getMessages() );
        }