paypkg 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7a1b1e82c065451cb13a76219b3a7f1cc89f3103
-  data.tar.gz: 8e3d7e284685f149e6e3184177214483186a77eb
+  metadata.gz: b5b0aa6a615a910d02a4c57fa7c2a70fbf95eeb3
+  data.tar.gz: 1fd27b3481a219eb03e2c98d11e4fa1e7a24033c
 SHA512:
-  metadata.gz: 2a81c0cda26d8a17407a211c53d619c8c4120c033c639f41983d7cdec42afec95c0bb5239cea66b102e9aafa2d5345a535e9f4a5a59f4199c3f0f7cea754fe00
-  data.tar.gz: 6d204a7697be19548a9f9090a8b7c2d91f969fbc16fc4f8b740df08daa79e8b78c3f008bdcdaa48974a342402b7d15e81d1945841516b467c77abbf6ea370bca
+  metadata.gz: 59f31039f45400d9897354dde0e50aaa23226f1ceb623f42a8adc20fbf9d82cf170466097cbbff8a0204ce295fa95e9ea58701d1c48239c2d1fe2e150d7420e3
+  data.tar.gz: 115c69d5783457506a674ee76505818c4ce00e648e6af3a5996b7ee94fc2386c00b061a58f13e8d239a48717f15d2bc4f553b830e68f99e457558f97928db947

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+0.1.1
+-----
+* Added PaypkgResponse, a class that converts a hash equivilent of the json output to an object.
+  This will make it more compatible with existing code based on ActiveRecord.
+* Added more documentation. See the README.md file.
+* Split out all the PayPal functions into individual files so that new functions can be added
+  without risking damaging anything. This also makes it easier to add new functions to the gem.
+* Added a PaypkgTestController and a paypkg_test views folder that can be used for testing,
+  and seeing how to use the package.
+
+0.1.0
+-----
+* Created initial Pay Package gem and uploaded it to rubygems.org. There is no documentation yet.

data/README.md

