AppFrontier

Table of Contents

Chargent Documentation

Recurring Billing

Recurring Billing Overview:

Chargent provides a very flexible, customizable system for managing subscription billing, installment payments, and recurring charges. There are two basic parts to setting up recurring payments:

  • Schedule the Recurring Batch in Salesforce (Scheduled Apex)
  • Use one of the following two methods to setup the Recurring Billing schedule

    • Chargent Anywhere to setup the Recurring Schedule through the Payment Console.
    • Using Chargent Orders to setup the correct fields.

The following fields and criteria determine if a recurring transaction should occur:

  • Payment Status = Recurring
  • Payment Start Date = Must be today or a date in the past or it is skipped
  • Payment Frequency = This will determine how often the recurring billing will happen (weekly, monthly, annually, etc…)
  • Was the last transaction that was marked as recurring within the set frequency.

    • If no transactions, manual transactions (not checked as recurring), or a recurring transaction older than the frequency are present, then it will run.

Note: If you change the Payment Start Date or the Charge Date, it could affect when your next Recurring transaction will process based on the last ‘Recurring’ Transaction. You should always check the Next Transaction Date field as a guide to keep your recurring schedule accurate. Adjust the Payment Start Date as needed.


Scheduling the Apex Batch

Chargent customers have the ability to create scheduled, recurring transactions using either Chargent Anywhere or the Chargent Order record. In order to begin recurring billing, you first need to setup a Scheduled Apex Batch in Salesforce. The batch will be set to run at a designated time and frequency you specify during the setup. The batch is designed to process any records that meet the criteria for the recurring billing cycle listed in the Recurring Billing Overview above.

For versions 5.40 and newer the Apex Job will be setup automatically when you setup your Payment Gateway. When prompted during the Gateway Setup Wizard, it will ask you if you want to setup Recurring Billing and the time you want the batch to run. Selecting Yes will take you through the prompts for scheduling your batch.

using

chargent

If you want to run the batch at a time other than what is recommended, you can select ‘No’ when prompted and it allows you to customize the batch days and times.

setup

Note: The instructions below are for scheduling the batch manually. If you are on a current version of Chargent, it may already be scheduled. You can check Setup > Scheduled Jobs to make sure you do not schedule it a second time.


If you originally said no when setting up your gateway, or if you are on a version prior to 5.40 and want to schedule your Apex batch manually, then do the following:

  1. Click on the gear icon gear icon on the top right side and select Setup.
  2. Under Custom Code select Apex Classes.
  3. Click Schedule Apex.

  4. apex

  5. Enter the following fields:

    • Job Name: You should name your batch something that reflects Recurring Billing so you can identify it later if needed.
    • Apex Class: Click on the magnifying glass and select the "sheduledBatchProcessing" class to be run.

    • Note: The class name contains a typo - there is no "c" in the word "scheduled". While that was not intentional, we can't change it!


    • Schedule Apex Execution:

      • Frequency = Weekly
      • Check every day of the week so that the batch runs daily.
      • Start Date = today’s date
      • End Date (important): The end date should be far into the future so that the schedule doesn’t end. Once the batch ends the recurring batch will no longer process recurring transactions. 2050 is generally a good year to use.
      • Start Time: Although you can choose any time you want we recommend 3am to give your team the whole day to review transactions and make any required adjustments or voids during business hours.

frequency

Recurring Billing Setup

Chargent Anywhere and Recurring Payments

In order to setup Recurring Billing using Chargent Anywhere you will need to have the Payment Console feature enabled. Payment Console is available with Chargent’s Platform Edition or higher. If you are not on Platform Edition you can contact our Sales team to upgrade or you can setup Recurring Billing via the Chargent Order object.

Once you have the Payment Console enabled and the activation key added to your Chargent Settings > Feature Activation tab, you can proceed to setup Recurring Billing for your customers.

The Chargent Anywhere Payment Console enables you to set up one-time scheduled payments, recurring / subscription payments, or a combination of both. You can also register tokens for future payment processing.

There are several fields within the Payment Console Layout that will allow you to process initial and recurring charges (as well as register tokens and authorize payments).

  • One Time / Recurring
  • Card / Bank Account
  • Process Type (Register Token, Authorize, and Charge)

Register Token, Authorize, and Charge buttons are enabled via your Gateway settings. If you don’t see one of these buttons, you may need to go into your Gateway setup and enable the appropriate check box.


