cieloz 0.0.2

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in spree_cielo.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012,2013 Fábio Luiz Nery de Miranda <github.com/fabiolnm>
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,170 @@
+[<img src="https://secure.travis-ci.org/fabiolnm/cieloz.png"/>](http://travis-ci.org/fabiolnm/cieloz)
+
+# Cieloz
+
+A utility gem for SpreeCielo Gateway gem.
+
+## Getting Started
+
+This is a step-by-step guide to enable Cielo Gateway as a payment method to your e-commerce store.
+
+First, you should create your credentials at the following Cielo Page:
+
+![Credentials](https://raw.github.com/fabiolnm/cieloz/master/readme/credentials.png)
+
+Then a form will be presented to be filled with Store, Store's Owner, Store's Address* and Banking data.
+* address must be the same as the present at Store CNPJ!
+
+After the form is submitted, a receipt number is generated, and generally in one or two business days,
+Cielo sends an e-mail with detailed instructions and manuals:
+
+ * [Email example](https://raw.github.com/fabiolnm/cieloz/master/readme/email_cielo.pdf)
+ * [Security Guide](https://raw.github.com/fabiolnm/cieloz/master/readme/cielo_guia_seguranca_ecommerce.pdf)
+ * [Affiliation Contract](https://raw.github.com/fabiolnm/cieloz/master/readme/contrato_de_afiliacao_ao_sistema_cielo.pdf)
+ * [Preventive Tips for securing sales](https://raw.github.com/fabiolnm/cieloz/master/readme/dicas_preventivas_para_vendas_mais_seguras.pdf)
+ * [Required documents for affiliation](https://raw.github.com/fabiolnm/cieloz/master/readme/lista_de_documentos_necessarios_para_afiliacao_de_vendas_pela_internet_pessoa_juridica.pdf)
+ * [Risk Terms](https://raw.github.com/fabiolnm/cieloz/master/readme/termo_de_adesao_de_risco.pdf)
+
+##### NOTE
+These were the documents sent by Cielo at December 21, 2012, and are subject to changes according to the Cielo affiliation processs changes.
+If you notice any document is changed since then, and wants to collaborate on keeping this gem updated, please open an issue
+so our team can update this README.
+
+##### Cielo Developer Kit
+Additionaly, the email provides a link where the Cielo Integration Kit can be downloaded:
+
+  http://www.cielo.com.br/portal/kit-e-commerce-cielo.html
+
+This kit contais the API documentation that served as a basis to developing this gem:
+[Cielo e-commerce Developer Guide v2.0.3](https://raw.github.com/fabiolnm/cieloz/master/readme/cielo_developer_guide_2.0.3.pdf).
+
+### The Test Environment
+
+The page 32 of this manual provides information about a Test Environment that can be used as a sandbox
+to test integration with Cielo Web Services:
+
+  https://qasecommerce.cielo.com.br/servicos/ecommwsec.do
+
+It also provides API ID and API Secret that are required to be sent within every request sent
+to Cielo Web Services, and valid test credit card numbers to be used at this environment.
+
+### The Cielo Payment Workflow
+
+#### Hosted Buy Page versus Store Buy Page
+
+Credit Card data can be provided directly to a Store BuyPage, but this requires the Store
+Owner to handle with security issues.
+
+The simplest alternative to get started is using an environment provided by the Cielo
+infrastructure. When the user is required to type his credit card data, he is redirected
+to a Cielo Hosted Buy Page. When the user submits his data, he's redirected back to
+a Callback URL provided by the store.
+
+
+#### Supported CreditCard operations
+
+The following diagram was extracted from Cielo Developer Guide v2.0.3, page 5.
+
+![Payment States](https://raw.github.com/fabiolnm/cieloz/master/readme/supported_products.png)
+
+#### TransactionRequest (RequisicaoTransacao)
+
+Every payment starts with a TransactionRequest. In the Hosted Mode, its main data are:
+ * Order Data (DadosPedido)
+ * PaymentMethod (FormaPagamento)
+ * Authorization Mode (whether it supports Authentication Programs)
+ * Capture Mode (can be util for fraud prevention)
+
+In Store Mode, it also should include Credit Card Data (DadosPortador).
+
+##### Authorization Modes
+
+Visa and Mastercard supports Authentication Programs. This means additional security, as the
+user is required to provide additional security credentials with his bank to be able to
+have a transaction authorized for online payments:
+
+ * [Verified by Visa](https://raw.github.com/fabiolnm/cieloz/master/readme/verified_by_visa.png),
+   from this [source](http://www.verifiedbyvisa.com.br/aspx/funciona/comofunciona.aspx)
+ * [MasterCard Secure Code](https://raw.github.com/fabiolnm/cieloz/master/readme/mastercard_securecodedemo.swf),
+   from this [source](https://www.mycardsecure.com/vpas/certegy_mc/i18n/en_US/securecodedemo.swf)
+
+Additionaly, a specific authorization mode is available to enable recurrent payments, in the
+case they are supported by the Credit Card operator.
+
+#### Transaction States and Web Service Operations
+
+The following diagram was extracted from Cielo Developer Guide v2.0.3, page 9.
+
+![Payment States](https://raw.github.com/fabiolnm/cieloz/master/readme/cielo_payment_states.png)
+
+When a TransactionRequest succeeds, it responds with a Transaction (Transacao) with Status 0 - CREATED.
+This response contains the Transaction ID (TID), and an Authentication URL (url-autenticacao)
+where the user must be redirected to start the Authorization flow.
+
+When the user visits this URL, the transaction assumes Status 1 - IN_PROGRESS.
+When the user submits its Credit Card data, the transaction can assume Authentication States,
+if supported by the selected credit card (Verified by Visa or MasterCard Secure Code programs).
+
+After authentication/authorization flow, if the user has available credit, the
+transaction assumes Status 4 - AUTHORIZED (Autorizada).
+
+When the transaction is at AUTHORIZED state, the Store Owner must capture this payment in the
+next five days. This can be done with a CaptureRequest (RequisicaoCaptura)
+
+The Store Owner also has the option to request automatic payment capture, bypassing AUTHORIZED state.
+After capture, the transaction assumes Status 6 - CAPTURED (Capturada).
+
+* Manual Capture can be useful for fraud prevention, but it requires aditional Admin efforts.
+
+In the 90 days that follows the Authorization or Capture, the transaction can be fully or
+partially cancelled, assuming state 9 - CANCELLED (Cancelada). This can be done with a
+CancelRequest (RequisicaoCancelamento).
+
+* At any time, a pending request can be expired at Cielo Gateway, that puts the transaction in CANCELLED state.
+* Each state has its own expire time, see the Developer Guide for detailed information.
+
+At any time, a QueryRequest (RequisicaoConsulta) can be made for a specific transaction
+(identified by its TID) to query about the state of the transaction.
+
+### What is this gem about?
+
+This gem provides a Ruby integration solution that consumes Cielo Web Services.
+
+A developer just instantiates one of the available operations:
+
+ * RequisicaoTransacao
+ * RequisicaoConsulta
+ * RequisicaoCaptura
+ * RequisicaoCancelamento
+
+Then populates them with appropriate data. This gem validates these request objects according to
+Cielo Specifications present at Developer Guide (pages 10, 11, 26, 28 and 30), so it makes error
+handling easier, before the request is sent to Cielo Web Service.
+
+If the operation is valid, this gem serializes them as XML and submits to Cielo, parsing the
+response as a Transaction (Transacao) or Error (Erro) objects. Both keeps the original XML response
+as a xml attribute, so it can be logged.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'cieloz'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install cieloz
+
+## Usage
+
+## 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

data/Rakefile

@@ -0,0 +1,16 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs.push "lib"
+  t.pattern = 'test/{minitest_helper,unit/**/*}.rb'
+  t.verbose = true
+end
+
+Rake::TestTask.new("test:integration") do |t|
+  t.libs.push "lib"
+  t.pattern = 'test/integration/**/*.rb'
+  t.verbose = true
+end
+
+task default: :test

data/cieloz.gemspec

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cieloz/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "cieloz"
+  gem.version       = Cieloz::VERSION
+  gem.authors       = ["Fábio Luiz Nery de Miranda"]
+  gem.email         = ["fabio@miranti.net.br"]
+  gem.description   = %q{A utility gem for Cielo Integration}
+  gem.summary       = %q{}
+  gem.homepage      = "https://github.com/fabiolnm/cieloz"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency "nokogiri"
+  gem.add_dependency "activesupport"
+  gem.add_dependency "activemodel"
+
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "turn"
+  gem.add_development_dependency "fakeweb"
+  gem.add_development_dependency "debugger"
+
+  # see https://github.com/thoughtbot/shoulda-matchers/issues/235
+  gem.add_development_dependency "bourne", "1.3.0"
+
+  gem.add_development_dependency "shoulda-matchers"
+  gem.add_development_dependency "minitest-matchers"
+end

data/config/locales/en.yml

@@ -0,0 +1,11 @@
+en:
+  activemodel:
+    errors:
+      models:
+        cieloz/requisicao_transacao:
+          attributes:
+            autorizar:
+              authentication_not_supported: Authentication not supported
+              direct_auth_available_for_credit_only: Direct auth available for credit only
+            forma_pagamento:
+              minimum_installment_not_satisfied: Installment should be greater than or equal to R$ 5,00

data/config/locales/pt-BR.yml

@@ -0,0 +1,11 @@
+pt-BR:
+  activemodel:
+    errors:
+      models:
+        cieloz/requisicao_transacao:
+          attributes:
+            autorizar:
+              authentication_not_supported: Bandeira não possui programa de autenticação
+              direct_auth_available_for_credit_only: Autorização Direta disponível apenas em operações de crédito
+            forma_pagamento:
+              minimum_installment_not_satisfied: O valor mínimo da parcela deve ser R$ 5,00

data/lib/cieloz/bandeiras.rb

@@ -0,0 +1,22 @@
+module Cieloz
+  module Bandeiras
+    ALL = %w(amex diners discover elo mastercard visa)
+    AMEX, DINERS, DISCOVER, ELO, MASTERCARD, VISA = ALL
+
+    def self.operacao produto
+      case produto.to_sym
+      when :mastercard_securecode
+        [MASTERCARD,      :autorizar_somente_autenticada]
+      when :verified_by_visa
+        [VISA,            :autorizar_somente_autenticada]
+      else
+        produto = produto.to_s
+        if ALL.include? produto
+          [produto,  :autorizacao_direta]
+        else
+          raise "product_not_supported"
+        end
+      end
+    end
+  end
+end

data/lib/cieloz/builder.rb

@@ -0,0 +1,71 @@
+module Cieloz
+  module Builder
+    def portador source, opts={}
+      num, val, cod, nome = attrs_from source, opts,
+        :numero, :validade, :codigo_seguranca, :nome_portador
+
+      RequisicaoTransacao::DadosPortador.new numero: num,
+        validade: val, codigo_seguranca: cod, nome_portador: nome
+    end
+
+    def pedido source, opts={}
+      mappings = attrs_from source, opts, :numero, :valor,
+        :descricao, :data_hora, :moeda, :idioma, :soft_descriptor
+
+      num, val, desc, time, cur, lang, soft = mappings
+      val = (val * 100).round unless val.nil? or val.integer?
+
+      time  ||= Time.now
+      cur   ||= Cieloz::Configuracao.moeda
+      lang  ||= Cieloz::Configuracao.idioma
+      soft  ||= Cieloz::Configuracao.soft_descriptor
+
+      RequisicaoTransacao::DadosPedido.new data_hora: time,
+        numero: num, valor: val, moeda: cur, idioma: lang,
+        descricao: desc, soft_descriptor: soft
+    end
+
+    def pagamento source, opts={}
+      opr, parcelas = attrs_from source, opts, :operacao, :parcelas
+      RequisicaoTransacao::FormaPagamento.new.operacao opr, parcelas
+    end
+
+    def transacao source, opts={}
+      portador, pedido, pagamento, url, capturar, campo_livre =
+        attrs_from source, opts, :dados_portador, :dados_pedido,
+        :forma_pagamento, :url_retorno, :capturar, :campo_livre
+
+      url ||= Cieloz::Configuracao.url_retorno
+
+      txn = RequisicaoTransacao.new dados_portador: portador,
+        dados_pedido: pedido, forma_pagamento: pagamento,
+        campo_livre: campo_livre, url_retorno: url,
+        dados_ec: Cieloz::Configuracao.credenciais
+
+      capturar ||= Cieloz::Configuracao.captura_automatica
+
+      case capturar.to_s
+      when 'true' then txn.capturar_automaticamente
+      else        txn.nao_capturar_automaticamente
+      end
+
+      txn.send pagamento.metodo_autorizacao
+
+      txn
+    end
+
+    private
+    def attrs_from source, opts, *keys
+      keys.map { |k|
+        value_or_attr_name = opts[k] || k
+        if value_or_attr_name.is_a? Symbol
+          source.send value_or_attr_name if source.respond_to? value_or_attr_name
+        else
+          value_or_attr_name
+        end
+      }
+    end
+  end
+
+  extend Builder
+end

data/lib/cieloz/configuracao.rb

@@ -0,0 +1,64 @@
+module Cieloz
+  module Configuracao
+    HOST    = "ecommerce.cielo.com.br"
+    WS_PATH = "/servicos/ecommwsec.do"
+
+    @@mode                = :cielo
+    @@moeda               = 986 # ISO 4217 - Manual Cielo, p 11
+    @@idioma              = "PT"
+    @@max_parcelas        = 3
+    @@max_adm_parcelas    = 10
+    @@captura_automatica  = false
+    @@credenciais         = nil
+    @@dados_ec            = nil
+
+    mattr_writer :credenciais, :captura_automatica
+    mattr_accessor :url_retorno, :soft_descriptor
+    mattr_accessor :max_parcelas, :max_adm_parcelas, :moeda, :idioma
+
+    def self.reset!
+      cielo_mode!
+      @@credenciais = nil
+    end
+
+    def self.store_mode!
+      @@mode = :store
+    end
+
+    def self.store_mode?
+      @@mode == :store
+    end
+
+    def self.cielo_mode!
+      @@mode = :cielo
+    end
+
+    def self.cielo_mode?
+      @@mode == :cielo
+    end
+
+    def self.credenciais
+      return @@dados_ec if @@dados_ec
+      return (@@dados_ec = Requisicao::DadosEc.new @@credenciais) if @@credenciais
+
+      mode = store_mode? ? :LOJA : :CIELO
+      Homologacao::Credenciais.const_get mode
+    end
+
+    def self.host
+      @@credenciais ? HOST : Homologacao::HOST
+    end
+
+    def self.path
+      WS_PATH
+    end
+
+    def self.url
+      "https://#{host}#{WS_PATH}"
+    end
+
+    def self.captura_automatica
+      !!@@captura_automatica
+    end
+  end
+end

data/lib/cieloz/helpers.rb

@@ -0,0 +1,35 @@
+module Cieloz
+  module Helpers
+    module ClassMethods
+      def hattr_writer *attrs
+        attrs.each { |attr|
+          define_method "#{attr}=" do |value|
+            if value.is_a? Hash
+              name = attr.to_s.camelize
+              cls = self.class.const_get name
+              value = cls.new(value)
+            end
+            instance_variable_set "@#{attr}", value
+            yield(value) if block_given?
+          end
+        }
+      end
+    end
+
+    def self.included base
+      base.extend ClassMethods
+      base.send :include, ActiveModel::Validations
+    end
+
+    def initialize attrs={}
+      self.attributes = attrs
+    end
+
+    def attributes= attrs
+      attrs.each {|k,v|
+        m = "#{k}="
+        send(m, v) if respond_to? m
+      }
+    end
+  end
+end

data/lib/cieloz/homologacao.rb

@@ -0,0 +1,16 @@
+module Cieloz
+  module Homologacao
+    HOST = "qasecommerce.cielo.com.br"
+
+    module Credenciais
+      CIELO = {
+        numero: "1001734898",
+        chave: "e84827130b9837473681c2787007da5914d6359947015a5cdb2b8843db0fa832"
+      }
+      LOJA  = {
+        numero: "1006993069",
+        chave: "25fbb99741c739dd84d7b06ec78c9bac718838630f30b112d033ce2e621b34f3"
+      }
+    end
+  end
+end

data/lib/cieloz/requisicao/dados_ec.rb

@@ -0,0 +1,14 @@
+module Cieloz
+  class Requisicao
+    class DadosEc
+      include Helpers
+
+      attr_accessor :numero, :chave
+      validates :numero, :chave, presence: true
+
+      def attributes
+        { numero: @numero, chave: @chave }
+      end
+    end
+  end
+end

data/lib/cieloz/requisicao/resposta/erro.rb

@@ -0,0 +1,11 @@
+module Cieloz
+  class Requisicao
+    class Erro < Resposta
+      attr_accessor :codigo, :mensagem
+
+      def success?
+        false
+      end
+    end
+  end
+end

data/lib/cieloz/requisicao/resposta/transacao.rb

@@ -0,0 +1,11 @@
+module Cieloz
+  class Requisicao
+    class Transacao < Resposta
+      attr_accessor :tid, :status, :url_autenticacao
+
+      def success?
+        true
+      end
+    end
+  end
+end

data/lib/cieloz/requisicao/resposta.rb

@@ -0,0 +1,35 @@
+module Cieloz
+  class Requisicao
+    class Resposta
+      include ActiveModel::Serializers::Xml
+      include Helpers
+
+      STATUSES = {
+        "0" => :criada,
+        "1" => :em_andamento,
+        "2" => :autenticada,
+        "3" => :nao_autenticada,
+        "4" => :autorizada,
+        "5" => :nao_autorizada,
+        "6" => :capturada,
+        "9" => :cancelada,
+        "10" => :em_autenticacao,
+        "12" => :em_cancelamento
+      }
+
+      attr_reader :xml
+
+      def self.from xml
+        obj = new.from_xml xml
+        obj.instance_variable_set :@xml, xml
+        obj
+      end
+
+      STATUSES.each do |_, status_type|
+        define_method "#{status_type}?" do
+          success? and STATUSES[status] == status_type
+        end
+      end
+    end
+  end
+end

data/lib/cieloz/requisicao.rb

@@ -0,0 +1,69 @@
+require 'net/http'
+require 'builder'
+
+class Cieloz::Requisicao
+  include Cieloz::Helpers
+
+  attr_accessor :id, :versao
+  attr_reader :dados_ec
+  hattr_writer :dados_ec
+
+  validates :id, :versao, :dados_ec, presence: true
+
+  def attributes
+    { dados_ec: @dados_ec }
+  end
+
+  def to_xml
+    x = Builder::XmlMarkup.new
+    x.instruct!
+    name = self.class.name.demodulize
+    x.tag! name.underscore.dasherize, id: id, versao: versao do
+      attributes.each { |attr, value|
+        next if value.nil?
+
+        unless value.respond_to? :attributes
+          x.tag! dash(attr), value
+        else
+          x.tag! dash(attr) do
+            value.attributes.each do |attr, value|
+              x.tag!(dash(attr), value) unless value.blank?
+            end
+          end
+        end
+      }
+    end
+  end
+
+  def submit
+    @id     = SecureRandom.uuid if id.blank?
+    @versao = "1.2.0"           if versao.blank?
+
+    if valid?
+      http = Net::HTTP.new Cieloz::Configuracao.host, 443
+      http.use_ssl = true
+      http.open_timeout = 5 * 1000
+      http.read_timeout = 30 * 1000
+      http.ssl_version = :SSLv3 #http://stackoverflow.com/questions/11321403/openssl-trouble-with-ruby-1-9-3
+
+      parse http.post Cieloz::Configuracao.path, "mensagem=#{to_xml}"
+    end
+  end
+
+  def parse res
+    body = res.body.force_encoding("ISO-8859-1").encode "UTF-8"
+    return Erro.new(codigo: res.code, mensagem: body) if res.code != "200"
+
+    root = Nokogiri::XML(body).root
+    response_class =  case root.name
+    when 'erro'       then Erro
+    when 'transacao'  then Transacao
+    end
+    response_class.from body
+  end
+
+  private
+  def dash value
+    value.to_s.gsub("@", "").dasherize
+  end
+end

data/lib/cieloz/requisicao_tid.rb

@@ -0,0 +1,23 @@
+module Cieloz
+  class RequisicaoTid < Requisicao
+    attr_accessor :tid
+
+    def attributes
+      { tid: @tid, dados_ec: @dados_ec }
+    end
+  end
+
+  class RequisicaoTidValor < RequisicaoTid
+    attr_accessor :valor
+
+    def attributes
+      { tid: @tid, dados_ec: @dados_ec, valor: @valor }
+    end
+  end
+
+  class RequisicaoConsulta < RequisicaoTid ; end
+  class RequisicaoAutorizacaoTid < RequisicaoTid ; end
+
+  class RequisicaoCaptura < RequisicaoTidValor ; end
+  class RequisicaoCancelamento < RequisicaoTidValor ; end
+end