@@ -0,0 +1,222 @@
+Copyright (c) 2014, Michael J. Welch, Ph.D. and Contributors. All Rights Reserved.
+Email: rubygems@czarmail.com
+
+This project is licenced under the [MIT License](LICENSE.md).
+
+
+###############
+### Install ###
+###############
+
+To install this gem, use:
+  gem install paypkg
+
+I also recommend pretty_inspect, which I use in my example below
+and in the test page:
+  gem install pretty_inspect
+  
+Add the following routes to your route file:
+  get   'paypkg_test/test1'           => 'paypkg_test#test1'
+  get   'paypkg_test/test2'           => 'paypkg_test#test2'
+  get   'paypkg_test/approved'        => 'paypkg_test#approved'
+  get   'paypkg_test/cancelled'       => 'paypkg_test#cancelled'
+
+Copy the files in the gem's test folder to the app/controllers and app/views, as appropriate:
+
+
+####################################
+### Setup the Configuration File ###
+####################################
+
+This gem requires a config file in config/paypkg.yml in your
+Rails project that looks like this:
+
+--- begin config/paypkg.yml -----------------------------------------------
+development:
+  client_id: 'AZPi5hCY-0SoaLmignRs9XV6N4mvRS2TVKFDF2ni53alKL0iJTvtcy9BSR4D'
+  secret: 'EDubEBAg_ZztC-_HlsW16IFZcxBIatFt7c0ILuxNTpWAVnvrsO9ywVxnHr7J'
+  uri_base: 'https://api.sandbox.paypal.com'
+  website: 'http://www.example.com:3000'
+
+test:
+  client_id: 'AZPi5hCY-0SoaLmignRs9XV6N4mvRS2TVKFDF2ni53alKL0iJTvtcy9BSR4D'
+  secret: 'EDubEBAg_ZztC-_HlsW16IFZcxBIatFt7c0ILuxNTpWAVnvrsO9ywVxnHr7J'
+  uri_base: 'https://api.sandbox.paypal.com'
+  website: 'http://www.example.com:3000'
+
+production:
+  client_id: 'AVWiuBCE6_ps2zCh0Qaq0MaIbP8v2bjfFnKH5esYR9v6sNvu-MzVeWny3crM'
+  secret: 'EKKoNhCgFn_0lmpUAxXir0ySN4cmaLzGugUmnkgZHR90Kg9Y_DFmJbI2H0Ee'
+  uri_base: 'https://api.paypal.com'
+  website: 'https://www.example.com'
+--- end config/paypkg.yml -------------------------------------------------
+
+See the sample in this gem under config/paypkg.yml.
+
+You have to place your client_id and secret in the file in place of these,
+and you have to replace the website with yours. Note that the production
+website has https, not http. If your production website is not encrypted
+with SSL, use http instead of https.
+
+
+######################
+### Testing in irb ###
+######################
+
+The Paypkg class can't see the session variable (because it's only visible
+in ApplicationController classes), so to test this interactively, go into
+your project and run "rails c" to start irb with a Rails environment, then
+create a session variable, and create an instance. You can then run the
+functions.
+
+Why can't I just use irb? Because you need the Rails environment.
+That's why the tests are supplied as a controller/views.
+
+
+######################
+### Using Bundler? ###
+######################
+
+If you're using bundler, you'll have to add 'paypkg' and 'pretty_inspect'
+to your Gemfile, then do a 'bundler install' to be able to use them.
+
+
+###############################
+### An Example in "rails c" ###
+###############################
+
+To use the example, by the way, you'll have to put in a 'CARD-XXX...'
+number of your own.
+
+Here is an example:
+
+devel@mail:~/czar$ rails c
+Loading development environment (Rails 4.0.4)
+irb(main):001:0> session = {}
+=> {}
+irb(main):002:0> pp = Paypkg.new session
+=> #<Paypkg:0x000000049f5138 @session={:paypal_authorization=>{:expires_after=>2014-04-19 04:54:05 +0000,\
+   :access_token=>"8PhJDJVg1mxxGUpSHj9RzzUxB0.sS0qiajx2Nxa1.Fg"}}, @mode=:development, 
+   @credentials={"client_id"=>"AZPi5hCY-0SoaLsvRSni5mignR3a9XlKL2TVKFDFV6N4m20iJTvtcy9BSR4D", 
+   "secret"=>"EDubEBAg_ZztC-_HlscxNTpWAVtFt7c0ILZW1BIaOnvrsux6IF9ywVxnHr7J",
+   "uri_base"=>"https://api.sandbox.paypal.com", "website"=>"http://www.example.com:3000"},
+   @website="http://www.example.com:3000", @uri_base="https://api.sandbox.paypal.com",
+   @http=#<Net::HTTP api.sandbox.paypal.com:443 open=false>,
+   @access_token="8PhJDJVg1mxxGUpSHj9RzzUxB0.sS0qiajx2Nxa1.Fg", @json=[], @hash=[], @status=[]>
+irb(main):003:0> @ok = pp.retrieve_credit_card('CARD-22T35414AU135641UKLX6GPQ')
+=> true
+irb(main):004:0> puts pp.json
+{"id":"CARD-22T35414AU135641UKLX6GPQ","state":"ok","payer_id":"admin","type":"visa",
+ "number":"xxxxxxxxxxxx0331","expire_month":"11","expire_year":"2018","first_name":"Betsy",
+ "last_name":"Buyer","billing_address":{"line1":"111 First Street",  "city":"Saratoga",
+ "state":"CA","postal_code":"95070","country_code":"US"},
+ "valid_until":"2017-02-02T00:00:00Z","create_time":"2014-02-03T18:43:10Z",
+ "update_time":"2014-02-03T18:43:10Z",
+ "links":[{"href":"https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-22T35414AU135641UKLX6GPQ","rel":"self","method":"GET"},
+ {"href":"https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-22T35414AU135641UKLX6GPQ","rel":"delete","method":"DELETE"},
+ {"href":"https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-22T35414AU135641UKLX6GPQ","rel":"patch","method":"PATCH"}]}
+=> nil
+irb(main):005:0> puts pp.status
+200
+=> nil
+irb(main):006:0> puts pp.mode
+development
+=> nil
+irb(main):007:0> puts pp.hash
+{:id=>"CARD-22T35414AU135641UKLX6GPQ", :state=>"ok", :payer_id=>"admin", :type=>"visa",
+ :number=>"xxxxxxxxxxxx0331", :expire_month=>"11", :expire_year=>"2018", :first_name=>"Betsy",
+ :last_name=>"Buyer", :billing_address=>{:line1=>"111 First Street", :city=>"Saratoga",
+ :state=>"CA", :postal_code=>"95070", :country_code=>"US"},
+ :valid_until=>"2017-02-02T00:00:00Z", :create_time=>"2014-02-03T18:43:10Z",
+ :update_time=>"2014-02-03T18:43:10Z",
+ :links=>[{:href=>"https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-22T35414AU135641UKLX6GPQ", :rel=>"self", :method=>"GET"},
+ {:href=>"https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-22T35414AU135641UKLX6GPQ", :rel=>"delete", :method=>"DELETE"},
+ {:href=>"https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-22T35414AU135641UKLX6GPQ", :rel=>"patch", :method=>"PATCH"}]}
+=> nil
+irb(main):008:0> puts pp.hash.pretty_inspect
+[
+  {
+    :id => "CARD-22T35414AU135641UKLX6GPQ",
+    :state => "ok",
+    :payer_id => "admin",
+    :type => "visa",
+    :number => "xxxxxxxxxxxx0331",
+    :expire_month => "11",
+    :expire_year => "2018",
+    :first_name => "Betsy",
+    :last_name => "Buyer",
+    :billing_address => {
+      :line1 => "111 First Street",
+      :city => "Saratoga",
+      :state => "CA",
+      :postal_code => "95070",
+      :country_code => "US"
+    },
+    :valid_until => "2017-02-02T00:00:00Z",
+    :create_time => "2014-02-03T18:43:10Z",
+    :update_time => "2014-02-03T18:43:10Z",
+    :links => [
+      {
+        :href => "https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-22T35414AU135641UKLX6GPQ",
+        :rel => "self",
+        :method => "GET"
+      },
+      {
+        :href => "https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-22T35414AU135641UKLX6GPQ",
+        :rel => "delete",
+        :method => "DELETE"
+      },
+      {
+        :href => "https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-22T35414AU135641UKLX6GPQ",
+        :rel => "patch",
+        :method => "PATCH"
+      }
+    ]
+  }
+]
+=> nil
+irb(main):009:0> r=pp.response
+=> #<PaypkgResponse:0x000000045fe7a0 @id="CARD-22T35414AU135641UKLX6GPQ", @state="ok", @payer_id="admin", @type="visa", @number="xxxxxxxxxxxx0331", @expire_month="11", @expire_year="2018", @first_name="Betsy", @last_name="Buyer", @billing_address=#<PaypkgResponse:0x000000045fd170 @state="CA", @line1="111 First Street", @city="Saratoga", @postal_code="95070", @country_code="US">, @valid_until="2017-02-02T00:00:00Z", @create_time="2014-02-03T18:43:10Z", @update_time="2014-02-03T18:43:10Z", @links=[#<PaypkgResponse:0x00000004603f20 @href="https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-22T35414AU135641UKLX6GPQ", @rel="self", @method="GET">, #<PaypkgResponse:0x00000004603728 @href="https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-22T35414AU135641UKLX6GPQ", @rel="delete", @method="DELETE">, #<PaypkgResponse:0x000000046030c0 @href="https://api.sandbox.paypal.com/v1/vault/credit-card/CARD-22T35414AU135641UKLX6GPQ", @rel="patch", @method="PATCH">]>
+irb(main):010:0> r.billing_address.line1
+=> "2945 Hampton Ave"
+irb(main):009:0>
+
+
+############################
+### PaypkgResponse Class ###
+############################
+
+The class PaypkgResponse is used to objectize a response hash (or almost any
+hash object). Free free to use it separately in other projects, if it works for you.
+
+To get the PayPal response in an object format, after a successful call, use response = pp.response.
+If you want this, for example:
+
+  payment_data = pp.hash.last
+  @amount = payment_data[:transactions][0][:related_resources][0][:sale][:amount][:total]
+
+you would use this:
+
+  payment_data = pp.response # this will convert pp.hash.last
+  @amount = payment_data.transactions[0].related_resources[0].sale.amount.total
+
+This is provided to be more compatible with views using ActiveRecord conventions.
+
+
+###############
+### Caveats ###
+###############
+
+Caveats:
+  1. This class is designed to do the most common things most people want
+     to do, but without much fuss.
+  2. You can make your own calls to PayPal by creating a json data string
+     and calling call_paypal. See the cURL commands in the documentation
+     to see how the json should be configured. Look at the existing methods
+     in lib/paypkg to see how they are structured. Just add yours to the
+     lib/paypkg folder, and it will be available after the gem is
+     reloaded. Refer to https://developer.paypal.com/webapps/developer/docs/api/
+     for PayPal Restful calls.
+  3. Be sure to look at the PaypkgTestController for information on how
+     to use the calls in your appication.
+

