epaybg 0.3.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d760a58e9e281c33db44a196e128081008e3396e
-  data.tar.gz: 7413851d1401e57b921af07da2e34d0430d70434
+  metadata.gz: cee407808cf74a63c73afee331e1b67bc6f96ebd
+  data.tar.gz: d02597a63bfb46b455bcd96aba99e0b9aac656f8
 SHA512:
-  metadata.gz: df47f5d8d0ea4a4aa6ca968b876f5095b9d0577dce9d491844a5ade81e0f2133ad3627ed46ae22e40d913d1fca7c1c97c670c58f5d5de073b5ed62624571f09b
-  data.tar.gz: f1ab7d15cd79bd089e99fba3056e85c72aded6bdc654d436739b6b42c2efc945a6f5bf62b0a0515da8e0c428e43db4b7d36e6612e6b5e4211539cda508097059
+  metadata.gz: ff4ee0df4a72c92f381e6d8063969c5fd08ccb689e646f515545d8172826def364865affdad77f8c50d6ca22612a055d667f12732f51ac210f90811c08124691
+  data.tar.gz: 88600f123e37752b2a6aab735da4dbd671cf12b5c54612d3d91f009e3b64c181ce07dbd1cfddf7929fa3267361c3aadfd7a79ba51362c63543a9b0eaf316c028

data/.travis.yml

@@ -1,6 +1,3 @@
 language: ruby
 rvm:
-  - 1.9.3
-  - jruby-19mode # JRuby in 1.9 mode
-  - rbx-19mode
   - ruby-head

data/README.md

@@ -21,7 +21,7 @@ Or install it yourself as:
 
 ## Configuration
 
-Create the config file config/epaybg.yml with the following contents:
+Create the config file `config/epaybg.yml` with the following contents:
 
 ```yml
 production:
@@ -37,7 +37,7 @@ test:
   url_idn: "https://demo.epay.bg/ezp/reg_bill.cgi"
 ```
 
-Set the mode to production in your config/environments/production.rb file:
+Set the mode to production in your `config/environments/production.rb` file:
 
 ```ruby
 # Add to bottom of the file
@@ -45,10 +45,10 @@ Epaybg.mode = :production
 ```
 
 ## Usage
-Handle a response callback from epay:
+Handle a response callback from EpayBG:
 
 ```ruby
-response = Epaybg::Response.new(params[:encoded], params[:checksum])
+response = Epaybg::Response.new params[:encoded], params[:checksum]
 response.valid?
 # => true
 
@@ -57,6 +57,7 @@ response.status
 ```
 
 Respond to their callback:
+
 ```ruby
 response = Epaybg::Response.new(params[:encoded], params[:checksum])
 
@@ -67,6 +68,174 @@ response.response_for(:ok)
 => "INVOICE=f5b1eaf:STATUS=PAID"
 ```
 