one time

Recurring Billing

  1. Click the Payment Console button
  2. If there isn’t already payment info on file then enter the billing information and click Continue.
  3. Click the Recurring payment type
  4. Choose the Payment Method (Card or Bank Account)
  5. Enter the payment details (Credit Card or Bank Account info)
  6. Enter the Initial Amount and the Recurring Amount
  7. Click the Next button

  8. card

  9. On the Recurring definition step, you can define the following details:

    • Frequency - What cycle you want the payments to charge? (weekly, monthly, annual, etc.)
    • Payment Start Date - When do you want the recurring billing to start? If you are processing a One Time Amount with Recurring Billing then set this date to the next expected payment date.
    • Fixed Day of Month to Charge - Is there a specific day of the month you need the payments to process on? Note, setting this to 31 will process transactions on the 30th for months that only have 30 days.
    • Stop Rule - When do you want your recurring payments to end? You can select a specific count of recurring transactions, a date to stop, or allow it to be unending.

      • Payment End Date - When you choose ‘Date’ as the Stop Rule, this field is used to specify the date on which this recurring payment schedule will stop.
      • Number of Payments - When you choose ‘Count’ as the Stop Rule, this field is used to specify the total number of payments to process before this recurring payment schedule stops.

      • setting

  10. Click the Next button
  11. The final step displays the payment summary of the recurring schedule that you’ve built. Verify all details are accurate, then click the Charge One Time Amount (amount) and Start Recurring Billing button.

details

Note: When you set up Recurring Payment with a Payment Stop of Balance Due, the record will need to be created after you submit the payment so your schedule may not be accurate at first glance. You will need to update the Chargent Order to Subtotal field to accurately determine the Balance Due..




Chargent Order Recurring Billing

In order to set up Recurring Charges directly from the Chargent Order (versus using the Chargent Anywhere Payment Console above), you will need to create a new Chargent Order record as outlined in the Using Chargent document. Some additional fields need to be set in order to process recurring / subscription billing. Here you will find a list of Recurring Billing options and how they work with Recurring Billing.

Payment Status

Chargent requires a value of "Recurring" to include a record in its batch. There are four Payment Status options that can regulate how Recurring transactions work.

  • Recurring: Allows the record to be picked up in the batch for processing based on the frequency, and Payment Start Date.
  • Error: If Chargent discovers a problem with the transaction such as a declined form of payment, the payment status will change to "Error" and no further transactions will be processed until the status is changed back to "Recurring".
  • Stopped: You may use the "Stopped" status to temporarily pause recurring transactions.
  • Complete: When Chargent reaches a stop event, such as Balance Due, End Date or Count, it will change the status to "Complete".

Payment Frequency

The Payment Frequency field tells the batch how often to process a payment. This field needs to be set in order for recurring payments to occur. Chargent will look at the last recurring transaction record, check the frequency, then determine by the other Recurring fields if the payment should be processed. Here are the different frequencies that can be set and what they mean.

  • --None-- (default) - This will not be processed in the Recurring Billing batch
  • Once - a single transaction will occur on the Payment Start Date
  • Daily - one transaction per day that the schedule process is executed
  • Weekly - one transaction per calendar week on the same weekday
  • Biweekly - one transaction every two weeks on the same weekday
  • Monthly - one transaction per calendar month on the same day as the Payment Start Date
  • Bimonthly - one transaction every two months on the same day of the month
  • Quarterly - one transaction per every three months on the same day of the month
  • Semiannual - one transaction per every six months on the same day of the month
  • Annual - one transaction per every year on the same day
  • Biennial - one transaction per every two years on the same day

frequency

Note: There is a difference between pressing the Manual Charge button and the "Recurring" transactions that occur in the batch. As such, if you are collecting a down payment and setting up Recurring billing, you should set the Payment Start Date to date you wish the next transaction to occur, to prevent it from running prematurely. This can lead to your customer getting charged twice.


For more information see What Determines Recurring Charges? below.

Payment Stop

The Payment Stop field is dependent on Payment Frequency. This field determines when transactions should stop running. Chargent offers you four options to manage the payment schedule of a recurring transaction. If this field is left blank, the payment schedule will run indefinitely.

  • Date - Chargent will process the last transaction on or before the Payment End Datedepending on frequency. Payment End Date needs to be set for this to end based on a date.
  • Count - Chargent will stop processing transactions when the number of approved recurring transactions equals the value in the Payment Count field. This is helpful to follow an agreed payment schedule based on number of payments instead of date.

  • Note: this only tracks against the total number of "Approved" recurring transactions and does not include manual transactions by hitting the Charge button. If you would like to monitor this field, you can display or report on "Transaction Count Recurring".


  • Balance Due - Chargent will continue to process transactions until Balance Due is less or equal to zero.

  • Note: If the number of payments exceeds the total balance due you may end up charging more than was intended, resulting in a negative Balance Due.

    Chargent recommends only using Balance Due when the Charge Amount is evenly divided into the Total.


  • Unending - Chargent will process transactions with no stop event for as long as the Scheduled Apex is automatically executed and the Payment Status remains as Recurring..

Charge Date

This optional field can be set to a value (1-31) and recurring charges will be done on that day of the month. Regardless of how long it took to get it paid last time. If a card is declined, then finally approved a week later, the customer will still be charged on the same date next month, rather than 30 days from the previous successful recurring transaction.

This field is not used in Daily, Weekly, or Biweekly recurring transactions, but will work for any time periods Monthly or above. If this field is set to 31, Chargent will automatically charge on the 30th for months with 30 days, or on the 28th/29th of February.

Next Transaction Date

Chargent runs its logic and indicates when the next recurring transaction is going to occur in this field. Useful for reporting, and double checking your configuration.

Please note that the Next Transaction Date field cannot be modified, as it is set automatically by Chargent when a record is saved. For this reason, we recommend setting it to Read Only at the Page Layout level (not the field level security level).

Other Transaction-Related Fields

  • Transaction Total: Transaction Total field represents the sum of all transactions including both charges and refunds.
  • Status: The Status field indicates the status of the Chargent Order. Based on the total minus all transactions, once the balance due is reached, the Status field gets updated to Complete.
  • Transaction Count: will display the sum total and number (respectively) of the Transactions related to this Chargent Order. Once the total of Approved charges equals the Total of the Chargent Order, the order is considered to be paid.
  • Payment Received: The Payment Receivedfield should automatically be updated to reflect this status after transactions are finalized, and has no impact on transaction behavior. Values for Payment Received include None, Partial and Full.
  • Balance Due: This field automatically calculates the difference between Amount and Transaction Total and is a useful field to display below or near Amount. Remember if "Manual Charge" is not checked, the Charge Amount will automatically reset to Balance Due.

Other fields that you may wish to send include:

  • Order Information field, which shows up as the Description in most gateways and email receipts to your customers.
  • Invoice Number. Not all gateways use the Invoice Number, but you may get more favorable rates if it is populated, and many companies use it for reconciliation.

Order Information and Invoice Number may be mapped to a different fields within your Gateway. Please check our Gateway Guides to make sure your Gateway has these fields mapped and which fields are mapped within your gateway.




Process builder and Validation Rules

Please be very cautious if you use the Process Builder, Validation Rules or Required fields on your Chargent Orders with recurring billing. Validation rules can prevent the Chargent Order from saving properly after a transaction occurs, and because Recurring transactions run in a batch you would only see the errors in the Apex Jobs monitoring page in Salesforce.

Certain validation rule problems can result in duplicate transactions, so please be sure to test any validation rules in Sandbox prior to deployment. Contact us for additional assistance.

Recurring Versus Manual Transactions

Chargent treats manual and recurring transactions separately. Many customers wish to charge the first transaction manually, to see if it goes through, before setting a recurring billing schedule.

The key thing to remember when running a manual transaction is that after you do a manual transaction, you need to set the Payment Start Date ahead a month or year, etc. to the day when you would like the customer to next be billed automatically, or use the new Charge Date field to indicate the day of the month when they should be billed. Because Chargent does not see manual charges as part of the recurring schedule, if you do not set the Payment Start Date ahead or the Charge Date is not populated, the following day it will once again attempt a transaction as part of its recurring schedule.

The Payment Start Date is the most effective way of preventing charges before a certain date, as Chargent does not evaluate records for possible charging until the Payment Start Date is today or in the past. So if my Charge Date is 15 and Payment Start Date is set for June 16th, the next transaction attempted will be July 15.

What determines a Recurring charge?

