slidepay 0.0.12 → 0.0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4fd5c93874d452c096489e21fc5e21299a402b6d
-  data.tar.gz: 831e67be3a2080f47b5d3bac38ca22c5989ddea7
+  metadata.gz: b65de9b4a73dbbcf304c9a88b93e9a03fcee70b4
+  data.tar.gz: cc564d6baeeec3e2ffbed1662ba04c5c82afcec1
 SHA512:
-  metadata.gz: 6c58e8724d17eb29812939567f60abcffea199e703842dfe3edfd61ba7761eb2da8a5fe748ab845ead0d48b77cf915e329303a829cc6c23b8fd75ad0b8664c89
-  data.tar.gz: 80276a5604efaa119532f372e4bcad0f6b4efd4cf557ccf03c0f81e9e79c257daf1f723891a5d0e9da5d7879fb6cff7eed6c9361875377076c172638139cc853
+  metadata.gz: 7ca65bf127f9c5e96dfb5436ce8ec413e97c95b562ae9ebea81fb65a4e8bb53f1e4b357026387825e37997d3fa483dfba150d23579ae4b0e2b270a8f9b01cb92
+  data.tar.gz: 39dd5940961c5a0642e9a6c9f409d7a7eec33e9a468bccddab6aeec87461a4e0284c51d2da2a934a261dc3bb110cbf935404e8d688a6ab0f10167d7ac59b162b

data/README.md