+## Recurring payments
+
+There is no testing environment. You're on your own.
+
+Your best bet is to contact EpayBG and ask for the technical specification because it can not be
+found on their site.
+
+### Workflow
+
+If your application has a subscription feature, you may consider implementing recurrent payments.
+EpayBG has a rather strange way of doing this.
+
+Here are the steps in their recurring payment cycle.
+
+ - Your user subscribes or makes a purchase.
+ - You provide them with an unique 'subscription' number.
+ - The user registers this number with EpayBG.
+ - From now on, every month EpayBG will 'ask' your application
+    (on a TCP server provided by you, explained below), if the registered
+    subscription has any outstanding debts.
+ - Your application searches for a debt related to the number and returns an answer.
+ - If a debt is returned, the user will receive a notification from EpayBG that there
+   is a pending payment.
+ - The user pays this pending payment.
+ - On the TCP server you will then receive a payment notification, process it and return
+   a response to EpayBG.
+ - The next month you will get another 'debt request' for this number.
+
+It is rather hard to find this information anywhere in the web. It's unclear even in the official
+documentation that
+EpayBG send to the developers.
+
+### Implementing a TCP server
+
+In order to accept recurring payment you have to implement a TCP server.
+
+Here is an example server for accepting incoming TCP requests.
+
+````ruby
+require 'socket'
+
+server = TCPServer.new 2000
+
+loop do
+  #  The code in this block has to be threadsafe
+  Thread.start(server.accept) do |client|
+    begin
+      # This line will read the incoming data stream until the tcp client on the other side sends a
+      # 'shutdown' message.
+      message = client.read
+
+      # Handle the payment.
+    rescue => e
+      # Handle an unexpected error
+    ensure
+      client.close
+    end
+  end
+end
+````
+
+### Handling debt requests
+
+The example will work with the TCP server implementation described above.
+EpayBG sends a list of messages separated by new lines `\n`.
+After that they stop sending data and now only wait for a response in the same TCP session.
+
+#### An example request
+
+```
+XTYPE=QBN
+AID=700021
+ACSID=0000900
+BORIKAID=0000900
+CLIENTID=67600000000000000
+LANG=1
+IDN=000000000001
+TID=20111010103406700021592704
+```
+
+Refer to the technical documentation for further details.
+
+#### Handling the request
+
+The gem provides a method which turns the message into a hash.
+
+````ruby
+message = client.read
+data = Epaybg::Recurring.parse_request_body(message)
+request = Epaybg::Recurring::Debt::Request.new data
+````
+
+After you do the processing of the request and find out that this number has a pending payment,
+you have to build a response object.
+
+This is done through a Epaybg::Recurring::Debt::Request object. It accepts a hash with parameters,
+validates them and builds a response array.
+
+````ruby
+# ...
+
+subscription = Subscription.find_by_epay_number request.idn
+
+response_params = {
+  xvalidto: (Time.now + 5.days), # Due date of the subscription
+  secondid: 45, # Custom id for this debt (Optional)
+  amount: 5000, # Debt in coins (bulgarian stotinki)
+  status: '00', # If the status is not '00' (debt found) the other fields will be ignored.
+                # Look up the documentation for the other status codes.
+  shortdesc: 'Debt description',
+  longdesc: 'Debt details' # Optional
+}
+
+response = Epaybg::Recurring::Debt::Response.new response_params
+````
+
+Now that you have a response object, you can send back an answer in the current TCP session.
+
+````ruby
+  response.body_array.each do |element|
+    client.puts element.encode('cp1251') # EpayBG requires that responses are windows-1251 encoded
+  end
+````
+
+We have notified EpayBG that this subscription has a pending payment. Now we wait for a payment
+request.
+
+### Payments
+
+After the user pays their debt through EpayBG's system, EpayBG will send a payment notification on
+the same TCP server used for debt request processing.
+
+This is an example payment request:
+
+```
+XTYPE=QBC
+AID=700021
+ACSID=0000900
+BORIKAID=0000900
+CLIENTID=67600000000000000
+IDN=000000000001
+NEWAMOUNT=000000003000
+AMOUNT=5000
+TID=20111010103406700021592705
+REF=592460592460
+TDATE=20111010103409
+```
+
+Different request types are identified by the `XTYPE` parameter. Refer to the technical
+documentation for further details.
+
+````ruby
+message = client.read
+data = Epaybg::Recurring.parse_request_body(message)
+epay_recurrent_payment = Epaybg::Recurring::Payment.new data
+
+# Handle the payment
+
+epay_recurrent_payment.respond_with(:ok) # This will generate a response for this session.
+
+epay_recurrent_payment.response_array.each do |element|
+  client.puts element
+end
+````
+
+The payment is accepted and EpayBG has been notified that the payment has been
+processed.
+
 ## Contributing
 
 1. Fork it

data/lib/epaybg.rb

@@ -2,6 +2,7 @@ require 'epaybg/railtie' if defined?(Rails)
 require 'epaybg/transaction'
 require 'epaybg/response'
 require 'epaybg/version'
+require 'epaybg/recurring'
 
 module Epaybg
   class << self

data/lib/epaybg/recurring.rb

@@ -0,0 +1,17 @@
+require 'epaybg/recurring/payment'
+require 'epaybg/recurring/debt/request'
+require 'epaybg/recurring/debt/response'
+
+
+module Epaybg
+  module Recurring
+    def self.parse_request_body(body)
+      array = body.split(/\s/).reject(&:empty?).compact
+      array.inject({}) do |hash, element|
+        key, value = *element.strip.split('=')
+        hash[key.downcase] = value
+        hash
+      end
+    end
+  end
+end

data/lib/epaybg/recurring/debt/request.rb

