pagseguro-oficial 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a980612b48482830bbc795d21b5e9b42c93fa734
-  data.tar.gz: d6d5239ec8867b09b90f1c916e57caeda56542f6
+  metadata.gz: 88901e2177d4f7a176e193f4fb6f21b62b7120f2
+  data.tar.gz: b025c4d828d375096fb7ee9defcca8c725c75e1a
 SHA512:
-  metadata.gz: ecb011aceae73b1cc57da82e3ab009b17608c07304b776775cea35f00fa8dfd4ef95139ecf164c22ab3bf268cfeafa9c7251b57d257c89c0e5a330ba5ef393e7
-  data.tar.gz: 9bd96ab418caf1824bdcecf0b9301ebf1d5440eeb7fc9bedec9a1fb638a788e9c7b897b92fcde4cc39c3f95253d5d637f454fa86641a16d0ba9a0a92f3c89342
+  metadata.gz: 1e6ae8a2ce4062e2c4108b39e32cfade79e2c973c2552cbc11d12f3a390c6a4a29442859525c95571757890f8c4d223099b1bc49e5ea51abe418218d12d5eac2
+  data.tar.gz: 356306e366dc20adc141362c205f051e48c7e0067dc67bb367b6d72a60993517a16976fbec1b83d2349685ec3ffae7ee9f305f9b8ba082edc3ee751d34f41296

data/CHANGELOG.md

@@ -1,4 +1,8 @@
-## Stable
+## Next release - 2.4.0
+
+- Estorno de transações
+- Cancelamento de transações
+- Consulta de histórico de status de transações
 
 2.3.0
 

data/README.md

@@ -12,7 +12,8 @@ A biblioteca PagSeguro em Ruby é um conjunto de classes de domínio que facilit
  - Consultar [transações por intervalo de datas] \(este serviço utiliza a versão **V3** da API)
  - Consultar [transações abandonadas] \(este serviço utiliza a versão **V2** da API\)
  - Receber [notificações] \(este serviço utiliza a versão **V3** da API\)
-
+ - Enviar estorno de transações \(este serviço utiliza a versão **V2** da API\)
+  - Cancelar transações \(este serviço utiliza a versão **V2** da API\)
 
 ## Requisitos
 
@@ -25,7 +26,7 @@ A biblioteca PagSeguro em Ruby é um conjunto de classes de domínio que facilit
  - Adicione a biblioteca ao seu Gemfile.
 
 ```ruby
-gem "pagseguro-oficial", "~> 2.3.0"
+gem "pagseguro-oficial", "~> 2.4.0"
 ```
 
  - Execute o comando `bundle install`.
@@ -178,6 +179,21 @@ while report.next_page?
 end
 ```
 
+### Histórico de status de transações
+
+É possível consultar o histórico de mudanças de status em transações
+
+```ruby
+response = PagSeguro::Transaction.find_status_history("transaction_code")
+
+response.each do |status|
+  puts "STATUS:"
+  puts "  code: #{status.code}"
+  puts "  date: #{status.date}"
+  puts "  notification_code: #{status.notification_code}"
+end
+```
+
 ### Consultar opções de parcelamento
 
 Você pode consultar as opções de parcelamento para um determinado valor.
@@ -219,6 +235,42 @@ Em seguida, acesse o link para confirmar as autorizações
   response.url
 ```
 
+### Estorno de Transações
+
+Você pode estornar pagamentos que as transações estiverem com status: Paga (3), Disponível (4), Em disputa (5).
+
+```ruby
+  refund = PagSeguro::Refund.new
+  refund.transaction_code = "D5D5BE444148407891E497B421975599"
+
+  response = refund.register
+
+  if response.errors.any?
+    puts response.errors.join("\n")
+  else
+    puts "=> REFUND RESPONSE"
+    puts response.result
+  end
+```
+
+### Cancelamento de Transações
+
+Você pode cancelar transações que estiverem com status: Aguardando pagamento ou Em análise.
+
+```ruby
+  cancellation = PagSeguro::TransactionCancellation.new
+  cancellation.transaction_code = "AFB8FCF29496401681257C1ECE3A98FF"
+
+  cancellation.register
+
+  if cancellation.errors.any?
+    puts cancellation.errors.join("\n")
+  else
+    puts "=> CANCELLATION RESPONSE"
+    puts cancellation.result
+  end
+```
+
 ## API
 
 ### PagSeguro::PaymentRequest (utiliza versão V2)

