webpay_rails 1.0.3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 66d74da610bd48aff215127601149dfb400f2c04
-  data.tar.gz: dbb3e7a94ebdc13ad70a44e10347813c69a934d7
+  metadata.gz: 45f7d47cef070f34e7a49e4d82f56be925a24100
+  data.tar.gz: cd1194ac36020b9cad4a31c61335d7aac0552e14
 SHA512:
-  metadata.gz: bbb1a70435388af9aaf3c25e51b7fc5c4b76be65138ca9da7cd4dfb2f48d4cbfd01795b988f12bb507113ed682aeaae3f81add4f617085a27156927322ba798f
-  data.tar.gz: e636f89ac6cd8e7deb37c654cd39c8d7e3012a5f5d3ed5b6b1df9e7585203474ac37b655f3c1aa52314b0ebf4d9cef28e7debc90171c6054b115fbea53cc9efe
+  metadata.gz: 3aa2cc1b4cda7282b2c7a20e1fb2a6903eb7df616c60a43d3f86709fd7ad0e224619ce2104d78728b8f3c6dbd11e17ba997d1b1cd70f930f0e9f430cc7aa1d9d
+  data.tar.gz: b75e3b18b128b5ac3b4a7c38c5144068340f30661653ce1e96a13144a232a2a5ca9bdf472507424eaff2b8d75556f2e89863336320d4cb20f6880481b7d87341

data/.gitignore

