Find file
Fetching contributors…
Cannot retrieve contributors at this time
143 lines (104 sloc) 4.92 KB


This gem is a lightweight wrapper for the paypal adaptive payments API.

This is very much a work in progress! Use at your own risk or submit bug fixes :)

Before you need start, read the API manual and check out the forums on It'll be invaluable for parameters and error messages. The gem keeps the request/response as hashes so you will have to read the manual to make the proper calls. I made a few test cases for further examples at


Create paypal_adaptive.yml to your config folder:

  environment: "sandbox"
  username: "sandbox_username"
  password: "sandbox_password"
  signature: "sandbox_signature"
  application_id: "sandbox_app_id"

  environment: "sandbox"
  username: "sandbox_username"
  password: "sandbox_password"
  signature: "sandbox_signature"
  application_id: "sandbox_app_id"

  environment: "production"
  username: "my_production_username"
  password: "my_production_password"
  signature: "my_production_signature"
  application_id: "my_production_app_id"

You can also use ENV variables when specifying your configuration. eg. <%= ENV[''paypal.username'] %>

Make the payment request:

pay_request =

data = {
"returnUrl" => "", 
"requestEnvelope" => {"errorLanguage" => "en_US"},
"receiverList"=>{"receiver"=>[{"email"=>"", "amount"=>"10.00"}]},

pay_response =

if pay_response.success?
  redirect_to pay_response.approve_paypal_payment_url
  puts pay_response.errors.first['message']
  redirect_to failed_payment_url

Once the user goes to pay_response.approve_paypal_payment_url, they will be prompted to login to Paypal for payment.

Upon payment completion page, they will be redirected to

They can also click cancel to go to

The actual payment details will be sent to your server via "ipnNotificationUrl" You have to create a listener to receive POST messages from paypal. I added a Rails metal template in the templates folder which handles the callback.

Additionally, you can make calls to Paypal Adaptive's other APIs: payment_details, preapproval, preapproval_details, cancel_preapproval, convert_currency, refund

Input is just a Hash just like the pay method. Refer to the Paypal manual for more details.

Certificate validation

You can set the location of the .pem file you wish to use for SSL certificate validation in paypal_adaptive.yml for each environment, e.g.:

  environment: "sandbox"
  username: "sandbox_username"
  password: "sandbox_password"
  signature: "sandbox_signature"
  application_id: "sandbox_app_id"
  ssl_cert_file: "/path/to/your/cacert.pem"

If you don't set ssl_cert_file then paypal_adaptive will check for certificates in /etc/ssl/certs if this location exists, otherwise falling back to the cacert.pem file included with paypal_adaptive.


0.2.7 Refactored config file handling for better non-Rails support, thanks mreinsch and dave-thompson.

0.2.6 Fix for using correct status field in pre-approval, thanks nbibler. Fix for ruby 1.9.3, thanks deepj.

0.2.5 Fix for embedded payments, thanks rafaelivan. Fix for Rails 3.1.1, thanks synth.

0.2.4 Support for embedded payments. Issue #21 thanks rafaelivan. Shipping address, wrapper methods has return response object. Issue #22 thanks tsmango.

0.2.3 Using bundler for gem creation. Moved all code to paypal_adaptive dir. Added ExecutePayment call to request. Thanks Roger Neel.

0.2.2 Added support for ERB in the config file. Thanks DanielVartanov.

0.2.1 Fixed SSL bug. Thanks gaelian.

0.2.0 Thanks to seangaffney for set payment option support. Thanks to gaelian for ssl cert support. Changed tests to use relative paths.

0.1.0 Fixed IPN rails metal template by sending the correct params back: ipn.send_back(env['rack.request.form_vars']) Thanks to for fixing this.

0.0.5 Added Preapproval preapproval_paypal_payment_url along with test case.

0.0.4 Preapproval now returns a PaypalAdaptive::Response class. Added preapproval test cases.

0.0.3 Renamed PayRequest, PayResponse into Request, Response since other api calls use the class as well.

0.0.2 Fixed initialized constant warning.

0.0.1 First release.


Copyright (c) 2009 Tommy Chheng. See LICENSE for details.