@@ -0,0 +1,17 @@
+module Epaybg
+  module Recurring
+    module Debt
+      class Request
+        attr_accessor :xtype, :idn, :tid, :aid, :clientid 
+
+        def initialize(params = {})
+          params.each do |k, v|
+            instance_variable_set("@#{k}", v)
+          end
+
+          yield self if block_given?
+        end
+      end
+    end
+  end
+end

data/lib/epaybg/recurring/debt/response.rb

@@ -0,0 +1,73 @@
+module Epaybg
+  module Recurring
+    module Debt
+      class Response
+        attr_accessor :xvalidto, :secondid, :amount, :status, :shortdesc, :longdesc, :errors
+
+        XTYPE = 'RBN'
+        STATUSES = %w(00 62 14 80 96)
+
+        # Status codes for epay
+
+        # 00 върнато е задължение / debt returned
+        # 62 няма задължение. / no debts for this isd
+        # 14 невалиден номер(idn) / invalid idn
+        # 80 заявката временно не може да бъде изпълнена / timeout, server buisy
+        # 96 обща грешка / other errors
+
+        def initialize(params = {})
+          @errors = []
+
+          params.each do |k, v|
+            instance_variable_set("@#{k}", v)
+          end
+
+          yield self if block_given?
+          validate!
+        end
+
+        def validate!
+          [:xvalidto, :amount, :status, :shortdesc].each do |element|
+            @errors << "Attribute #{element} is required!" if send(element).blank?
+          end
+
+          @errors << "'xvalidto' should be a time type field!" unless xvalidto.kind_of?(Time)
+
+          {secondid: 15, shortdesc: 40, longdesc: 1800}.each do |k, v|
+            @errors << "Attribute #{k} is too long. Maximum length should be #{v}." if send(k).to_s.length > v
+          end
+
+          @errors << "Invalid value #{status} for status" unless STATUSES.include?(status)
+        end
+
+        def valid?
+          @errors.empty?
+        end
+
+        def longdesc
+          return nil unless @longdesc
+
+          @longdesc.gsub("\n", "\\n")
+        end
+
+        def body_array
+          @body_array = [
+                          "XTYPE=#{XTYPE}",
+                          "XVALIDTO=#{xvalidto.strftime('%Y%m%d000000')}",
+                          "AMOUNT=#{amount}",
+                          "STATUS=#{status}",
+                          "SHORTDESC=#{shortdesc}"
+                        ]
+
+          @body_array << "SECONDID=#{secondid}" if secondid
+          @body_array << "LONGDESC=#{longdesc}" if longdesc
+          @body_array
+        end
+
+        def body
+          body_array.join("\n") + "\n"
+        end
+      end
+    end
+  end
+end

data/lib/epaybg/recurring/payment.rb

@@ -0,0 +1,37 @@
+module Epaybg
+  module Recurring
+    class Payment
+
+      RESPONSE_STATUS_CODES = {
+        ok: '00',
+        err: '96',
+        duplicate: '94'
+      }
+
+      attr_accessor :xtype, :idn, :tid, :amount, :secondid, :ref, :aid, :tdate, :clientid
+
+      def initialize(params = {})
+        params.each do |k, v|
+          instance_variable_set("@#{k}", v)
+        end
+
+        yield self if block_given?
+      end
+
+      def respond_with(symbol)
+        raise 'Invalid symbol' unless RESPONSE_STATUS_CODES.keys.include?(symbol)
+
+        code = RESPONSE_STATUS_CODES[symbol]
+        @response = "XTYPE=RBC\nSTATUS=#{code}\n"
+      end
+
+      def response_array
+        @response.split("\n")
+      end
+
+      def tdate
+        Date.parse(@tdate)
+      end
+    end
+  end
+end

data/lib/epaybg/version.rb

@@ -1,3 +1,3 @@
 module Epaybg
-  VERSION = '0.3.1'
+  VERSION = '1.0.0'
 end

data/spec/recurring/recurring_payments_spec.rb

