Back in late 2005 when Rails hit the mainstream, we were eager to do a complete bottom-up rewrite.  However, management was rather concerned that our customers would react negatively to such a radical technology change.  Would people trust their financial data with an unproven web framework that had only recently been publicly released?  To stay on the safe side, we decided to disguise the new Rails app to appear as though it was still the old PHP version.

Thanks to Rails’ flexibility, this was surprisingly easy to achieve.  The heart of the disguise is a single line added to our routes.rb file:

  map.connect ':fake_filename.php', :controller => 'php', :action => 'dispatch'

This takes what appear to be requests for php files and sends them over to our PhpController controller.  In the dispatch action, we lookup the “filename” that was requested and map it to an action and a controller to actually handle the request.

class PhpController < ApplicationController
  FILENAME_ROUTES = {
    'about' => { :controller => 'about', :action => 'index' },
    'pricing' => { :controller => 'pricing', :action => 'index' },
    # ...snip…
  }

  def dispatch
    redirect_to :controller => FILENAME_ROUTES[params[:fake_filename]][:controller], :action => FILENAME_ROUTES[params[:fake_filename]][:action]
  end
end

Sure, there is a little performance hit with the redirect, but we’ve found that most users don’t really notice.

We use Apache (with mod_proxy) to send requests to Webrick application servers.  Although it uses a lot of memory, our Webrick cluster has held up surprisingly well.  We’ve been meaning to switch to something more modern like FastCGI + lighttpd so we’ll keep you posted.

Anyway, I hope that this hasn’t come as too much of a shock to anyone. We’ve been running this setup for quite a while and felt it was time to come clean (although some people have suspected that this is what we were up to for some time now).

Creating an invoice with a return-to-merchant link.
If you already have code that creates new invoices, adding return-to-merchant links when creating an invoice means adding one more element to the <invoice /> element in your request: <return_uri>YOUR URL HERE</return_uri>. The URI from your API request will be used verbatim, so remember to include the http:// or https:// at the beginning.

<?xml version="1.0" encoding="utf-8"?>

  
    2

    
      
    

    http://invoices.example.com/thanks-for-paying
  

The <request_uri /> element is supported in invoice.update, and it’s returned from invoice.get requests.

What will your customers see?
The return-to-merchant link is shown to your customers only after they’ve paid their invoices. The payment summary page has an extra link, which will send them to… well, anywhere you want. We’ve also streamlined the payment landing page so that it acts more like the rest of FreshBooks: it now has a clear confirmation message, then the next steps to take, and finally extra information.

Recurring profiles can have return-to-merchant links too.
You can include <return_uri />s in recurring.create and recurring.update, too. When an invoice is created from a recurring profile, some variable substitution takes place, so that the generated link can include a reference back to the invoice.

Let’s say you set your recurring profile’s return_uri to

http://invoices.example.com/invoices/::invoice id::/paid

The invoice ID (invoice_id in the invoice.get API response) of the generated invoices will show up in each invoice’s <recurring_uri> - for example, if the generated invoice ID is 16, then the return-to-merchant link will point to

http://invoices.example.com/invoices/16/paid

This works with ::invoice number:: and the invoice_number of the generated invoices, too.

What about…
There are lots of things we’d like to do with this in the future to make the FreshBooks API support more scenarios. I’m sure some of you have software you’d like to have notified when a customer pays an invoice, for example - that comes up a lot with PayPal’s basic integration, which uses a similar “return to merchant” feature to implement notifications. We’d love to hear other ways of extending the API to better fit how you want to use FreshBooks.

1. Click on your white “My Account” link on the top right corner.

2. Click on your “FreshBooks API” sub-tab on the top right.

3. Click on your checkbox next to “Yes, I agree to the API terms of service”.

4. Your “API URL” and “Authentication Token” will become visible on your screen.

We hope you have enjoyed this update.

Recurring invoices now default to auto-bill
We have changed the default so that recurring invoices automatically bill client credit cards for future invoices, rather than asking the client if they’d like this. We feel this fits better with everyone’s expectations of what should happen. You should expect less confusion around customers needing to enter credit cards multiple times. Note that you will need to purchase enough auto-bills in your system.

Recurring profiles starting today will invoice immediately.
Previously, you could only create recurring profiles starting on a future date. Now, if you create a recurring profile with today’s date, an invoice will be created and sent immediately. The response XML includes the created invoice_id.

This means you can set up a recurring profile immediately at the time of initial purchase, and then immediately redirect your customer to pay the invoice. This should dramatically speed up the time it takes for you get paid, as well as lower attrition rates on payment.

Hopefully these changes will really help your business. Let us know how it goes!

Enjoy!