starkbank 2.2.1 → 2.6.0

data/lib/invoice/payment.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative('../utils/sub_resource')
+require_relative('invoice')
+
+module StarkBank
+    class Invoice
+        # # Payment object
+        #
+        # When an Invoice is paid, its InvoicePayment sub-resource will become available.
+        # It carries all the available information about the invoice payment.
+        #
+        # ## Attributes (return-only):
+        # - amount [long]: amount in cents that was paid. ex: 1234 (= R$ 12.34)
+        # - name [string]: payer full name. ex: 'Anthony Edward Stark'
+        # - tax_id [string]: payer tax ID (CPF or CNPJ). ex: '20.018.183/0001-80'
+        # - bank_code [string]: code of the payer bank institution in Brazil. ex: '20018183'
+        # - branch_code [string]: payer bank account branch. ex: '1357-9'
+        # - account_number [string]: payer bank account number. ex: '876543-2'
+        # - account_type [string]: payer bank account type. ex: 'checking', 'savings', 'salary' or 'payment'
+        # - end_to_end_id [string]: central bank's unique transaction ID. ex: 'E79457883202101262140HHX553UPqeq'
+        # - method [string]: payment method that was used. ex: 'pix'
+        class Payment < StarkBank::Utils::SubResource
+            attr_reader :name, :tax_id, :bank_code, :branch_code, :account_number, :account_type, :amount, :end_to_end_id, :method
+            def initialize(name:, tax_id:, bank_code:, branch_code:, account_number:, account_type:, amount:, end_to_end_id:, method:)
+                @name = name
+                @tax_id = tax_id
+                @bank_code = bank_code
+                @branch_code = branch_code
+                @account_number = account_number
+                @account_type = account_type
+                @amount = amount
+                @end_to_end_id = end_to_end_id
+                @method = method
+            end
+
+            def self.resource
+                {
+                    sub_resource_name: 'Payment',
+                    sub_resource_maker: proc { |json|
+                        Payment.new(
+                            name: json['name'],
+                            tax_id: json['tax_id'],
+                            bank_code: json['bank_code'],
+                            branch_code: json['branch_code'],
+                            account_number: json['account_number'],
+                            account_type: json['account_type'],
+                            amount: json['amount'],
+                            end_to_end_id: json['end_to_end_id'],
+                            method: json['method']
+                        )
+                    }
+                }
+            end
+        end
+    end
+end

