pensio_api 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: 689ae01e09472f1266a2da94b30861b7bda91871
-  data.tar.gz: 8c73eccf3325acbddd6c7eb258bc4ef2ec500196
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MmJkMDI1NTg4NzNiYjk4NjQ1ZTFjMGY5YTAxOGMxM2Y1MTgwMWZkZg==
+  data.tar.gz: !binary |-
+    NTEzODc3OWY4Yjc2YjA1NDk0ODQ1MGU2MzE3NTQ1OWI0MThmZTA0NQ==
 SHA512:
-  metadata.gz: 85db0f900db0c6a16e6d0a1fbd9175fdd394d1c7e6a4ca2af78bd2b0e17ead99fd0607e2912948ea7cc6d0e21d0cbb1510ded4cc41dc32a15a4734e5a85088e5
-  data.tar.gz: fff1cdfe9534a05e774d332db04919f069d832d50ec65614d6dc808f136d193015401ce432741c35bff17d0f292668844a70709dc7c1129114f1f3ef0d888529
+  metadata.gz: !binary |-
+    N2U3YjYwMjZjYWVlN2UyNTczYmNiZTZhMzE1N2JjYzgwMzAwMmYwZmNlOThh
+    NjM3YzdhOTMwZmVkYTBlMDFiODExNzEzYzNmMzgxMDNmZWU0OTc4MGU4NWI3
+    OTkwOWFkNjVkN2RjMzNhNDkyNjE2ZWM5ODdiYTgxNGEzMjJkYjk=
+  data.tar.gz: !binary |-
+    ODRiYzQzY2JmODhkYmFhMjE4ZTdhZjQzMWJhMzU2ZmRhMGRhNTMwMjgzMTc0
+    NTBlNWE0ZDVlNmE0NDIzNjdlNDE4ODQzMDAwZDBiNTMyNjkxOWNhMjAyMmM0
+    NjBlNzUwMjY0ZDdiMTk0NjhhZDc1NDQxMmRmZjAzZTJmMGE2YjE=

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,83 @@
+PATH
+  remote: .
+  specs:
+    pensio_api (0.2.2)
+      activesupport (>= 3.2)
+      httparty (>= 0.12.0)
+      multi_xml (>= 0.5.2)
+
+GEM
+  remote: https://www.rubygems.org/
+  specs:
+    activesupport (4.0.4)
+      i18n (~> 0.6, >= 0.6.9)
+      minitest (~> 4.2)
+      multi_json (~> 1.3)
+      thread_safe (~> 0.1)
+      tzinfo (~> 0.3.37)
+    addressable (2.3.5)
+    celluloid (0.15.2)
+      timers (~> 1.1.0)
+    coderay (1.1.0)
+    crack (0.4.1)
+      safe_yaml (~> 0.9.0)
+    diff-lcs (1.2.5)
+    ffi (1.9.3)
+    formatador (0.2.4)
+    guard (2.2.5)
+      formatador (>= 0.2.4)
+      listen (~> 2.1)
+      lumberjack (~> 1.0)
+      pry (>= 0.9.12)
+      thor (>= 0.18.1)
+    guard-rspec (4.2.4)
+      guard (~> 2.1)
+      rspec (>= 2.14, < 4.0)
+    httparty (0.13.0)
+      json (~> 1.8)
+      multi_xml (>= 0.5.2)
+    i18n (0.6.9)
+    json (1.8.1)
+    listen (2.4.0)
+      celluloid (>= 0.15.2)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9)
+    lumberjack (1.0.4)
+    method_source (0.8.2)
+    minitest (4.7.5)
+    multi_json (1.9.2)
+    multi_xml (0.5.5)
+    pry (0.9.12.4)
+      coderay (~> 1.0)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    rb-fsevent (0.9.4)
+    rb-inotify (0.9.3)
+      ffi (>= 0.5.0)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.7)
+    rspec-expectations (2.14.4)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.4)
+    safe_yaml (0.9.7)
+    slop (3.4.7)
+    thor (0.18.1)
+    thread_safe (0.3.2)
+    timers (1.1.0)
+    tzinfo (0.3.39)
+    webmock (1.16.1)
+      addressable (>= 2.2.7)
+      crack (>= 0.3.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  guard (~> 2.2.5)
+  guard-rspec (~> 4.2.4)
+  pensio_api!
+  rspec (>= 2.14)
+  webmock (~> 1.16.1)

data/Guardfile

@@ -0,0 +1,23 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  # Rails example
+  watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^app/(.*)(\.erb|\.haml|\.slim)$})          { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
+  watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }
+  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+  watch('config/routes.rb')                           { "spec/routing" }
+  watch('app/controllers/application_controller.rb')  { "spec/controllers" }
+
+  # Capybara features specs
+  watch(%r{^app/views/(.+)/.*\.(erb|haml|slim)$})     { |m| "spec/features/#{m[1]}_spec.rb" }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$})   { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'spec/acceptance' }
+end