data/examples/{authorization.rb → authorization/authorization.rb}

@@ -1,4 +1,4 @@
-require_relative "boot"
+require_relative "../boot"
 
 # Authorization
 #

data/examples/{authorization_by_code.rb → authorization/authorization_by_code.rb}

@@ -1,4 +1,4 @@
-require_relative 'boot'
+require_relative "../boot"
 
 # Authorization by code
 #

data/examples/{authorization_by_notification_code.rb → authorization/authorization_by_notification_code.rb}

@@ -1,4 +1,4 @@
-require_relative 'boot'
+require_relative "../boot"
 
 # Authorization by notification code
 #

data/examples/refund.rb

@@ -0,0 +1,25 @@
+require_relative "boot"
+
+# Refund
+#
+# You need:
+#   - set your AccountCredentials (EMAIL, TOKEN) in the application config
+#   - set transaction code
+#   - set value (optional)
+#
+# P.S: See the boot file example for more details
+
+refund = PagSeguro::Refund.new
+refund.transaction_code = "D5D5BE444148407891E497B421975599"
+
+# Partial refund
+# refund.value = 400.00
+
+response = refund.register
+
+if response.errors.any?
+  puts response.errors.join("\n")
+else
+  puts "=> REFUND RESPONSE"
+  puts response.result
+end

data/examples/{abandoned_transactions.rb → transaction/abandoned_transactions.rb}

@@ -1,5 +1,5 @@
-require_relative "boot"
 require "active_support/all"
+require_relative "../boot"
 
 # Abandoned Transactions
 #

data/examples/{boleto_transaction_request.rb → transaction/boleto_transaction_request.rb}

@@ -1,4 +1,4 @@
-require_relative "boot"
+require_relative "../boot"
 
 # Credit card transaction request
 #

data/examples/{credit_card_transaction_request.rb → transaction/credit_card_transaction_request.rb}

@@ -1,4 +1,4 @@
-require_relative "boot"
+require_relative "../boot"
 
 # Credit card transaction request
 #

data/examples/{invalid_transaction_by_notification_code.rb → transaction/invalid_transaction_by_notification_code.rb}

@@ -1,4 +1,4 @@
-require_relative "boot"
+require_relative "../boot"
 
 # Invalid transaction by notification code
 #

data/examples/{online_debit_transaction.rb → transaction/online_debit_transaction.rb}

@@ -1,4 +1,4 @@
-require_relative "boot"
+require_relative "../boot"
 
 # Credit card transaction request
 #

data/examples/{transaction_by_code.rb → transaction/transaction_by_code.rb}

@@ -1,4 +1,4 @@
-require_relative "boot"
+require_relative "../boot"
 
 # Transaction by code
 #

data/examples/{transaction_by_notification_code.rb → transaction/transaction_by_notification_code.rb}

@@ -1,4 +1,4 @@
-require_relative "boot"
+require_relative "../boot"
 
 # Transaction by notification code
 #

data/examples/{transaction_by_reference.rb → transaction/transaction_by_reference.rb}

@@ -1,4 +1,4 @@
-require_relative 'boot'
+require_relative "../boot"
 
 # Transaction by reference
 #

data/examples/transaction/transaction_cancellation.rb

@@ -0,0 +1,19 @@
+require_relative "../boot"
+
+# Transaction cancellation
+#
+#   You need:
+#     - give TRANSACTION CODE to TransactionCancellation#transaction_code
+#     - set your AccountCredentials (EMAIL, TOKEN) in the application config (P.S.: See the boot file example)
+
+cancellation = PagSeguro::TransactionCancellation.new
+cancellation.transaction_code = "AFB8FCF29496401681257C1ECE3A98FF"
+
+cancellation.register
+
+if cancellation.errors.any?
+  puts cancellation.errors.join("\n")
+else
+  puts "=> CANCELLATION RESPONSE"
+  puts cancellation.result
+end

