pin-payments 1.0 → 1.1

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - 2.0.0
+
+script: bundle exec rake

data/README.md

@@ -2,6 +2,16 @@
 
 A wrapper for the [pin.net.au](https://pin.net.au/) [API](https://pin.net.au/docs/api). MIT licensed.
 
+## Installation
+
+Available via [RubyGems](https://rubygems.org/gems/pin-payments). Install the usual way;
+
+    gem install pin-payments
+
+## Build Status
+
+[![Build status](https://travis-ci.org/ghiculescu/pin-payments.png)](https://travis-ci.org/ghiculescu/pin-payments)
+
 ## Usage
 
 ### Prerequisites
@@ -13,7 +23,7 @@ You'll need to create an account at [pin.net.au](https://pin.net.au/) first.
 Create an initializer, eg. `pin.rb`, using keys from Pin's [Your Account](https://dashboard.pin.net.au/account) page.
 
 ```ruby
-Pin.setup secret_key: 'PIN_SECRET_KEY', publishable_key: 'PIN_PUBLISHABLE_KEY', mode: :test
+Pin.setup secret_key: ENV['PIN_SECRET_KEY'], publishable_key: ENV['PIN_PUBLISHABLE_KEY'], mode: ENV['PIN_ENV']
 ```
 
 The `mode` should be `:live` or `:test` depending on which API you want to access. The `publishable_key` is optional.
@@ -50,59 +60,135 @@ production:
 
 This allows you to inject `pin.yml` at deployment time, so that the secret key can be kept separate from your codebase.
 
-### Usage
+### JavaScript Helpers
+
+You'll probably want to create a form through which users can enter their details. [Pin's guide](https://pin.net.au/docs/guides/payment-forms) will step you through this. The publishable key will be necessary and, if set, can be obtained by calling `Pin.publishable_key`. So for example, you could have at the bottom of your form:
 
-You'll probably want to create a form through which users can enter their details. [Pin's guide](https://pin.net.au/docs/guides/payment-forms) will step you through this. The publishable key will be necessary and, if set, can be obtained by calling `Pin.publishable_key`. You can also ask the module for the path to the javascript for the configured mode:
+```javascript
+$('form.pin').pinForm('<%= Pin.publishable_key %>')
+```
+
+You also need to include [Pin.js](https://pin.net.au/pin-js) in pages that will talk to Pin via JavaScript. You can easily do this (and load the appropriate live or test version of pin.js) by doing:
 
 ```erb
 <%= javascript_include_tag Pin.js_url %>
 ```
 
-Creating a charge is simple. In your controller:
+### Charges
+
+[API Documentation](https://pin.net.au/docs/api/charges)
+
+**Creating a charge**
 
 ```ruby
 def create
-  Pin::Charge.create email: 'user@example.com', description: '1 year of service', amount: 10000,
-                     currency: 'AUD', ip_address: params[:ip_address], card_token: params[:card_token]
-
-  redirect_to new_payment_path, notice: "Your credit card has been charged"
+  Pin::Charge.create email: 'user@example.com',
+                     description: '1 year of service', amount: 10000,
+                     currency: 'AUD',
+                     ip_address: params[:ip_address],
+                     card_token: params[:card_token]
 end
 ```
 
-This will issue a once-off charge ([API](https://pin.net.au/docs/api/charges)).
+This will issue a once-off charge. Generally it's a good practice to do this in a background job and not directly in the controller. You can also create a charge against a customer token, once you have saved a customer (more details below).
+
+```ruby
+Pin::Charge.create email: 'user@example.com',
+                   description: '1 year of service', amount: 10000,
+                   currency: 'AUD',
+                   ip_address: params[:ip_address],
+                   customer_token: customer.token
+```
+
+**Retrieving charges**
+
+```ruby
+# get all charges
+Pin::Charge.all
+
+# get a charge with token "ch_lfUYEBK14zotCTykezJkfg"
+Pin::Charge.find("ch_lfUYEBK14zotCTykezJkfg")
+```
+
+### Customers
+
+[API Documentation](https://pin.net.au/docs/api/customers)
 
 For a recurring charge, you may wish to create a customer record at Pin. To do this, either create a `Card` object first, then a corresponding `Customer` via the [API](https://pin.net.au/docs/api/customers); or use a `card_token` returned from `Pin.js` to create a customer. Note that in either case you may activate additional compliance provisions in Pin's [Terms & Conditions](https://pin.net.au/terms).
 
+**Creating a customer**
+
 ```ruby
 # this doesn't contact the API
 card = Pin::Card.new number: '5520000000000000', expiry_month: '12', expiry_year: '2018', cvc: '123',
-                     name: 'User Name', address_line1: 'GPO Box 1234', address_city: 'Melbourne', address_postcode: '3001', address_state: 'VIC', address_country: 'Australia'
+                     name: 'User Name', address_line1: 'GPO Box 1234', address_city: 'Melbourne',
+                     address_postcode: '3001', address_state: 'VIC', address_country: 'Australia'
 
-# this contacts the API and returns a customer
+# create a customer using a card object
 customer = Pin::Customer.create 'user@example.com', card
 
-# this contacts the API and returns a charge
-Pin::Charge.create email: 'user@example.com', description: '1 year of service', amount: 10000,
-                   currency: 'AUD', ip_address: '127.0.0.1', customer: customer # shorthand for customer_token: customer.token
+# you can also create a customer using a card token - for example, in a controller
+def create
+  customer = Pin::Customer.create 'user@example.com', params[:card_token]
+end
 ```
 
-You can view your customers in the [Pin dashboard](https://dashboard.pin.net.au/test/customers). This lets you charge customers regularly without asking for their credit card details each time.
+**Retrieving a customer**
 
 ```ruby
-# get all customers from the API
-customers = Pin::Customer.all
+# get all customers
+Pin::Customer.all
 
-# find the customer you are trying to charge, assuming `current_user` is defined elsewhere
-customer = customers.find {|c| c.email == current_user.email}
+# get a customer with token "cus_XZg1ULpWaROQCOT5PdwLkQ"
+Pin::Customer.find("cus_XZg1ULpWaROQCOT5PdwLkQ")
+```
 
-# create a charge for the customer
-# note that using this method you will need to store the `ip_address` of the user
-# generally you can store this from when you initially created the customer (via Pin.js)
-Pin::Charge.create email: user.email, description: '1 month of service', amount: 19900,
-                   currency: 'AUD', ip_address: user.ip_address, customer: customer
+### Refunds
+
+[API Documentation](https://pin.net.au/docs/api/refunds)
+
+Refunds work based on charges, so you'll need a charge first.
+
+```ruby
+charge = Pin::Charge.first
+```
+
+Create a refund:
+
+```ruby
+# provide an amount to refund that amount - defaults to refunding the full amount
+# both methods do the same thing
+charge.refund!(250)
+Pin::Refund.create(charge, 250)
+```
+
+Get refunds for this charge:
+
+```ruby
+# both do the same thing
+refunds = charge.refunds
+refunds = Pin::Refund.all(charge)
 ```
 
-Errors from the API will result in a`Pin::APIError` exception being thrown:
+### Card Tokens
+
+[API Documentation](https://pin.net.au/docs/api/cards)
+
+Given a credit card, store it in Pin and get a card token in exchange:
+
+```ruby
+# contact the API and get a card token
+card = Pin::Card.create number: '5520000000000000', expiry_month: '12', expiry_year: '2018', cvc: '123',
+                        name: 'User Name', address_line1: 'GPO Box 1234', address_city: 'Melbourne',
+                        address_postcode: '3001', address_state: 'VIC', address_country: 'Australia'
+token = card.token
+```
+
+You can then use this token to create a customer or make a charge. If possible, it is better practice to create card tokens using `Pin.js` and only pass on the required information (ie. the card token and IP address) to your server.
+
+### Errors
+
+Errors from the API will result in a`Pin::APIError` exception being raised:
 
 ```ruby
 begin
@@ -111,3 +197,11 @@ rescue Pin::APIError => e
   redirect_to new_payment_path, flash: { error: "Charge failed: #{e.message}" }
 end
 ```
+
+## License
+
+MIT
+
+## Contributors
+
+https://github.com/ghiculescu/pin-payments/graphs/contributors

data/lib/pin-payments/base.rb

@@ -25,14 +25,10 @@ module Pin
       
       def all(options = {})
         options = {path: api_path, page: 1}.merge(options)
-        paging = "page=#{options[:page]}" unless options[:page] == 1
+        paging = {page: options[:page]} unless options[:page] == 1
         build_collection_from_response(authenticated_get(options[:path], paging))
       end
 
-      def all_pages(options = {})
-        options = options.merge(path: api_path)
-      end
-
       def first(options = {})
         all(options).first
       end
@@ -46,7 +42,6 @@ module Pin
       end
     
     protected
-    
       def auth
         Pin.auth
       end

data/lib/pin-payments/charge.rb

@@ -21,6 +21,18 @@ module Pin
         options[:customer_token] = options.delete(:customer).token unless options[:customer].nil?
         super(options)
       end
+
+      # search for charges using parameters provided in options
+      # available parameters:
+      #   query (string)
+      #   start_date (date, or string formatted as 'YYYY-MM-DD')
+      #   end_date (date, or string formatted as 'YYYY-MM-DD')
+      #   sort (string or symbol: "created_at" (default), "description", or "amount")
+      #   direction ("asc"/"desc", or 1/-1)
+      def search(options = {})
+        options[:direction] = options[:direction] == 'asc' ? 1 : -1 if ['asc', 'desc'].include?(options[:direction])
+        build_collection_from_response(authenticated_get('/charges/search', options))
+      end
     end
 
     # find all refunds for the current Charge object

data/pin-payments.gemspec

@@ -4,7 +4,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |s|
   s.name        = 'pin-payments'
-  s.version     = '1.0'
+  s.version     = '1.1'
   s.date        = '2013-08-06'
   s.summary     = "Pin Payments API wrapper"
   s.description = "A wrapper for the Pin Payments (https://pin.net.au/) API"
@@ -23,4 +23,6 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency "bundler", "~> 1.3"
   s.add_development_dependency "webmock"
+  s.add_development_dependency "rake"
+  s.add_development_dependency "activesupport"
 end

data/test/test_helper.rb

@@ -1,5 +1,5 @@
 require "rubygems"
-require 'debugger'
+#require 'debugger'
 require 'test/unit'
 require 'webmock/test_unit'
 require 'active_support/inflector'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pin-payments
 version: !ruby/object:Gem::Version
-  version: '1.0'
+  version: '1.1'
   prerelease: 
 platform: ruby
 authors:
@@ -59,6 +59,38 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A wrapper for the Pin Payments (https://pin.net.au/) API
 email: alexghiculescu@gmail.com
 executables: []
@@ -66,6 +98,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - Gemfile.lock
 - README.md
@@ -132,3 +165,4 @@ test_files:
 - test/unit/charges_test.rb
 - test/unit/customers_test.rb
 - test/unit/refunds_test.rb
+has_rdoc: