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.
Once a recurring transaction is created, every day at 8:30 AM EST, the system will check all enabled recurring transactions to see if there is, any that have a next run date as that day. If there is then an individual transaction will be processed under that merchant.
Once the individual transaction is processed from the recurring transaction, a push notification will be sent to the merchant's Push Notification URL if they have one set.
When a recurring transaction is processed, if it fails validation an email will be sent to the merchant with the failure reasons. The merchant will then want to review the errors to then process a single payment to cover the failed one, or cancel the recurring transaction and create a new one with the updates needed to fix the failure reasons.
If the payment is declined by the the card holder's issuer an email will be sent to the merchant. Also a push notification will be sent to the push notification URL set on the merchant, if one is set. On that push notification it will include the transaction on it which should be checked to confirm it was successful (based off the documentation on BankCardTransactions and BankAccountTransactions and which status you are expecting). If the status is declined, then the merchant will want to handle that recurring transaction the same way as if it failed, which is up to their judgement. A new single transaction can be made to cover the failed one, or a new recurring transaction it is up to the merchant either way they will need to have the reason it failed addressed before hand.
Whether the transaction fails validation or declines, the next frequency of the recurring transaction it will still be tried to process again but Base Commerce does not retry failed/declined single transactions that are processed from a recurring transaction.
Process a Recurring Transaction
|Field||Method on RecurringTransaction|
|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 setToken() method would be used on the BankCard class, then set the BankCard object on the Recurring Transaction object.|
|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 setToken() method would be used on the BankAccount class, then set the BankAccount object on the Recurring Transaction object.|
|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 and would be pulled as a static variable off the BankAccountTransaction object.
|Type||setType( String vs_type )|
Sets the Type of the RecurringTransaction. It can be either XS_BAT_TYPE_CREDIT or XS_BAT_TYPE_DEBIT for ACH, and should be pulled from the BankAccountTransaction object's static variable. If it is a BankCardTransaction then it should be a type of SALE.
Credit Card Example: BankCardTransaction.XS_BCT_TYPE_SALE
|RecurringTransactionID||getRecurringTransactionID()||Returns the ID of the RecurringTransaction. This is the value that's used for canceling RecurringTransactions.|
These static Strings are on the RecurringTransaction object and should be used for when setting the frequency of a RecurringTransaction.
|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.|
These are the Statuses that a RecurringTransaction can be in.
|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.|
|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.|
Example JAVA Process RecurringTransaction ( BankAccount)
Example PHP Process RecurringTransaction ( BankAccount)
Example PHP Process RecurringTransaction ( BankCard)
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.