@@ -0,0 +1,111 @@
+require 'spec_helper'
+require 'yaml'
+
+describe 'Recurring Payments' do
+  let(:request_string) {
+    "XTYPE=QBN\nAID=000100\nACSID=0000897\nBORIKAID=0000897\nCLIENTID=67600000000000000\nIDN=6460392\nTID=20160225080306000100705669\n"
+  }
+
+  let(:debt_params){
+    Epaybg::Recurring.parse_request_body(request_string)
+  }
+
+  before do
+    Epaybg.config = YAML.load_file('spec/test_config.yml')
+  end
+
+  describe 'Recurring module methods' do
+    it 'should parse a request string' do
+      expect(debt_params).to be_kind_of Hash
+      expect(debt_params['xtype']).to eq 'QBN'
+      expect(debt_params['idn']).to eq '6460392'
+    end
+  end
+
+  describe 'Recurrent payment debt request' do
+    it 'should create a valid object' do
+      request = Epaybg::Recurring::Debt::Request.new debt_params
+
+      expect(request.xtype).not_to be_nil
+      expect(request.idn).not_to be_nil
+      expect(request.tid).not_to be_nil
+      expect(request.aid).not_to be_nil
+      expect(request.clientid).not_to be_nil
+    end
+  end
+
+  describe 'Recurrent payment debt response' do
+    let(:valid_params){
+      {
+        xvalidto: ( Time.now + 5.days ),
+        secondid: 'sid25',
+        amount: 5000,
+        status: '00',
+        shortdesc: 'Some description',
+        longdesc: 'Some long description'
+      }
+    }
+
+    it 'create a valid object' do
+      response = Epaybg::Recurring::Debt::Response.new valid_params
+      expect(response).to be_valid
+      expect(response.body_array).not_to be_empty
+    end
+
+    describe 'Invalid objects' do
+      it 'should have the right elements' do
+        response = Epaybg::Recurring::Debt::Response.new {}
+        expect(response).not_to be_valid
+      end
+
+      it 'should not have too long messages' do
+        invalid_params = {
+          shortdesc: "a" * 60,
+          longdesc: "b" * 1801,
+        }
+
+        response = Epaybg::Recurring::Debt::Response.new(valid_params.merge(invalid_params))
+        expect(response).not_to be_valid
+      end
+
+      it 'should not accept invalid status codes' do
+        invalid_params = {
+          status: '1233'
+        }
+        response = Epaybg::Recurring::Debt::Response.new(valid_params.merge(invalid_params))
+        expect(response).not_to be_valid
+      end
+
+    end
+  end
+
+  describe 'Recurring payment object' do
+    let(:valid_params) {
+      {
+        xtype: 'RBN',
+        idn: '0000000001',
+        tid: '423423423423423423',
+        amount: 5000,
+        secondid: 'si45',
+        ref: '234234234234234',
+        aid: '000100',
+        tdate: '20160224173336',
+        clientid: '07728424664'
+      }
+    }
+
+    it 'should create a valid object' do
+      payment = Epaybg::Recurring::Payment.new valid_params
+
+      expect(payment.tdate).to be_kind_of(Date)
+
+      expect{ payment.respond_with(:ok) }.not_to raise_error
+      expect{ payment.respond_with(:err) }.not_to raise_error
+      expect{ payment.respond_with(:duplicate) }.not_to raise_error
+
+      expect{ payment.respond_with(:something_else) }.to raise_error('Invalid symbol')
+
+      expect(payment.respond_with(:ok)).not_to be_nil
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: epaybg
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 1.0.0
 platform: ruby
 authors:
 - gmitrev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-17 00:00:00.000000000 Z
+date: 2016-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -69,12 +69,16 @@ files:
 - epaybg.gemspec
 - lib/epaybg.rb
 - lib/epaybg/railtie.rb
+- lib/epaybg/recurring.rb
+- lib/epaybg/recurring/debt/request.rb
+- lib/epaybg/recurring/debt/response.rb
+- lib/epaybg/recurring/payment.rb
 - lib/epaybg/response.rb
 - lib/epaybg/transaction.rb
 - lib/epaybg/version.rb
 - lib/epaybg/view_helpers.rb
-- log/test.log
 - spec/epaybg/transaction_spec.rb
+- spec/recurring/recurring_payments_spec.rb
 - spec/spec_helper.rb
 - spec/test_config.yml
 homepage: http://github.com/gmitrev/epaybg
@@ -96,12 +100,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Epaybg provides integration with the epay.bg payment services. It supports
   payments through epay.bg, credit cards and in EasyPay offices.
 test_files:
 - spec/epaybg/transaction_spec.rb
+- spec/recurring/recurring_payments_spec.rb
 - spec/spec_helper.rb
 - spec/test_config.yml