data/config/paypkg.yml

@@ -0,0 +1,18 @@
+development:
+  client_id: 'AZPi5hCY-0SoaLmignRs9XV6N4mvRS2TVKFDF2ni53alKL0iJTvtcy9BSR4D'
+  secret: 'EDubEBAg_ZztC-_HlsW16IFZcxBIatFt7c0ILuxNTpWAVnvrsO9ywVxnHr7J'
+  uri_base: 'https://api.sandbox.paypal.com'
+  website: 'http://www.example.com:3000'
+
+test:
+  client_id: 'AZPi5hCY-0SoaLmignRs9XV6N4mvRS2TVKFDF2ni53alKL0iJTvtcy9BSR4D'
+  secret: 'EDubEBAg_ZztC-_HlsW16IFZcxBIatFt7c0ILuxNTpWAVnvrsO9ywVxnHr7J'
+  uri_base: 'https://api.sandbox.paypal.com'
+  website: 'http://www.example.com:3000'
+
+production:
+  client_id: 'AVWiuBCE6_ps2zCh0Qaq0MaIbP8v2bjfFnKH5esYR9v6sNvu-MzVeWny3crM'
+  secret: 'EKKoNhCgFn_0lmpUAxXir0ySN4cmaLzGugUmnkgZHR90Kg9Y_DFmJbI2H0Ee'
+  uri_base: 'https://api.paypal.com'
+  website: 'https://www.example.com'
+  

