pxfusion 0.0.4

data/README.md

@@ -0,0 +1,117 @@
+# PxFusion
+
+[![Build Status](https://magnum.travis-ci.com/3months/pxfusion.png?token=FA4EnSunh4Af329WCePs&branch=master)](https://magnum.travis-ci.com/3months/pxfusion)
+
+A Rubygem for talking to DPS's PxFusion payment product via their SOAP API. Includes the ablity to start a transaction, and then query for the status of that transaction once the payment is complete, following the pictured flow:
+
+![PxFusion Workflow](http://www.paymentexpress.com/DPS/media/technical/Work_Flow.png)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'pxfusion'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install pxfusion
+    
+Some configuration settings are available:
+
+``` ruby
+# Your PxFusion username
+PxFusion.username = 'sample'
+      
+ # Your PxFusion password
+PxFusion.password = 'sample'
+
+# A global return URL
+# You can also override the return URL by passing
+# it into a Transaction constructor
+PxFusion.default_return_url = 'https://test.site/purchase'
+
+# Override the default currency to charge in
+# (Default is NZD)
+PxFusion.default_currency = 'USD'
+```
+   
+In a Rails project, you should put this configuration in an initializer or your Rails
+environment configuration. Remember, DO NOT PLACE PASSWORDS IN YOUR CODE. Instead, you 
+might want to load your configuration into environment variables, and refer to them 
+using notation like `ENV['PXFUSION_USERNAME']`.     
+
+## Usage
+
+The gem wraps around PxFusion's SOAP API. Given correct credentials, it will happily build a `PxFusion` transaction for you, but then it's up to you to build the form required to submit to DPS. Any `PxFusion::Transaction` object can be passed straight to a `form_for` method though, so it oughtn't be too difficult:
+
+``` ruby
+# app/controllers/payments_controller.rb
+
+def new
+  @order = Order.find(1)
+  @transaction = PxFusion::Transaction.new(amount: @order.total, reference: @order.to_param, return_url: payments_path)
+  render
+ end
+ 
+ # This is the POST-back destination for PxFusion
+ def create
+   @order = Order.find(1)
+   @transaction = PxFusion::Transaction.fetch(params[:sessionid])
+   
+   if @transaction.status == PxFusion.statuses[:approved]
+     @order.paid!
+     respond_to root_path and return
+   else
+     render :new
+   end
+ end
+ ```
+ 
+ And then your view:
+ 
+ ``` erb
+ # app/views/payments/new.html.erb
+ 
+ <%= form_for @transaction do |f| %>
+   <%= f.hidden_field :session_id, name: 'SessionId' %>
+   <%= text_field_tag 'CardNumber' %>
+   <%= date_select_tag 'ExpiryMonth', include_days: false %>
+   <%= text_field_tag 'CardHolderName' %>
+   <%= text_field_tag 'Cvc2', maxlength: 4 %>
+   <%= f.submit 'Make Payment' %>
+<% end %>
+```
+
+**Please read the [PxFusion docs](http://www.paymentexpress.com/Technical_Resources/Ecommerce_NonHosted/PxFusion) while implementing your payment flow to ensure you understand the process - it'll help you avoid confusing problems, which is important, as this gateway is not well documented**.
+
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Run the specs: `rspec spec`
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Think something's missing?
+
+If you can think of a way that this gem could be easier to use, or if you've found a bug (reasonably) likely, then please [lodge an issue on Github](https://github.com/3months/pxfusion/issues/), so that we can help out. Thanks!
+
+
+## If you need to regenerate the HTTP fixtures
+
+For portability and testing speed, we use fixtures to test API calls against, rather than calling the actual API. This works usually, but if you're seeing strange results or have changed any API methods, you can rengenerate the fixtures:
+
+1. Remove the current fixtures: `rm -r spec/fixtures`
+3. Add your credentials to `spec/spec_helper.rb` **BE SURE NOT TO COMMIT THIS FILE**
+4. Generate a Transaction and add the transaction ID into: `spec/pxfusion/transaction_spec.rb`
+5. Run the specs 
+6. Commit and pull request the fixture changes as above if necessary
+
+

data/Rakefile

@@ -0,0 +1,5 @@
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/pxfusion.rb

@@ -0,0 +1,59 @@
+require "pxfusion/version"
+require "pxfusion/client"
+require "pxfusion/transaction"
+
+module PxFusion
+  class << self
+    attr_writer :endpoint,
+                :form_endpoint,
+                :username,
+                :password,
+                :default_currency,
+                :logger,
+                :logging
+    attr_accessor :default_return_url
+
+    [:username, :password].each do |required_attribute|
+      define_method required_attribute do
+        raise "#{required_attribute} must be set" if !instance_variable_get("@#{required_attribute}")
+        instance_variable_get("@#{required_attribute}")
+      end
+    end
+
+    def endpoint
+      @endpoint ||= "https://sec.paymentexpress.com/pxf/pxf.svc"
+    end
+
+    def form_endpoint
+      @form_endpoint ||= "https://sec.paymentexpress.com/pxmi3/pxfusionauth"
+    end
+
+    def default_currency
+      @default_currency ||= "NZD"
+    end
+
+    def logger
+      @logger ||= Logger.new(STDOUT) if logging
+    end
+
+    def logging
+      @logging ||= false
+    end
+
+    def client
+      @client ||= Client.new
+    end
+
+    def statuses
+      {
+        approved: 0,
+        declined: 1,
+        retry: 2,
+        invalid_post: 3,
+        unknown: 4,
+        cancelled: 5,
+        not_found: 6
+      }
+    end
+  end
+end

data/lib/pxfusion/client.rb

@@ -0,0 +1,13 @@
+require "savon"
+
+class PxFusion::Client < Savon::Client
+  def initialize(options = {})
+    super(options.merge(
+      wsdl: PxFusion.endpoint.dup + "?wsdl",
+      element_form_default: :qualified,
+      log: PxFusion.logging,
+      logger: PxFusion.logger,
+      filters: [:password]
+    ))
+  end
+end

data/lib/pxfusion/transaction.rb

@@ -0,0 +1,115 @@
+require "ostruct"
+require "active_support/core_ext/hash/reverse_merge"
+
+class PxFusion::Transaction < OpenStruct
+  def initialize(attributes = {})
+    attributes.reverse_merge!(
+      username: PxFusion.username,
+      password: PxFusion.password,
+      currency: PxFusion.default_currency,
+      return_url: "https://test.host/",
+      type: 'Purchase',
+    )
+
+    super(attributes)
+    [:username, :password, :currency, :amount, :type].each do |required_attribute|
+      raise ArgumentError.new("Missing attribute: #{required_attribute}") if !self.send(required_attribute)
+    end
+
+    {amount: 12, currency: 3, reference: 16, return_url: 255, type: 8}.each_pair do |attribute, length|
+      next unless self.send(attribute)
+      attribute_value = self.send(attribute).to_s
+      given_length = attribute_value.length
+      raise ArgumentError.new("PxFusion #{attribute} too long (max #{length} characters). #{attribute} given (#{given_length} characters): #{attribute_value}") if given_length > length
+    end
+  end
+
+  def generate_session_id!
+    response = PxFusion.client.call(
+      :get_transaction_id,
+      message: Request.get_transaction_id(self)
+      ).body[:get_transaction_id_response][:get_transaction_id_result]
+
+    self.id = response[:transaction_id]
+    self.session_id = response[:session_id]
+
+    raise "Session could not be obtained from DPS" unless id && session_id
+
+    session_id
+  end
+
+  def self.fetch(id)
+    response = PxFusion.client.call(:get_transaction,message: {username: PxFusion.username, password: PxFusion.password, transactionId: id}).body
+    attributes = response[:get_transaction_response][:get_transaction_result]
+    raise PxFusion::Transaction::NotFound if attributes[:status].to_i == PxFusion.statuses[:not_found]
+
+    mapped_attributes = attributes.dup
+    attributes.each do |attribute, value|
+      case attribute
+      when :currency_name
+        mapped_attributes[:currency] = attributes[:currency_name]
+      when :txn_type
+        mapped_attributes[:type] = attributes[:txn_type]
+      when :response_text
+        mapped_attributes[:response] = attributes[:response_text]
+      when :merchant_reference
+        mapped_attributes[:reference] = attributes[:merchant_reference]
+      when :status
+        mapped_attributes[:status] = attributes[:status].to_i
+      end
+    end
+
+    self.new(mapped_attributes.merge(username: PxFusion.username, password: PxFusion.password))
+  end
+
+  private
+
+
+    class NotFound < Exception
+    end
+
+    module Request
+      def self.get_transaction_id_with_token(transaction)
+        attributes = transaction.instance_variable_get("@table")
+
+        msg = {
+          username: attributes[:username],
+          password: attributes[:password],
+          tranDetail: {
+            amount: attributes[:amount],
+            currency: attributes[:currency],
+            enableAddBillCard: true,
+            merchantReference: attributes[:reference],
+            returnUrl: attributes[:return_url],
+            txnRef: attributes[:reference],
+            txnType: attributes[:type]
+          }
+        }
+      end
+
+      def self.get_transaction_id_without_token(transaction)
+        attributes = transaction.instance_variable_get("@table")
+
+        msg = {
+          username: attributes[:username],
+          password: attributes[:password],
+          tranDetail: {
+            amount: attributes[:amount],
+            currency: attributes[:currency],
+            merchantReference: attributes[:reference],
+            returnUrl: attributes[:return_url],
+            txnRef: attributes[:reference],
+            txnType: attributes[:type]
+          }
+        }
+      end
+
+      def self.get_transaction_id(transaction)
+        # Build the hash to be sent to DPS
+        # THE ORDER MATTERS
+        attributes = transaction.instance_variable_get("@table")
+
+        attributes[:token_billing] ? get_transaction_id_with_token(transaction) : get_transaction_id_without_token(transaction)
+      end
+    end
+end

data/lib/pxfusion/version.rb

@@ -0,0 +1,3 @@
+module PxFusion
+  VERSION = "0.0.4"
+end

data/pxfusion.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'pxfusion/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "pxfusion"
+  spec.version       = PxFusion::VERSION
+  spec.authors       = ["Josh McArthur"]
+  spec.email         = ["joshua.mcarthur@gmail.com"]
+  spec.description   = %q{A Rubygem for talking to DPS's PxFusion payment product}
+  spec.summary       = %q{A Rubygem for talking to DPS's PxFusion payment product}
+  spec.homepage      = "https://github.com/3months/pxfusion"
+  spec.license       = "GPL"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "vcr"
+  spec.add_development_dependency "webmock"
+  spec.add_dependency "savon"
+  spec.add_dependency "activesupport"
+end

data/spec/fixtures/PxFusion_Transaction/_fetch/transaction_does_not_exist/.yml

@@ -0,0 +1,50 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://sec.paymentexpress.com/PxF/pxf.svc
+    body:
+      encoding: UTF-8
+      string: <?xml version="1.0" encoding="UTF-8"?><env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:tns="http://paymentexpress.com"
+        xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"><env:Body><tns:GetTransaction><tns:username><USERNAME></tns:username><tns:password><PASSWORD></tns:password><tns:transactionId>1234</tns:transactionId></tns:GetTransaction></env:Body></env:Envelope>
+    headers:
+      Soapaction:
+      - '"http://paymentexpress.com/IPxFusion/GetTransaction"'
+      Content-Type:
+      - text/xml;charset=UTF-8
+      Content-Length:
+      - '501'
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Accept:
+      - '*/*'
+      User-Agent:
+      - Ruby
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Server:
+      - DPS_PX_SERVER
+      Cache-Control:
+      - private
+      Content-Type:
+      - text/xml; charset=utf-8
+      Vary:
+      - Accept-Encoding
+      Date:
+      - Thu, 08 Aug 2013 02:03:37 GMT
+      Content-Length:
+      - '561'
+    body:
+      encoding: UTF-8
+      string: <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body><GetTransactionResponse
+        xmlns="http://paymentexpress.com"><GetTransactionResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance"><amount/><authCode/><billingId/><cardHolderName/><cardName/><cardNumber/><cardNumber2/><currencyId/><currencyName/><currencyRate
+        i:nil="true"/><cvc2ResultCode/><dateExpiry/><dateSettlement>0001-01-01T00:00:00</dateSettlement><dpsBillingId/><dpsTxnRef/><merchantReference/><responseCode/><responseText/><riskRuleMatches
+        xmlns:a="http://schemas.datacontract.org/2004/07/"/><sessionId>1234</sessionId><status>6</status><testMode>false</testMode><transactionId>1234</transactionId><transactionResultFields
+        xmlns:a="http://schemas.datacontract.org/2004/07/"/><txnData1/><txnData2/><txnData3/><txnMac/><txnRef/><txnType/></GetTransactionResult></GetTransactionResponse></s:Body></s:Envelope>
+    http_version: 
+  recorded_at: Thu, 08 Aug 2013 02:03:39 GMT
+recorded_with: VCR 2.5.0

data/spec/fixtures/PxFusion_Transaction/_fetch/transaction_is_complete/.yml

@@ -0,0 +1,52 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://sec.paymentexpress.com/PxF/pxf.svc
+    body:
+      encoding: UTF-8
+      string: <?xml version="1.0" encoding="UTF-8"?><env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:tns="http://paymentexpress.com"
+        xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"><env:Body><tns:GetTransaction><tns:username><USERNAME></tns:username><tns:password><PASSWORD></tns:password><tns:transactionId>0000010016327641e4c03879868bd001</tns:transactionId></tns:GetTransaction></env:Body></env:Envelope>
+    headers:
+      Soapaction:
+      - '"http://paymentexpress.com/IPxFusion/GetTransaction"'
+      Content-Type:
+      - text/xml;charset=UTF-8
+      Content-Length:
+      - '529'
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      Accept:
+      - '*/*'
+      User-Agent:
+      - Ruby
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Server:
+      - DPS_PX_SERVER
+      Cache-Control:
+      - private
+      Content-Type:
+      - text/xml; charset=utf-8
+      Vary:
+      - Accept-Encoding
+      Date:
+      - Thu, 08 Aug 2013 02:03:38 GMT
+      Content-Length:
+      - '769'
+    body:
+      encoding: UTF-8
+      string: <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body><GetTransactionResponse
+        xmlns="http://paymentexpress.com"><GetTransactionResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance"><amount>1.00</amount><authCode>145217</authCode><billingId/><cardHolderName>JOE
+        BLOGGS</cardHolderName><cardName>Visa</cardName><cardNumber>411111........11</cardNumber><cardNumber2/><currencyId>554</currencyId><currencyName>NZD</currencyName><currencyRate
+        i:nil="true"/><cvc2ResultCode>NotUsed</cvc2ResultCode><dateExpiry>1212</dateExpiry><dateSettlement>2013-08-01T00:00:00</dateSettlement><dpsBillingId/><dpsTxnRef>0000000108d32712</dpsTxnRef><merchantReference>Px
+        Fusion - PHP</merchantReference><responseCode>00</responseCode><responseText>APPROVED</responseText><riskRuleMatches
+        xmlns:a="http://schemas.datacontract.org/2004/07/"/><sessionId>0000010016327641e4c03879868bd001</sessionId><status>0</status><testMode>false</testMode><transactionId>0000010016327641e4c03879868bd001</transactionId><transactionResultFields
+        xmlns:a="http://schemas.datacontract.org/2004/07/"/><txnData1/><txnData2/><txnData3/><txnMac>2BC20210</txnMac><txnRef>51f9cd5705064611</txnRef><txnType>Purchase</txnType></GetTransactionResult></GetTransactionResponse></s:Body></s:Envelope>
+    http_version: 
+  recorded_at: Thu, 08 Aug 2013 02:03:40 GMT
+recorded_with: VCR 2.5.0