A record will only be considered for processing if the following criteria is met.

  • The Payment Status = "Recurring"
  • The Frequency is set
  • The Payment Start Date is set to a date prior to the batch run
  • The last transaction date was greater than the frequency.

    • Eg the last transaction was more than a month ago and frequency is monthly.
    • This only applies to transactions that are marked ‘Recurring’. If no transactions are present, or only manually run transactions not marked as recurring, then it would also be counted as outside the frequency and needing to be charged.

    Another consideration that determines if a transaction should be processed is the Charge Date.

  • Charge Date - If there is a specific day of the month the transaction should be processed.

If no Charge Date is set, Chargent evaluates the "last recurring transaction" and ensure that it has been the correct number of days since the last one was processed (9/15, 10/15, 11/15 if it was monthly). Chargent only looks at the date of the last recurring transaction that was successful (Response = Approved, Recurring = True, not voided).

Chargent Orders that meet the criteria will then be processed, and a transaction with the Recurring field = true will be created (assuming the charge is successfully approved).

recurring

Installment Payments

The Charge Amount field is the amount to be charged or authorized by the next transaction. If there are multiple charges, it will automatically reflect the Total of the Chargent Order, minus the total of past successful charges (also shown in the Balance Due field).

Check the Manual Charge field when you want to charge an amount different than the amount due on the Chargent Order, such as a fixed amount every month. This field prevents the Charge Amount from automatically being calculated and updated.

One thing to be aware of when using this manual override, however, is that your Charge Amount will not be prorated. So if the Amount is $100, and you set the Charge Amount is $30, Chargent will charge 4 x $30. The system does not automatically prorate the last amount to equal the remaining balance (if less than the Charge Amount).

To automatically set the Charge Amount to the final balance that is smaller than previous installments:

  1. Create a workflow rule that fires when the Payment Status is Recurring and the Stop is Balance Due
  2. Have it check the Charge Amount.
  3. If the Charge Amount is > Balance Due, set the Charge Amount to the Balance Due

When the next to last transaction gets run, the totals update and the charge amount would be updated at that time preparing it for the final charge.

Usage Examples

Charge a Credit Card manually from Salesforce, and then set a Recurring Payment schedule

  1. Recurring Payment Via Payment Console (Chargent Anywhere)

    • Click Payment Console
    • Select your Payment Gateway
    • If you have your Page setup to select Contacts select the contact from the dropdown, otherwise enter the credit card billing address.
    • Click Continue
    • Select the Recurring option and enter in Payment Details
    • Enter both the Initial Amount and Recurring Amount
    • Click Next
    • Set the Frequency and Payment Start
    • Optional (set the Payment Stop)
    • Optional (Set Day of the Month)
    • Click Next
    • Review the Scheduled Payments
    • Press the “Charge One Time Amount and Start Recurring Billing” button.

  2. Recurring Payment Setup from a Chargent Order (Sites Edition)

    • Enter a Subtotal or Total in the Chargent Order record
    • Set Manual Charge to "TRUE" and enter Charge Amount (this prevents the Charge Amount from recalculating based on Total minus Transaction Total)
    • Set Payment Method to "Credit Card"
    • Choose a Payment Frequency (anything from daily to Biennial)
    • OPTIONALLY choose a Payment Stop (Date, Count, Balance Due or unending)
    • OPTIONALLY choose a Charge Date to have the customer billed on the same date of the month
    • Set Payment Status to "Recurring"
    • Save the record

payment

Be sure to set your Payment Start Date to when the next transaction should process. The recurring batch will not recognize the initial charge using the charge button since the transaction record will not have the Recurring box checked.




Single Scheduled Transaction

To run a single scheduled charge in the recurring batch, first complete the Billing and credit card data as shown in the Recurring Billing setup above (Although it’s a one time charge Chargent still requires the recurring billing batch to pick it up automatically for a one time charge in the future).

  1. Set Payment Frequency to "Once"
  2. Set Payment Status to "Recurring"
  3. Set Payment Start Date to the date you want the single charge to run.
  4. Save the record



Recurring Billing Declines

If a card is declined as part of the scheduled Apex batch that runs recurring billing transactions:

  1. Payment Status will automatically change from Recurring to Error.
  2. Once you have received updated billing information, change the Payment Status back to Recurring.
  3. If you have processed a charge manually outside of the recurring billing schedule by clicking the Charge button, be sure to set the Payment Start Dateahead to the next time the record should be billed, to avoid a recurring charge the next time the batch runs.