data/lib/paypkg/accept-pp-payment.rb

@@ -0,0 +1,77 @@
+##############################
+### Payment Through PayPal ###
+##############################
+
+class Paypkg
+  # This method is intended for use when you want to charge
+  # a user's PayPay account. The user will be required to give
+  # an on-line approval.
+  #
+  # The two urls shown here must be in your controller, and
+  # in your config/routes.rb file. See the execute_payment
+  # method below. You should store the payment_id you get
+  # back from this call (in session[:payment_id] here).
+  #
+  # @param amount
+  # @param desc
+  # @param approved_url
+  # @param cancelled_url
+  # @param payer_id
+  def accept_pp_payment(amount, desc, approved_url, cancelled_url, payer_id)
+    set_access_token # we need this here to set the @website
+    formatted_amount = "%0.2f"%amount
+    json, status = call_paypal("/v1/payments/payment", "{
+      'intent':'sale',
+      'redirect_urls':{
+        'return_url':'#{@website}/#{approved_url}/',
+        'cancel_url':'#{@website}/#{cancelled_url}/'
+      },
+      'payer':{
+        'payment_method':'paypal'
+      },
+      'transactions':[
+        {
+          'amount':{
+            'total':'#{formatted_amount}',
+            'currency':'USD'
+          },
+          'description':'#{desc}'
+        }
+      ]
+    }")
+    if (@status.last=='201') && (@hash.last[:state]=='created')
+      @session[:payment_id] = @hash.last[:id]
+      @link = @hash.last[:links].select{|link| link[:rel]=='approval_url'}[0][:href]
+      return true
+    else
+      return false
+    end
+  end
+
+  # This is executed by the code at the 'accepted' url.
+  #
+  # Your controller must provide two url's that look like
+  # the code below, and are in your config/routes.rb
+  #
+  #   def approved
+  #     pp = Paypkg.new(session)
+  #     @ok = pp.execute_payment(params[:PayerID],session[:payment_id])
+  #     ... more logic ...
+  #   end
+  # 
+  #   def cancelled
+  #     ... handle the user cancelling out ...
+  #   end
+  #
+  # You should save the sale_id returned from this call in your
+  # database.
+  #
+  # @param payer_id
+  # @param payment_id
+  def execute_payment(payer_id, payment_id)
+    call_paypal("/v1/payments/payment/#{payment_id}/execute/", "{
+      'payer_id' : '#{payer_id}'
+    }")
+    return (@status.last=='200') && (@hash.last[:state]=='approved')
+  end
+end