data/examples/transaction/transaction_status_history.rb

@@ -0,0 +1,22 @@
+require_relative "../boot"
+
+# Transaction status history
+#
+# You need to set your credentials in the application config
+#
+# P.S: See the boot file example for more details
+
+response = PagSeguro::Transaction.find_status_history("transaction_code")
+
+puts response.inspect
+
+if response.errors.any?
+  puts response.errors.join("\n")
+else
+  response.each do |status|
+    puts "STATUS:"
+    puts "  code: #{status.code}"
+    puts "  date: #{status.date}"
+    puts "  notification_code: #{status.notification_code}"
+  end
+end

data/examples/{transactions_by_date.rb → transaction/transactions_by_date.rb}

@@ -1,4 +1,4 @@
-require_relative "boot"
+require_relative "../boot"
 require "active_support/all"
 
 # Transactions by date

data/lib/pagseguro/installment.rb

@@ -39,5 +39,19 @@ module PagSeguro
     def self.api_version
       'v2'
     end
+
+    def self.load_from_response(response)
+      if response.success? and response.xml?
+        Nokogiri::XML(response.body).css("installments > installment").map do |node|
+          load_from_xml(node)
+        end
+      else
+        Response.new Errors.new(response)
+      end
+    end
+
+    def self.load_from_xml(xml)
+      new Serializer.new(xml).serialize
+    end
   end
 end

data/lib/pagseguro/payment_request/serializer.rb

@@ -9,87 +9,80 @@ module PagSeguro
       end
 
       def to_params
-        params[:credentials] = payment_request.credentials if payment_request.credentials
-        params[:receiverEmail] = PagSeguro.receiver_email
-        params[:currency] = payment_request.currency
-        params[:reference] = payment_request.reference
-        params[:extraAmount] = to_amount(payment_request.extra_amount)
-        params[:redirectURL] = payment_request.redirect_url
-        params[:notificationURL] = payment_request.notification_url
-        params[:abandonURL] = payment_request.abandon_url
-        params[:maxUses] = payment_request.max_uses
-        params[:maxAge] = payment_request.max_age
-        payment_request.items.each.with_index(1) do |item, index|
-          serialize_item(item, index)
-        end
-
-        serialize_sender(payment_request.sender)
-        serialize_shipping(payment_request.shipping)
-        serialize_extra_params(payment_request.extra_params)
-
-        params.delete_if {|key, value| value.nil? }
-
-        params
+        {}.tap do |data|
+          data[:receiverEmail] = PagSeguro.receiver_email
+          data[:currency] = payment_request.currency
+          data[:reference] = payment_request.reference
+          data[:extraAmount] = to_amount(payment_request.extra_amount)
+          data[:redirectURL] = payment_request.redirect_url
+          data[:notificationURL] = payment_request.notification_url
+          data[:abandonURL] = payment_request.abandon_url
+          data[:maxUses] = payment_request.max_uses
+          data[:maxAge] = payment_request.max_age
+          payment_request.items.each_with_index do |item, index|
+            serialize_item(data, item, index.succ)
+          end
+
+          serialize_sender(data, payment_request.sender)
+          serialize_shipping(data, payment_request.shipping)
+          serialize_extra_params(data, payment_request.extra_params)
+        end.delete_if { |_, value| value.nil? }
       end
 
       private
-      def params
-        @params ||= {}
-      end
-
-      def serialize_item(item, index)
-        params["itemId#{index}"] = item.id
-        params["itemDescription#{index}"] = item.description
-        params["itemAmount#{index}"] = to_amount(item.amount)
-        params["itemQuantity#{index}"] = item.quantity
-        params["itemShippingCost#{index}"] = to_amount(item.shipping_cost)
-        params["itemWeight#{index}"] = item.weight if item.weight
+      def serialize_item(data, item, index)
+        data["itemId#{index}"] = item.id
+        data["itemDescription#{index}"] = item.description
+        data["itemAmount#{index}"] = to_amount(item.amount)
+        data["itemQuantity#{index}"] = item.quantity
+        data["itemShippingCost#{index}"] = to_amount(item.shipping_cost)
+        data["itemWeight#{index}"] = item.weight if item.weight
       end
 
