At the time I was developing Drawbridge there was plenty of documentation written about implementing a shopping cart and collecting single payments with PayPal through various means (active merchant) but there wasn’t anything written on integrating recurring payments with PayPal since PayPal had just launched their recurring payment option (active merchant did not have PayPal recurring payment integration at the time). After finding and dissecting the PayPal SDK for Ruby on Rails I decided to use the callers in the SDK and tie them into the recurring payments.

Download and Install the PayPal SDK
You can download the full PayPal SDK to get an idea of how the basic transaction process works with Ruby on Rails, but you really only need the PayPalSDK Plugin (I couldn’t find any type of gem, so I have posted the files on my server.)

Onc you have downloaded the plugin, you will see three files in the “lib” folder:
caller.rb – which handles the request and transactions
profile.rb – which handles authentication information and end points
utils.rb – which includes logging utilities

The only thing I changed in these files was to move the credentials and endpoints out of profile.rb and into initializers/globals.rb, this way I can control where the transactions go depending on the environment — development environment to the PayPal sandbox for testing and the production environment to my real PayPal account and live server.

Update vendor/plugins/PayPalSDK/lib/profile.rb

# specify the 3-token values.
@@credentials =  {"USER" => API_USER, "PWD" => API_PASS, "SIGNATURE" => API_SIG }
# endpoint of PayPal server against which call will be made.
@@endpoints = {"SERVER" => API_SERVER, "SERVICE" => "/nvp/"}
# Proxy information of the client environment.
@@proxy_info = {"USE_PROXY" => false, "ADDRESS" => nil, "PORT" => nil, "USER" => nil, "PASSWORD" => nil }
# Information needed for tracking purposes.
@@client_info = { "VERSION" => "50.0", "SOURCE" => "PayPalRubySDKV1.2.0"}

Add this to config/initializers/globals.rb

# ==== PAYPAL INFORMATION =====
# Depending on environment, either send to PayPal sandbox or real account
# ENVIRONMENT: DEVELOPMENT
if ENV["RAILS_ENV"] == 'production'
  API_USER = "YOUR PAYPAL API USER NAME"
  API_PASS = "YOUR PAYPAL API PASSWORD"
  API_SIG = "YOUR PAYPAL API SIGNATURE"
  API_SERVER = "api-3t.paypal.com"
# ENVIRONMENT: PRODUCTION
else
  API_USER = "YOUR SANDBOX API USER NAME"
  API_PASS = "YOUR SANDBOX API PASSWORD"
  API_SIG = "YOUR SANDBOX API SIGNATURE"
  API_SERVER = "api-3t.beta-sandbox.paypal.com"
end

CreateRecurringPaymentsProfile
Now you can include caller.rb in your transactions  controller (require ‘caller’) which will allow you to use the “CreateRecurringPaymentsProfile” method in the “call” method. There are many options that can be included in this hash that can be found here, but the only required items for creating a new recurring profile are (or see full PayPal API list):

• CREDITCARDTYPE
• ACCT (credit card number)
• EXPDATE
• FIRSTNAME
• LASTNAME
• PROFILESTARTDATE
• BILLINGPERIOD
• BILLINGFREQUENCY
• AMT

You can also include a trial period. I use this with Drawbridge to allow new users to have a 30 day free trial. This means they will not be charged the monthly price until after the first 30 days (see full list here).

• TRIALBILLINGPERIOD
• TRIALBILLINGFREQUENCY
• TRIALAMT
• TRIALTOTALBILLINGCYCLES

There is much more information of what you can do on the PayPal Recurring Payments with PayPal Payments Pro page.

Using the Call method
Once you are familiar with what PayPal requires to create a recurring profile, using the call method in Ruby on Rails is pretty easy. Here is an example of how I use the call method and the variables I send. Obviously some of these items are sent from the form on DrawbridgeApp.com, but some are set in the hash.

