Recurring Billing

Related Links: Recurring Postback

When a transaction is initially submitted for processing, recurring details may be passed as part of the form that will automatically create future recurring charges, based on the details that you provide. In addition, you may also modify previously submitted transactions and mark them as recurring. This is done via the Transaction Listing.

The Recurring Billing Module is quite sophisticated, but is easy to use. There are two aspects to the module, as explained below.

Read the RESTRICTIONS & CONSIDERATIONS below before using this function. As always, test your forms before making them live.

The Recipe Builder

The Recipe Builder enables you to create pre-set recurring data. Each "recipe" may be used for any transaction. The Recipe Builder allows you to name your recipes and specify whether an associated transaction will repeat every x number of days, every x weeks on specific days, every x months on specific days of the month, or only as scheduled using a 'scheduled' recipe. You may create as many recipes as needed.

For example, you may create recipes such as the following:

Recipe Name Repeat
daily Every day.
monthly13 Every 1 month on the 13th day of the month.
threeweeksun Every three weeks on Sunday.
6monthlast Every 6 months on the last day of the month.
scheduled Only when scheduled.

If you are logged in, you may use the Recipe Builder to create a recipe. You may also view your Recipe List. (Recipes may be edited from the list.)

Scheduled Recipes

Using a scheduled recipe allows you to run ALL transactions linked to a recipe at a date that can be explicitely controlled and scheduled manually using the scheduling tool. The scheduling tool may be accessed from your Recipe List. The scheduling tool is only available for scheduled recipes.

Delay Period:  You may wish to prevent a transaction from recurring too soon after the initial transaction is processed. The Delay Period is the number of days after the original transaction before it is eligible for a scheduled recurrence.

Initiating Recurring Transactions

Option 1:
Passed with original transaction

Recurring transactions may be initiated at the time the original transaction is processed. To initially set a transaction as recurring, simply add the following input fields to your order form. In this example we'll use the "monthly13" recipe from the examples above and we'll have the transaction recur six times:

<input type="hidden" name="recur_recipe" value="monthly13">
<input type="hidden" name="recur_reps" value="6">

The recur_recipe field value should contain the name of the recipe that you'd like to use for the transaction. You create the recipe name when using the Recipe Builder.

The recur_reps field value should contain the total number of repetitions that should be initiated for the transaction. This is in addition to the original instance of the transaction.

As you can see in this example, in addition to the initial transaction, new transactions will be processed each month for the following six months on the 13th day of each month.

Optional Split Recurring Billing: Merchants may submit two separate transaction totals for recurring billing: one for the initial transaction and one for future recurring transactions. The merchant may also submit a unique description to be included with the recurring confirmation email message. The required fields to be used for split billing are:

<input type="hidden" name="recur_total" value="50.00">
<input type="hidden" name="recur_desc" value="Enter a description here.">

The recur_total field value should contain the transaction total to be used for all future recurring transactions. Note that this value will NOT be used for the initial transaction.

The recur_desc field value should contain the description to be used for all future recurring transactions. Note that this value will NOT be used for the initial transaction.

Split recurring billing is only allowed for transactions whose recipe allows it. Split recurring billing must be allowed at the time the recipe is created. It may also be enabled later by editing the recipe.

Option 2:
Manually scheduled after the original transaction

From the Transaction Listing, click on the XID of any transaction. You will be taken to the transaction detail page. If the transaction can be set as recurring, you will see a "Recur" button. From here you may update, change, or cancel the recurring settings for the transaction.

Placing Recurring Transactions On Hold

The gateway allows merchants to put specific transactions "on hold" to temporarily prevent recurring billing attempts. The Recurring On-Hold feature allows a merchant to toggle recurring on and off for specific transactions, without changing the number of remaining repetitions for that account. To place a transaction on hold, access the specific transaction (either in the Recurring History interface or in the Transaction Detail interface) and click on the "On Hold" toggle (which is a green "No"). A dialogue box will display verifying that you want to activate the hold for this transaction. Click "OK". The setting will change from "No" to "Yes". To take the transaction off hold, follow the same procedure (but the toggle will display a red "Yes").

Hold On Failure

If the Hold On Failure feature is enabled in a recipe, a failed recurring credit card billing will automatically place a transaction on-hold to prevent future billing attempts so that account information can be updated (either by the merchant or the customer). When this is triggered by a failed transaction, the merchant will be notified by email in the Recurring Failure email and in the Recurring Postback (using the "on_hold" parameters). This feature is only available for credit card transactions.

Allowing Customer Billing Updates

Merchants can opt to let their customers update their own credit card billing information for recurring charges. This feature is only available on recurring recipes that have been enabled for "Allow Customer Update" - and can ONLY be used for credit card transactions. This can be enabled for new and existing recipes. When a recurring transaction is successful or fails, an email including a link for the secure update interface will be generated to the cardholder. Following the simple instructions, they can update their own billing information. If the update was necessary because a recurring attempt had failed, a transaction will be attempted to bring the missed recurring billing up to date. Most merchants choose to use this feature in conjunction with the "Hold on Failure" recurring function - so that when a transaction fails, the recurring is put on hold (to prevent future attempts), and the update link is sent out. A merchant can also resend confirmation emails including the link to their customers from the Transaction Options area of the Transaction Listing.

Because the token is unique for each cardholder, you can use the data in the recurring postback to generate and display your own link to the system. The "Recurring Postback" and "Lookup" parameter is called "billing_update_token". It is 60-80 characters and must be appended to the following URL:

Restrictions & Considerations

  • You may cancel a recurring transaction at any time by setting the remaining repetitions to zero.
  • Only one recurring recipe may be used per transaction.
  • The number of repetitions is only decremented after a successful transaction.
  • Recipes cannot be deleted once they are created. However, you may change the recipe associated with a specific transaction.
  • Email confirmation letters will be sent to the customer and merchant each time a recurring transaction takes place. The letter will include the history of the recurring transaction and the number or repetitions remaining. You may elect to turn off customer confirmation email letters via your Account Settings.
  • Recurring transactions will be attempted multiple times on the specified recurring date. If the transaction fails all attempts during that day, you will receive an email notification. A failed recurring transaction will not affect future repetition attempts.
  • The Allow Customer Update and Hold On Failure features are only available for credit card transactions.
  • Recurring transactions have their own AVS setting. By default, your AVS setting for recurring transaction is NONE. This is very important since your customer may have a different address when the transaction is attempted again. If you would like to change your recurring AVS setting, please do so via your Account Settings.