-      def serialize_sender(sender)
+      def serialize_sender(data, sender)
         return unless sender
 
-        params[:senderEmail] =  sender.email
-        params[:senderName] = sender.name
-        params[:senderCPF] = sender.cpf
+        data[:senderEmail] =  sender.email
+        data[:senderName] = sender.name
+        data[:senderCPF] = sender.cpf
 
-        serialize_phone(sender.phone)
+        serialize_phone(data, sender.phone)
       end
 
-      def serialize_phone(phone)
+      def serialize_phone(data, phone)
         return unless phone
 
-        params[:senderAreaCode] = phone.area_code
-        params[:senderPhone] = phone.number
+        data[:senderAreaCode] = phone.area_code
+        data[:senderPhone] = phone.number
       end
 
-      def serialize_shipping(shipping)
+      def serialize_shipping(data, shipping)
         return unless shipping
 
-        params[:shippingType] = shipping.type_id
-        params[:shippingCost] = to_amount(shipping.cost)
+        data[:shippingType] = shipping.type_id
+        data[:shippingCost] = to_amount(shipping.cost)
 
-        serialize_address(shipping.address)
+        serialize_address(data, shipping.address)
       end
 
-      def serialize_address(address)
+      def serialize_address(data, address)
         return unless address
 
-        params[:shippingAddressCountry] = address.country
-        params[:shippingAddressState] = address.state
-        params[:shippingAddressCity] = address.city
-        params[:shippingAddressPostalCode] = address.postal_code
-        params[:shippingAddressDistrict] = address.district
-        params[:shippingAddressStreet] = address.street
-        params[:shippingAddressNumber] = address.number
-        params[:shippingAddressComplement] = address.complement
+        data[:shippingAddressCountry] = address.country
+        data[:shippingAddressState] = address.state
+        data[:shippingAddressCity] = address.city
+        data[:shippingAddressPostalCode] = address.postal_code
+        data[:shippingAddressDistrict] = address.district
+        data[:shippingAddressStreet] = address.street
+        data[:shippingAddressNumber] = address.number
+        data[:shippingAddressComplement] = address.complement
       end
 
-      def serialize_extra_params(extra_params)
+      def serialize_extra_params(data, extra_params)
         return unless extra_params
 
         extra_params.each do |extra_param|
-          params[extra_param.keys.first] = extra_param.values.first
+          data[extra_param.keys.first] = extra_param.values.first
         end
       end
 

data/lib/pagseguro/refund/request_serializer.rb

@@ -0,0 +1,24 @@
+module PagSeguro
+  class Refund
+    class RequestSerializer
+      # The refund that will be serialized.
+      attr_reader :refund
+
+      def initialize(refund)
+        @refund = refund
+      end
+
+      def to_params
+        {}.tap do |data|
+          data[:transactionCode] = refund.transaction_code
+          data[:refundValue] = to_amount(refund.value)
+        end.delete_if { |_, value| value.nil? }
+      end
+
+      private
+      def to_amount(amount)
+        "%.2f" % BigDecimal(amount.to_s).round(2).to_s("F") if amount
+      end
+    end
+  end
+end

data/lib/pagseguro/refund/response.rb

@@ -0,0 +1,33 @@
+module PagSeguro
+  class Refund
+    class Response
+      def initialize(response, refund)
+        @response = response
+        @refund = refund
+      end
+
+      def serialize
+        if success?
+          xml = Nokogiri::XML(response.body)
+          serialize = ResponseSerializer.new(xml).serialize
+          refund.update_attributes(serialize)
+        else
+          refund.errors.add(response)
+        end
+
+        refund
+      end
+
+      def success?
+        response.success? && response.xml?
+      end
+
+      private
+      # The request response.
+      attr_reader :response
+
+      # The refund object to return
+      attr_reader :refund
+    end
+  end
+end