def do_payment
  @caller =  PayPalSDKCallers::Caller.new(false)
  @transaction = @caller.call(
    {
      :PROFILEREFERENCE => @account.id,
      :method          => 'CreateRecurringPaymentsProfile',
      :amt             => @price,
      :currencycode    => 'USD',
      :paymentaction   => "Sale",
      :creditcardtype  => @creditCardType,
      :acct            => @creditCardNumber,
      :firstname       => @first_name,
      :lastname        => @last_name,
      :email           => @email,
      :zip             => @zip,
      :countrycode     => 'US',
      :expdate         => @expDate,
      :cvv2            => @cvv2Number,
      :ProfileStartDate => Time.now.strftime('%Y-%m-%d %H:%M:%S'),
      :BillingFrequency => 1,
      :BillingPeriod => "Month",
      :desc => "Drawbride Quote Manager",
      :note => "A note about the transaction",
      :TRIALBILLINGPERIOD => "Month",
      :TRIALBILLINGFREQUENCY => "1",
      :TRIALAMT => "0",
      :TRIALTOTALBILLINGCYCLES => "1"
    }
  )
end

You can check whether the transaction was successful by doing

if @transaction.success?
  # Do whatever
end

If everything is successful, save the returned PayPal recurring profile id to be used when referencing the account’s PayPal transaction history. If there is an error, PayPal returns the reason in it’s response. You can save and grab this message in a session by doing this:

# Get response from PayPal
session[:paypal_error] = @transaction.response
@response = session[:paypal_error]
@longmessage = @response["L_LONGMESSAGE0"]
# Send errors
flash.now[:warning] = @response["L_LONGMESSAGE0"]
render :action => "index"

Change Credit Card Numbers
What happens when a user needs to update their credit card number? Since PayPal doesn’t allow a recurring payment profile to change it’s credit card number, a new profile must be created for that account. This is quite unpleasant, but understandable. Here is the process I decided was the safest and most efficient.

Suspend the Current PayPal Profile
First suspend the current PayPal profile by using “ManageRecurringPaymentsProfileStatus” to have an action of “Suspend”:

@caller = PayPalSDKCallers::Caller.new(false)
@suspend = @caller.call(
  {
    :method          => 'ManageRecurringPaymentsProfileStatus',
    :profileid       => @account.paypal_id,
    :action          => 'Suspend',
    :note            => 'A note about what you are doing'
  }
)

Create a New PayPal Profile

Then create a new PayPal profile for the user, using their new credit card information. It is VERY important that you update the PayPal profile id in your database and also start the new recurring date the same as the suspended account, otherwise you will charge the user again. First check that the account was suspended and then create a new PayPal profile by doing:

if @suspend.success?
  # NOW WE CREATE A NEW RECURRING PAYMENT PROFILE
  # *NOTE: USE THE CURRENT BILLING DATE AS TO NOT BILL MORE THAN ONCE IN THE MONTH
  @caller =  PayPalSDKCallers::Caller.new(false)
  @transaction = @caller.call(
    {
      :PROFILEREFERENCE => @account.id,
      :method          => 'CreateRecurringPaymentsProfile',
      :amt             => @price,
      :currencycode    => 'USD',
      :paymentaction   => "Sale",
      :creditcardtype  => @creditCardType,
      :acct            => @creditCardNumber,
      :firstname       => @first_name,
      :lastname        => @first_name,
      :email           => @email,
      :zip             => @zip,
      :countrycode     => 'US',
      :expdate         => @expDateYear,
      :cvv2            => @cvv2Number,
      :ProfileStartDate => @account.nextPayPalBillingDate.strftime('%Y-%m-%d %H:%M:%S'),
      :BillingFrequency => 1,
      :BillingPeriod => "Month",
      :desc => "Drawbride Quote Manager",
      :note => "UPDATED CREDIT CARD"
    }
  )
end

To do the above “:ProfileStartDate”, you will need to get the next billing date. I created a method in models/account.rb (where I track my PayPal profile):