data/lib/paypkg/accept-stored-cc-payment.rb

@@ -0,0 +1,43 @@
+########################################
+### Payment Using Stored Credit Card ###
+########################################
+
+class Paypkg
+  # This method is intended for use when you want to charge
+  # a card stored in the vault.
+  # @param card_id [String] Required.
+  # @param amount [Numeric] Required.
+  # @param desc [String] Required.
+  # @param email [String] Required.
+  # @param payer_id [String] Required.
+  def accept_stored_cc_payment(card_id, amount, desc, email, payer_id)
+    formatted_amount = "%0.2f"%amount
+    call_paypal("/v1/payments/payment", "{
+      'intent':'sale',
+      'payer':{
+        'payment_method':'credit_card',
+        'payer_info':{
+          'email':'#{email}'
+        },
+        'funding_instruments':[
+          {
+            'credit_card_token':{
+              'credit_card_id':'#{card_id}',
+              'payer_id':'#{payer_id}'
+            }
+          }
+        ]
+      },
+      'transactions':[
+        {
+          'amount':{
+            'total':'#{formatted_amount}',
+            'currency':'USD'
+          },
+          'description':'#{desc}'
+        }
+      ]
+    }")
+    return (@status.last=='201') && (@hash.last[:state]=='approved')
+  end
+end

data/lib/paypkg/accept-tendered-cc-payment.rb

@@ -0,0 +1,50 @@
+##########################################
+### Payment Using Accepted Credit Card ###
+##########################################
+
+class Paypkg
+  # This call is intended for use when the card is presented, but
+  # not stored in the vault.
+  # @param number [String] Required.
+  # @param cvv2 [String] Optional.
+  # @param first_name [String] Optional.
+  # @param last_name [String] Optional.
+  # @param expire_month [String] Required.
+  # @param expire_year [String] Required.
+  # @param amount [String] Required.
+  # @param desc [String] Required.
+  def accept_tendered_cc_payment(type, number, expire_month, expire_year, cvv2, first_name,
+    last_name, amount, desc)
+    formatted_amount = "%0.2f"%amount
+    json = "{
+      'intent':'sale',
+      'payer':{
+        'payment_method':'credit_card',
+        'funding_instruments':[
+          {
+            'credit_card':{
+              'type':'#{type}',
+              'number':'#{number}',"
+    json << " 'cvv2':'#{cvv2}'," if cvv2
+    json << " 'first_name':'#{first_name}'," if first_name
+    json << " 'last_name':'#{last_name}'," if last_name
+    json << " 'expire_month':'#{expire_month}',
+              'expire_year':'#{expire_year}'
+            }
+          }
+        ]
+      },
+      'transactions':[
+        {
+          'amount':{
+            'total':'#{formatted_amount}',
+            'currency':'USD'
+          },
+          'description':'#{desc}'
+        }
+      ]
+    }"
+    call_paypal("/v1/payments/payment", json)
+    return (@status.last=='201') && (@hash.last[:state]=='approved')
+  end
+end

data/lib/paypkg/delete-credit-card.rb

@@ -0,0 +1,13 @@
+##########################
+### Delete Credit Card ###
+##########################
+
+class Paypkg
+  # Delete a card from the vault. If Paypal already removed the card
+  # because it expired, just ignore the error. NO JSON STRING is
+  # returned with this call.
+  def delete_credit_card(vault_id)
+    call_paypal("/v1/vault/credit-card/#{vault_id}", nil, :method => :delete)
+    return (@status.last=='204') && (@hash.last==nil)
+  end
+end

data/lib/paypkg/nil-empty?.rb

@@ -0,0 +1,12 @@
+#####################################################
+### This extends NilClass to add empty? #############
+### It just makes sense that nil is empty, right? ###
+#####################################################
+
+class NilClass
+  # This adds the empty? method to nil, so that nil.empty? => true
+  def empty?
+    true
+  end
+end
+