paypoint-blue 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9097aafc20b17695e989cce94618d414cb72d404
+  data.tar.gz: 7dfc8e09ba1b8268dfc7e357eb62b87ca8964d86
+SHA512:
+  metadata.gz: fa0c78e2028e56f6b876ba359a0090360975fee9432d6e87af6420d022069af5f01ce607d5d7f3bc4b46afad7a72bba970d5047b1224f7acd0cb5ac5de4c30f6
+  data.tar.gz: 9ae0701c9674f7b3b048f42d23ab68de6417bf14c11c8ebef486d220a46991115bebc961a90d449be04ece80f4ddd5ea1213b6fee58c469c1873072e53f538c0

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.2.1

data/.yardopts

@@ -0,0 +1 @@
+-e support/yard_ext.rb --tag "applies_defaults:Payload defaults this method will apply" --tag "api_url:API reference"

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in paypoint-blue.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Laszlo Bacsi
+Copyright (c) 2015 Drop and Collect Ltd
+
+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,71 @@
+# PayPoint::Blue
+
+API client for PayPoint's 3rd generation PSP product a.k.a PayPoint Blue.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'paypoint-blue'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install paypoint-blue
+
+## Usage
+
+Read the [documentation](http://www.rubydoc.info/gems/paypoint-blue).
+
+Run `bin/console` to start an interactive prompt for a playgound where
+you can experiment with the API. You will have a bunch of meaningful
+defaults set and some helpers to use. Just call the `help` or `h` method
+in the console to learn more about the different helpers.
+
+### Example
+
+    # Endpoint can be the actual URL or one of :test or :live.
+    # Installation id and credentials default to these ENV vars if omitted.
+    blue = PayPoint::Blue.hosted_client(
+      endpoint: :test,
+      inst_id: ENV['BLUE_API_INSTALLATION'],
+      api_id: ENV['BLUE_API_ID'],
+      api_password: ENV['BLUE_API_PASSWORD'],
+      defaults: {
+        currency: "GBP",
+        return_url: "http://example.com/callback/return",
+        skin: "9001"
+      }
+    )
+
+    blue.ping # => true
+
+    result = blue.make_payment(
+      merchant_ref: "abcd-1234",
+      amount: "4.89",
+      customer_ref: "42",
+      customer_name: "Alice"
+    )
+    result.session_id # => "39ac..."
+    result.redirect_url # => "https://hosted.paypoint.net/..."
+
+    # The hosted product doesn't have this endpoint, but the client will delegate
+    # this request to an API client for the regular API product behind the scenes.
+    blue.transaction(transaction_id) # => { processing: { ... }, payment_method: { ... }, ... }
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+1. Fork it ( https://github.com/CPlus/paypoint-blue/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,8 @@
+require "rake/testtask"
+require "bundler/gem_tasks"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/test_*.rb']
+  t.verbose = true
+end

data/bin/console

@@ -0,0 +1,167 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "paypoint/blue"
+
+def bold(text)
+  "\e[1m#{text}\e[0m"
+end
+
+def help
+  puts <<-EOS
+#{bold "API client helpers"}
+
+  #{bold "blue"}(**api_options)
+  #{bold "blue_hosted"}(**api_options)
+
+Create and memoize API clients with these two. Options are the same as for
+PayPoint::Blue::Base#initialize, but default endpoint to :test.
+
+Export BLUE_API_INSTALLATION, BLUE_API_ID, and BLUE_API_PASSWORD as environment
+variables, and you won't have to pass them to the helpers. See direnv.net for
+an easy way to do that.
+
+It's recommended to use either logging or the Runscope integration to keep track
+and inspect all the traffic. You may set the RUNSCOPE_BUCKET environment
+variable to have the integration be turned on by default. Otherwise you only
+have to provide the runscope option the first time you call one of the API
+client helpers:
+
+    blue(runscope: 'bucket-key')
+
+#{bold "Callback endpoints"}
+
+  #{bold "cb"}(id)
+
+This is most useful when using the Runscope integration. The available ids are:
+
+  :preauth_proceed, :preauth_cancel, :preauth_suspend, :preauth_suspend_replay,
+  :postauth_proceed, :postauth_cancel, :empty
+
+These will return mocky.io urls which return the proper response. Using the
+Runscope integration you will see the requests PayPoint makes to these endpoints
+in your bucket.
+
+  #{bold "callbacks"}()
+
+Returns the callbacks section of the payload with all callbacks set to proceed.
+
+#{bold "Credit/Debit cards helpers"}
+
+  #{bold "card"}(type: :mc, valid: true, threeDS: true)
+
+Returns a credit/debit card number for testing. Possible options:
+
+  type:    :mc_debit, :mc_credit, :visa_debit, :visa_credit
+  valid:   true, false
+  threeDS: true, false, :unknown
+  EOS
+end
+alias :h :help
+
+def blue_default_options
+  return_base = ENV['RUNSCOPE_BUCKET'] ? "https://#{RUNSCOPE_BUCKET}.runscope.net" : "http://bluedemo.dev"
+  {
+    runscope: ENV['RUNSCOPE_BUCKET'],
+    defaults: {
+      currency: 'GBP',
+      commerce_type: 'ECOM',
+      skin: ENV['BLUE_SKIN'],
+      return_url: "#{return_base}/callback/return",
+      restore_url: "#{return_base}/callback/restore",
+      pre_auth_callback: cb(:preauth_proceed),
+      post_auth_callback: cb(:postauth_proceed),
+      transaction_notification: cb(:empty),
+      expiry_notification: cb(:empty)
+    }
+  }
+end
+
+def blue(endpoint: :test, **options)
+  options = blue_default_options.merge(options)
+  $blue_api ||= PayPoint::Blue.api_client(endpoint: endpoint, **options)
+end
+
+def blue_hosted(endpoint: :test, **options)
+  options = blue_default_options.merge(options)
+  $blue_hosted ||= PayPoint::Blue.hosted_client(endpoint: endpoint, **options)
+end
+
+def cb(id)
+  {
+    preauth_proceed:        "http://www.mocky.io/v2/550f10df3645066a0a2a420e",
+    preauth_cancel:         "http://www.mocky.io/v2/550f10ec364506660a2a420f",
+    preauth_suspend:        "http://www.mocky.io/v2/550f10ff364506670a2a4210",
+    preauth_suspend_replay: "http://www.mocky.io/v2/550f110a364506690a2a4211",
+    postauth_proceed:       "http://www.mocky.io/v2/550f1159364506650a2a4212",
+    postauth_cancel:        "http://www.mocky.io/v2/550f11633645066c0a2a4213",
+    empty:                  "http://www.mocky.io/v2/550f11723645066c0a2a4214"
+  }[id]
+end
+
+def callbacks
+  {
+    callbacks: {
+      preAuthCallback: { url: cb(:preauth_proceed), format: "REST_JSON" },
+      postAuthCallback: { url: cb(:postauth_proceed), format: "REST_JSON" },
+      transactionNotification: { url: cb(:empty), format: "REST_JSON" },
+      expiryNotification: { url: cb(:empty), format: "REST_JSON" }
+    }
+  }
+end
+
+def card(type: :mc_debit, valid: true, threeDS: true)
+  {
+    mc_debit: {
+      true => {
+        true     => "9900000000005159",
+        false    => "9900000000000010",
+        :unknown => "9900000000010258"
+      },
+      false => {
+        true     => "9900000000005282",
+        false    => "9900000000000168",
+        :unknown => "9900000000010407"
+      }
+    },
+    mc_credit: {
+      true => {
+        true     => "9901000000005133",
+        false    => "9901000000000019",
+        :unknown => "9901000000010257"
+      },
+      false => {
+        true     => "9901000000005281",
+        false    => "9901000000000167",
+        :unknown => "9901000000010406"
+      }
+    },
+    visa_debit: {
+      true => {
+        true     => "9902000000005132",
+        false    => "9902000000000018",
+        :unknown => "9902000000010256"
+      },
+      false => {
+        true     => "9902000000005280",
+        false    => "9902000000000166",
+        :unknown => "9902000000010405"
+      }
+    },
+    visa_credit: {
+      true => {
+        true     => "9903000000005131",
+        false    => "9903000000000017",
+        :unknown => "9903000000010255"
+      },
+      false => {
+        true     => "9903000000005289",
+        false    => "9903000000000165",
+        :unknown => "9903000000010404"
+      }
+    }
+  }[type][valid][threeDS]
+end
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/paypoint/blue/api.rb

@@ -0,0 +1,134 @@
+require "paypoint/blue/base"
+
+# Client class for the API product.
+class PayPoint::Blue::API < PayPoint::Blue::Base
+
+  ENDPOINTS = {
+    test: "https://api.mite.paypoint.net:2443/acceptor/rest",
+    live: "https://api.paypoint.net/acceptor/rest",
+  }.freeze
+
+  shortcut :merchant_ref,  'transaction.merchant_ref'
+  shortcut :amount,        'transaction.amount'
+  shortcut :currency,      'transaction.currency'
+  shortcut :commerce_type, 'transaction.commerce_type'
+  shortcut :customer_ref,  'customer.merchant_ref'
+  shortcut :customer_name, 'customer.display_name'
+
+  shortcut :pre_auth_callback,        'callbacks.pre_auth_callback.url'
+  shortcut :post_auth_callback,       'callbacks.post_auth_callback.url'
+  shortcut :transaction_notification, 'callbacks.transaction_notification.url'
+  shortcut :expiry_notification,      'callbacks.expiry_notification.url'
+
+  # Test connectivity
+  #
+  # @return [true,false]
+  def ping
+    client.get "transactions/ping"
+    true
+  rescue Faraday::ClientError
+    false
+  end
+
+  # Make a payment
+  #
+  # @api_url https://developer.paypoint.com/payments/docs/#payments/make_a_payment
+  #
+  # @applies_defaults
+  #   +:currency+, +:commerce_type+, +:pre_auth_callback+,
+  #   +:post_auth_callback+, +:transaction_notification+,
+  #   +:expiry_notification+
+  #
+  # @param [Hash] payload the payload is made up of the keyword
+  #   arguments passed to the method
+  #
+  # @return the API response
+  def make_payment(**payload)
+    payload = build_payload(payload,
+      defaults: %i[
+        currency commerce_type pre_auth_callback post_auth_callback
+        transaction_notification expiry_notification
+      ]
+    )
+    client.post "transactions/#{inst_id}/payment", payload
+  end
+
+  # Submit an authorisation
+  #
+  # @api_url https://developer.paypoint.com/payments/docs/#payments/submit_an_authorisation
+  # @see #make_payment
+  #
+  # This is a convenience method which makes a payment with the
+  # transaction's +deferred+ value set to +true+.
+  #
+  # @param (see #make_payment)
+  #
+  # @return the API response
+  def submit_authorisation(**payload)
+    payload[:transaction] ||= {}
+    payload[:transaction][:deferred] = true
+    make_payment(**payload)
+  end
+
+  # Capture an authorisation
+  #
+  # @api_url https://developer.paypoint.com/payments/docs/#payments/capture_an_authorisation
+  #
+  # @applies_defaults +:commerce_type+
+  #
+  # @param [String] transaction_id the id of the previous transaction
+  # @param [Hash] payload the payload is made up of the keyword
+  #   arguments passed to the method
+  #
+  # @return the API response
+  def capture_authorisation(transaction_id, **payload)
+    payload = build_payload(payload, defaults: %i[commerce_type])
+    client.post "transactions/#{inst_id}/#{transaction_id}/capture", payload
+  end
+
+  # Cancel an authorisation
+  #
+  # @api_url https://developer.paypoint.com/payments/docs/#payments/cancel_an_authorisation
+  #
+  # @applies_defaults +:commerce_type+
+  #
+  # @param (see #capture_authorisation)
+  #
+  # @return the API response
+  def cancel_authorisation(transaction_id, **payload)
+    payload = build_payload(payload, defaults: %i[commerce_type])
+    client.post "transactions/#{inst_id}/#{transaction_id}/cancel", payload
+  end
+
+  # Get transaction details
+  #
+  # @api_url https://developer.paypoint.com/payments/docs/#payments/request_a_previous_transaction
+  #
+  # @param [String] transaction_id the id of the transaction
+  #
+  # @return the API response
+  def transaction(transaction_id)
+    client.get "transactions/#{inst_id}/#{transaction_id}"
+  end
+
+  # Refund a payment
+  #
+  # @api_url https://developer.paypoint.com/payments/docs/#payments/refund_a_payment
+  #
+  # Without a payload this will refund the full amount. If you only want
+  # to refund a smaller amount, you will need to pass either the
+  # +amount+ or a +transaction+ hash as a keyword argument.
+  #
+  # @example Partial refund
+  #   blue.refund_payment(txn_id, amount: '3.49') # assumes currency set as default
+  #
+  # @param (see #capture_authorisation)
+  #
+  # @return the API response
+  def refund_payment(transaction_id, **payload)
+    defaults = payload[:amount] || payload[:transaction] && payload[:transaction][:amount] ? %i[currency commerce_type] : []
+    payload = build_payload(payload, defaults: defaults)
+    client.post "transactions/#{inst_id}/#{transaction_id}/refund", payload
+  end
+
+end

data/lib/paypoint/blue/base.rb

@@ -0,0 +1,122 @@
+require "faraday"
+require "faraday_middleware"
+
+require "paypoint/blue/payload_builder"
+require "paypoint/blue/body_extractor"
+require "paypoint/blue/hash_key_converter"
+require "paypoint/blue/raise_errors"
+require "paypoint/blue/faraday_runscope"
+
+module PayPoint
+  module Blue
+
+    # Abstract base class for the API clients. Takes care of
+    # initializing the Faraday client by setting up middlewares in the
+    # right order.
+    #
+    # The base class doesn't implement any of the API interface methods,
+    # but leaves that to the subclasses.
+    #
+    # @note All payloads expected by the API interface methods in the
+    #   subclasses will be processed by {PayloadBuilder} and the
+    #   {HashKeyConverter} middleware. Shortcuts will be moved to their
+    #   proper paths, default values will be applied, and snakecase keys
+    #   will be converted to camelcase.
+    #
+    # @abstract
+    class Base
+
+      include PayloadBuilder
+
+      # The Faraday client
+      attr_reader :client
+
+      # Creates a PayPoint Blue API client
+      #
+      # Options not listed here will be passed on to the Faraday client.
+      #
+      # @param endpoint +:test+, +:live+, or a string with the API
+      #   endpoint URL
+      # @param inst_id the ID for your installation as provided by
+      #   PayPoint
+      # @param api_id your API user ID
+      # @param api_password your API user password
+      #
+      # @option options [Hash] :defaults default payload values; see the
+      #   documentation of the methods of {API} and {Hosted} for the
+      #   payload keys that can have defaults
+      # @option options [true,false] :log whether to log requests and
+      #   responses
+      # @option options [Logger] :logger a custom logger instance,
+      #   implies +log: true+
+      # @option options [true,false] :raw whether to return the raw
+      #   +Faraday::Response+ object instead of a parsed value
+      # @option options [String] :runscope when used, all traffic will
+      #   pass through the provided {https://www.runscope.com/ Runscope}
+      #   bucket, including notification callbacks
+      def initialize(endpoint:,
+                     inst_id: ENV['BLUE_API_INSTALLATION'],
+                     api_id: ENV['BLUE_API_ID'],
+                     api_password: ENV['BLUE_API_PASSWORD'],
+                     **options)
+
+        @endpoint = self.class.const_get('ENDPOINTS').fetch(endpoint, endpoint.to_s)
+
+        @inst_id      = inst_id or raise ArgumentError, "missing inst_id"
+        @api_id       = api_id or raise ArgumentError, "missing api_id"
+        @api_password = api_password or raise ArgumentError, "missing api_password"
+
+        options[:url] = @endpoint
+        @options = options
+
+        self.defaults = options.delete(:defaults)
+
+        @client = build_client
+      end
+
+      private
+
+      attr_reader :inst_id, :options
+
+      def client_options
+        options.select { |k,v| Faraday::ConnectionOptions.members.include?(k) }
+      end
+
+      def build_client
+        Faraday.new(client_options) do |f|
+          unless options[:raw]
+            # This extracts the body and discards all other data from the
+            # Faraday::Response object. It should be placed here before
+            # all response middlewares, so that it runs as the last one.
+            f.use PayPoint::Blue::BodyExtractor
+          end
+
+          f.use PayPoint::Blue::RaiseErrors
+          unless options[:raw]
+            f.response :mashify
+            f.use PayPoint::Blue::HashKeyConverter
+          end
+          f.response :dates
+          f.response :json, content_type: /\bjson$/
+          f.response :logger, options[:logger] if options[:logger] || options[:log]
+
+          # This sends all API traffic through Runscope, including
+          # notifications. It needs to be inserted here before the JSON
+          # request middleware so that it is able to transform
+          # notification URLs too.
+          if options[:runscope]
+            f.use FaradayRunscope, options[:runscope],
+              transform_paths: /\A(callbacks|session)\.\w+(Callback|Notification)\.url\Z/
+          end
+
+          f.request :basic_auth, @api_id, @api_password
+          f.request :json
+
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+    end
+
+  end
+end

data/lib/paypoint/blue/body_extractor.rb

@@ -0,0 +1,18 @@
+module PayPoint
+  module Blue
+
+    # Faraday middleware which extracts the body from the response
+    # object and returns with just that discarding all other meta
+    # information.
+    class BodyExtractor < Faraday::Middleware
+
+      # Extract and return just the body discarding everything else
+      def call(env)
+        response = @app.call(env)
+        response.env[:body]
+      end
+
+    end
+
+  end
+end

data/lib/paypoint/blue/error.rb

@@ -0,0 +1,57 @@
+module PayPoint
+  module Blue
+
+    # Abstract error base class
+    # @abstract
+    class Error < StandardError
+
+      # the response that caused the error
+      attr_reader :response
+
+      # the outcome code (e.g. +'V402'+)
+      attr_reader :code
+
+      # Initializes the error from the response object. It uses the
+      # outcome message from the response if set.
+      def initialize(response)
+        @response = response
+
+        if outcome
+          @code   = outcome[:reason_code]
+          message = outcome[:reason_message]
+        else
+          message = "the server responded with status #{response[:status]}"
+        end
+
+        super(message)
+      end
+
+      private
+
+      def outcome
+        @outcome ||= response[:body].is_a?(Hash) && response[:body][:outcome]
+      end
+
+      # Generic client error class, also a base class for more specific
+      # types of errors
+      class Client < Error; end
+
+      # Specific error class for errors with a +'V'+ outcome code
+      class Validation < Error; end
+
+      # Specific error class for errors with an +'A'+ outcome code
+      class Auth < Error; end
+
+      # Specific error class for errors with a +'C'+ outcome code
+      class Cancelled < Error; end
+
+      # Specific error class for errors with a +'X'+ outcome code
+      class External < Error; end
+
+      # Specific error class for errors with an +'U'+ outcome code
+      class Suspended < Error; end
+
+    end
+
+  end
+end

data/lib/paypoint/blue/faraday_runscope.rb

@@ -0,0 +1,74 @@
+class FaradayRunscope < Faraday::Middleware
+
+  CUSTOM_PORT = "Runscope-Request-Port".freeze
+
+  def initialize(app, bucket, transform_paths: false)
+    super(app)
+    self.bucket = bucket
+    self.transform_paths = Array(transform_paths)
+  end
+
+  def call(env)
+    if env.url.port != env.url.default_port
+      env.request_headers[CUSTOM_PORT] = env.url.port.to_s
+      env.url.port = env.url.default_port
+    end
+
+    transform_url env.url
+
+    if transform_paths && env.body.respond_to?(:each_with_index)
+      transform_paths!(env.body)
+    end
+
+    @app.call env
+  end
+
+  protected
+
+  attr_accessor :bucket, :transform_paths
+
+  def transform_url(url)
+    if url.respond_to?(:host=)
+      url.host = runscope_host(url.host)
+    elsif url.is_a?(String)
+      uri = URI.parse(url)
+      uri.host = runscope_host(uri.host)
+      return uri.to_s
+    end
+    url
+  end
+
+  def runscope_host(host)
+    "#{host.tr('.', '-')}-#{bucket}.runscope.net"
+  end
+
+  def transform_paths!(enum, path=nil)
+    each_pair(enum) do |key, value|
+      key_path = path ? "#{path}.#{key}" : key.to_s
+      if value.respond_to?(:each_with_index)
+        transform_paths!(value, key_path)
+      elsif transform_path?(key_path)
+        enum[key] = transform_url(value)
+      end
+    end
+  end
+
+  def each_pair(enum)
+    if enum.respond_to?(:each_pair)
+      enum.each_pair do |key, value|
+        yield key, value
+      end
+    else
+      enum.each_with_index do |value, index|
+        yield index, value
+      end
+    end
+  end
+
+  def transform_path?(path)
+    transform_paths.any? do |path_to_transform|
+      path_to_transform === path
+    end
+  end
+
+end

data/lib/paypoint/blue/hash_key_converter.rb

@@ -0,0 +1,26 @@
+module PayPoint
+  module Blue
+
+    # Faraday middleware for converting hash keys in the request payload
+    # from snake_case to camelCase and the other way around in the
+    # response.
+    class HashKeyConverter < Faraday::Middleware
+
+      # Convert hash keys to camelCase in the request and to snake_case
+      # in the response
+      def call(env)
+        if env.body.is_a?(Enumerable)
+          env.body = Utils.camelcase_and_symbolize_keys(env.body)
+        end
+
+        @app.call(env).on_complete do |response_env|
+          if response_env.body.is_a?(Enumerable)
+            response_env.body = Utils.snakecase_and_symbolize_keys(response_env.body)
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/paypoint/blue/hosted.rb

@@ -0,0 +1,92 @@
+require "forwardable"
+
+require "paypoint/blue/base"
+
+# Client class for the Hosted product.
+class PayPoint::Blue::Hosted < PayPoint::Blue::Base
+
+  ENDPOINTS = {
+    test: "https://hosted.mite.paypoint.net/hosted/rest",
+    live: "https://hosted.paypoint.net/hosted/rest"
+  }.freeze
+
+  shortcut :merchant_ref,  'transaction.merchant_reference'
+  shortcut :amount,        'transaction.money.amount.fixed'
+  shortcut :currency,      'transaction.money.currency'
+  shortcut :customer_ref,  'customer.identity.merchant_customer_id'
+  shortcut :customer_name, 'customer.details.name'
+  shortcut :return_url,    'session.return_url.url'
+  shortcut :restore_url,   'session.restore_url.url'
+  shortcut :skin,          'session.skin'
+
+  shortcut :pre_auth_callback,        'session.pre_auth_callback.url'
+  shortcut :post_auth_callback,       'session.post_auth_callback.url'
+  shortcut :transaction_notification, 'session.transaction_notification.url'
+
+  extend Forwardable
+
+  def_delegators :@api_client,
+    :capture_authorisation,
+    :cancel_authorisation,
+    :transaction,
+    :refund_payment
+
+  # The Hosted product has only a few endpoints. However, users most
+  # likey will want to access the endpoints of the API product as well.
+  # Therefore, this class also delegates to an API client which is
+  # initialized using the same options that this object receives.
+  def initialize(**options)
+    @api_client = PayPoint::Blue::API.new(**options)
+    super
+  end
+
+  # Test connectivity
+  #
+  # @return [true,false]
+  def ping
+    client.get "sessions/ping"
+    true
+  rescue Faraday::ClientError
+    false
+  end
+
+  # Make a payment
+  #
+  # @api_url https://developer.paypoint.com/payments/docs/#payments/make_a_payment
+  #
+  # @applies_defaults
+  #   +:currency+, +:return_url+, +:restore_url+, +:skin+,
+  #   +:pre_auth_callback+, +:post_auth_callback+, +:transaction_notification+
+  #
+  # @param [Hash] payload the payload is made up of the keyword
+  #   arguments passed to the method
+  #
+  # @return the API response
+  def make_payment(**payload)
+    payload = build_payload(payload,
+      defaults: %i[
+        currency return_url restore_url skin
+        pre_auth_callback post_auth_callback transaction_notification
+      ]
+    )
+    client.post "sessions/#{inst_id}/payments", build_payload(payload)
+  end
+
+  # Submit an authorisation
+  #
+  # @api_url https://developer.paypoint.com/payments/docs/#payments/submit_an_authorisation
+  # @see #make_payment
+  #
+  # This is a convenience method which makes a payment with the
+  # transaction's +deferred+ value set to +true+.
+  #
+  # @param (see #make_payment)
+  #
+  # @return the API response
+  def submit_authorisation(**payload)
+    payload[:transaction] ||= {}
+    payload[:transaction][:deferred] = true
+    make_payment(**payload)
+  end
+
+end

data/lib/paypoint/blue/payload_builder.rb

@@ -0,0 +1,77 @@
+module PayPoint
+  module Blue
+
+    # Provides helper methods for payload construction used throughout
+    # the API. It allows definition of payload shortcuts and default
+    # values.
+    module PayloadBuilder
+
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        attr_accessor :shortcuts
+
+        # Define a payload shortcut
+        #
+        # Shortcuts help payload construction by defining short aliases
+        # to commonly used paths.
+        #
+        # @example Define and use a shortcut
+        #   PayPoint::Blue::Hosted.shortcut :amount, 'transaction.money.amount.fixed'
+        #   blue.make_payment(amount: '3.49', ...)
+        #     # this will be turned into
+        #     # { transaction: { money: { amount: { fixed: '3.49' } } } }
+        #
+        # @param [Symbol] key the shortcut key
+        # @param [String] path a path into the payload with segments
+        #   separated by dots (e.g. +'transaction.money.amount.fixed'+)
+        def shortcut(key, path=nil)
+          if path.nil?
+            shortcuts && shortcuts[key]
+          else
+            self.shortcuts ||= {}
+            shortcuts[key] = path
+          end
+        end
+      end
+
+      attr_accessor :defaults
+
+      # Builds the payload by applying default values and replacing
+      # shortcuts
+      #
+      # @param [Hash] payload the original payload using shortcuts
+      # @param [Array<Symbol>] defaults an array of symbols for defaults
+      #   that should be applied to this payload
+      def build_payload(payload, defaults: [])
+        apply_defaults(payload, defaults)
+        payload.keys.each do |key|
+          if path = self.class.shortcut(key)
+            value = payload.delete(key)
+            segments = path.split('.').map(&:to_sym)
+            leaf = segments.pop
+            leaf_parent = segments.reduce(payload) {|h,k| h[k] ||= {}}
+            leaf_parent[leaf] ||= value
+          end
+        end
+        payload
+      end
+
+      private
+
+      def apply_defaults(payload, applicable_defaults)
+        return unless defaults
+
+        defaults.each do |key, value|
+          if applicable_defaults.include?(key) && !payload.has_key?(key)
+            payload[key] = value
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/paypoint/blue/raise_errors.rb

@@ -0,0 +1,53 @@
+require "paypoint/blue/error"
+
+module PayPoint
+  module Blue
+
+    # Faraday response middleware for handling various error scenarios
+    class RaiseErrors < Faraday::Response::Middleware
+
+      # Raise an error if the response outcome signifies a failure or
+      # the HTTP status code is 400 or greater.
+      #
+      # @raise [Error::Validation] for an outcome code starting with +V+
+      # @raise [Error::Auth]       for an outcome code starting with +A+
+      # @raise [Error::Cancelled]  for an outcome code starting with +C+
+      # @raise [Error::External]   for an outcome code starting with +X+
+      # @raise [Error::Suspended]  for an outcome code starting with +U+
+      # @raise [Error::Client]     for all other error scenarios
+      def on_complete(env)
+        outcome = fetch_outcome(env)
+        if outcome
+          case outcome[:reason_code]
+          when /^S/ then return
+          when /^V/ then raise Error::Validation, response_values(env)
+          when /^A/ then raise Error::Auth,       response_values(env)
+          when /^C/ then raise Error::Cancelled,  response_values(env)
+          when /^X/ then raise Error::External,   response_values(env)
+          when /^U/ then raise Error::Suspended,  response_values(env)
+          else
+            raise Error::Client, response_values(env)
+          end
+        elsif env.status >= 400
+          raise Error::Client, response_values(env)
+        end
+      end
+
+      private
+
+      def fetch_outcome(env)
+        env.body.is_a?(Hash) && env.body[:outcome]
+      end
+
+      def response_values(env)
+        {
+          status:  env.status,
+          headers: env.response_headers,
+          body:    env.body
+        }
+      end
+
+    end
+
+  end
+end

data/lib/paypoint/blue/utils.rb

@@ -0,0 +1,51 @@
+module PayPoint
+  module Blue
+    module Utils
+
+      extend self
+
+      def snakecase_and_symbolize_keys(hash)
+        case hash
+        when Hash
+          hash.each_with_object({}) do |(key, value), snakified|
+            snakified[snakecase(key)] = snakecase_and_symbolize_keys(value)
+          end
+        when Enumerable
+          hash.map {|v| snakecase_and_symbolize_keys(v)}
+        else
+          hash
+        end
+      end
+
+      def camelcase_and_symbolize_keys(hash)
+        case hash
+        when Hash
+          hash.each_with_object({}) do |(key, value), camelized|
+            camelized[camelcase(key)] = camelcase_and_symbolize_keys(value)
+          end
+        when Enumerable
+          hash.map {|v| camelcase_and_symbolize_keys(v)}
+        else
+          hash
+        end
+      end
+
+      private
+
+      def snakecase(original)
+        string = original.is_a?(Symbol) ? original.to_s : original.dup
+        string.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+        string.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+        string.downcase!
+        string.to_sym
+      end
+
+      def camelcase(original)
+        string = original.is_a?(Symbol) ? original.to_s : original.dup
+        string.gsub!(/_([a-z\d]*)/) { $1.capitalize }
+        string.to_sym
+      end
+
+    end
+  end
+end

data/lib/paypoint/blue/version.rb

@@ -0,0 +1,5 @@
+module PayPoint
+  module Blue
+    VERSION = "0.1.0"
+  end
+end

data/lib/paypoint/blue.rb

@@ -0,0 +1,24 @@
+require "paypoint/blue/version"
+require "paypoint/blue/api"
+require "paypoint/blue/hosted"
+require "paypoint/blue/utils"
+
+module PayPoint
+  module Blue
+
+    # Creates a client for the PayPoint Blue API product
+    #
+    # @see PayPoint::Blue::Base#initialize
+    def self.api_client(**options)
+      PayPoint::Blue::API.new(**options)
+    end
+
+    # Creates a client for the PayPoint Blue Hosted product
+    #
+    # @see PayPoint::Blue::Base#initialize
+    def self.hosted_client(**options)
+      PayPoint::Blue::Hosted.new(**options)
+    end
+
+  end
+end

data/paypoint-blue.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'paypoint/blue/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "paypoint-blue"
+  spec.version       = PayPoint::Blue::VERSION
+  spec.authors       = ["Laszlo Bacsi"]
+  spec.email         = ["lackac@lackac.hu"]
+
+  spec.summary       = %q{API client for PayPoint Blue}
+  spec.description   = %q{API client for PayPoint's 3rd generation PSP product a.k.a PayPoint Blue}
+  spec.homepage      = "https://github.com/CPlus/paypoint-blue"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday"
+  spec.add_dependency "faraday_middleware"
+  spec.add_dependency "hashie"
+
+  spec.add_development_dependency "bundler", "~> 1.8"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "webmock"
+end

data/support/yard_ext.rb

@@ -0,0 +1,13 @@
+class ShortcutHandler < YARD::Handlers::Ruby::Base
+  handles method_call(:shortcut)
+  namespace_only
+
+  def process
+    unless namespace.docstring.index('== Payload Shortcuts')
+      namespace.docstring += "\n\n== Payload Shortcuts\n"
+    end
+    shortcut = statement.parameters.first.jump(:ident).source
+    path = statement.parameters[1].jump(:string_content).source
+    namespace.docstring += "\n[+:#{shortcut}+] +#{path}+"
+  end
+end

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: paypoint-blue
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Laszlo Bacsi
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-03-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: API client for PayPoint's 3rd generation PSP product a.k.a PayPoint Blue
+email:
+- lackac@lackac.hu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- ".yardopts"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/paypoint/blue.rb
+- lib/paypoint/blue/api.rb
+- lib/paypoint/blue/base.rb
+- lib/paypoint/blue/body_extractor.rb
+- lib/paypoint/blue/error.rb
+- lib/paypoint/blue/faraday_runscope.rb
+- lib/paypoint/blue/hash_key_converter.rb
+- lib/paypoint/blue/hosted.rb
+- lib/paypoint/blue/payload_builder.rb
+- lib/paypoint/blue/raise_errors.rb
+- lib/paypoint/blue/utils.rb
+- lib/paypoint/blue/version.rb
+- paypoint-blue.gemspec
+- support/yard_ext.rb
+homepage: https://github.com/CPlus/paypoint-blue
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: API client for PayPoint Blue
+test_files: []
+has_rdoc: