Installing Ruby-PayPal

A lightweight ruby wrapper for PayPal NVP (Name-Value Pair) APIs. To install type the following at the command line:

  $ gem install ruby-paypal

Using Ruby-PayPal

It‘s critical that you understand how PayPal works and how the PayPal NVP API works. You should be relatively well-versed in the NVP API Developer Guide and Reference - see:

• www.paypal.com/en_US/ebook/PP_NVPAPI_DeveloperGuide/index.html
• cms.paypal.com/us/cgi-bin/?&cmd=_render-content&content_ID=developer/e_howto_api_soap_NVPAPIOverview

You should also visit and register yourself with the PayPal Developer Network and get a Sandbox account with in the PayPal Development Central (developer.paypal.com/).

Note that this library only supports the API signature method of securing the API credentials.

By setting Paypal.debug=true, the API will "pretty-print" the PayPal parameters to the console.

Direct Payment

To use credit card payment through PayPal, you need to use the DoDirectPayment APIs:

        username = <PayPal API username>
        password = <PayPal API password>
        signature = <PayPal API signature>

        ipaddress = '192.168.1.1' # can be any IP address
        amount = '100.00' # amount paid
        card_type = 'VISA' # can be Visa, Mastercard, Amex etc
        card_no = '4512345678901234' # credit card number
        exp_date = '022010' # expiry date of the credit card
        first_name = 'Sau Sheong'
        last_name = 'Chang'

    paypal = Paypal.new(username, password, signature) # uses the PayPal sandbox
    response = paypal.do_direct_payment_sale(ipaddress, amount, card_type,
                           card_no, exp_date, first_name, last_name)
        if response.ack == 'Success' then
          # do your thing
        end

The above code is for a final sale only.

Note that the credit card number is checked against a modulo-10 algorithm (Luhn check) as well as a simple credit card type check. For more information please refer to en.wikipedia.org/wiki/Luhn_algorithm and en.wikipedia.org/wiki/Credit_card_number

Express Checkout

To use the customer‘s PayPal account for payment, you will need to use the ExpressCheckout APIs:

<to be documented>

PayPal Subscriptions

PayPal Subscriptions is a service offering allowing you to sell subscriptions, consisting of an initial payment followed by several recurring payments. For a good technical overview, review the following guide:

• www.paypal.com/en_US/ebook/PP_ExpressCheckout_IntegrationGuide/RecurringPayments.html

Using the subscriptions service involve understanding the series of exchanges to perform using the NVP API. There are 3 key phases of a subscription:

1. Creating a subscription request (and button for the customer)
2. Customer review and confirmation on the PayPal site
3. Processing of a subscription agreement

Each phase involves specific APIs.

Phase 1 - Subscription Request

In this phase, the do_set_express_checkout method will be called. PayPal will return a token we can use in subsequent API calls.

Let‘s create a subcription request with the details of our subscription:

        subscription_request = create_monthly_subscription_request(
                name='_Why's Ruby Camping Adventures',
                id='MNWRCA',
                description='_Why's Ruby Camping Adventures - Monthly Tips And Tricks For Camping Development',
                invoice_number='INV20091122',
                amount='5.00')

Let‘s call do_set_express_checkout to get a token back:

        response = paypal.do_set_express_checkout(
                return_url='http://www.yoursite.com/subscription-confirmed',
                cancel_url='http://www.yoursite.com/subscription-aborted',
                amount='5.00',
                other_params=subscription_request)

        token = (response.ack == 'Success') ? response['TOKEN'] : ''

Let‘s use the token to create a PayPal button to request payment via the sandbox:

        form( { :method => 'post' ,
                                :action => 'https://www.sandbox.paypal.com/cgi-bin/webscr' #sandbox
                                } ) do

                        input :id => 'cmd', :name => 'cmd', :type => 'hidden',
                                  :value => "_express-checkout";

                        input :id => 'token', :name => 'token', :type => 'hidden',
                                  :value => "#{token}";

                        input :id => 'submit_subscription_request', :name => 'submit', :type => 'submit',
                                  :value => 'Subscribe Via PayPal'
        end #form

Phase 2 - Customer Review and Confirmation

The customer will see the details of the subscription agreement we created previously. Upon confirmation, PayPal will redirect the customer to the return_url we specified passing the token back as well as the payerid.

Phase 3 = Subscription Processing

First we will retrieve the details of the check-out:

        response = paypal.do_get_express_checkout_details(token)

Then we will execute the actual payment:

        response = paypal.do_express_checkout_payment(token=token,
                payment_action='Sale',
                payer_id=payerid,
                amount='5.00')

        transaction_id = response['TRANSACTIONID']

Now we can create the actual PayPal subscription

        response = @paypal.do_create_recurring_payments_profile(token,
                start_date='2009-11-22 14:30:10',
                profile_reference='INV20091122',
                description='_Why's Ruby Camping Adventures - Monthly Tips And Tricks For Camping Development',
                billing_period='Month',
                billing_frequency=1,
                total_billing_cycles=11,
                amount='5.00',
                currency='USD')

        profile_id = @response['PROFILEID']

The profile_id can then be used in the future to access the details of the subscription, suspend it, reactivate it or cancel it using the following methods:

• do_get_recurring_payments_profile_details

        response = paypal.do_get_recurring_payments_profile_details(profile_id)
  

• do_manage_recurring_payments_profile_status

        # Suspend
        response = paypal.do_manage_recurring_payments_profile_status(profile_id,
                action='Suspend',
                note='The subscription is being suspended due to payment cancellation by the customer')
  
        # Re-Activate
        response = paypal.do_manage_recurring_payments_profile_status(profile_id,
                action='Reactivate',
                note='The subscription is being reactivated due to new payment by the customer')
  
        # Cancel
        response = paypal.do_manage_recurring_payments_profile_status(profile_id,
                action='Cancel',
                note='The subscription is being cancelled due to cancellation of the account by the customer')
  

The customer information associated with the subscription can be retrieved using:

• do_get_billing_agreement_customer_details

        response = paypal.do_get_billing_agreement_customer_details(token)
  

Note: all subscriptions methods also accept an optional other_params hash for any other NVP you need to pass.

More information

Check for updates in our blogs:

• blog.saush.com
• blog.monnet-usa.com