A quick overview of integrating PayPal’s Recurring Payments into Ruby on Rails. With companies developing more and more software-as-a-service applications, developers are needing to accept and bill credit cards on a recurring basis (monthly, yearly, etc.). With PayPal’s new recurring payment API it has become much easier to integrate recurring payments into any Ruby on Rails application.

After finishing the majority of the development on DrawbridgeApp.com, a project proposal creator and manager, I realized other freelancers and small companies were also running into the same issues with managing the proposals they needed to deliver to clients. I decided to deliver Drawbridge to the public at a low monthly rate, jumping on the “software as a service” train. The issue with running software in return for a monthly payment is having the ability to take and, more importantly, save credit card numbers. These obviously must be saved through a third-party merchant account. After researching many options, I decided to go with PayPal — which may or may not have been the best solution, but this is about implementing the solutions.

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.