docdata 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 092c89afd8ea21f98293b06c1dc41204c606290f
-  data.tar.gz: 18726ea6de8213826d69d7d916172a841e52aba0
+  metadata.gz: c5ff4754891764a2fadf457caa3103234ab0ff66
+  data.tar.gz: 4a88eccbd3b38ca964800661cbff4f8caa01d856
 SHA512:
-  metadata.gz: 269ff144bf374c38aafc9037ddd8ee089a05084e282362b28072d54462a5eb85691d684763acfb3f3e5a56fb98a67fa26dbeb9420b03993e06517a0469eb3402
-  data.tar.gz: bc7586ee50bc8150d76002065aaf0e78d9a719aadcc7270cd5d1c9f279f6d87c3bc293211f14c81f8bd8fd7cfde8e160d9f08df2b134438ac6177943cec406b1
+  metadata.gz: 14bb38e8034b1b17ce035e0e2a49637491622a699556b1886aa803bedd78e52685de32fa2cb4110c975cea5c8bb52d29d7e46af219b200f0ad1f4e0911042ab3
+  data.tar.gz: bf6a93bb98864ffb8a576bf6c9e4ef07e6832fc3221d1cd5805302dcd21bc0fd0da042f11ef17dcdff66b25d9ee3017775ec4dfcfd7328cbe24c04e9be7cbff7

data/.coveralls.yml

@@ -0,0 +1,2 @@
+service_name: travis-pro
+repo_token: 6imlOxW82jtN0x1uQsfPlrn9BbJaouXdI

data/.gitignore

@@ -1,5 +1,6 @@
 *.gem
 *.rbc
+.DS_Store
 .bundle
 .config
 .yardoc
@@ -7,11 +8,13 @@ Gemfile.lock
 InstalledFiles
 _yardoc
 coverage
-doc/
 lib/bundler/man
 pkg
+doc
 rdoc
 spec/reports
 test/tmp
 test/version_tmp
 tmp
