pin_pays 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2cbfbd8f959f73fcbf5e6d71bf79699b7a7032e2
+  data.tar.gz: 2793f70e8da74a6c84d62025d802c4e0c9cf024c
+SHA512:
+  metadata.gz: 93ec2c47b016fab6c1efbf37e15b65faf62cd5f50d85866340b54175755029d4eb28e4cf5f88cbe3f47cde2d7e4c74acbcb8fa517cba2a239992a026d1418607
+  data.tar.gz: fd4ea8b8c759818445569ca02cf3fb28654a365941d30e5e6ca0a3a917d7d369e9491183e0c050d6ca9b18ac8879ae9452b2b2cc0c1e000bcaa02cf85512de25

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+*.sublime-project
+*.sublime-workspace
+Gemfile.lock

data/.ruby-gemset

@@ -0,0 +1 @@
+pin_pays

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.1.1

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://www.rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Michael Lilley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,288 @@
+pin_pays
+========
+
+Super simple implementation of the Pin Payments API (pin.com.au) for Ruby and Rails projects.
+
+## Installation
+
+PinPays is available as a gem:
+
+    $ gem install pin_pays
+
+## Setup
+
+Configure your secret-key and whether to use the test or live modes:
+
+```ruby
+# config/initializers/pin_pay.rb (for rails)
+PinPays.configure do |config|
+  config.key  = "your-secret-key" # NB: use the right one for the mode!
+  config.mode = :test             # or :live
+end
+```
+
+TIP: If you're using Rails 4+, I recommend [using your secrets.yml file for the secret key](https://github.com/mlilley/pin_pays/wiki/Using-Rails-4-secrets.yml-file-for-secret-key).
+
+## Usage
+
+PinPays replicates the PinPayments documented API closely.  To understand the requirements for method inputs or return values refer to the [PinPayments documentation](https://pin.net.au/docs/api), then refer to [Responses](#Responses) section below to see how PinPays transforms the API json responses before giving them to you.
+
+Examples:
+
+```ruby
+# create a customer
+customer = PinPays::Customers:create('moo@cow.com', 'card_token_xyz')
+customer[:token] # => 'cust_token_xyz'
+
+# issue a charge
+charge = PinPays::Charges:create({ customer_token: customer[:token], email: 'moo@cow.com', description: 'Pants', amount: 4995, remote_ip: '127.0.0.1'})
+charge[:token] # => 'charge_token_789'
+
+# pay a refund
+refund = PinPays::Refunds.create(charge[:token], 2500)
+refund[:token] # => 'refund_token_123'
+```
+
+### Cards
+
+##### Create a card ([ref](https://pin.net.au/docs/api/cards))
+```ruby
+PinPays::Cards.create(card)
+```
+where ```card``` is a hash of the card details
+
+### Customers
+
+##### Create a customer ([ref](https://pin.net.au/docs/api/customers#post-customers))
+```ruby
+PinPays::Customers.create(email, card)
+```
+where ```card``` is either a card_token (of a previously created card) or a hash of card details.
+
+##### List all customers ([ref](https://pin.net.au/docs/api/customers#get-customers))
+```ruby
+PinPays::Customers.list(page=nil)
+```
+where ```page``` is the results page number to return (optional)
+
+##### Retrieve details of a specific customer ([ref](https://pin.net.au/docs/api/customers#get-customer))
+```ruby
+PinPays::Customers.show(customer_token)
+```
+
+##### Update a customer's details ([ref](https://pin.net.au/docs/api/customers#put-customer))
+```ruby
+PinPays::Customers.update(customer_token, options)
+```
+where ```options``` is a hash of one or more of: ```email:```, ```card_token:```, or ```card:``` (hash of card details).
+
+##### List all charges for a customer ([ref](https://pin.net.au/docs/api/customers#get-customers-charges))
+```ruby
+PinPays::Customers.charges(customer_token, page=nil)
+```
+where ```page``` is the results page number to return (optional)
+
+### Charges
+
+##### Create a charge ([ref](https://pin.net.au/docs/api/charges#post-charges))
+```ruby
+PinPays::Charges.create(options)
+```
+where ```options``` contains:
+- (mandatory) ```email:```, ```description:```, ```amount:```, and ```remote_ip:```
+- (mandatory, one of) ```customer_token:```, ```card_token:```, or ```card:``` (hash of card details)
+- (optional) ```currency:```, and ```capture:```
+
+##### Capture a charge ([ref](https://pin.net.au/docs/api/charges#put-charges))
+```ruby
+PinPays::Charges.capture(charge_token)
+```
+
+##### List all charges ([ref](https://pin.net.au/docs/api/charges#get-charges))
+```ruby
+PinPays::Charges.list(page=nil)
+```
+where ```page``` is the results page number to return (optional)
+
+##### Search for a charge that matches one or more criteria ([ref](https://pin.net.au/docs/api/charges#search-charges))
+```ruby
+PinPays::Charges.search(criteria)
+```
+where ```criteria``` is a hash containing one or more criteria to search for.
+
+##### Show details of a specific charge ([ref](https://pin.net.au/docs/api/charges#get-charge))
+```ruby
+PinPays::Charges.show(charge_token)
+```
+
+### Refunds
+
+##### Create a refund ([ref](https://pin.net.au/docs/api/refunds#post-refunds))
+```ruby
+PinPays::Refunds.create(charge_token, amount=nil)
+```
+where ```amount``` is the amount in cents of the original charge to refund (optional, otherwise the entire amount).
+
+##### List all refunds for a given charge ([ref](https://pin.net.au/docs/api/refunds#get-refunds))
+```ruby
+PinPays::Refunds.list(charge_token)
+```
+
+### Responses
+
+##### Success Responses
+
+All successful calls return a hash.  Fields of the hash are the same as those documented in PinPayments documentation (with some small convenience tweaks):
+
+Non-paginated style responses have the parent "response" field omitted.  For example, this:
+
+```json
+{
+  "response": {
+    "token": "rf_ERCQy--Ay6o-NKGiUVcKKA",
+    "success": null,
+    "amount": 400,
+    "currency": "USD",
+    "charge": "ch_bZ3RhJnIUZ8HhfvH8CCvfA",
+    "created_at": "2012-10-27T13:00:00Z",
+    "error_message": null,
+    "status_message": "Pending"
+  }
+}
+```
+
+becomes this:
+
+```ruby
+{
+  token: "rf_ERCQy--Ay6o-NKGiUVcKKA",
+  success: null,
+  amount: 400,
+  currency: "USD",
+  charge: "ch_bZ3RhJnIUZ8HhfvH8CCvfA",
+  created_at: "2012-10-27T13:00:00Z",
+  error_message: null,
+  status_message: "Pending"
+}
+```
+
+Note:
+- the parent "response" field is omitted
+- the hash keys are symbols (not strings)
+
+Additionally, paginated style responses like this:
+
+```json
+{
+  "response": [
+    {
+      "token": "ch_lfUYEBK14zotCTykezJkfg",
+      "success": true,
+      "amount": 400,
+      "currency": "USD",
+      "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",
+        "expiry_month": 6,
+        "expiry_year": 2020,
+        "name": "Roland Robot",
+        "address_line1": "42 Sevenoaks St",
+        "address_line2": null,
+        "address_city": "Lathlain",
+        "address_postcode": "6454",
+        "address_state": "WA",
+        "address_country": "Australia",
+        "scheme": "master"
+      },
+      "captured": true,
+      "authorisation_expired": false,
+      "transfer": null,
+      "settlement_currency": "AUD"
+    }
+  ],
+  "pagination": {
+    "current": 1,
+    "per_page": 25,
+    "count": 1
+  }
+}
+```
+
+Become this:
+
+```ruby
+{
+  items: [
+    {
+      token: "ch_lfUYEBK14zotCTykezJkfg",
+      success: true,
+      amount: 400,
+      currency: "USD",
+      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",
+        expiry_month: 6,
+        expiry_year: 2020,
+        name: "Roland Robot",
+        address_line1: "42 Sevenoaks St",
+        address_line2: null,
+        address_city: "Lathlain",
+        address_postcode: "6454",
+        address_state: "WA",
+        address_country: "Australia",
+        scheme: "master"
+      },
+      captured: true,
+      authorisation_expired: false,
+      transfer: null,
+      settlement_currency: "AUD"
+    }
+  ],
+  pages: {
+    current: 1,
+    per_page: 25,
+    count: 1
+  }
+}
+```
+
+Note that:
+- the "response" field becomes "items"
+- the "pagination" field becomes "pages"
+
+The only exception to the above is the ```PinPays::Refunds.list``` call, which returns only an array of hashes.
+
+
+##### Error Responses
+
+All error responses result in an Exception of the type ```PinPays::ApiError```.  The exception contains details about the specific error as properties on it:
+
+```ruby
+...
+rescue PinPays::ApiError => e
+  e.error               # -> error code (ie: "insufficient_funds")
+  e.error_description   # -> error description (ie: "There are not enough funds available to process the requested amount")
+  e.charge_token        # -> of the failed charge (for charge-related api calls)
+  e.messages            # -> an array of error messages (useful for displaying to the user on failed form submissions)
+  e.raw_response        # -> the raw json api response as a ruby hash
+end
+...
+```
+
+For a list of possible error codes, and example responses see https://pin.net.au/docs/api/test-cards and the remainder of the PinPayments documentation pages.
+
+## License
+
+Released under the [MIT license](http://www.opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['spec/lib/pin_pays/*_spec.rb']
+  t.verbose = true
+end
+
+task :default => :test

data/lib/pin_pays/api.rb

@@ -0,0 +1,48 @@
+module PinPays
+  class Api
+    LIVE_URI = 'https://api.pin.net.au/1'
+    TEST_URI = 'https://test-api.pin.net.au/1'
+
+    include HTTParty
+
+    class << self
+
+      def setup(config)
+        base_uri(config.mode == :live ? LIVE_URI : TEST_URI)
+        @@auth = { username: config.key, password: '' }
+      end
+
+      protected
+
+      def api_get(path, query = nil)
+        get(path, query: query, basic_auth: @@auth)
+      end
+
+      def api_post(path, body = nil)
+        post(path, body: body, basic_auth: @@auth)
+      end
+
+      def api_put(path, body = nil)
+        put(path, body: body, basic_auth: @@auth)
+      end
+
+      def api_response(response)
+        raise ApiError.new(response.code, response.parsed_response) unless response.code == 200 || response.code == 201
+        symbolize_keys(response.parsed_response['response'])
+      end
+
+      def api_paginated_response(response)
+        raise ApiError.new(response.code, response.parsed_response) unless response.code == 200 || response.code == 201
+        { items: symbolize_keys(response.parsed_response['response']), pages: symbolize_keys(response.parsed_response['pagination']) }
+      end
+
+      def symbolize_keys(o)
+        return o.reduce({}) {|memo, (k, v)| memo.tap { |m| m[k.to_sym] = symbolize_keys(v) }} if o.is_a?(Hash)
+        return o.reduce([]) {|memo, v| memo << symbolize_keys(v); memo } if o.is_a?(Array)
+        o
+      end
+
+    end
+
+  end
+end

data/lib/pin_pays/cards.rb

@@ -0,0 +1,16 @@
+module PinPays
+  class Cards < Api
+    PATH = '/cards'
+
+    class << self
+
+      # Create a card
+      #   card - hash of card details
+      def create(card)
+        api_response(api_post(PATH, card))
+      end
+
+    end
+
+  end
+end

data/lib/pin_pays/charges.rb

@@ -0,0 +1,42 @@
+module PinPays
+  class Charges < Api
+    PATH = '/charges'
+
+    class << self
+
+      # Create a charge for a customer or card
+      # Options (hash) containing:
+      #   (mandatory)         email, description, amount, and remote_ip
+      #   (mandatory, one of) customer_token, card_token, or card (a hash of card details)
+      #   (optional)          currency, capture
+      def create(options)
+        api_response(api_post(PATH, options))
+      end
+
+      # Captures a previously authorized charge
+      def capture(charge_token)
+        api_response(api_put("#{PATH}/#{charge_token}/capture"))
+      end
+
+      # Lists all charges
+      # Page - the page number to return (optional)
+      def list(page = nil)
+        options = (page.nil? ? nil : { page: page })
+        api_paginated_response(api_get(PATH, options))
+      end
+
+      # Search for charges that match one or more criteria
+      # Criteria - a hash of search criteria
+      def search(criteria)
+        api_paginated_response(api_get("#{PATH}/search", criteria))
+      end
+
+      # Retrieve details of a specific charge
+      def show(charge_token)
+        api_response(api_get("#{PATH}/#{charge_token}"))
+      end
+
+    end
+
+  end
+end

data/lib/pin_pays/config.rb

@@ -0,0 +1,21 @@
+module PinPays
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+    Api.setup(configuration)
+  end
+
+  class Configuration
+    attr_accessor :key
+    attr_accessor :mode
+
+    def initialize
+      @key  = nil
+      @mode = :test
+    end
+  end
+end

data/lib/pin_pays/customers.rb

@@ -0,0 +1,43 @@
+module PinPays
+  class Customers < Api
+    PATH = '/customers'
+
+    class << self
+
+      # Creates a customer
+      #   card - either a card token (string), or a hash of card details
+      def create(email, card)
+        options = { email: email }
+        options = options.merge(card.is_a?(String) ? { card_token: card } : { card: card })
+        api_response(api_post(PATH, options))
+      end
+
+      # List all customers
+      # Page - the page number to return (optional)
+      def list(page = nil)
+        options = (page.nil? ? nil : { page: page })
+        api_paginated_response(api_get(PATH, options))
+      end
+
+      # Retrieve details of a specific customer
+      def show(customer_token)
+        api_response(api_get("#{PATH}/#{customer_token}"))
+      end
+
+      # Update a customer
+      # Options - a hash specifying one or more of: email, card_token, or card (hash)
+      def update(customer_token, options)
+        api_response(api_put("#{PATH}/#{customer_token}", options))
+      end
+
+      # List all charges for a customer
+      # Page - the page number to return (optional)
+      def charges(customer_token, page = nil)
+        options = (page.nil? ? nil : { page: page })
+        api_paginated_response(api_get("#{PATH}/#{customer_token}/charges", options))
+      end
+
+    end
+
+  end
+end

data/lib/pin_pays/error.rb

@@ -0,0 +1,25 @@
+module PinPays
+  class ApiError < StandardError
+
+    attr_accessor :status, :error, :error_description, :charge_token, :messages, :raw_response
+
+    def initialize(status, response)
+      @status            = status
+
+      @error             = response['error']
+      @error_description = response['error_description']
+      @charge_token      = response['charge_token']
+      @messages          = response['messages']
+
+      @raw_response      = response
+
+      #puts "ApiError"
+      #puts "  #{@status} #{@error} #{@error_description}"
+    end
+
+    def to_s
+      "#{@error}"
+    end
+
+  end
+end

data/lib/pin_pays/refunds.rb

@@ -0,0 +1,23 @@
+module PinPays
+  class Refunds < Api
+    PATH = '/charges'
+
+    class << self
+
+      # Create a refund
+      # Amount - amount of charge to refund (optional)
+      def create(charge_token, amount = nil)
+        options = (amount.nil? ? nil : { amount: amount })
+        api_response(api_post("#{PATH}/#{charge_token}/refunds", options))
+      end
+
+      # List all refunds for a charge
+      # Note: does not return the usual paginated response.  Instead returns only an array.
+      def list(charge_token)
+        api_response(api_get("#{PATH}/#{charge_token}/refunds"))
+      end
+
+    end
+
+  end
+end

data/lib/pin_pays/version.rb

@@ -0,0 +1,3 @@
+module PinPays
+  VERSION = "0.2.0"
+end

data/lib/pin_pays.rb

@@ -0,0 +1,11 @@
+require 'httparty'
+
+require 'pin_pays/version'
+require 'pin_pays/config'
+require 'pin_pays/error'
+require 'pin_pays/api'
+require 'pin_pays/cards'
+require 'pin_pays/customers'
+require 'pin_pays/charges'
+require 'pin_pays/refunds'
+

data/pin_pays.gemspec

@@ -0,0 +1,21 @@
+require File.expand_path('../lib/pin_pays/version.rb', __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = 'pin_pays'
+  s.version     = PinPays::VERSION
+  s.licenses    = ['MIT']
+  s.summary     = "Pin Payments API Implementation for Ruby and Rails"
+  s.description = "Provides an implementation of the Pin Payments API (pin.com.au) for Ruby and Rails projects"
+  s.authors     = ["Michael Lilley"]
+  s.email       = 'mike@mlilley.com'
+  s.homepage    = 'https://github.com/mlilley/pin_pays'
+
+  s.add_dependency "httparty", "~> 0.13"
+
+  s.add_development_dependency "webmock", '~> 1.17'
+  s.add_development_dependency "vcr",     '~> 2.9'
+  s.add_development_dependency "turn",    '~> 0.9'
+  s.add_development_dependency "rake",    '~> 10.3'
+
+  s.files       = `git ls-files`.split("\n")
+end

data/spec/README.txt

@@ -0,0 +1,12 @@
+
+How To Run Tests
+----------------
+
+1. update spec_helper.rb with your pin payments testing secret key
+
+2. optionally delete spec/fixtures/vcr/*.yml, if you want to run tests against
+   the real pin payments api, instead of against previously captured api
+   response fixtures.
+
+3. run the tests
+   $ rake test

data/spec/fixtures/vcr/cards-create.yml

@@ -0,0 +1,53 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://<SECRET_KEY>:@test-api.pin.net.au/1/cards
+    body:
+      encoding: UTF-8
+      string: number=5520000000000000&expiry_month=12&expiry_year=2020&cvc=123&name=Mr%20Test%20Case&address_line1=1%20Long%20St&address_line2=&address_city=Somewhereville&address_postcode=30000&address_state=Somewherestate&address_country=Australia
+    headers: {}
+  response:
+    status:
+      code: 201
+      message: Created
+    headers:
+      Cache-Control:
+      - max-age=0, private, must-revalidate
+      Content-Type:
+      - application/json; charset=utf-8
+      Date:
+      - Sat, 26 Apr 2014 03:53:59 GMT
+      Etag:
+      - '"591261f1ede0d497395bc465d63e6921"'
+      Server:
+      - Apache/2.2.20 (Ubuntu)
+      Status:
+      - '201'
+      Strict-Transport-Security:
+      - max-age=31536000
+      Vary:
+      - User-Agent
+      X-Powered-By:
+      - Phusion Passenger (mod_rails/mod_rack) 3.0.11
+      X-Rack-Cache:
+      - invalidate, pass
+      X-Request-Id:
+      - 565552946a61935cf3df15864d12320e
+      X-Requested-From:
+      - 60.242.140.170
+      X-Runtime:
+      - '0.059031'
+      X-Ua-Compatible:
+      - IE=Edge,chrome=1
+      Content-Length:
+      - '367'
+      Connection:
+      - keep-alive
+    body:
+      encoding: UTF-8
+      string: '{"response":{"token":"card_j2RKCKH0RE4fhWVa0TXo3A","scheme":"master","display_number":"XXXX-XXXX-XXXX-0000","expiry_month":12,"expiry_year":2020,"name":"Mr
+        Test Case","address_line1":"1 Long St","address_line2":"","address_city":"Somewhereville","address_postcode":"30000","address_state":"Somewherestate","address_country":"Australia"},"ip_address":"60.242.140.170"}'
+    http_version: 
+  recorded_at: Sat, 26 Apr 2014 03:53:59 GMT
+recorded_with: VCR 2.9.0