pin-payments 0.0.2 → 0.0.3

data/.gitignore

@@ -0,0 +1,36 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+doc/
+lib/bundler/man
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+## PROJECT::SPECIFIC
+testing

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/README.md

@@ -0,0 +1,62 @@
+## pin-payments
+
+A wrapper for the [pin.net.au](https://pin.net.au/) [API](https://pin.net.au/docs/api). Available via [RubyGems](http://rubygems.org/gems/pin-payments):
+
+    gem install pin-payments
+
+Extracted from [PayAus](http://www.payaus.com/). Still a bit rough around the edges.
+
+MIT licensed, contributions are very welcome!
+
+## Usage
+
+### Prerequisites
+
+You'll need to create an account at [pin.net.au](https://pin.net.au/) first.
+
+### Setup
+
+Create an initializer, eg. `pin.rb`:
+
+```ruby
+Pin::Base.setup ENV['PIN_SECRET_KEY'], ENV['PIN_ENV']
+```
+
+You can get your secret key from Pin's [Your Account](https://dashboard.pin.net.au/account) page. The second argument should be "live" or "test" depending on which API you want to access.
+
+### Usage
+
+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.
+
+Then, in your controller:
+
+```ruby
+def create
+  Pin::Charge.create email: 'alex@payaus.com', description: '1 month of service', amount: 19900,
+                     currency: 'AUD', ip_address: params[:ip_address], card_token: params[:card_token]
+  redirect_to new_payment_path, notice: "Your credit card has been charged"
+end
+```
+
+This will issue a once-off charge ([API](https://pin.net.au/docs/api/charges)). Alternatively, you may wish to create a customer. To do this, create a `Card` object first, then a corresponding `Customer` via the [API](https://pin.net.au/docs/api/customers).
+
+```ruby
+card = Pin::Card.new number: '5520000000000000', expiry_month: '12', expiry_year: '2014', cvc: '123',
+                     name: 'Roland Robot', address_line1: '42 Sevenoaks St', address_city: 'Lathlain', address_postcode: '6454', address_state: 'WA', address_country: 'Australia'
+customer = Pin::Customer.create 'alex@payaus.com', card # this contacts the API
+Pin::Charge.create email: 'alex@payaus.com', description: '1 month of service', amount: 19900,
+                   currency: 'AUD', ip_address: '203.192.1.172', customer: customer # shorthand for customer_token: customer.token
+```
+
+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.
+
+```ruby
+customers = Pin::Customer.all
+customer = customers.find {|c| c.email == user.email} # assume user is the user you are trying to charge
+Pin::Charge.create email: user.email, description: '1 month of service', amount: 19900, currency: 'AUD',
+                   ip_address: user.ip_address, customer: customer
+```
+
+## Credits
+
+https://github.com/ghiculescu/pin-payments/graphs/contributors

data/Rakefile

@@ -0,0 +1,12 @@
+require 'rake'
+require 'rake/testtask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Run unit tests.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << ['lib', 'test']
+  t.pattern = 'test/unit/**/*_test.rb'
+  t.verbose = true
+end

data/lib/pin-payments/base.rb

@@ -0,0 +1,50 @@
+module Pin
+  class Base
+    include HTTParty
+
+    def initialize(attributes = {})
+      attributes.each do |name, value|
+        if name == 'card' # TODO: this should be generalised (has_one relationship i suppose)
+          self.card = Card.new value
+        else
+          send("#{name}=", value) if respond_to? "#{name}="
+        end
+      end
+    end
+
+    def self.setup(key, mode = :live)
+      @@auth = {username: key, password: ''}
+      mode = mode.to_sym
+      uri = if mode == :test
+        "https://test-api.pin.net.au/1"
+      elsif mode == :live
+        "https://api.pin.net.au/1"
+      else
+        raise "Incorrect API mode! Must be :live or :test (leave blank for :live)."
+      end
+      base_uri uri
+    end
+
+    protected
+    def self.authenticated_post(url, body)
+      post(url, body: body, basic_auth: @@auth)
+    end
+    def self.authenticated_get(url, query = nil)
+      get(url, query: query, basic_auth: @@auth)
+    end
+
+    def self.build_instance_from_response(response)
+      new(response.parsed_response['response'])
+    end
+
+    def self.build_collection_from_response(response)
+      models = []
+      if response.code == 200
+        response.parsed_response['response'].each do |model|
+          models << new(model)
+        end
+      end
+      models
+    end
+  end
+end

data/lib/pin-payments/card.rb

@@ -0,0 +1,34 @@
+module Pin
+	class Card < Base
+    attr_accessor :number, :expiry_month, :expiry_year, :cvc, :name, :address_line1,
+                  :address_line2, :address_city, :address_postcode, :address_state,
+                  :address_country,
+                  :token, :display_number, :scheme
+
+    def initialize(attributes = {})
+      attributes.each {|name, value| send("#{name}=", value)}
+    end
+
+    def to_hash
+      hash = {}
+      instance_variables.each {|var| hash[var.to_s.delete("@")] = instance_variable_get(var) }
+      hash
+    end
+
+    # options should be a hash with the following keys:
+    # :number, :expiry_month, :expiry_year, :cvc, :name, :address_line1,
+    # :address_city, :address_postcode, :address_state, :address_country
+    #
+    # it can also have the following optional keys:
+    # :address_line2
+    def self.create(options = {})
+      response = authenticated_post '/cards', options
+      if response.code == 201 # card created
+        build_instance_from_response(response)
+      else
+        # handle the error
+        false
+      end
+    end
+  end
+end

data/lib/pin-payments/charge.rb

@@ -0,0 +1,30 @@
+module Pin
+  class Charge < Base
+    attr_accessor :token,
+                  :email, :description, :amount, :currency, :ip_address,
+                  :card, :card_token, :customer_token,
+                  :amount_refunded, :total_fees, :merchant_entitlement, :refund_pending,
+                  :success, :status_message, :error_message, :transfer, :created_at
+
+    # options should be a hash with the following params
+    # email, description, amount, currency, ip_address are mandatory
+    # identifier must be a hash, can take the forms
+    #   {card: <Pin::Card>}
+    #   {card_token: String<"...">}
+    #   {customer_token: String<"...">}
+    #   {customer: <Pin::Customer>}
+    # eg. {email: 'alex@payaus.com', description: '1 month of PayAus', amount: 19900, currency: 'AUD', ip_address: '203.192.1.172', customer_token: 'asdf'}
+    def self.create(options = {})
+      options[:customer_token] = options.delete(:customer).token unless options[:customer].nil?
+      build_instance_from_response(authenticated_post('/charges', options))
+    end
+
+    def self.all # TODO: pagination
+      build_collection_from_response(authenticated_get('/charges'))
+    end
+
+    def self.find(token)
+      build_instance_from_response(authenticated_get("/charges/#{token}"))
+    end
+  end
+end

data/lib/pin-payments/customer.rb

@@ -0,0 +1,26 @@
+module Pin
+  class Customer < Base
+    attr_accessor :email, :created_at, :token, :card
+
+    # email should be a string
+    # card_or_token can be a Pin::Card object
+    # or a card_token (as a string)
+    def self.create(email, card_or_token)
+      options = if card_or_token.respond_to?(:to_hash) # card
+        {card: card_or_token.to_hash}
+      else # token
+        {card_token: card_or_token}
+      end.merge(email: email)
+
+      build_instance_from_response(authenticated_post('/customers', options))
+    end
+
+    def self.all # TODO: pagination
+      build_collection_from_response(authenticated_get('/customers'))
+    end
+
+    def self.find(token)
+      build_instance_from_response(authenticated_get("/customers/#{token}"))
+    end
+  end
+end

data/pin-payments.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |s|
+  s.name        = 'pin-payments'
+  s.version     = '0.0.3'
+  s.date        = '2013-07-26'
+  s.summary     = "Pin Payments API wrapper"
+  s.description = "A wrapper for the Pin Payments (https://pin.net.au/) API"
+  s.authors     = ["Alex Ghiculescu"]
+  s.email       = 'alexghiculescu@gmail.com'
+
+  s.files         = `git ls-files`.split($/)
+  s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths = ["lib"]
+
+  s.licenses    = ["MIT"]
+  s.homepage    = 'https://github.com/ghiculescu/pin-payments'
+
+  s.add_dependency "httparty"
+
+  s.add_development_dependency "bundler", "~> 1.3"
+  s.add_development_dependency "webmock"
+end

data/test/stub_responses/cards.json

@@ -0,0 +1,13 @@
+{
+  "response": {
+    "token": "card_nytGw7koRg23EEp9NTmz9w",
+    "display_number": "XXXX-XXXX-XXXX-0000",
+    "scheme": "master",
+    "address_line1": "42 Sevenoaks St",
+    "address_line2": null,
+    "address_city": "Lathlain",
+    "address_postcode": "6454",
+    "address_state": "WA",
+    "address_country": "Australia"
+  }
+}

data/test/stub_responses/charges.json

@@ -0,0 +1,33 @@
+{
+  "response": [
+    {
+      "token": "ch_lfUYEBK14zotCTykezJkfg",
+      "success": true,
+      "amount": 400,
+      "currency": null,
+      "description": "test charge",
+      "email": "roland@pin.net.au",
+      "ip_address": "203.192.1.172",
+      "created_at": "2012-06-20T03:10:49Z",
+      "status_message": "Success!",
+      "error_message": null,
+      "card": {
+        "token": "card_nytGw7koRg23EEp9NTmz9w",
+        "display_number": "XXXX-XXXX-XXXX-0000",
+        "scheme": "master",
+        "address_line1": "42 Sevenoaks St",
+        "address_line2": null,
+        "address_city": "Lathlain",
+        "address_postcode": "6454",
+        "address_state": "WA",
+        "address_country": "Australia"
+      },
+      "transfer": null
+    }
+  ],
+  "pagination": {
+    "current": 1,
+    "per_page": 25,
+    "count": 1
+  }
+}

data/test/stub_responses/customers.json

@@ -0,0 +1,25 @@
+{
+  "response": [
+    {
+      "token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
+      "email": "roland@pin.net.au",
+      "created_at": "2012-06-22T06:27:33Z",
+      "card": {
+        "token": "card_nytGw7koRg23EEp9NTmz9w",
+        "display_number": "XXXX-XXXX-XXXX-0000",
+        "scheme": "master",
+        "address_line1": "42 Sevenoaks St",
+        "address_line2": null,
+        "address_city": "Lathlain",
+        "address_postcode": "6454",
+        "address_state": "WA",
+        "address_country": "Australia"
+      }
+    }
+  ],
+  "pagination": {
+    "current": 1,
+    "per_page": 25,
+    "count": 1
+  }
+}

data/test/stub_responses/records/charge-ch_lfUYEBK14zotCTykezJkfg.json

@@ -0,0 +1,26 @@
+{
+  "response": {
+    "token": "ch_lfUYEBK14zotCTykezJkfg",
+    "success": true,
+    "amount": 400,
+    "currency": null,
+    "description": "test charge",
+    "email": "roland@pin.net.au",
+    "ip_address": "203.192.1.172",
+    "created_at": "2012-06-20T03:10:49Z",
+    "status_message": "Success!",
+    "error_message": null,
+    "card": {
+      "token": "card_nytGw7koRg23EEp9NTmz9w",
+      "display_number": "XXXX-XXXX-XXXX-0000",
+      "scheme": "master",
+      "address_line1": "42 Sevenoaks St",
+      "address_line2": null,
+      "address_city": "Lathlain",
+      "address_postcode": "6454",
+      "address_state": "WA",
+      "address_country": "Australia"
+    },
+    "transfer": null
+  }
+}

data/test/stub_responses/records/customer-cus_XZg1ULpWaROQCOT5PdwLkQ.json

@@ -0,0 +1,18 @@
+{
+  "response": {
+    "token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
+    "email": "roland@pin.net.au",
+    "created_at": "2012-06-22T06:27:33Z",
+    "card": {
+      "token": "card_nytGw7koRg23EEp9NTmz9w",
+      "display_number": "XXXX-XXXX-XXXX-0000",
+      "scheme": "master",
+      "address_line1": "42 Sevenoaks St",
+      "address_line2": null,
+      "address_city": "Lathlain",
+      "address_postcode": "6454",
+      "address_state": "WA",
+      "address_country": "Australia"
+    }
+  }
+}

data/test/test_helper.rb

@@ -0,0 +1,50 @@
+require "rubygems"
+require 'debugger'
+require 'test/unit'
+require 'webmock/test_unit'
+require 'active_support/inflector'
+
+require File.dirname(__FILE__) + '/../lib/pin-payments.rb'
+
+module TestHelper
+  
+  SECRET_KEY = ENV["PIN_SECRET_KEY"] || "fake_key"
+  PIN_ENV = ENV["PIN_ENV"] || :test
+
+  Pin::Base.setup SECRET_KEY, PIN_ENV
+
+  def get_file(filename)
+    File.new(File.dirname(__FILE__) + "/stub_responses/" + filename)
+  end
+  
+  def get_record_json(type, token = nil)
+    if token.nil?
+      get_file("#{type}.json")
+    else
+      get_file("records/#{type}-#{token}.json")
+    end
+  end
+  
+  def mock_get(model_name, do_each = true)
+    stub_request(:get, /#{model_name.downcase}$/).to_return(body: get_record_json(model_name.downcase.pluralize), status: 200, headers: {'Content-Type' => 'application/json; charset=utf-8'})
+    if do_each
+      Pin.const_get(model_name.singularize).all.each do |record|
+        stub_request(:get, /#{model_name.downcase}\/#{record.token}$/).to_return(body: get_record_json(model_name.downcase.singularize, record.token), status: 200, headers: {'Content-Type' => 'application/json; charset=utf-8'})
+      end
+    end
+  end
+
+  def mock_post(model_name, do_each = true)
+    stub_request(:post, /#{model_name.downcase}$/).to_return(body: get_record_json(model_name.downcase.pluralize), status: 201, headers: {'Content-Type' => 'application/json; charset=utf-8'})
+    if do_each
+      Pin.const_get(model_name.singularize).all.each do |record|
+        stub_request(:post, /#{model_name.downcase}\/#{record.token}$/).to_return(body: get_record_json(model_name.downcase.singularize, record.token), status: 201, headers: {'Content-Type' => 'application/json; charset=utf-8'})
+      end
+    end
+  end
+
+  def mock_api(model_name)
+    mock_get(model_name)
+    mock_post(model_name)
+  end
+end

data/test/unit/cards_test.rb

@@ -0,0 +1,16 @@
+require 'test_helper'
+
+class CardsTest < Test::Unit::TestCase
+  include TestHelper
+  
+  def setup
+    mock_post('Cards', false)
+  end
+
+  def test_create
+    attributes = {number: '5520000000000000', expiry_month: '12', expiry_year: '2014', cvc: '123', name: 'Roland Robot', address_line1: '42 Sevenoaks St', address_city: 'Lathlain', address_postcode: '6454', address_state: 'WA', address_country: 'Australia'}
+    card = Pin::Card.create(attributes)
+    assert_not_nil card
+    assert_not_nil card.token
+  end
+end

data/test/unit/charges_test.rb

@@ -0,0 +1,60 @@
+require 'test_helper'
+
+class ChargesTest < Test::Unit::TestCase
+  include TestHelper
+  
+  def setup
+    mock_post('Cards', false)
+    mock_api('Charges')
+    mock_api('Customers')
+  end
+
+  def test_get_all # for some reason `test "get all" do` wasn't working...
+    charges = Pin::Charge.all
+    assert_equal 1, charges.length
+
+    first = charges.first
+    charge = Pin::Charge.find(first.token)
+    assert_not_nil charge
+  end
+
+  def test_create_charge_with_card
+    card = Pin::Card.new number: '5520000000000000', expiry_month: '12', expiry_year: '2014', cvc: '123', name: 'Roland Robot', address_line1: '42 Sevenoaks St', address_city: 'Lathlain', address_postcode: '6454', address_state: 'WA', address_country: 'Australia'
+
+    charge = Pin::Charge.create email: 'alex@payaus.com', description: '1 month of service', amount: 19900, currency: 'AUD', ip_address: '203.192.1.172',
+                                card: card
+    assert_not_nil charge
+  end
+
+  def test_create_charge_with_card_token
+    card = Pin::Card.create number: '5520000000000000', expiry_month: '12', expiry_year: '2014', cvc: '123', name: 'Roland Robot', address_line1: '42 Sevenoaks St', address_city: 'Lathlain', address_postcode: '6454', address_state: 'WA', address_country: 'Australia'
+
+    charge = Pin::Charge.create email: 'alex@payaus.com', description: '1 month of service', amount: 19900, currency: 'AUD', ip_address: '203.192.1.172',
+                                card_token: card.token
+    assert_not_nil charge
+  end
+
+  def test_create_charge_with_already_created_card
+    card = Pin::Card.create number: '5520000000000000', expiry_month: '12', expiry_year: '2014', cvc: '123', name: 'Roland Robot', address_line1: '42 Sevenoaks St', address_city: 'Lathlain', address_postcode: '6454', address_state: 'WA', address_country: 'Australia'
+
+    charge = Pin::Charge.create email: 'alex@payaus.com', description: '1 month of service', amount: 19900, currency: 'AUD', ip_address: '203.192.1.172',
+                                card: card
+    assert_not_nil charge
+  end
+
+  def test_create_charge_with_customer_token
+    customer = Pin::Customer.all.first
+
+    charge = Pin::Charge.create email: 'alex@payaus.com', description: '1 month of service', amount: 19900, currency: 'AUD', ip_address: '203.192.1.172',
+                                customer_token: customer.token
+    assert_not_nil charge
+  end
+
+  def test_create_charge_with_customer
+    customer = Pin::Customer.all.first
+
+    charge = Pin::Charge.create email: 'alex@payaus.com', description: '1 month of service', amount: 19900, currency: 'AUD', ip_address: '203.192.1.172',
+                                customer: customer
+    assert_not_nil charge
+  end
+end

data/test/unit/customers_test.rb

@@ -0,0 +1,33 @@
+require 'test_helper'
+
+class CustomersTest < Test::Unit::TestCase
+  include TestHelper
+  
+  def setup
+    mock_api('Customers')
+    mock_post('Cards', false)
+  end
+
+  def test_get_all # for some reason `test "get all" do` wasn't working...
+    customers = Pin::Customer.all
+    assert_equal 1, customers.length
+
+    first = customers.first
+    customer = Pin::Customer.find(first.token)
+    assert_not_nil customer
+  end
+
+  def test_create_customer_with_card
+    card = Pin::Card.new number: '5520000000000000', expiry_month: '12', expiry_year: '2014', cvc: '123', name: 'Roland Robot', address_line1: '42 Sevenoaks St', address_city: 'Lathlain', address_postcode: '6454', address_state: 'WA', address_country: 'Australia'
+
+    customer = Pin::Customer.create('alex@payaus.com', card)
+    assert_not_nil customer
+  end
+
+  def test_create_customer_with_token
+    card = Pin::Card.create number: '5520000000000000', expiry_month: '12', expiry_year: '2014', cvc: '123', name: 'Roland Robot', address_line1: '42 Sevenoaks St', address_city: 'Lathlain', address_postcode: '6454', address_state: 'WA', address_country: 'Australia'
+
+    customer = Pin::Customer.create('alex@payaus.com', card.token)
+    assert_not_nil customer
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pin-payments
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -65,7 +65,26 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
 - lib/pin-payments.rb
+- lib/pin-payments/base.rb
+- lib/pin-payments/card.rb
+- lib/pin-payments/charge.rb
+- lib/pin-payments/customer.rb
+- pin-payments.gemspec
+- test/stub_responses/cards.json
+- test/stub_responses/charges.json
+- test/stub_responses/customers.json
+- test/stub_responses/records/charge-ch_lfUYEBK14zotCTykezJkfg.json
+- test/stub_responses/records/customer-cus_XZg1ULpWaROQCOT5PdwLkQ.json
+- test/test_helper.rb
+- test/unit/cards_test.rb
+- test/unit/charges_test.rb
+- test/unit/customers_test.rb
 homepage: https://github.com/ghiculescu/pin-payments
 licenses:
 - MIT
@@ -91,4 +110,13 @@ rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: Pin Payments API wrapper
-test_files: []
+test_files:
+- test/stub_responses/cards.json
+- test/stub_responses/charges.json
+- test/stub_responses/customers.json
+- test/stub_responses/records/charge-ch_lfUYEBK14zotCTykezJkfg.json
+- test/stub_responses/records/customer-cus_XZg1ULpWaROQCOT5PdwLkQ.json
+- test/test_helper.rb
+- test/unit/cards_test.rb
+- test/unit/charges_test.rb
+- test/unit/customers_test.rb