Recurring Billing Basics

The Scenario

A merchant has several monthly service plans customers can choose from that vary in price. The merchant would like to setup the recurring billing so that the customer is automatically set up to be charged the appropriate amount on the preferred day of each month.

There are multiple ways that merchants can setup recurring billing with us. The approach described in this article has Braintree doing the monthly billing once the customer is signed up versus the merchant maintaining the billing data on their side and sending API calls on the desired date.

The Setup

Managing recurring billing is extremely simple with Braintree. For the most part, it can be completed via the API. The one exception is the initial set up of your specific plans which is done via the Virtual Terminal. There is not a lot of logic written into the Recurring Billing API because we feel it provides greater flexibility, which you’ll see when it comes time to add a customer to a plan.

Setting Up A Plan

The first step is to add a plan under Recurring -> Add Plan.

You have the ability to set up the following parameters that accommodate your billing needs: 1. Amount 2. Frequency – e.g. every 30 days, 1st day of the month, etc. 3. Duration – e.g. only four times, perpetually, etc. 4. Plan descriptor – SKU. We recommend you choose a simple name for the HTTP variable. If you choose a longer SKU name remember to escape the value, like ‘A%20Monthly%20Plan’.

For this example, we will use the following parameters: 1. Amount – $10 2. Frequency – 1st of each month 3. Duration – until canceled 4. Plan Descriptor – monthly

After creating this plan, you can view it in the Virtual Terminal under Recurring -> List Plans. That’s basically all you need to do to setup recurring billing plans. Now, on to application integration.

How To Do It

We’ve already setup our plan in the Virtual Terminal and now we can start to administer customers to it via the API. The important parameter to remember when dealing with recurring billing is product_sku_X where ‘X’ is a counter of the number of plans that a customer is associated with. Note that a customer can be associated with multiple plans. Also note that a customer can only be added to a recurring billing plan along with a transaction. Let’s start by setting up our regular credentials.

username=demo&password=password

Adding Users

Let’s start by adding a customer to the ‘monthly’ plan. This will mean that we’re going to add product_sku_1=monthly on to our query parameter string. Adding a customer to this SKU means that they will be charged on the 1st of month $10.00.

This will leave us with the following:

username=demo&password=password&product_sku_1=monthly

As mentioned before, you need to run a transaction when adding a customer to a billing plan. For this, you have two options 1) charge the customer the full or pro rated amount of the plan or 2) do a $1.00 auth (that disappears in a few days) to validate the card.

When considering your options, first realize that when the cc # is entered into our system, the only validation check we do is Luhn-10, which validates the # of digits is correct. We can’t do any further validation until we hit the issuing bank with a auth request.

If you choose to do the $1.00 auth, you can check for correct cc #, Address Verification (AVS) and CVV2 (three or four digit code). Adding an authorization for $1.00 and passing the credit card information will leave our query as the following:

username=demo&password=password&product_sku_1=monthly& \ 
ccnumber=4111111111111111&ccexp=1010&type=auth&amount=1.00

In most cases, the customer will never see this authorization on their account, it drops off within a day or so.

If you are not giving any sort of ‘grace’ period, meaning that you’re going to charge them a pro-rated amount until the next billing cycle then we recommend that the amount you are charging them be calculated as the monthly value divided by how many days are left in the current billing cycle. In our example, we bill $10.00 on the 1st. If a customer signs up on the 20th we would charge $3.33 ($10.00 / 30 days in a month) X 10 days = $3.33. This will leave us with this:

username=demo&password=password&product_sku_1=monthly& \ 
ccnumber=4111111111111111&ccexp=1010&type=sale&amount=3.33

Make sure that you save the transaction ID in the gateway response, you’ll need it to delete a customer from the plan and track what customer is a part of what plan. For the time being, you have to manually track who’s a member of what plan in your application. This isn’t as difficult as it sounds since if the transaction ID is kept from the previous step. We’re going to be added better reporting information on the Query API for tracking this in the future.

Deleting Users

Deleting a customer from a recurring billing plan is simple. We just need to add a parameter called delete_recurring with the value to be the transaction ID of the transaction that added them to the plan. Deleting a customer from a recurring billing plan looks like this:

username=demo&password=password&delete_recurring=1234567

Switching Users To A Different Plan

When someone upgrades to a different plan you’ll need to simply delete them from a current plan and add them to a different plan. We can accomplish this all in one transaction. This transaction looks like a delete and an add all at the same time. Here I remove a customer from the ‘monthly’ and plan add them to the ‘personal’ plan which costs $16.00 a month and charge them a pro-rated amount for the difference:

username=demo&password=password&delete_recurring=1234567& \ 
product_sku_1=personal&ccnumber=4111111111111111&ccexp=1010& \ 
type=sale&amount=6.00

If they are downgrading their account, you can either chose to do a refund transaction or it you want to credit them for the future, do an auth for $1.00.

Discussion

Please ask any questions on this article in the Articles Discussion Forum.