data/lib/payment_preview/boleto_preview.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative('../utils/sub_resource')
+require_relative('../utils/rest')
+require_relative('../utils/checks')
+
+module StarkBank
+  class PaymentPreview
+    # # BoletoPreview object
+    #
+    # A BoletoPreview is used to get information from a Boleto payment you received before confirming the payment.
+    #
+    # ## Attributes (return-only):
+    # - status [string]: current boleto status. ex: 'active', 'expired' or 'inactive'
+    # - amount [int]: final amount to be paid. ex: 23456 (= R$ 234.56)
+    # - discount_amount [int]: discount amount to be paid. ex: 23456 (= R$ 234.56)
+    # - fine_amount [int]: fine amount to be paid. ex: 23456 (= R$ 234.56)
+    # - interest_amount [int]: interest amount to be paid. ex: 23456 (= R$ 234.56)
+    # - due [DateTime or string]: Boleto due date. ex: '2020-04-30'
+    # - expiration [DateTime or string]: Boleto expiration date. ex: '2020-04-30'
+    # - name [string]: beneficiary full name. ex: 'Anthony Edward Stark'
+    # - tax_id [string]: beneficiary tax ID (CPF or CNPJ). ex: '20.018.183/0001-80'
+    # - receiver_name [string]: receiver (Sacador Avalista) full name. ex: 'Anthony Edward Stark'
+    # - receiver_tax_id [string]: receiver (Sacador Avalista) tax ID (CPF or CNPJ). ex: '20.018.183/0001-80'
+    # - payer_name [string]: payer full name. ex: 'Anthony Edward Stark'
+    # - payer_tax_id [string]: payer tax ID (CPF or CNPJ). ex: '20.018.183/0001-80'
+    # - line [string]: Number sequence that identifies the payment. ex: '34191.09008 63571.277308 71444.640008 5 81960000000062'
+    # - bar_code [string]: Bar code number that identifies the payment. ex: '34195819600000000621090063571277307144464000'
+    class BoletoPreview < StarkBank::Utils::SubResource
+      attr_reader :status, :amount, :discount_amount, :fine_amount, :interest_amount, :due, :expiration, :name, :tax_id, :receiver_name, :receiver_tax_id, :payer_name, :payer_tax_id, :line, :bar_code
+      def initialize(status:, amount:, discount_amount:, fine_amount:, interest_amount:, due:, expiration:, name:, tax_id:, receiver_name:, receiver_tax_id:, payer_name:, payer_tax_id:, line:, bar_code:)
+        @status = status
+        @amount = amount
+        @discount_amount = discount_amount
+        @fine_amount = fine_amount
+        @interest_amount = interest_amount
+        @due = StarkBank::Utils::Checks.check_datetime(due)
+        @expiration = StarkBank::Utils::Checks.check_datetime(expiration)
+        @name = name
+        @tax_id = tax_id
+        @receiver_name = receiver_name
+        @receiver_tax_id = receiver_tax_id
+        @payer_name = payer_name
+        @payer_tax_id = payer_tax_id
+        @line = line
+        @bar_code = bar_code
+      end
+
+      def self.resource
+        {
+          resource_name: 'BoletoPreview',
+          resource_maker: proc { |json|
+            BoletoPreview.new(
+              status: json['status'],
+              amount: json['amount'],
+              discount_amount: json['discount_amount'],
+              fine_amount: json['fine_amount'],
+              interest_amount: json['interest_amount'],
+              due: json['due'],
+              expiration: json['expiration'],
+              name: json['name'],
+              tax_id: json['tax_id'],
+              receiver_name: json['receiver_name'],
+              receiver_tax_id: json['receiver_tax_id'],
+              payer_name: json['payer_name'],
+              payer_tax_id: json['payer_tax_id'],
+              line: json['line'],
+              bar_code: json['bar_code'],
+            )
+          }
+        }
+      end
+    end
+  end
+end