def nextPayPalBillingDate
  # The PayPal next billing date is based on when the account was created
  # It assumes that this was when the credit card was charged for the first time
  curdate = Time.now
  unless paypal_created_at.nil?
    accountdate = self.paypal_created_at
    new_start_date = Time.parse("#{curdate.strftime('%Y')}-#{curdate.strftime('%m')}-#{accountdate.strftime('%d')} #{curdate.strftime('%H:%M:%S')}")
    # If the date is less than this month and days we move the start date to next month
    # (i.e. curdate = 10/16/08 & new_start_date = 10/14/08)
    if new_start_date <= Time.now
      curdate = Time.now + 1.months
      new_start_date = Time.parse("#{curdate.strftime('%Y')}-#{curdate.strftime('%m')}-#{accountdate.strftime('%d')} #{curdate.strftime('%H:%M:%S')}")
    end
    return new_start_date
  else
    return Time.now
  end
end

This way you can easily set

:ProfileStartDate => @account.nextPayPalBillingDate.strftime('%Y-%m-%d %H:%M:%S'),

Reactivate Suspended Profile on Failure
If the credit card is invalid, does not have enough funds, or whatever else happens to return an error when creating a new PayPal Recurring profile, the suspended account must be reactivated. This is exactly the same process as suspending the profile, except you would just set the action to “Reactivate”.

else
  # CREATE FAILED SO WE MUST REACTIVATE SUSPENDED ACCOUNT
  @caller = PayPalSDKCallers::Caller.new(false)
  @reactivate = @caller.call(
    {
      :method          => 'ManageRecurringPaymentsProfileStatus',
      :profileid       =>  @account.paypal_id,
      :action          => 'Reactivate',
      :note            => 'UPDATED CREDIT CARD'
    }
  )

  session[:dcc_response]=@transaction.response # this is actually the create response
  @response = session[:dcc_response]
  flash[:warning] = @response["L_LONGMESSAGE0"]
  redirect_to :action => "somewhere"
end

What Else?
Hopefully this will help answer some of the questions I originally had when I had set up PayPal Recurring Payments for other developers trying to accomplish the same thing. Here are a few other things:

• You can sign-up for the PayPal recurring payments here: https://www.paypal.com/cgi-bin/webscr?cmd=xpt/Marketing/general/ProRecurringPayments-outside. You will need to have a PalPal pro account first for $30 per month and then you can add the recurring payment plan on to the service for an extra $30 per month. So all together you will be paying around $60 per month.

• You will definitely need an SSL certificate. These are pretty easy to install, especially if you are using a large host. I purchased mine from GoDaddy.com for $29.99 per year and have everything hosted at MediaTemple.net (which made it extremely easy to install the certificate).

• PayPal Pro Recurring Payments: https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=developer/e_howto_api_WPRecurringPayments

• PayPal Ruby on Rails SDK (this is not the recurring payments but is very helpful): https://cms.paypal.com/cms_content/US/en_US/files/developer/PP_Ruby_NVP_SDK.zip

• The PayPalSDK Ruby on Rails plugin I used: http://brandonpassley.com/wp-content/uploads/2009/04/paypalsdk.zip

Questions or Comments
Please feel free to contact me with questions or comments. I am 100% sure I left something out, so please don’t hesitate to add to this, or ask me questions — I will respond.

I wanted to use Sparklines on a project I had been working on in Ruby on Rails. There are plenty of resources for installing the Sparkline gem, but I couldn’t find much on actually implementing them. I created a quick script that could render sparklines with variables I could send from the URL. (NOTE: This could probably be written better, but it worked for me.)

You will need to get the RMagick and Sparkline gems:

$ gem install rmagick
$ gem install sparklines

Here is what your action (apps/controllers/controller_name.rb) would look like:

