docdata 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4760635525904b78d47e8390f2c371e45f316a18
-  data.tar.gz: a91306598ed4b29b5adf81eb172da822ac4e3b3e
+  metadata.gz: 0b7fce0fc2d60f3333084ba16516eb7ad414b728
+  data.tar.gz: 52f071c31314b98fd530bb62b3f0fb007c4d4b33
 SHA512:
-  metadata.gz: 2ad18cf614968cb60eccb8abc1c9577462ee8b9e67bfe701d9887f092d9a42cb55da399d80ac6932578431b81b62d53ffe8fbebde142719b78349f2fb79129b6
-  data.tar.gz: 9f31c54925a1b75fd2bda0ddc6341438256a6de96817153204a7be24121470b7665a9793401a08ca1df93c4eed5fb39875eb0a351b6fe63933a95eb2c971a876
+  metadata.gz: 25d68049043573abdbd864625135dab093f86cd2cba3ce5095f9de81bca2b3d6429859e29f63bd2211aae374ada25d8c03d8a8614e0fb21600a6915812f53514
+  data.tar.gz: fe7766f96151b852e3fcb4702f977e6b84fbbd73810ac0d969f814cb62b685a1aaed37e65b55cc609403c2b6714fcdfb6f57625260e579fc1959cf2865d52d1c

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## v0.1.8
+* You can now make refunds. See documentation.
+* Updated README
+
 ## v0.1.7
 * Bug fixed where the gem didn't handle docdata XML response with multiple 'payment' nodes well. The gem assumed that the nodes where in chronological order, but they aren't.
 

data/README.md