data/lib/payment_preview/brcode_preview.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative('../utils/sub_resource')
+require_relative('../utils/rest')
+require_relative('../utils/checks')
+
+module StarkBank
+  class PaymentPreview
+    # # BrcodePreview object
+    #
+    # A BrcodePreview is used to get information from a BR Code you received before confirming the payment.
+    #
+    # ## Attributes (return-only):
+    # - status [string]: Payment status. ex: 'active', 'paid', 'canceled' or 'unknown'
+    # - name [string]: Payment receiver name. ex: 'Tony Stark'
+    # - tax_id [string]: Payment receiver tax ID. ex: '012.345.678-90'
+    # - bank_code [string]: Payment receiver bank code. ex: '20018183'
+    # - branch_code [string]: Payment receiver branch code. ex: '0001'
+    # - account_number [string]: Payment receiver account number. ex: '1234567'
+    # - account_type [string]: Payment receiver account type. ex: 'checking'
+    # - allow_change [bool]: If True, the payment is able to receive amounts that are different from the nominal one. ex: True or False
+    # - amount [integer]: Value in cents that this payment is expecting to receive. If 0, any value is accepted. ex: 123 (= R$1,23)
+    # - nominal_amount [integer]: Original value in cents that this payment was expecting to receive without the discounts, fines, etc.. If 0, any value is accepted. ex: 123 (= R$1,23)
+    # - interest_amount [integer]: Current interest value in cents that this payment is charging. If 0, any value is accepted. ex: 123 (= R$1,23)
+    # - fine_amount [integer]: Current fine value in cents that this payment is charging. ex: 123 (= R$1,23)
+    # - reduction_amount [integer]: Current value reduction value in cents that this payment is expecting. ex: 123 (= R$1,23)
+    # - discount_amount [integer]: Current discount value in cents that this payment is expecting. ex: 123 (= R$1,23)
+    # - reconciliation_id [string]: Reconciliation ID linked to this payment. ex: 'txId', 'payment-123'
+    class BrcodePreview < StarkBank::Utils::SubResource
+      attr_reader :status, :name, :tax_id, :bank_code, :branch_code, :account_number, :account_type, :allow_change, :amount, :nominal_amount, :interest_amount, :fine_amount, :reduction_amount, :discount_amount, :reconciliation_id
+      def initialize(status:, name:, tax_id:, bank_code:, branch_code:, account_number:, account_type:, allow_change:, amount:, nominal_amount:, interest_amount:, fine_amount:, reduction_amount:, discount_amount:, reconciliation_id:)
+        @status = status
+        @name = name
+        @tax_id = tax_id
+        @bank_code = bank_code
+        @branch_code = branch_code
+        @account_number = account_number
+        @account_type = account_type
+        @allow_change = allow_change
+        @amount = amount
+        @nominal_amount = nominal_amount
+        @interest_amount = interest_amount
+        @fine_amount = fine_amount
+        @reduction_amount = reduction_amount
+        @discount_amount = discount_amount
+        @reconciliation_id = reconciliation_id
+      end
+
+      def self.resource
+        {
+          resource_name: 'BrcodePreview',
+          resource_maker: proc { |json|
+            BrcodePreview.new(
+              status: json['status'],
+              name: json['name'],
+              tax_id: json['tax_id'],
+              bank_code: json['bank_code'],
+              branch_code: json['branch_code'],
+              account_number: json['account_number'],
+              account_type: json['account_type'],
+              allow_change: json['allow_change'],
+              amount: json['amount'],
+              nominal_amount: json['nominal_amount'],
+              interest_amount: json['interest_amount'],
+              fine_amount: json['fine_amount'],
+              reduction_amount: json['reduction_amount'],
+              discount_amount: json['discount_amount'],
+              reconciliation_id: json['reconciliation_id']
+            )
+          }
+        }
+      end
+    end
+  end
+end

data/lib/payment_preview/payment_preview.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative('../utils/resource')
+require_relative('../utils/rest')
+require_relative('../utils/checks')
+
+module StarkBank
+  # # PaymentPreview object
+  #
+  # A PaymentPreview is used to get information from a payment code before confirming the payment.
+  # This resource can be used to preview BR Codes and bar codes of boleto, tax and utility payments
+  #
+  # ## Attributes (return-only):
+  # - id [string]: Main identification of the payment. This should be the BR Code for Pix payments and lines or bar codes for payment slips. ex: '34191.09008 63571.277308 71444.640008 5 81960000000062', '00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff817b5a8520400005303986540510.005802BR5908T'Challa6009Sao Paulo62090505123456304B14A'
+  # - scheduled [DateTime or string]: intended payment date. Right now, this parameter only has effect on BrcodePreviews. ex: '2020-04-30'
+  # - type [string]: Payment type. ex: 'brcode-payment', 'boleto-payment', 'utility-payment' or 'tax-payment'
+  # - payment [BrcodePreview, BoletoPreview, UtilityPreview or TaxPreview]: Information preview of the informed payment.
+  class PaymentPreview < StarkBank::Utils::Resource
+    attr_reader :id, :scheduled, :type, :payment
+    def initialize(id: nil, scheduled: nil, type: nil, payment: nil)
+      super(id)
+      @scheduled = StarkBank::Utils::Checks.check_date(scheduled)
+      @type = type
+      @payment = payment
+      return if type.nil?
+
+      resource = {
+        'brcode-payment': StarkBank::PaymentPreview::BrcodePreview.resource,
+        'boleto-payment': StarkBank::PaymentPreview::BoletoPreview.resource,
+        'tax-payment': StarkBank::PaymentPreview::TaxPreview.resource,
+        'utility-payment': StarkBank::PaymentPreview::UtilityPreview.resource
+      }[type.to_sym]
+
+      @payment = StarkBank::Utils::API.from_api_json(resource[:resource_maker], payment) unless resource.nil?
+    end
+
+    # # Create PaymentPreviews
+    #
+    # Send a list of PaymentPreviews objects for processing in the Stark Bank API
+    #
+    # ## Parameters (required):
+    # - previews [list of PaymentPreviews objects]: list of PaymentPreviews objects to be created in the API
+    #
+    # ## Parameters (optional):
+    # - user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call
+    #
+    # ## Return:
+    # - list of PaymentPreviews objects with updated attributes
+    def self.create(previews, user: nil)
+      StarkBank::Utils::Rest.post(entities: previews, user: user, **resource)
+    end
+
+    def self.resource
+      {
+        resource_name: 'PaymentPreview',
+        resource_maker: proc { |json|
+          PaymentPreview.new(
+            id: json['id'],
+            scheduled: json['scheduled'],
+            type: json['type'],
+            payment: json['payment']
+          )
+        }
+      }
+    end
+  end
+end