@@ -1,5 +1,7 @@
-test/dummy/log/*
-test/dummy/tmp/*
+spec/internal/log/*
+spec/internal/tmp/*
+spec/internal/db/*.sqlite3
+spec/internal/db/log/*.log
 *~
 coverage/*
 *.sqlite3

data/.travis.yml

@@ -4,5 +4,9 @@ cache: bundler
 rvm:
   - 2.2.2
   - 2.3.0
+env:
+  - CAPYBARA_DRIVER=poltergeist
+after_success:
+  - coveralls
 notifications:
   email: false

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ### Unreleased
 
+### 1.1.0 - 2016-11-03
+
+#### bug fixes
+* fix response verification
+
+#### enhancements
+* add support for nullify method
+* raise detailed execptions when rescued from Savon::SOAPFault
+* group certificates and private keys on Vault
+* improve execptions when missing certificates, private_keys or commerce_code, and when set an invalid environment
+* add support for certificates and private key as a files
+* replace specific exceptions by generic exceptions with more detailed explanations
+* add an option for disable the auto acknowledgement on transaction_result method
+
 ### 1.0.3 - 2016-09-15
 
 #### bug fixes

data/Gemfile

@@ -12,3 +12,5 @@ gemspec
 
 # To use a debugger
 # gem 'byebug', group: [:development, :test]
+
+gem 'phantomjs', group: :development, require: 'phantomjs/poltergeist'

data/README.md

@@ -2,6 +2,8 @@
 
 [![Build Status](https://travis-ci.org/limcross/webpay_rails.svg?branch=master)](https://travis-ci.org/limcross/webpay_rails)
 [![Code Climate](https://codeclimate.com/github/limcross/webpay_rails/badges/gpa.svg)](https://codeclimate.com/github/limcross/webpay_rails)
+[![Coverage Status](https://coveralls.io/repos/github/limcross/webpay_rails/badge.svg?branch=master)](https://coveralls.io/github/limcross/webpay_rails?branch=master)
+[![Dependency Status](https://gemnasium.com/badges/github.com/limcross/webpay_rails.svg)](https://gemnasium.com/github.com/limcross/webpay_rails)
 [![Gem Version](https://badge.fury.io/rb/webpay_rails.svg)](https://badge.fury.io/rb/webpay_rails)
 
 WebpayRails is an easy solution for integrate Transbank Webpay in Rails applications.
@@ -9,6 +11,9 @@ WebpayRails is an easy solution for integrate Transbank Webpay in Rails applicat
 _This gem (including certificates used in tests) was originally based on the SDK for Ruby (distributed under the **open source license**) available in www.transbankdevelopers.cl_
 
 ## Getting started
+
+__This README is only valid for the *master* branch, click [here](https://github.com/limcross/webpay_rails/blob/v1.1.0/README.md) for see the latest released version.__
+
 You can add it to your `Gemfile`:
 
 ```ruby
@@ -20,12 +25,11 @@ Run the bundle command to install it.
 ### Configuring models
 After that, extend the model to `WebpayRails` and add `webpay_rails` to this, like below.
 
-
 ```ruby
 class Order < ActiveRecord::Base
   extend WebpayRails
 
-  webpay_rails({
+  webpay_rails(
     commerce_code: 123456789,
     private_key: '-----BEGIN RSA PRIVATE KEY-----
 ...
@@ -38,10 +42,16 @@ class Order < ActiveRecord::Base
 -----END CERTIFICATE-----',
     environment: :integration,
     log: Rails.env.development?
-  })
+  )
 end
 ```
 
+As you can see for `private_key`, `public_cert`, and `webpay_cert`, the content of the files is entered, without prejudice to the above you can also indicate the absolute path to these files.
+
+The default `environment` is `:integration`, and the valid environments are `:integration`, `:certification` and `:production`. Depending on the environment is assigned the wsdl path.
+
+The `log` is very useful when generating the evidence of integration, and is enabled by default.
+
 Obviously all these values should not be defined directly in the model. It is strongly recommended to use environment variables for this ([dotenv](https://github.com/bkeepers/dotenv)).
 
 ### Using WebpayRails
@@ -51,16 +61,16 @@ Obviously all these values should not be defined directly in the model. It is st
 First we need to initialize an transaction, like below:
 
 ```ruby
-@transaction = Order.init_transaction(amount, buy_order, session_id, return_url, final_url)
+@transaction = Order.init_transaction(amount: amount, buy_order: buy_order, session_id: session_id, return_url: return_url, final_url: final_url)
 ```
 
-Where `amount` is an __integer__ that define the amount of the transaction (_obviously_), `buy_order` is an __intenger__ that define the order number of the buy, `session_id` is an __string__ that define a local variable that will be returned as part of the result of the transaction, `return_url` and `final_url` are a __string__ for the redirections.
+Where `amount` is an __integer__ that define the amount of the transaction (_obviously_), `buy_order` is an __string__ that define the order number of the buy, `session_id` is an __string__ that define a local variable that will be returned as part of the result of the transaction, `return_url` and `final_url` are a __string__ for the redirections.
 
 This method return a `Transaction` object, that contain a redirection `url` and `token` for redirect the customer through POST method, like below.
 
 ```erb
 <% if @transaction.success? %>
-  <%= form_tag(@transaction.url, method: "post") do %>
+  <%= form_tag(@transaction.url, method: :post) do %>
     <%= hidden_field_tag(:token_ws, @transaction.token) %>
     <%= submit_tag("Pagar con Webpay") %>
   <% end %>
@@ -74,7 +84,7 @@ Once Webpay displays the form of payment and authorization of the bank, the cust
 When Webpay send a __POST__ to `return_url` with `token_ws`, we need to ask for the transaction result, like below.
 
 ```ruby
-@result = Order.transaction_result(params[:token_ws])
+@result = Order.transaction_result(token: params[:token_ws])
 ```
 
 This method return a `TransactionResult` object, that contain an `buy_order`, `session_id`, `accounting_date`, `transaction_date`, `vci`, `url_redirection`, `card_number`, `card_expiration_date`, `authorization_code`, `payment_type_code`, `response_code`, `amount`, `shares_number` and `commerce_code`.
@@ -87,6 +97,21 @@ Now we need to send back the customer to `url_redirection` with `token_ws` throu
 
 When Webpay send customer to `final_url`, we are done. Finally the transaction has ended. :clap:
 
+#### Nullify a transaction
+
+To cancel a transaction we must use the method described below.
+
+```ruby
+@transaction = Order.nullify(authorization_code: authorization_code, authorized_amount: authorized_amount, buy_order: buy_order, nullify_amount: nullify_amount)
+```
+
+Where `authorization_code`, `authorized_amount`, `buy_order`, are known and corresponds to the transaction to be canceled, and `nullify_amount` it corresponds to the amount to be canceled.
+
+This method return a `TransactionNullified` object, that contain an `token`, `authorization_code`, `authorization_date`, `balance` and
+ `nullified_amount`.
+
+Note that you can only make a single cancellation, whether total or partial.
+
 ## Contributing
 Any contribution is welcome. Personally I prefer to use English to do documentation and describe commits, however there is no problem if you make your comments and issues in Spanish.
 

data/config.ru

@@ -0,0 +1,7 @@
+require 'rubygems'
+require 'bundler'
+
+Bundler.require :default, :development
+
+Combustion.initialize! :active_record, :action_controller, :action_view
+run Combustion::Application

data/lib/webpay_rails.rb

@@ -10,10 +10,15 @@ require 'openssl'
 
 require 'webpay_rails/version'
 require 'webpay_rails/errors'
+require 'webpay_rails/vault'
 require 'webpay_rails/soap'
+require 'webpay_rails/soap_normal'
+require 'webpay_rails/soap_nullify'
 require 'webpay_rails/verifier'
+require 'webpay_rails/transaction_base'
 require 'webpay_rails/transaction'
 require 'webpay_rails/transaction_result'
+require 'webpay_rails/transaction_nullified'
 require 'webpay_rails/railites'
 
 module WebpayRails

data/lib/webpay_rails/base.rb

@@ -3,50 +3,125 @@ module WebpayRails
     extend ActiveSupport::Concern
 
     module ClassMethods
-      def webpay_rails(options)
-        class_attribute :commerce_code, :webpay_cert, :environment, :soap, instance_accessor: false
+      # Setup a model for use Webpay Rails.
+      #
+      # ==== Variations of #webpay_rails
+      #
+      #   # setup with certificates and private_key content
+      #   webpay_rails(
+      #     commerce_code: 123456789,
+      #     private_key: '-----BEGIN RSA PRIVATE KEY-----
+      #   ...
+      #   -----END RSA PRIVATE KEY-----',
+      #     public_cert: '-----BEGIN CERTIFICATE-----
+      #   ...
+      #   -----END CERTIFICATE-----',
+      #     webpay_cert: '-----BEGIN CERTIFICATE-----
+      #   ...
+      #   -----END CERTIFICATE-----',
+      #     environment: :integration,
+      #     log: Rails.env.development?
+      #   )
+      #
+      #   # setup with certificates and private_key files
+      #   webpay_rails(
+      #     commerce_code: 123456789,
+      #     private_key: 'absolute/path/to/private_key.key',
+      #     public_cert: 'absolute/path/to/public_cert.crt',
+      #     webpay_cert: 'absolute/path/to/webpay_cert.crt',
+      #     environment: :integration,
+      #     log: Rails.env.development?
+      #   )
+      def webpay_rails(args)
+        class_attribute :vault, :soap_normal, :soap_nullify,
+                        instance_accessor: false
 
-        self.commerce_code = options[:commerce_code]
-        self.webpay_cert = OpenSSL::X509::Certificate.new(options[:webpay_cert])
-        self.environment = options[:environment]
-
-        self.soap = WebpayRails::Soap.new(options)
+        self.vault = args[:vault] = WebpayRails::Vault.new(args)
+        self.soap_normal = WebpayRails::SoapNormal.new(args)
+        self.soap_nullify = WebpayRails::SoapNullify.new(args)
       end
 
-      def init_transaction(amount, buy_order, session_id, return_url, final_url)
-        begin
-          response = soap.init_transaction(commerce_code, amount, buy_order, session_id, return_url, final_url)
-        rescue StandardError
-          raise WebpayRails::FailedInitTransaction
-        end
-
-        raise WebpayRails::InvalidCertificate unless WebpayRails::Verifier.verify(response, webpay_cert)
+      # Initializes a transaction
+      # Returns a WebpayRails::Transaction if successfully initialised.
+      # If fault a WebpayRails::RequestFailed exception is raised.
+      # If the SOAP response cant be verified a WebpayRails::InvalidCertificate
+      # exception is raised.
+      #
+      # === Arguments
+      # [:amount]
+      #   An integer that define the amount of the transaction.
+      # [:buy_order]
+      #   An string that define the order number of the buy.
+      # [:session_id]
+      #   An string that define a local variable that will be returned as
+      #   part of the result of the transaction.
+      # [:return_url]
+      #   An string that define the url that Webpay redirect after client is
+      #   authorized (or not) by the bank  for get the result of the transaction.
+      # [:final_url]
+      #   An string that define the url that Webpay redirect after they show
+      #   the webpay invoice, or cancel the transaction from Webpay.
+      def init_transaction(args)
+        response = soap_normal.init_transaction(args)
 
-        WebpayRails::Transaction.new(Nokogiri::HTML(response.to_s))
+        WebpayRails::Transaction.new(response)
       end
 
-      def transaction_result(token)
-        begin
-          response = soap.get_transaction_result(token)
-        rescue StandardError
-          raise WebpayRails::FailedGetResult
-        end
+      # Retrieves the result of a transaction
+      # Returns a WebpayRails::TransactionResult if successfully get a response.
+      # If fault a WebpayRails::RequestFailed exception is raised.
+      # If the SOAP response cant be verified a WebpayRails::InvalidCertificate
+      # exception is raised.
+      #
+      # === Arguments
+      # [:token]
+      #   An string that responds Webpay when redirect to +return_url+.
+      # [:ack]
+      #   An optional boolean with which you can disable the auto
+      #   acknowledgement (I guess if you do this, you will know what you do).
+      def transaction_result(args)
+        response = soap_normal.get_transaction_result(args)
 
-        raise WebpayRails::InvalidResultResponse if response.blank?
+        acknowledge_transaction(args) if args[:ack] != false
 
-        acknowledge_transaction(token)
+        WebpayRails::TransactionResult.new(response)
+      end
 
-        WebpayRails::TransactionResult.new(Nokogiri::HTML(response.to_s))
+      # Reports the correct reception of the result of the transaction
+      # If fault a WebpayRails::RequestFailed exception is raised.
+      # If the SOAP response cant be verified a WebpayRails::InvalidCertificate
+      # exception is raised.
+      #
+      # === Arguments
+      # [:token]
+      #   An string that responds Webpay when redirect to +return_url+.
+      #
+      # NOTE: It is not necessary to use this method because it is consumed by
+      # +transaction_result+.
+      def acknowledge_transaction(args)
+        soap_normal.acknowledge_transaction(args)
       end
 
-      def acknowledge_transaction(token)
-        begin
-          response = soap.acknowledge_transaction(token)
-        rescue StandardError
-          raise WebpayRails::FailedAcknowledgeTransaction
-        end
+      # Nullify a transaction
+      # Returns a WebpayRails::TransactionNullified if successfully initialised.
+      # If fault a WebpayRails::RequestFailed exception is raised.
+      # If the SOAP response cant be verified a WebpayRails::InvalidCertificate
+      # exception is raised.
+      #
+      # === Arguments
+      # [:authorization_code]
+      #   An string that original belongs to the transaction.
+      # [:authorize_amount]
+      #   An integer that define the original amount of the transaction.
+      # [:buy_order]
+      #   An string that define the order number of the transaction to be
+      #   nullified.
+      # [:nullify_amount]
+      #   An intenger that define the amount to be nullified on the transaction.
+      def nullify(args)
+        response = soap_nullify.nullify(args)
 
-        raise WebpayRails::InvalidAcknowledgeResponse if response.blank?
+        WebpayRails::TransactionNullified.new(response)
       end
     end
   end

data/lib/webpay_rails/errors.rb

@@ -1,10 +1,48 @@
 module WebpayRails
-  class Error < StandardError; end
-  class FailedInitTransaction < Error; end
-  class FailedGetResult < Error; end
-  class InvalidResultResponse < Error; end
-  class FailedAcknowledgeTransaction < Error; end
-  class InvalidAcknowledgeResponse < Error; end
-  class InvalidEnvironment < Error; end
-  class InvalidCertificate < Error; end
+  # Generic WebpayRails exception class.
+  class WebpayRailsError < StandardError; end
+
+  # Raise when the commerce code has not been defined.
+  class MissingCommerceCode < WebpayRailsError; end
+  # Raise when the environment is not valid.
+  class InvalidEnvironment < WebpayRailsError; end
+
+  # Generic Soap exception class.
+  class SoapError < WebpayRailsError
+    def initialize(action, error)
+      super("Attempted to #{action} but #{error}")
+    end
+  end
+
+  # Raise when the SOAP request has failed.
+  class RequestFailed < SoapError
+    def initialize(action, error)
+      super(action, "SOAP responds with a #{error.http.code} " \
+                    "status code: #{error}")
+    end
+  end
+  # Raise when the SOAP response of a request is blank.
+  class InvalidResponse < SoapError
+    def initialize(action)
+      super(action, 'SOAP response is blank')
+    end
+  end
+  # Raise when the SOAP response cannot be verify with the webpay cert.
+  class InvalidCertificate < SoapError
+    def initialize(action)
+      super(action, 'the response was not signed with the correct certificate')
+    end
+  end
+
+  # Generic Vault exception class.
+  class VaultError < WebpayRailsError; end
+
+  # Raise when vault cant load the file.
+  class FileNotFound < VaultError; end
+  # Raise when private key has not been defined.
+  class MissingPrivateKey < VaultError; end
+  # Raise when public certificate has not been defined.
+  class MissingPublicCertificate < VaultError; end
+  # Raise when webpay certificate has not been defined.
+  class MissingWebpayCertificate < VaultError; end
 end

data/lib/webpay_rails/soap.rb

@@ -3,56 +3,32 @@ module WebpayRails
     extend Savon::Model
 
     def initialize(args)
-      @private_key = OpenSSL::PKey::RSA.new(args[:private_key])
-      @public_cert = OpenSSL::X509::Certificate.new(args[:public_cert])
-      @environment = args[:environment]
+      @vault = args[:vault]
+      @environment = args[:environment] || :integration
+      @commerce_code = args[:commerce_code]
 
-      self.class.client(wsdl: wsdl_path, log: args[:log], logger: WebpayRails.logger)
-    end
-
-    def init_transaction(commerce_code, amount, buy_order, session_id, return_url, final_url)
-      request = client.build_request(:init_transaction, message: {
-        wsInitTransactionInput: {
-          wSTransactionType: 'TR_NORMAL_WS',
-          buyOrder: buy_order,
-          sessionId: session_id,
-          returnURL: return_url,
-          finalURL: final_url,
-          transactionDetails: {
-            amount: amount,
-            commerceCode: commerce_code,
-            buyOrder: buy_order
-          }
-        }
-      })
-
-      call(request, :init_transaction)
-    end
-
-    def get_transaction_result(token)
-      request = client.build_request(:get_transaction_result, message: {
-        tokenInput: token
-      })
+      raise WebpayRails::MissingCommerceCode unless @commerce_code
 
-      call(request, :get_transaction_result)
-    end
-
-    def acknowledge_transaction(token)
-      request = client.build_request(:acknowledge_transaction, message: {
-        tokenInput: token
-      })
+      unless valid_environments.include? @environment
+        raise WebpayRails::InvalidEnvironment
+      end
 
-      call(request, :acknowledge_transaction)
+      self.class.client(wsdl: wsdl_path, log: args[:log] || true,
+                        logger: WebpayRails.logger)
     end
 
-  private
+    private
 
     def call(request, operation)
       signed_document = sign_xml(request)
 
-      client.call(operation) do
+      response = client.call(operation) do
         xml signed_document.to_xml(save_with: 0)
       end
+
+      verify_response(response, operation)
+    rescue Savon::SOAPFault => error
+      raise WebpayRails::RequestFailed.new(operation, error)
     end
 
     def sign_xml(input_xml)
@@ -63,8 +39,8 @@ module WebpayRails
 
       signer = Signer.new(xml)
 
-      signer.cert = @public_cert
-      signer.private_key = @private_key
+      signer.cert = @vault.public_cert
+      signer.private_key = @vault.private_key
 
       signer.document.xpath('//soapenv:Body', { soapenv: 'http://schemas.xmlsoap.org/soap/envelope/' }).each do |node|
         signer.digest!(node)
@@ -75,7 +51,7 @@ module WebpayRails
 
       document = Nokogiri::XML(signed_xml)
       x509data = document.at_xpath('//*[local-name()=\'X509Data\']')
-      new_data = x509data.clone()
+      new_data = x509data.clone
       new_data.set_attribute('xmlns:ds', 'http://www.w3.org/2000/09/xmldsig#')
 
       n = Nokogiri::XML::Node.new('wsse:SecurityTokenReference', document)
@@ -85,17 +61,18 @@ module WebpayRails
       document
     end
 
-    def wsdl_path
-      case @environment
-      when :production
-        'https://webpay3g.transbank.cl/WSWebpayTransaction/cxf/WSWebpayService?wsdl'
-      when :certification
-        'https://webpay3gint.transbank.cl/WSWebpayTransaction/cxf/WSWebpayService?wsdl'
-      when :integration
-        'https://webpay3gint.transbank.cl/WSWebpayTransaction/cxf/WSWebpayService?wsdl'
+    def verify_response(response, operation)
+      raise(WebpayRails::InvalidResponse, operation) if response.blank?
+
+      if WebpayRails::Verifier.verify(response, @vault.webpay_cert)
+        response
       else
-        raise WebpayRails::InvalidEnvironment
+        raise WebpayRails::InvalidCertificate, operation
       end
     end
+
+    def valid_environments
+      [:production, :certification, :integration]
+    end
   end
 end