@@ -253,6 +253,77 @@ payment_report.retrieve()
 
 ```
 
+## ACH
+
+SlidePay supports ACH retrievals, programmatic settlements via ACH, and checking the balance of unsettled funds for an account.
+
+### Balance
+
+To check the balance of a settlement ledger, just provide a location_id to the ```Balance.retrieve``` class method.
+
+```ruby
+location_id = 18
+balance = SlidePay::ACH::Balance.retrieve(location_id)
+```
+
+### ACH Retrieval
+
+To initiate an ACH retrieval from a bank account, supply a hash with bank account details to the
+```Retrieval.create_with_bank_account``` class method, or create an instance of the Retrieval class and
+use the instance method of the same name.
+
+A retrieval can be initiated using either a stored bank account or explicit bank account details. A full
+explanation of the differences can be found on the
+[ACH retrieval documentation page](https://getcube.atlassian.net/wiki/display/CDP/Processing+Manual+ACH+Retrievals).
+
+```ruby
+retrieval_info = {
+  location_id: 12,
+  company_id: 10,
+  bank_account_id: 3,
+  user_master_id: 20,
+  retrieval_amount: 1.02
+}
+
+# class method
+r = ACH::Retrieval.create_with_bank_account(retrieval_info)
+
+# instance method - the retrieval instance will be populated with the
+# retrieval response data from the server.
+r = ACH::Retrieval.new()
+r.create_with_bank_account(retrieval_info)
+```
+
+### ACH Settlement
+
+SlidePay users can settle funds from an account ledger to one or more bank accounts programmatically
+via ACH. Note: To do this, an account must have manual settlement enabled. Complete documentation for
+ACH settlements lives on the [documentation page](https://getcube.atlassian.net/wiki/display/CDP/Processing+Manual+ACH+Settlements).
+
+To initiate an ACH settlement to one or more bank accounts, supply a settlement
+descriptor Hash to the ```Settlement.process``` method in the following format:
+
+```ruby
+settlement_descriptor = {
+  location_id: YOUR_LOCATION_ID,
+  company_id: YOUR_COMPANY_ID,
+  settlement_list:[
+    { bank_account_id: FIRST_SETTLEMENT_BANK_ACCOUNT_ID, amount: 0.25 },
+    { bank_account_id: SECOND_SETTLEMENT_BANK_ACCOUNT_ID, amount: 0.25 }
+  ],
+  notes:'Really important notes about this settlement. '
+}
+```
+
+The Settlement.process class method will return an array of [transaction processor responses](https://getcube.atlassian.net/wiki/display/CDP/processor_ach_txn_response)
+corresponding to the list of settlements requested.
+
+```ruby
+
+# Process the settlement
+settlment_result = SlidePay::ACH::Settlement.process(settlement_descriptor)
+```
+
 ## Testing
 
 ### Basics

data/TODO.md

@@ -1,12 +1,14 @@
-[ ] Reports
+[x] Reports
 ---------------
-[ ] Account
-[ ] Payment
+[x] Account
+[x] Payment
 
 [ ] ACH
 ---------------
-[ ] Retrieval
+[x] Retrieval
 [ ] Settlement
-[ ] Balance
+[x] Balance
 -- Speculative
-[ ] Credit
+[x] Credit
+-- Payments
+[x] is_settled? method

data/lib/slidepay.rb

@@ -28,6 +28,11 @@ require "slidepay/reports/post_report"
 require "slidepay/reports/account_report"
 require "slidepay/reports/payment_report"
 
+# ACH
+require "slidepay/ach/resource"
+require "slidepay/ach/retrieval"
+require "slidepay/ach/balance"
+require "slidepay/ach/settlement"
 
 module SlidePay
   class << self

data/lib/slidepay/ach/balance.rb

@@ -0,0 +1,31 @@
+module SlidePay
+  module ACH
+    class Balance
+
+      class << self
+
+        def retrieve(location_id, options={})
+          token = options[:token]
+          api_key = options[:api_key]
+          endpoint = options[:endpoint]
+
+          path = "settlement/balance/#{location_id}"
+
+          response = SlidePay.post(path: path, data: {}.to_json, token: token, api_key: api_key, endpoint: endpoint)
+
+          if response.was_successful?
+            return response.data
+          else
+            error_text = response.error_text unless response.error == false
+
+            if error_text != nil
+              raise "Could not get settlement balance: #{error_text}"
+            else
+              raise "Could not get settlement balance."
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/slidepay/ach/resource.rb

@@ -0,0 +1,17 @@
+module SlidePay
+  module ACH
+    class Resource < ApiResource
+      def initialize(values_hash={})
+        super(values_hash)
+      end
+
+      def save
+        raise "ACH Resources cannot be saved"
+      end
+
+      def destroy
+        raise "ACH Resources cannot be destroyed"
+      end
+    end
+  end
+end

data/lib/slidepay/ach/retrieval.rb

@@ -0,0 +1,111 @@
+module SlidePay
+  module ACH
+    class Retrieval < Resource
+      attr_accessor :retrieval_bank_account
+
+      @url_root = "retrieval"
+      @id_attribute = "retrieval_id"
+
+      def initialize(values_hash={})
+        @url_root = "retrieval"
+        @id_attribute = "retrieval_id"
+
+        # if values_hash[:retrieval_bank_account] is present and a hash, then we should probably pull
+        # that out and set the instance attribute for bank account
+        # @retrieval_bank_account = values_hash[:retrieval_bank_account]
+        # values_hash.remove(:retrieval_bank_account)
+
+        super(values_hash)
+      end
+
+      # url should allow retrieving by settlement_transaction_token
+      def url
+        if is_new?
+          @url_root
+        elsif self.settlement_transaction_token != nil
+          "#{@url_root}?settlement_transaction_token=#{self['settlement_transaction_token']}"
+        else
+          "#{@url_root}/#{self.id()}"
+        end
+      end
+
+      def settlement_transaction_token
+        self['settlement_transaction_token']
+      end
+
+      def is_new?
+        if id() == nil && self.settlement_transaction_token == nil
+          true
+        else
+          false
+        end
+      end
+
+      def create_with_bank_account(bank_account, options={})
+        options[:token]     = options[:token] || @token
+        options[:api_key]   = options[:api_key] || @api_key
+        options[:endpoint]  = options[:endpoint] || @endpoint
+
+        r = self.class.create_with_bank_account(bank_account, options)
+        merge! r
+      end
+
+      def retrieve_by_settlement_token(settlement_transaction_token, options={})
+        options[:token]     = options[:token] || @token
+        options[:api_key]   = options[:api_key] || @api_key
+        options[:endpoint]  = options[:endpoint] || @endpoint
+
+        r = self.class.retrieve_by_settlement_token(settlement_transaction_token, options)
+        merge! r
+      end
+
+      def is_ledgered?
+        return self['ledgered'] == 1
+      end
+
+      def ledger_after
+        return self['ledger_after']
+      end
+
+      def retrieval_amount
+        return self['retrieval_amount']
+      end
+
+      def provider_status
+        return self['provider_status']
+      end
+
+      class << self
+        def create_with_bank_account(bank_account, options={})
+          token = options[:token]
+          api_key = options[:api_key]
+          endpoint = options[:endpoint]
+
+          response = SlidePay.post(path: "#{@url_root}/manual", data: bank_account.to_json, token: token, api_key: api_key, endpoint: endpoint)
+          if response.was_successful?
+            r = self.new()
+            r.populate_from_response(response)
+          end
+        end
+
+        def retrieve_by_settlement_token(settlement_transaction_token, options={})
+          if ! settlement_transaction_token.is_a? String
+            raise "settlement_transaction_token must be a String"
+          end
+
+          token = options[:token]
+          api_key = options[:api_key]
+          endpoint = options[:endpoint]
+
+          url_suffix = "?settlement_transaction_token=#{settlement_transaction_token}"
+
+          response = SlidePay.get(path: "#{@url_root}#{url_suffix}", token: token, api_key: api_key, endpoint: endpoint)
+          if response.was_successful?
+            r = self.new()
+            r.populate_from_response(response)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/slidepay/ach/settlement.rb

@@ -0,0 +1,68 @@
+module SlidePay
+  module ACH
+    class Settlement < Resource
+      @url_root = "settlement"
+      @id_attribute = "settlement_id"
+
+      def initialize(values_hash={})
+        @url_root = "settlement"
+        @id_attribute = "settlement_id"
+
+        super(values_hash)
+      end
+
+      class << self
+
+        def process(settlement_order, options={})
+          validate_settlement_order(settlement_order)
+
+          token = @token || options[:token]
+          api_key = @api_key || options[:api_key]
+          endpoint = @endpoint || options[:endpoint]
+
+          response = SlidePay.post(path: "settlement/manual", api_key: api_key, token: token, endpoint: endpoint, data: settlement_order.to_json)
+
+          if response.was_successful?
+            return response.data
+          elsif response.error_text
+            raise Exception.new(response.error_text)
+          elsif response.data["status_message"]
+            raise Exception.new(response.data["status_message"])
+          else
+            raise Exception.new("Settlement(s) could not be processed.")
+          end
+        end
+
+        private
+
+        def validate_single_settlement_descriptor(descriptor)
+          puts "Descriptor: #{descriptor}\n\n"
+          if ! descriptor.is_a? Hash
+            raise "Cannot validate a settlement descriptor that is not a hash."
+          elsif ! descriptor.include?(:bank_account_id) && ! descriptor.include?("bank_account_id")
+            raise "A bank_account_id is required for each settlement being processed."
+          elsif ! descriptor.include?(:amount) && ! descriptor.include?("amount")
+            raise "An amount is required for each settlement being processed."
+          else
+            return true
+          end
+        end
+
+        def validate_settlement_order(settlement_order)
+          raise "A settlement must be a Hash object." unless settlement_order.is_a? Hash
+          raise "company_id is required for a settlement." unless (settlement_order['company_id'] || settlement_order[:company_id])
+          raise "location_id is required for a settlement." unless (settlement_order['location_id'] || settlement_order[:location_id])
+          raise "settlement_list is required for a settlement." unless (settlement_order['settlement_list'] || settlement_order[:settlement_list])
+
+          descriptor_list = settlement_order['settlement_list'] || settlement_order[:settlement_list]
+          descriptor_list.each do |descriptor|
+            validate_single_settlement_descriptor(descriptor)
+          end
+
+          return true
+        end
+
+      end
+    end
+  end
+end

data/lib/slidepay/resources/api_resource.rb

@@ -3,32 +3,34 @@ module SlidePay
     attr_accessor :url_root, :id_attribute, :token, :api_key, :endpoint
 
     def initialize(values_hash={})
-      if values_hash[:url_root]
-        @url_root = values_hash[:url_root]
-        values_hash.delete(:url_root)
+      values_clone = values_hash.clone()
+
+      if values_clone[:url_root]
+        @url_root = values_clone[:url_root]
+        values_clone.delete(:url_root)
       end
 
-      if values_hash[:id_attribute]
-        @id_attribute = values_hash[:id_attribute]
-        values_hash.delete(:id_attribute)
+      if values_clone[:id_attribute]
+        @id_attribute = values_clone[:id_attribute]
+        values_clone.delete(:id_attribute)
       end
 
-      if values_hash[:token]
-        @token = values_hash[:token]
-        values_hash.delete(:token)
+      if values_clone[:token]
+        @token = values_clone[:token]
+        values_clone.delete(:token)
       end
 
-      if values_hash[:api_key]
-        @api_key = values_hash[:api_key]
-        values_hash.delete(:api_key)
+      if values_clone[:api_key]
+        @api_key = values_clone[:api_key]
+        values_clone.delete(:api_key)
       end
 
-      if values_hash[:endpoint]
-        @endpoint = values_hash[:endpoint]
-        values_hash.delete(:endpoint)
+      if values_clone[:endpoint]
+        @endpoint = values_clone[:endpoint]
+        values_clone.delete(:endpoint)
       end
 
-      merge! values_hash
+      merge! values_clone
     end
 
     def url

data/lib/slidepay/resources/payment.rb

@@ -18,6 +18,23 @@ module SlidePay
       refund(options_hash)
     end
 
+    def is_settled?
+      raise "Cannot check settlement status for a payment with no ID." unless is_new? == false
+
+      if ! self['provider_capture_state'].eql? "Captured"
+        # puts "#{self['provider_capture_state']}. \"Captured\" has evaluated to false"
+        return false
+      elsif self['settlement_transaction_token'] == nil
+        # puts 'self[\settlement_transaction_token\] == nil has evaluated to false'
+        return false
+      elsif self['settlement_transaction_token'].is_a?(String) && self['settlement_transaction_token'].empty?
+        # puts 'self[\'settlement_transaction_token\'].kind_of? String && self[\'settlement_transaction_token\'].empty? has evaluated to false'
+        return false
+      else
+        return true
+      end
+    end
+
     def process(options_hash={})
       token = @token || options_hash[:token]
       api_key = @api_key || options_hash[:api_key]

data/lib/slidepay/version.rb

@@ -1,3 +1,3 @@
 module SlidePay
-  VERSION = "0.0.12"
+  VERSION = "0.0.13"
 end

data/scenarios/ach/balance.rb

@@ -0,0 +1,18 @@
+$:.unshift(File.join(File.dirname(__FILE__), 'lib'))
+$:.unshift(File.join(File.dirname(__FILE__), 'spec'))
+
+require 'multi_json'
+require 'slidepay'
+require 'spec_helper'
+
+include SlidePay
+
+SlidePay.configure(development: true)
+SlidePay.api_key = ENV["ach_api_key"]
+
+RestClient.proxy = "http://127.0.0.1:8888"
+
+location_id = 18
+balance = SlidePay::ACH::Balance.retrieve(location_id)
+
+puts "Balance for location_id #{location_id}: #{balance}"