data/lib/payment_preview/tax_preview.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative('../utils/sub_resource')
+require_relative('../utils/rest')
+require_relative('../utils/checks')
+
+module StarkBank
+  class PaymentPreview
+    # # TaxPreview object
+    #
+    # A TaxPreview is used to get information from a Tax Payment you received before confirming the payment.
+    #
+    # ## Attributes (return-only):
+    # - amount [int]: final amount to be paid. ex: 23456 (= R$ 234.56)
+    # - name [string]: beneficiary full name. ex: "Iron Throne"
+    # - description [string]: tax payment description. ex: "ISS Payment - Iron Throne"
+    # - line [string]: Number sequence that identifies the payment. ex: "85660000006 6 67940064007 5 41190025511 7 00010601813 8"
+    # - bar_code [string]: Bar code number that identifies the payment. ex: "85660000006679400640074119002551100010601813"
+    class TaxPreview < StarkBank::Utils::SubResource
+      attr_reader :amount, :name, :description, :line, :bar_code
+      def initialize(amount:, name:, description:, line:, bar_code:)
+        @amount = amount
+        @name = name
+        @description = description
+        @line = line
+        @bar_code = bar_code
+      end
+
+      def self.resource
+        {
+          resource_name: 'TaxPreview',
+          resource_maker: proc { |json|
+            TaxPreview.new(
+              amount: json['amount'],
+              name: json['name'],
+              description: json['description'],
+              line: json['line'],
+              bar_code: json['bar_code']
+            )
+          }
+        }
+      end
+    end
+  end
+end

data/lib/payment_preview/utility_preview.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative('../utils/sub_resource')
+require_relative('../utils/rest')
+require_relative('../utils/checks')
+
+module StarkBank
+  class PaymentPreview
+    # # UtilityPreview object
+    #
+    # A UtilityPreview is used to get information from a Utility Payment you received before confirming the payment.
+    #
+    # ## Attributes (return-only):
+    # - amount [int]: final amount to be paid. ex: 23456 (= R$ 234.56)
+    # - name [string]: beneficiary full name. ex: "Light Company"
+    # - description [string]: utility payment description. ex: "Utility Payment - Light Company"
+    # - line [string]: Number sequence that identifies the payment. ex: "82660000002 8 44361143007 7 41190025511 7 00010601813 8"
+    # - bar_code [string]: Bar code number that identifies the payment. ex: "82660000002443611430074119002551100010601813"
+    class UtilityPreview < StarkBank::Utils::SubResource
+      attr_reader :amount, :name, :description, :line, :bar_code
+      def initialize(amount:, name:, description:, line:, bar_code:)
+        @amount = amount
+        @name = name
+        @description = description
+        @line = line
+        @bar_code = bar_code
+      end
+
+      def self.resource
+        {
+          resource_name: 'UtilityPreview',
+          resource_maker: proc { |json|
+            UtilityPreview.new(
+              amount: json['amount'],
+              name: json['name'],
+              description: json['description'],
+              line: json['line'],
+              bar_code: json['bar_code']
+            )
+          }
+        }
+      end
+    end
+  end
+end