data/lib/pagseguro/refund/response_serializer.rb

@@ -0,0 +1,17 @@
+module PagSeguro
+  class Refund
+    class ResponseSerializer
+      attr_reader :xml
+
+      def initialize(xml)
+        @xml = xml
+      end
+
+      def serialize
+        {}.tap do |data|
+          data[:result] = xml.css("> result").text
+        end
+      end
+    end
+  end
+end

data/lib/pagseguro/refund/serializer.rb

@@ -0,0 +1,24 @@
+module PagSeguro
+  class Refund
+    class Serializer
+      # The refund that will be serialized.
+      attr_reader :refund
+
+      def initialize(refund)
+        @refund = refund
+      end
+
+      def to_params
+        {}.tap do |data|
+          data[:transactionCode] = refund.transaction_code
+          data[:refundValue] = to_amount(refund.value)
+        end
+      end
+
+      private
+      def to_amount(amount)
+        "%.2f" % BigDecimal(amount.to_s).round(2).to_s("F") if amount
+      end
+    end
+  end
+end

data/lib/pagseguro/refund.rb

@@ -0,0 +1,44 @@
+module PagSeguro
+  class Refund
+    include Extensions::MassAssignment
+
+    # Set the transaction code.
+    # The transaction status must be: Paga (3), Disponível (4), Em disputa (5)
+    attr_accessor :transaction_code
+
+    # Set the refund value.
+    # Greater than 0.00 and less or equal than transaction value.
+    # If not informed, PagSeguro will assume the total transaction value.
+    attr_accessor :value
+
+    # Result from request.
+    attr_accessor :result
+
+    # PagSeguro::Errors object.
+    attr_reader :errors
+
+    # Calls the PagSeguro webservice and register the refund.
+    # Return PagSeguro::Refund.
+    def register
+      response_request = Request.post("transactions/refunds", api_version, params)
+      Response.new(response_request, self).serialize
+    end
+
+    def errors
+      @errors ||= Errors.new
+    end
+
+    def update_attributes(attrs)
+      attrs.map { |name, value| send("#{name}=", value) }
+    end
+
+    private
+    def api_version
+      "v2"
+    end
+
+    def params
+      RequestSerializer.new(self).to_params
+    end
+  end
+end

data/lib/pagseguro/transaction/collection.rb

@@ -0,0 +1,20 @@
+module PagSeguro
+  class Transaction
+    class Collection
+      extend Forwardable
+
+      def_delegators :@transactions, :each, :empty?, :any?
+
+      def transactions=(objects)
+        @transactions = objects
+      end
+
+      def errors
+        @errors ||= Errors.new
+      end
+
+      # PagSeguro::TransactionStatus instances.
+      attr_reader :transactions
+    end
+  end
+end

data/lib/pagseguro/transaction/response.rb

@@ -1,11 +1,44 @@
 module PagSeguro
   class Transaction
     class Response
-      # The response errors.
-      attr_reader :errors
+      def initialize(response, object)
+        @response = response
+        @object = object
+      end
+
+      def serialize
+        if success?
+          object.update_attributes(Serializer.new(xml).serialize)
+        else
+          object.errors.add response
+        end
+
+        object
+      end
+
+      def serialize_statuses
+        if success?
+          object.statuses = Serializer.new(xml).serialize_status_history
+        else
+          object.errors.add(response)
+        end
+
+        object
+      end
+
+      def success?
+        response.success? && response.xml?
+      end
+
+      # The http response.
+      attr_reader :response
+
+      # Set the that will receive errors or updates
+      attr_reader :object
 
-      def initialize(errors = Errors.new)
-        @errors = errors
+      private
+      def xml
+        Nokogiri::XML(response.body)
       end
     end
   end

data/lib/pagseguro/transaction/search.rb

@@ -27,7 +27,7 @@ module PagSeguro
     # call. Remember that this will perform an additional HTTP request.
     def transactions
       xml do |xml|
-        xml.css("transactionSearchResult transaction").map do |node|
+        xml.css("transactionSearchResult > transactions > transaction").map do |node|
           Transaction.load_from_xml(node)
         end
       end