+spec/vcr_cassettes
+test-credentials.yaml

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+script: bundle exec rake --trace
+rvm:
+- '2.0'
+env:
+  global:
+  - secure: TIDimYgwlRDIMSeNUDsc3Bwb1dCSdfyF89clBbGssrolmxDSOMCWEkKg+XVeiR8ZTaprule80X35rw8xqoNqpYuZedH0Z6owu1JQ6C3XkUW9TXVhcIQ3WF7KF8YVXwSLYTf9W4F9j8KNW8azb2PmmuLbDqmqAhBxMsG+i1hgPaw=
+  - secure: ZrkG1/8uInY6xiP8xD7HhjDxgxmvbxRHdmzveN/qh9CIsOjCAESfgjd9WjiP8IiW2/G5tYRkVeqYijDLnTkWuyn2lsiWRjE+CflwqTo8XHQCKLCKGbLJzR13i+ulos5ByjUV7OVPTZ241Lxaaw7JBgUgFP3BUqA0127pX8mxpm0=
+  - secure: MQLynyivQIoClPKv3mA62S3E3SVR1ho/8rQ3xs43fsT4PNClwftOO+fRiH0djkmZ4dzJSAD5H70ikcAJoOQ3dAul2+xA5uPAt4AUBk0sindcT2PeEnjPIH9rt/AxLYG67MWZihTr2xcQ38xh6nNJZslyFSglntCTFPmyBy3D0KM=
+  - secure: FrWAE8ZvvBnI6+VwxdBZIHQwQPQKOqFMP9g3XVMyJOPCF4HWlzBor1e5MZ9UquVYaL+/2OL0aDxhgN33y0YsX3/2c5Z25cPGglzE3VsPzRdzDqarwPEz/tEzTYG/bKKPIEI9q+cKQNnSBuMtk4EELBmOJ9iA8jPD0OCNgRedlRw=

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014 Henk Meijer
+Copyright (c) 2014 Henk Meijer, Eseks Media
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,6 +1,12 @@
-# DocData
+# Docdata
+[![Build Status](https://secure.travis-ci.org/henkm/docdata.png)](http://travis-ci.org/henkm/docdata)
+[![Gem Version](https://badge.fury.io/rb/docdata.svg)](http://badge.fury.io/rb/docdata)
+[![Code Climate](https://codeclimate.com/github/henkm/docdata/badges/gpa.svg)](https://codeclimate.com/github/henkm/docdata)
+[![Coverage Status](https://coveralls.io/repos/henkm/docdata/badge.png?branch=master)](https://coveralls.io/r/henkm/docdata)
 
-DocData is a Ruby binder for DocData payments. Current status: in progress, not stable.
+Docdata is a Ruby binder for Docdata Payments. Current status: **in progress, not stable**. 
+
+This gem relies on the awesom Savon gem to communicate with Docdata Payments' SOAP API.
 
 ## Installation
 
@@ -16,14 +22,174 @@ Or install it yourself as:
 
     $ gem install docdata
 
-## Usage
+## Workflow
+Each transaction consists of 2 - optionally 3 - parts:
+
+- `Docdata::Shopper` (details about the shopper: name, email, etc.)
+- `Docdata::Payment` (details about the payment: currency, gross amount, etc.) 
+- `Docdata::LineItem` (optionally list the products of this payment) **currently not working!**
+
+
+The general workflow is as follows:
+
+1. Set up a `Docdata::Shopper` object with the details of your shopper: `@shopper = Docdata::Shopper.new` 
+2. Set up a `Docdata::Payment` object with the details of your order: `@payment = Docdata::Payment.new(shopper: @shopper)`
+3. Call the `create` method (`@payment.create`)
+4. On success, store the payment key and use `@payment.redirect_url` to redirect the consumer to the transaction page.
+5. When the consumer gets back to your application, use the `Docdata::Payment.find("PA1M3NTK3Y").status.paid` to check if the order was paid for.
+
+## Parameters
+All the payment details that Docdata Payments requires, are - obviously - also required to make payments via this gem.
+
+#### Docdata::Shopper:
+| Name | Type | Required | Defaults to |
+|-----------|------------|---------|----|
+| id | String (ID for own reference) | Yes | |
+| first_name | String | Yes | First Name |
+|	last_name | String | Yes | Last Name |
+| street | String | Yes | Main Street |
+| house_number | String | Yes | 123 |
+| postal_code | String | Yes | 2244 |
+| city | String | Yes | City |
+| country_code | String (ISO country code) | Yes | NL |
+| language_code | String (ISO language code) | Yes | nl |
+| email | String | Yes | random@example.com |
+
+#### Docdata::Payment:
+| Name | Type | Required |
+|-----------|------------|---------|
+| amount | Integer (amount in cents) | Yes |
+| currency | String (ISO currency code) | Yes |
+| order_reference | String (your own unique reference) | Yes |
+| profile | String (name of your Docdata Payment profile)| Yes |
+| shopper | Docdata::Shopper | Yes |
+| line_items | Array (of Docdata::LineItem objects) | No |
+| bank_id | String | No |
+| prefered_payment_method | String | No |
+| key | String (is availabel after successful 'create' action) | No (readonly)
+
+
+## Default values
+A quick warning about the default values for the Shopper object: **For some payment methods, Docdata Payments needs the actual information in order for the payment to take place.**
+
+If you use `GIROPAY`, `SEPA` and `AFTERPAY` this is the case. (Maybe also in other payment methods, please let me know!)
+
+## Example usage in Rails application
+The example below assumes you have your application set up with a Order model, which contains the information needed for this transaction (amount, name, etc.).
+```ruby
+# orders_controller.rb
+def start_transaction
+	# find the order from your database
+	@order = Order.find(params[:id])
+	
+	# initialize a shopper, use details from your order
+	shopper = Docdata::Shopper.new(first_name: @order.first_name, last_name: @order.last_name)
+
+	# set up a payment
+	@payment = Docdata::Payment.new(
+		amount: @order.total, 
+		currency: @order.currency, 
+		shopper: shopper,
+		profile: "My Default Profile",
+		order_reference: "order ##{@order.id}"
+	)
+	
+	# create the payment via the docdata api and collect the result
+	result = @payment.create
+
+	if result.success?
+		# Set the transaction key for future reference
+		@order.update_column :docdata_key, result.key
+		# redirect the user to the docdata payment page
+		redirect_to @payment.redirect_url
+	else
+		# TODO: Display the error and warn the user that something went wrong.
+	end
+end
+```
+
+## Ideal
+
+For transactions in the Netherlands, iDeal is the most common option. To redirect a user directly to the bank page (skipping the Docdata web menu page), you can ask your user to choose a bank from any of the banks listed in the `Docdata::Ideal.banks` method.
+
+In `Docdata::Payment` you can set `bank_id` to any value. If you do, the redirect URI will redirect your user directly to the bank page.
+
+Example code:
+```ruby
+# orders_controller.rb
+def ideal_checkout
+	@order = Order.find(params[:order_id])
+	@banks = Docdata::Ideal.banks
+end
+
+def start_ideal_transaction
+	@order = Order.find(params[:order_id])
+
+	# initialize a shopper, use details from your order
+	shopper = Docdata::Shopper.new(first_name: @order.first_name, last_name: @order.last_name)
+
+	# set up a payment
+	@payment = Docdata::Payment.new(
+		amount: @order.total, 
+		currency: @order.currency, 
+		shopper: shopper,
+		profile: "My Default Profile",
+		order_reference: "order ##{@order.id}",
+		bank_id: params[:bank_id],
+		default_act: true # redirect directly to the bank, skipping the Docdata web menu
+	)
+
+	# create the payment via the docdata api and collect the result
+	result = @payment.create
+
+	if result.success?
+		# Set the transaction key for future reference
+		@order.update_column :docdata_key, result.key
+		# redirect the user to the bank page
+		redirect_to @payment.redirect_url
+	else
+		# TODO: Display the error and warn the user that something went wrong.
+	end
+end
+```
+
+View template (ideal_checkout.html.erb):
+
+```erb
+<h2>Choose your bank</h2>
+<%= form_tag start_ideal_transaction_path, method: :post, target: "_blank" do %>
+<%= select_tag "bank_id", options_from_collection_for_select(@banks, "id", "name") %>
+<%= hidden_field_tag :order_id, @order.id %>
+<%= submit_tag "Proceed to checkout" %>
+<% end %>
+```
+
+## Tips and samples
+
+#### Redirect directly to bank page (skip Docdata web menu)
+When making a new `Docdata::Payment`, use the `default_act` parameter to redirect consumers directly to the acquirers website. Example:
+
+```ruby
+	@payment = Docdata::Payment.new(
+		amount: @order.total, 
+		currency: @order.currency, 
+		shopper: shopper,
+		profile: "My Default Profile",
+		order_reference: "order ##{@order.id}",
+		bank_id: params[:bank_id],
+		default_act: true # redirect directly to the bank, skipping the Docdata web menu
+	)
+```
 
-TODO: Write usage instructions here
+#### Retrieve a list of iDeal banks to show
+`Docata::Ideal.banks` returns an Array.
 
 ## Contributing
 
 1. Fork it
 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 new Pull Request
+3. Make changes, document them and add tests (rspec)
+4. Run the entire test suite and make sure all tests pass
+5. Commit your changes (`git commit -am 'Add some feature'`)
+6. Push to the branch (`git push origin my-new-feature`)
+7. Create new Pull Request

data/Rakefile

@@ -1 +1,9 @@
 require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = "spec/*_spec.rb"
+end
+
+task :default => :spec
+task :test => :spec

data/docdata.gemspec

@@ -8,23 +8,30 @@ Gem::Specification.new do |spec|
   spec.version       = Docdata::VERSION
   spec.authors       = ["Henk Meijer", "Eskes Media"]
   spec.email         = ["meijerhenk@gmail.com"]
-  spec.description   = %q{A ruby binder for the DocData payment gateway.}
-  spec.summary       = %q{This gem provides a ruby API for the DocData payment gateway.}
-  spec.homepage      = ""
+  spec.description   = %q{A ruby binder for the Docdata Payment API.}
+  spec.summary       = %q{This gem provides a ruby interface for the Docdata Payment API. You basically create a Payment object and receive a reirect_url back to take your users to the checkout page.}
+  spec.homepage      = "http://rdoc.info/github/henkm/docdata/"
   spec.license       = "MIT"
 
+  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 "fakeweb"
   spec.add_development_dependency "coveralls"
   spec.add_development_dependency "simplecov"
   spec.add_development_dependency "yard"
+  spec.add_development_dependency "rubyntlm"
 
-  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"
-end
+  # spec.add_runtime_dependency 'savon', git: 'savonrb/savon'
+  spec.add_dependency 'savon', '~> 2.0'
+  spec.add_dependency 'nori'
+  spec.add_dependency 'veto'
+  spec.add_dependency 'nokogiri'
+  spec.add_dependency("railties")
+end

data/lib/docdata.rb

@@ -1,5 +1,78 @@
+# Libraries
+require 'ostruct'
+require 'rails'
+require 'savon'
+require 'active_support/dependencies'
+require 'active_support'
+require 'open-uri'
+require 'nokogiri'
+require 'veto'
+
+
+#  Files
 require "docdata/version"
+require "docdata/docdata_error"
+require "docdata/shopper"
+require "docdata/payment"
+require "docdata/line_item"
+require "docdata/response"
+require "docdata/ideal"
+require "docdata/bank"
 
+include Savon
+
+# 
+# Docdata Module
+# 
 module Docdata
-  # Your code goes here...
+  API_VERSION = 1
+
+  # @return [String] Your DocData username
+  # @note The is a required parameter.
+  mattr_accessor :username
+  @@username = nil
+
+  # @return [String] Your DocData password
+  mattr_accessor :password
+  @@password = nil
+
+  # @return [Boolean] Test mode switch
+  mattr_accessor :test_mode
+  @@test_mode = true
+
+  # @param [String] Set the url of your website where docdata can send messages to
+  mattr_accessor :return_url
+  @@return_url = nil
+
+  # returns the version number
+  def self.version
+    VERSION
+  end 
+
+  # sets up configuration
+  def self.setup
+    yield self
+  end
+
+  def self.url
+    if test_mode
+      "https://test.docdatapayments.com/ps/services/paymentservice/1_1?wsdl"
+    else
+      "https://www.docdatapayments.com/ps/services/paymentservice/1_1?wsdl"
+    end
+  end
+
+  # For testing purpose only: set the username and password
+  # in environment variables to make the tests pass with your test
+  # credentials.
+  def self.set_credentials_from_environment
+    self.password   = ENV["DOCDATA_PASSWORD"]
+    self.username   = ENV["DOCDATA_USERNAME"]
+    self.return_url = ENV["DOCDATA_RETURN_URL"]
+  end
+
+  def self.client
+    Savon.client(wsdl: url)
+  end
+
 end

data/lib/docdata/bank.rb

@@ -0,0 +1,27 @@
+module Docdata
+  #
+  # Object representing a "Bank" object with attributes provided by Mollie
+  #
+  # @example
+  #   Bank.new({
+  #     :id => "0031",
+  #     :name => "ABN AMRO"
+  #   })
+  class Bank
+    # @return [String] The id of the bank provided by Mollie.
+    attr_accessor :id
+    # @return [String] The name of the bank.
+    attr_accessor :name
+
+    #
+    # Initializer to transform a +Hash+ into an Bank object
+    #
+    # @param [Hash] values
+    def initialize(values=nil)
+      return if values.nil?
+
+      @id = values[:id].to_s
+      @name = values[:name].to_s
+    end
+  end
+end

data/lib/docdata/config.rb

@@ -0,0 +1,41 @@
+#
+# Configuration object for storing some parameters required for making transactions
+#
+module Docdata::Config
+  class << self
+    # @return [String] Your DocData username
+    # @note The is a required parameter.
+    attr_accessor :username
+    # @return [String] Your DocData password
+    attr_accessor :password
+    # @return [Boolean] Test mode switch
+    attr_accessor :test_mode
+
+
+    # Set's the default value's to nil and false
+    # @return [Hash] configuration options
+    def init!
+      @defaults = {
+        :@username => nil,
+        :@password => nil,
+        :@test_mode => true
+      }
+    end
+
+    # Resets the value's to there previous value (instance_variable)
+    # @return [Hash] configuration options
+    def reset!
+      @defaults.each { |key, value| instance_variable_set(key, value) }
+    end
+
+    # Set's the new value's as instance variables
+    # @return [Hash] configuration options
+    def update!
+      @defaults.each do |key, value|
+        instance_variable_set(key, value) unless instance_variable_defined?(key)
+      end
+    end
+  end
+  init!
+  reset!
+end