data/lib/payment_request/payment_request.rb

@@ -7,17 +7,17 @@ require_relative('../utils/checks')
 module StarkBank
   # # PaymentRequest object
   # A PaymentRequest is an indirect request to access a specific cash-out service
-  # (such as Transfer, BoletoPayments, etc.) which goes through the cost center
+  # (such as Transfer, BrcodePayments, etc.) which goes through the cost center
   #  approval flow on our website. To emit a PaymentRequest, you must direct it to
   #  a specific cost center by its ID, which can be retrieved on our website at the
   #  cost center page.
   #
   # ## Parameters (required):
   # - center_id [String]: target cost center ID. ex: '5656565656565656'
-  # - payment [Transfer, BoletoPayment, UtilityPayment, Transaction or dictionary]: payment entity that should be approved and executed.
+  # - payment [Transfer, BrcodePayment, BoletoPayment, UtilityPayment, Transaction or dictionary]: payment entity that should be approved and executed.
   #
   # ## Parameters (optional):
-  # - type [String]: payment type, inferred from the payment parameter if it is not a dictionary. ex: 'transfer', 'boleto-payment'
+  # - type [String]: payment type, inferred from the payment parameter if it is not a dictionary. ex: 'transfer', 'brcode-payment'
   # - due [Date, DateTime, Time or string]: Payment target date in ISO format. ex: 2020-12-31
   # - tags [list of strings]: list of strings for tagging
   #
@@ -53,7 +53,7 @@ module StarkBank
     #
     # ## Parameters
     # - payment_requests [list of PaymentRequest objects]: list of PaymentRequest objects to be created in the API
-    # - user [Project object]: Project object. Not necessary if StarkBank.User.Default was set before function call
+    # - user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call
     #
     # ## Return
     # - list of PaymentRequest objects with updated attributes
@@ -70,21 +70,57 @@ module StarkBank
     # - center_id [string]: target cost center ID. ex: '5656565656565656'
     # ## Parameters (optional):
     # - limit [integer, default nil]: maximum number of objects to be retrieved. Unlimited if nil. ex: 35
-    # - after [Date , DateTime, Time or string, default nil] date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)
-    # - before [Date, DateTime, Time or string, default nil] date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)
+    # - after [Date, DateTime, Time or string, default nil]: date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)
+    # - before [Date, DateTime, Time or string, default nil]: date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)
     # - status [string, default '-created']: sort order considered in response. Valid options are '-created' or '-due'.
-    # - type [string, default nil]: payment type, inferred from the payment parameter if it is not a dictionary. ex: 'transfer', 'boleto-payment'
+    # - type [string, default nil]: payment type, inferred from the payment parameter if it is not a dictionary. ex: 'transfer', 'brcode-payment'
     # - sort [list of strings, default nil]: tags to filter retrieved objects. ex: ['tony', 'stark']
     # - tags [list of strings, default nil]: tags to filter retrieved objects. ex: ['tony', 'stark']
     # - ids [list of strings, default nil]: list of ids to filter retrieved objects. ex: ['5656565656565656', '4545454545454545']
-    # - user [Project object, default nil]: Project object. Not necessary if StarkBank.user was set before function call
+    # - user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call
     #
     # ## Return:
     # - generator of PaymentRequest objects with updated attributes
     def self.query(center_id:, limit: nil, after: nil, before: nil, status: nil, type: nil, sort: nil, tags: nil, ids: nil, user: nil)
       after = StarkBank::Utils::Checks.check_date(after)
       before = StarkBank::Utils::Checks.check_date(before)