data/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2014, ASMALLWORLD, AG
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of ASMALLWORLD, AG nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL ASMALLWORLD, AG BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,77 @@
+# PensioAPI
+This gem covers most of the Merchant and eCommerce API functionality provided by Pensio (http://www.pensio.com).
+
+## Getting Started
+
+First, register your Pensio credentials. For example, if you're using rails, create `config/initializers/pensio.rb` with the following contents:
+
+```
+PensioAPI::Credentials.base_uri = 'Your pensio gateway URI'
+PensioAPI::Credentials.username = 'Your pensio username'
+PensioAPI::Credentials.password = 'Your pensio password'
+```
+
+## Transactions
+
+To query transactions in your Pensio gateway, use the method `PensioAPI::Transaction.find`. This takes a number of parameters as defined in the Pensio documentation. For example:
+
+```
+PensioAPI::Transaction.find(transaction_id: '123')
+```
+
+This returns an enumerable `PensioAPI::Responses::Transaction` object as many `PensioAPI::Transaction` objects as match your criteria.
+
+With a transaction object, you can perform several actions.
+
+* Determine status via `.status`, `.captured?` and `.reserved`
+* Refund via `.refund`
+* Expose terminal details via `.terminal`
+* Expose billing address via `.billing_address`
+* Map to a subscription object via `.to_subscription`
+* Map to a reservation object via `.to_reservation`
+
+## Funding Lists
+
+The funding list functionality of the Pensio Merchant API is exposed via `PensioAPI::FundingList.all` which returns an iterable collection of `PensioAPI::FundingList` objects. Calling `.download` on any of these objects downloads and parses the CSV file from the Pensio Gateway.
+
+## Terminals
+
+To query terminals, use the method `PensioAPI::Terminal.all`. This will return an enumerable object containing as many `PensioAPI::Terminals` as are associated with your gateway.
+
+## Reservations
+
+To create a fixed amount reservation (via the API call '/merchant/API/reservationOfFixedAmount') use the class method `PensioAPI::Reservation.of_fixed_amount`.
+
+To capture an existing reservation, use `.capture`. Likewise to release it, use `.release`.
+
+## Subscriptions
+
+To create a subscription, use the class method `PensioAPI::Subscription.setup`. This takes the arguments documented in Pensio's documentation for the '/merchant/API/setupSubscription' API call.
+
+With an existing subscription, use `.reserve_charge` to place a charge reservation upon the subscription or `.charge` to attempt a reservation and charge of the associated transaction.
+
+## eCommerce
+
+PensioAPI::Ecommerce is a module which exposes the eCommerce API endpoints. Two module methods `.create_payment_request` and `.create_multi_payment_request` can be used to generate payment URLs for a multitude of payment types. Consult the Pensio eCommerce API documentation for parameter details.
+
+## Callbacks
+
+`PensioAPI::Callback` provides two methods `.parse_success` and `.parse_failure`. These are designed to parse the callbacks Pensio send to your transaction success and transaction failure endpoints. Each returns a callback response which exposes the transaction details for processing by your app.
+
+## Error Handling
+
+The library provides two generic error classes for requests.
+
+* `PensioAPI::Errors::BadRequest` is raised when the response from Pensio indicates that a request has invalid parameters
+* `PensioAPI::Errors::GatewayError` is raised when the parameters have been provided correctly, but the gateway was unable to process the request
+
+Additionally, a third error class `PensioAPI::NoCredentials` is raised if credentials have not been provided. See "Getting Started" for more details.
+
+## TODO
+
+* Better documentation - more examples, RDoc docs
+* Further API implementation
+
+## Contributing
+
+Contributions are very welcome. Please submit pull requests with adequately-tested code.

data/lib/pensio_api/billing_address.rb

@@ -0,0 +1,15 @@
+module PensioAPI
+  class BillingAddress
+    attr_reader :first_name, :last_name, :street_address, :city, :region, :postal_code, :country
+
+    def initialize(address_params)
+      @first_name = address_params['Firstname']
+      @last_name = address_params['Lastname']
+      @street_address = address_params['Address']
+      @city = address_params['City']
+      @region = address_params['Region']
+      @postal_code = address_params['PostalCode']
+      @country = address_params['Country']
+    end
+  end
+end

data/lib/pensio_api/callback.rb

@@ -0,0 +1,30 @@
+module PensioAPI
+  module Callback
+    FakeRequest = Struct.new(:headers, :body)
+ 
+    def self.parse_success(xml)
+      parse(xml, true)
+    end
+    
+    def self.parse_failure(xml)
+      parse(xml, false)
+    end
+    
+    private 
+    
+    def self.parse(xml, success)
+      params = MultiXml.parse(xml)
+      
+      request = FakeRequest.new(
+        params['APIResponse']['Header'],
+        params['APIResponse']['Body']
+      )
+      
+      if success
+        PensioAPI::Responses::SuccessCallback.new(request)
+      else
+        PensioAPI::Responses::SubscriptionFailureCallback.new(request)
+      end
+    end
+  end
+end

data/lib/pensio_api/credentials.rb

@@ -0,0 +1,7 @@
+module PensioAPI
+  module Credentials
+    class << self
+      attr_accessor :base_uri, :username, :password
+    end
+  end
+end

data/lib/pensio_api/ecommerce.rb

@@ -0,0 +1,13 @@
+module PensioAPI
+  module Ecommerce
+    def self.create_payment_request(options={})
+      request = Request.new('/merchant/API/createPaymentRequest', options)
+      Responses::GatewayURL.new(request)
+    end
+
+    def self.create_multi_payment_request(options={})
+      request = Request.new('/merchant/API/createMultiPaymentRequest', options)
+      Responses::GatewayURL.new(request)
+    end
+  end
+end

data/lib/pensio_api/errors/bad_request.rb

@@ -0,0 +1,15 @@
+module PensioAPI
+  module Errors
+    class BadRequest < StandardError
+      attr_reader :request_time, :request_path, :error_code
+
+      def initialize(request)
+        super(request.headers['ErrorMessage'])
+
+        @request_time = Time.parse(request.headers['Date'])
+        @request_path = request.headers['Path']
+        @error_code = request.headers['ErrorCode'].to_i
+      end
+    end
+  end
+end

data/lib/pensio_api/errors/gateway_error.rb

@@ -0,0 +1,21 @@
+module PensioAPI
+  module Errors
+    class GatewayError < StandardError
+      include Mixins::HasTransactions
+      attr_reader :request_time, :request_path, :cardholder_message
+
+      def initialize(request)
+        super(request.body['MerchantErrorMessage'])
+
+        @raw = request.body
+
+        @request_time = Time.parse(request.headers['Date'])
+        @request_path = request.headers['Path']
+
+        @cardholder_message = request.body['CardHolderErrorMessage']
+
+        map_transactions
+      end
+    end
+  end
+end

data/lib/pensio_api/errors/no_credentials.rb

@@ -0,0 +1,9 @@
+module PensioAPI
+  module Errors
+    class NoCredentials < StandardError
+      def initialize
+        super('Incomplete credentials were supplied')
+      end
+    end
+  end
+end

data/lib/pensio_api/funding_list.rb

@@ -0,0 +1,30 @@
+module PensioAPI
+  class FundingList
+    attr_reader :filename
+    attr_reader :amount
+    attr_reader :acquirer
+    attr_reader :funding_date
+    attr_reader :created_at
+    attr_reader :download_link
+
+    def self.all(options={})
+      request = Request.new('/merchant/API/fundingList', options)
+      Responses::FundingList.new(request)
+    end
+
+    def initialize(funding_list_body)
+      @raw = funding_list_body
+
+      @filename = @raw['Filename']
+      @amount = @raw['Amount']
+      @acquirer = @raw['Acquirer']
+      @funding_date = Date.parse(@raw['FundingDate'])
+      @created_at = Date.parse(@raw['CreatedDate'])
+      @download_link = @raw['DownloadLink']
+    end
+
+    def download
+      @result ||= FundingListRequest.new(@download_link).result
+    end
+  end
+end

data/lib/pensio_api/funding_list_request.rb

@@ -0,0 +1,15 @@
+require 'csv'
+
+module PensioAPI
+  class FundingListRequest
+    include Mixins::RequestDefaults
+
+    attr_reader :result
+
+    def initialize(path, options={})
+      super(path, options)
+
+      @result = CSV.parse(@response.parsed_response, col_sep: ';', headers: true).reject(&:empty?)
+    end
+  end
+end

data/lib/pensio_api/mixins/has_transactions.rb

@@ -0,0 +1,36 @@
+module PensioAPI
+  module Mixins
+    module HasTransactions
+      def self.included(base)
+        base.send(:include, Enumerable)
+        base.send(:attr_reader, :transactions)
+      end
+
+      def each
+        @transactions.each { |t| yield t }
+      end
+
+      def last
+        @transactions.last
+      end
+
+      private
+
+      def map_transactions
+        @transactions = if raw_transactions.is_a?(Array)
+          raw_transactions.map { |t| PensioAPI::Transaction.new(t) }
+        else
+          [PensioAPI::Transaction.new(raw_transactions)]
+        end
+      end
+
+      def raw_transactions
+        @raw_transactions ||= if @raw['Transactions']
+          @raw['Transactions']['Transaction']
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/pensio_api/mixins/id.rb

@@ -0,0 +1,9 @@
+module PensioAPI
+  module Mixins
+    module ID
+      def id
+        @raw["#{ self.class.name.demodulize }Id"]
+      end
+    end
+  end
+end

data/lib/pensio_api/mixins/method_missing.rb

@@ -0,0 +1,9 @@
+module PensioAPI
+  module Mixins
+    module MethodMissing
+      def method_missing(method, *args, &block)
+        @raw[method.to_s.camelize] || super
+      end
+    end
+  end
+end

data/lib/pensio_api/mixins/request_defaults.rb

@@ -0,0 +1,50 @@
+module PensioAPI
+  module Mixins
+    module RequestDefaults
+      def self.included(base)
+        base.send(:include, HTTParty)
+        base.send(:attr_reader, :response)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def set_base_uri
+          self.base_uri PensioAPI::Credentials.base_uri unless self.base_uri
+        end
+      end
+
+      HEADERS = {
+        'Content-Type' => 'application/x-www-form-urlencoded'
+      }
+
+      def initialize(path, options={})
+        self.class.set_base_uri
+
+        raise Errors::NoCredentials unless credentials_supplied?
+
+        @response = self.class.post(path, request_options(options))
+      end
+
+      private
+
+      def request_options(options)
+        {
+          basic_auth: auth,
+          headers: (options.delete(:headers) || {}).merge(HEADERS),
+          body: options
+        }
+      end
+
+      def auth
+        {
+          username: PensioAPI::Credentials.username,
+          password: PensioAPI::Credentials.password
+        }
+      end
+
+      def credentials_supplied?
+        Credentials.base_uri && Credentials.username && Credentials.password
+      end
+    end
+  end
+end

data/lib/pensio_api/mixins/timestamps.rb

@@ -0,0 +1,13 @@
+module PensioAPI
+  module Mixins
+    module Timestamps
+      def created_at
+        Time.parse(@raw['CreatedDate'])
+      end
+
+      def updated_at
+        Time.parse(@raw['UpdatedDate'])
+      end
+    end
+  end
+end

data/lib/pensio_api/request.rb

@@ -0,0 +1,18 @@
+module PensioAPI
+  class Request
+    include Mixins::RequestDefaults
+
+    attr_reader :headers, :body
+
+    def initialize(path, options={})
+      super(path, options)
+
+      @headers = @response.parsed_response['APIResponse']['Header']
+      @body = @response.parsed_response['APIResponse']['Body']
+    end
+
+    def response_contains?(key)
+      @body && @body.has_key?(key)
+    end
+  end
+end

data/lib/pensio_api/reservation.rb

@@ -0,0 +1,28 @@
+module PensioAPI
+  class Reservation
+    def self.of_fixed_amount(options={})
+      request = Request.new('/merchant/API/reservationOfFixedAmount', options)
+      Responses::Reservation.new(request)
+    end
+
+    def initialize(transaction)
+      @transaction = transaction
+    end
+
+    def capture(options={})
+      request = Request.new('/merchant/API/captureReservation', options.merge(reservation_options))
+      Responses::ReservationCapture.new(request)
+    end
+
+    def release(options={})
+      request = Request.new('/merchant/API/releaseReservation', options.merge(reservation_options))
+      Responses::ReservationRelease.new(request)
+    end
+
+    private
+
+    def reservation_options
+      { transaction_id: @transaction.id }
+    end
+  end
+end

data/lib/pensio_api/responses/base.rb

@@ -0,0 +1,32 @@
+module PensioAPI
+  module Responses
+    class Base
+      include PensioAPI::Mixins::MethodMissing
+
+      attr_reader :raw
+
+      def initialize(request)
+        @raw = request.body
+        @headers = request.headers
+        unless success?
+          raise PensioAPI::Errors::BadRequest.new(request) unless header_ok
+          raise PensioAPI::Errors::GatewayError.new(request) unless body_ok
+        end
+      end
+
+      def success?
+        header_ok && body_ok
+      end
+
+      private
+
+      def header_ok
+        @headers['ErrorCode'].to_i == 0
+      end
+
+      def body_ok
+        !@raw.has_key?('Result') || ['Success', 'OK', nil].include?(@raw['Result'])
+      end
+    end
+  end
+end

data/lib/pensio_api/responses/funding_list.rb

@@ -0,0 +1,43 @@
+module PensioAPI
+  module Responses
+    class FundingList < Base
+      attr_reader :funding_lists, :page_count
+
+      include Enumerable
+
+      def initialize(request)
+        super(request)
+
+        map_funding_lists
+
+        @page_count = if @raw['Fundings']
+          (@raw['Fundings']['numberOfPages'] || 0).to_i
+        else
+          0
+        end
+      end
+
+      def each
+        @funding_lists.each { |fl| yield fl }
+      end
+
+      private
+
+      def map_funding_lists
+        @funding_lists = if raw_funding_lists.is_a?(Array)
+          raw_funding_lists.map { |fl| PensioAPI::FundingList.new(fl) }
+        else
+          [PensioAPI::FundingList.new(raw_funding_lists)]
+        end
+      end
+
+      def raw_funding_lists
+        @raw_funding_lists ||= if @raw['Fundings'] && raw['Fundings']['Funding']
+          @raw['Fundings']['Funding']
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/pensio_api/responses/gateway_url.rb

@@ -0,0 +1,13 @@
+module PensioAPI
+  module Responses
+    class GatewayURL < Base
+      attr_reader :url
+
+      def initialize(request)
+        super(request)
+
+        @url = @raw['Url']
+      end
+    end
+  end
+end