@@ -82,7 +82,7 @@ If you use `GIROPAY`, `SEPA` and `AFTERPAY` this is the case. (Maybe also in oth
 
 
 ## Configuration in Rails application
-Example usage. Use appropriate settings in `development.rb`, `production.rb` etc.
+Example usage. Use appropriate settings in `development.rb`, `production.rb` etc. 
 ```ruby
 config.docdata.username   = "my_app_com"
 config.docdata.password   = "HeJ35N"
@@ -243,17 +243,32 @@ When making a new `Docdata::Payment`, use the `default_act` parameter to redirec
 #### Check the status of a payment
 `payment = Docdata::Payment.find("KEY"); payment.status => <Payment::Status>`
 
-
 #### Cancel a payment
 To cancel an existing Payment, you can do one of the following:
 `payment = Docdata::Payment.find("KEY"); payment.cancel` or `Docdata::Payment.cancel("KEY")`
 
+#### Make refunds
+You can make a refund for a payment. In fact: each payment can have multiple refunds. Each refund has an amount (`Integer` type - cents) and as long as the refund amount doesn't exceed the total Payment amount, you can make as many partial refunds as you whish. Keep in mind that Docdata will charge you for each refund.
+
+```ruby
+payment = Docdata::Payment.find("KEY") # find the payment
+payment.refund(500) # => true or false
+```
+
+
+
+## Test credentials
+In order tot test this gem, you'll need to set the following environment variables to make it work. With other words: you can't test this gem without valid test credentials and you can't use my test credentials. Tip: set the environment variables in your .bash_profile file.
+```
+ENV["DOCDATA_PASSWORD"] = "your_password"
+ENV["DOCDATA_USERNAME"] = "your_docdata_username"
+ENV["DOCDATA_RETURN_URL"] = "http://return-url-here"
+```    
 
 
 ## Contributing
 Want to contribute? Great!
 
-
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Make changes, document them and add tests (rspec)

data/lib/docdata.rb

@@ -16,6 +16,7 @@ require "docdata/engine" if defined?(Rails) && Rails::VERSION::MAJOR.to_i >= 3
 require "docdata/docdata_error"
 require "docdata/shopper"
 require "docdata/payment"
+require "docdata/refund"
 require "docdata/line_item"
 require "docdata/response"
 require "docdata/ideal"

data/lib/docdata/payment.rb

@@ -54,6 +54,7 @@ module Docdata
     attr_accessor :key
     attr_accessor :default_act
     attr_accessor :canceled
+    attr_accessor :id
 
 
     #
@@ -121,6 +122,27 @@ module Docdata
       return true
     end
 
+    # 
+    # This calls the 'refund' method of the SOAP API
+    # It refunds (part of) the amount paid
+    def refund(amount_to_refund, refund_description="")
+      p = Docdata::Payment.new(key: key)
+      p = p.status.payment
+      refund_object = Docdata::Refund.new(
+        currency: p.currency,
+        amount: amount_to_refund,
+        description: refund_description,
+        payment: p
+      )
+      if refund_object.valid?
+        refund_object.perform_refund
+      else
+        raise DocdataError.new(refund_object), refund_object.errors.full_messages.join(", ")
+      end
+    end
+
+
+
     # This method makes it possible to find and cancel a payment with only the key
     # It combines 
     def self.cancel(api_key)
@@ -128,6 +150,14 @@ module Docdata
       p.cancel
     end
 
+    # This method makes it possible to find and refund a payment with only the key
+    # exmaple usage: Docdata::Payment.refund("APIT0K3N", 250)
+    def self.refund(api_key, amount_to_refund, refund_description="")
+      p = self.find(api_key)
+      p.refund(amount_to_refund, refund_description)
+    end
+
+
     # Initialize a Payment object with the key set
     def self.find(api_key)
       p = self.new(key: api_key)
@@ -153,9 +183,12 @@ module Docdata
       response        = Docdata.client.call(:status, xml: xml)
       response_object = Docdata::Response.parse(:status, response)
 
+      response_object.set_attributes
+
+      self.id                 = response_object.pid
+      self.currency           = response_object.currency
       response_object.key     = key
       response_object.payment = self
-
       return response_object # Docdata::Response
     end
     alias_method :check, :status
@@ -216,6 +249,7 @@ module Docdata
       xml             = ERB.new(template).result(namespace.instance_eval { binding })
     end
 
+
     private
 
     # In case there are any line_items, validate them all and

data/lib/docdata/refund.rb

@@ -0,0 +1,77 @@
+module Docdata
+
+
+  # Creates a validator
+  class RefundValidator
+    include Veto.validator
+    validates :amount, presence: true, integer: true
+    validates :currency, presence: true, format: /[A-Z]{3}/
+    validates :payment, presence: true
+  end
+
+
+  #
+  # Refund
+  #
+  # @example
+  #   Refund.new({
+  #     :amount => 2500,
+  #     :currency => "EUR",
+  #     :description => "Canceled order #123"
+  #     :payment => @payment
+  #   })
+  # 
+
+  # 
+  class Refund
+    attr_accessor :errors
+    attr_accessor :amount
+    attr_accessor :currency
+    attr_accessor :payment
+    attr_accessor :description
+    @@amount = "?"
+
+    #
+    # Initializer to transform a +Hash+ into an Refund object
+    #
+    # @param [Hash] args
+    def initialize(args=nil)
+      @line_items = []
+      return if args.nil?
+      args.each do |k,v|
+        instance_variable_set("@#{k}", v) unless v.nil?
+      end
+    end
+
+    # @return [Boolean] true/false, depending if this instanciated object is valid
+    def valid?
+      validator = RefundValidator.new
+      validator.valid?(self)
+    end
+
+    # 
+    # This calls the 'refund' method of the SOAP API
+    # It refunds (part of) the payment and returns a Docdata::Response object
+    def perform_refund
+      # make the SOAP API call
+      response        = Docdata.client.call(:refund, xml: refund_xml)
+      response_object = Docdata::Response.parse(:refund, response)
+      if response_object.success?
+        return true
+      else
+        return false
+      end
+    end
+
+    # @return [String] the xml to send in the SOAP API
+    def refund_xml
+      xml_file        = "#{File.dirname(__FILE__)}/xml/refund.xml.erb"
+      template        = File.read(xml_file)      
+      namespace       = OpenStruct.new(refund: self, payment: self.payment)
+      xml             = ERB.new(template).result(namespace.instance_eval { binding })
+    end
+
+
+  end
+
+end

data/lib/docdata/response.rb

@@ -133,6 +133,15 @@ module Docdata
       end
     end
 
+    # @return [String] the PID of the transaction
+    def pid
+      if report && Response.payment_node(report) && Response.payment_node(report)[:id]
+        Response.payment_node(report)[:id]
+      else
+        nil
+      end      
+    end
+
     # @return [Boolean] true/false, depending wether this payment is considered paid.
     # @note Docdata doesn't explicitly say 'paid' or 'not paid', this is a little bit a gray area.
     # There are several approaches to determine if a payment is paid, some slow and safe, other quick and unreliable.

data/lib/docdata/version.rb

@@ -1,3 +1,3 @@
 module Docdata
-  VERSION = "0.1.7"
+  VERSION = "0.1.8"
 end

data/lib/docdata/xml/refund.xml.erb

@@ -0,0 +1,15 @@
+<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:_1="http://www.docdatapayments.com/services/paymentservice/1_1/">
+   <soapenv:Header/>
+   <soapenv:Body>
+      <_1:refundRequest version="1.1">
+         <_1:merchant name="<%= Docdata::Config.username %>" password="<%= Docdata::Config.password %>"/>
+         <_1:paymentId><%= payment.id %></_1:paymentId>
+         <!--Optional:-->
+         <% if refund.description.present? %>
+         <_1:merchantRefundReference><%= refund.description %></_1:merchantRefundReference>
+         <% end %>
+         <!--Optional:-->
+         <_1:amount currency="<%= refund.currency %>"><%= refund.amount %></_1:amount>
+      </_1:refundRequest>
+   </soapenv:Body>
+</soapenv:Envelope>

data/spec/payment_spec.rb

@@ -141,6 +141,18 @@ describe Docdata::Payment do
       expect(@new_payment).to be_kind_of(Docdata::Payment)
     end
 
+    it "returns a pid" do
+      file = "#{File.dirname(__FILE__)}/xml/status-paid-ideal.xml"
+      @xml = open(file)
+      @response = Docdata::Response.parse(:status, @xml)
+
+      @payment = @response.payment
+      expect(@response.is_paid?).to eq(true)
+      # expect(@payment).to be_kind_of(Docdata::Payment)
+      expect(@response.pid).to match /[0-9]{10}/
+
+    end
+
     it "raises error if order is not found" do
       VCR.use_cassette("perform-invalid-status-call") do
         Docdata.set_credentials_from_environment

data/spec/refund_spec.rb

@@ -0,0 +1,86 @@
+require 'spec_helper'
+
+describe Docdata::Refund do
+
+  context "validation" do
+    it "has validation" do
+      refund = Docdata::Refund.new
+      expect(refund).not_to be_valid
+    end
+
+    it "validates amount" do
+      refund = Docdata::Refund.new
+      expect(refund).not_to be_valid
+      expect(refund.errors.full_messages).to eq(["amount is not present", "amount is not a number", "currency is not present", "currency is not valid", "payment is not present"])
+    end
+  end
+
+  context "valid refund" do
+    before(:each) do
+      Docdata.set_credentials_from_environment
+      Docdata::Config.test_mode = true
+      VCR.use_cassette("find-payment-by-key") do
+        @payment = Docdata::Payment.find("2BAFAEB26EF760458B9343DEA4950D91")
+        # puts @payment.inspect
+      end
+    end
+
+    it "has a currency" do
+      expect(@payment.currency).to be_present
+      expect(@payment.currency).to eq("EUR")
+    end
+
+    it "performs refund" do
+      VCR.use_cassette("refund-amount") do
+        expect(@payment.refund(100)).to eq(true)
+      end
+    end
+
+    it "performs refund with description" do
+      VCR.use_cassette("refund-amount-with-description") do
+        expect(@payment.refund(100, "user wanted to cancel...")).to eq(true)
+      end
+    end
+
+  end
+
+  context "successfull response" do
+    before(:each) do
+      file = "#{File.dirname(__FILE__)}/xml/refund_success.xml"
+      @xml = open(file)
+      @response = Docdata::Response.parse(:refund, @xml)
+    end
+
+
+    it "is successfull" do
+      expect(@response).to be_success
+    end
+
+    it "has xml attribute with raw data" do
+      expect(@response.xml).to be_present
+    end
+  end
+
+  context "invalid amount response" do
+    before(:each) do
+      file = "#{File.dirname(__FILE__)}/xml/refund_invalid_amount.xml"
+      @xml = open(file)
+    end
+    
+    it "raises error" do
+      expect { Docdata::Response.parse(:refund, @xml) }.to raise_error(DocdataError, "Invalid amount.")
+    end
+  end
+
+  context "invalid amount response" do
+    before(:each) do
+      file = "#{File.dirname(__FILE__)}/xml/refund_no_amount_captured.xml"
+      @xml = open(file)
+    end
+    
+    it "raises error" do
+      expect { Docdata::Response.parse(:refund, @xml) }.to raise_error(DocdataError, "No amount captured available to refund.")
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -33,4 +33,5 @@ end
 
 RSpec.configure do |config|
   config.order = "random"
+  # config.filter_run :focus => true
 end

data/spec/xml/refund_invalid_amount.xml

@@ -0,0 +1,9 @@
+<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
+   <S:Body>
+      <refundResponse xmlns="http://www.docdatapayments.com/services/paymentservice/1_1/">
+         <refundError>
+            <error code="REQUEST_DATA_INCORRECT">Invalid amount.</error>
+         </refundError>
+      </refundResponse>
+   </S:Body>
+</S:Envelope>

data/spec/xml/refund_no_amount_captured.xml

@@ -0,0 +1,9 @@
+<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
+   <S:Body>
+      <refundResponse xmlns="http://www.docdatapayments.com/services/paymentservice/1_1/">
+         <refundError>
+            <error code="REQUEST_DATA_INCORRECT">No amount captured available to refund.</error>
+         </refundError>
+      </refundResponse>
+   </S:Body>
+</S:Envelope>

data/spec/xml/refund_success.xml

@@ -0,0 +1,9 @@
+<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
+   <S:Body>
+      <refundResponse xmlns="http://www.docdatapayments.com/services/paymentservice/1_1/">
+         <refundSuccess>
+            <success code="SUCCESS">Operation successful.</success>
+         </refundSuccess>
+      </refundResponse>
+   </S:Body>
+</S:Envelope>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docdata
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - Henk Meijer
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-24 00:00:00.000000000 Z
+date: 2014-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -260,12 +260,14 @@ files:
 - lib/docdata/ideal.rb
 - lib/docdata/line_item.rb
 - lib/docdata/payment.rb
+- lib/docdata/refund.rb
 - lib/docdata/response.rb
 - lib/docdata/shopper.rb
 - lib/docdata/version.rb
 - lib/docdata/xml/bank-list.xml
 - lib/docdata/xml/cancel.xml.erb
 - lib/docdata/xml/create.xml.erb
+- lib/docdata/xml/refund.xml.erb
 - lib/docdata/xml/start.xml.erb
 - lib/docdata/xml/status.xml.erb
 - php-example/create.xml.erb
@@ -277,9 +279,13 @@ files:
 - spec/ideal_spec.rb
 - spec/line_item_spec.rb
 - spec/payment_spec.rb
+- spec/refund_spec.rb
 - spec/response_spec.rb
 - spec/shopper_spec.rb
 - spec/spec_helper.rb
+- spec/xml/refund_invalid_amount.xml
+- spec/xml/refund_no_amount_captured.xml
+- spec/xml/refund_success.xml
 - spec/xml/status-canceled-creditcard.xml
 - spec/xml/status-canceled-ideal.xml
 - spec/xml/status-new.xml
@@ -319,9 +325,13 @@ test_files:
 - spec/ideal_spec.rb
 - spec/line_item_spec.rb
 - spec/payment_spec.rb
+- spec/refund_spec.rb
 - spec/response_spec.rb
 - spec/shopper_spec.rb
 - spec/spec_helper.rb
+- spec/xml/refund_invalid_amount.xml
+- spec/xml/refund_no_amount_captured.xml
+- spec/xml/refund_success.xml
 - spec/xml/status-canceled-creditcard.xml
 - spec/xml/status-canceled-ideal.xml
 - spec/xml/status-new.xml