-      StarkBank::Utils::Rest.get_list(
+      StarkBank::Utils::Rest.get_stream(
+        center_id: center_id,
+        limit: limit,
+        after: after,
+        before: before,
+        status: status,
+        type: type,
+        sort: sort,
+        tags: tags,
+        ids: ids,
+        user: user,
+        **resource
+      )
+    end
+
+    # # Retrieve paged PaymentRequests
+    #
+    # Receive a list of up to 100 PaymentRequest objects previously created in the Stark Bank API and the cursor to the next page.
+    # Use this function instead of query if you want to manually page your requests.
+    #
+    # ## Parameters (optional):
+    # - cursor [string, default nil]: cursor returned on the previous page function call
+    # - limit [integer, default nil]: maximum number of objects to be retrieved. Unlimited if nil. ex: 35
+    # - after [Date, DateTime, Time or string, default nil]: date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)
+    # - before [Date, DateTime, Time or string, default nil]: date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)
+    # - status [string, default nil]: filter for status of retrieved objects. ex: 'paid' or 'registered'
+    # - tags [list of strings, default nil]: tags to filter retrieved objects. ex: ['tony', 'stark']
+    # - ids [list of strings, default nil]: list of ids to filter retrieved objects. ex: ['5656565656565656', '4545454545454545']
+    # - user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call
+    #
+    # ## Return:
+    # - list of PaymentRequest objects with updated attributes and cursor to retrieve the next page of PaymentRequest objects
+    def self.page(cursor: nil, center_id:, limit: nil, after: nil, before: nil, status: nil, type: nil, sort: nil, tags: nil, ids: nil, user: nil)
+      after = StarkBank::Utils::Checks.check_date(after)
+      before = StarkBank::Utils::Checks.check_date(before)
+      return StarkBank::Utils::Rest.get_page(
+        cursor: cursor,
         center_id: center_id,
         limit: limit,
         after: after,
@@ -102,16 +138,22 @@ module StarkBank
     def parse_payment(payment:, type:)
       return [payment, 'transfer'] if payment.is_a?(StarkBank::Transfer)
       return [payment, 'transaction'] if payment.is_a?(StarkBank::Transaction)
+      return [payment, 'brcode-payment'] if payment.is_a?(StarkBank::BrcodePayment)
       return [payment, 'boleto-payment'] if payment.is_a?(StarkBank::BoletoPayment)
       return [payment, 'utility-payment'] if payment.is_a?(StarkBank::UtilityPayment)
+      return [payment, 'tax-payment'] if payment.is_a?(StarkBank::TaxPayment)
+      return [payment, 'darf-payment'] if payment.is_a?(StarkBank::DarfPayment)
 
-      raise(Exception('Payment must either be a Transfer, a Transaction, a BoletoPayment, a UtilityPayment or a hash.')) unless payment.is_a?(Hash)
+      raise(Exception('Payment must either be a Transfer, a Transaction, a BrcodePayment, BoletoPayment, a UtilityPayment, a TaxPayment, a DarfPayment or a hash.')) unless payment.is_a?(Hash)
 
       resource = {
         'transfer': StarkBank::Transfer.resource,
         'transaction': StarkBank::Transaction.resource,
+        'brcode-payment': StarkBank::BrcodePayment.resource,
         'boleto-payment': StarkBank::BoletoPayment.resource,
-        'utility-payment': StarkBank::UtilityPayment.resource
+        'utility-payment': StarkBank::UtilityPayment.resource,
+        'tax-payment': StarkBank::TaxPayment.resource,
+        'darf-payment': StarkBank::DarfPayment.resource
       }[type.to_sym]
 
       payment = StarkBank::Utils::API.from_api_json(resource[:resource_maker], payment) unless resource.nil?