def sparkline
  require 'RMagick'
  require 'sparklines'
  respond_to do |format|
    data = params[:d]
    params[:h].blank? ? (height = 40) : (height = params[:h])
    params[:s].blank? ? (step = 4) : (step = params[:s])
    params[:c].blank? ? (color = "2A5DB8") : (color = params[:c])
    params[:t].blank? ? (type = "smooth") : (type = params[:t])

    data = "0" if params[:d].blank?
    format.png do
      sparkline = Sparklines.plot_to_image(
                                    data.split(",").collect { |d| d.to_i },
                                    :type => type,
                                    :upper => 0,
                                    :above_color => "##{color}",
                                    :line_color => "##{color}",
                                    :step => step,
                                    :height => height
                                    )
      send_data sparkline.to_blob,  :filename => "sparkline.png",
                                    :disposition => 'inline',
                                    :type => "image/png"
    end
  end
end

Don’t forget to add the sparkline to your routes (config/routes.rb):

map.sparkline      '/sparkline', :controller => 'graphs', :action => 'sparkline'

I’ve been listening to Ari Hest for a few years now and still haven’t gotten tired of his music. Make sure to check out his new site.

[ Visit the Ari Hest website ]

Ari Hest Screenshot

Design and function of the “Boards”
The design is information driven. I wanted to keep the design simple and focused and out of the way of the information the user is trying to find. With so much information, the most logical solution was to create individual boards that displayed specific search driven results. These boards are extremely versatile and can be customized to call and display any information from the database. For example one board could simply be “Top Websites” where another board could be “Top Websites by Females”. Each board is also self contained and paginates the results. These boards carry throughout the website. Whether the user is on the homepage or on a website’s details page or on the search page, the boards stay consistent.

The WebbChange SmartSearch
The search results that can be populated (user info stays confidential, of course) from the information WebbChange stores is amazing. If you are looking for what users in Australia who are 20 to 30, who don’t smoke and who enjoy “Horses” value, WebbChange will show you. We have coined the term “Social Search Engine” because it populates its results based on each user’s interests, networks, location, etc. and then organizes them by top coin amounts. Even Google and Yahoo don’t do this ;)

The future of WebbChange
We have sooo many features in development and planned for the future from personalization of a user’s homepage, top website competitions, to bringing WebbChange out of the “web”. Make sure to keep checking on WebbChange.com and on my personal site for upcoming changes.

[ Visit WebbChange.com ]

Therefore, we focused on typography and movement. The UI consists of a plane and a grid of every page laying flat on it. Any internal link the user follows does not load a new page, but rather moves the entire plane and grid to the appropriate “slide”. This movement is not only intriguing, but begins to create interesting layouts since a portion of each adjacent “slide” peaks into the browser window.

Development Notes
Because of the nature of the site, I built a custom content management system (CMS) with PHP/MySQL to work specifically with the difficult front-end layouts. One of the most interesting features no one would see is that Parrish only has to update the basic content in the CMS and the front-end will determine which of the three layouts it should use based on images, text, files, etc. The very cool sliding feature uses the MooTools JavaScript library. This would have gotten a little hairy without it.

Final Thoughts
A text-based website does not have to be boring.

[ Visit the Parrish Hanna site ]

[ Visit the DrawbridgeApp.com site ]

[ Visit the ETC ComputerLand website ]
[ Download the PDF welcome packet ]

This was a welcome packet that was designed to give new customers a general overview of everything that ETC ComputerLand could do for them.

These business cards deliver the first taste of the ETC brand. The clean typography, white space and simple color scheme show a professional, contemporary brand.

These business cards deliver the first taste of the ETC brand. The clean typography, white space and simple color scheme show a professional, contemporary brand.

If you’re in the mood for folk-ish music to ease (or not ease) the soul check out William Fitszimmons.

[ Visit the William Fitszimmons site ]

This wasn’t an easy process considering there were over 11 main categories to manage, each having one or more sub-categories. From customers, vendors and salespeople to inventory and reports, the software had to manage everything, but most importantly had to tie all of these areas together into one universal work flow.

Team members: Brandon Passley, Graphic Design/Electronic Visualization; Jack Fisher, Graphic Design; Gene Parcellano, Graphic Design; Camille Mankus, Graphic Design; Anna Trzyna, Electronic Visualization; Santi Vitayaudom, Electronic Visualization;

[ more information ]