starkinfra 0.5.2 → 0.7.0

data/lib/pix_pull_subscription/pix_pull_subscription.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require('starkcore')
+require_relative('../utils/rest')
+require_relative('../utils/parse')
+
+module StarkInfra
+  # # PixPullSubscription object
+  #
+  # A PixPullSubscription is a recurring Pix debit authorization. It defines the frequency, amount,
+  # and required payer authorizations for a series of Pix debits to be pulled from the sender by
+  # the receiver. Each cycle of an active subscription is triggered by a PixPullRequest whose
+  # subscription_id references the subscription's id.
+  #
+  # When you initialize a PixPullSubscription, the entity will not be automatically
+  # created in the Stark Infra API. The 'create' function sends the objects
+  # to the Stark Infra API and returns the list of created objects.
+  #
+  # ## Parameters (required):
+  # - bacen_id [string]: Central Bank's unique recurrency id. Identifies the subscription in the Pix infrastructure.
+  # - external_id [string]: url safe string that must be unique among all your Pix Pull Subscriptions. Used for idempotency. ex: 'my-internal-id-123456'
+  # - installment_start [DateTime or string]: start datetime of settlements allowed for this subscription. ex: '2020-10-28T17:59:26.249976+00:00'
+  # - interval [string]: cycle definition. Options: 'week', 'month', 'quarter', 'semester', 'year'
+  # - receiver_name [string]: receiver's full name. ex: 'Edward Stark'
+  # - receiver_tax_id [string]: receiver's tax ID (CPF or CNPJ) with or without formatting. ex: '01234567890' or '20.018.183/0001-80'
+  # - sender_account_number [string]: sender's bank account number. Use '-' before the verifier digit. ex: '876543-2'
+  # - sender_bank_code [string]: sender's bank institution code in Brazil. ex: '20018183'
+  # - sender_branch_code [string]: sender's bank account branch code. Use '-' in case there is a verifier digit. ex: '1357-9'
+  # - sender_tax_id [string]: sender's tax ID (CPF or CNPJ) with or without formatting. ex: '01234567890' or '20.018.183/0001-80'
+  # - type [string]: subscription journey type. Options: 'push', 'qrcode', 'qrcodeAndPayment', 'paymentAndOrQrcode'
+  #
+  # ## Parameters (conditionally-required):
+  # - amount [integer, default nil]: amount in cents charged every cycle. Required if the subscription has a fixed amount. ex: 1234 (= R$ 12.34)
+  # - amount_min_limit [integer, default nil]: floor value for the maximum amount the sender can set when approving. Required if the subscription has a variable amount. ex: 1234 (= R$ 12.34)
+  #
+  # ## Parameters (optional):
+  # - description [string, default nil]: additional information delivered to the sender. ex: 'Payment for service #1234'
+  # - due [DateTime or string, default nil]: due date for the sender's answer (approval or denial). ex: '2020-10-28T17:59:26.249976+00:00'
+  # - installment_end [DateTime or string, default nil]: end datetime of settlements allowed for this subscription. ex: '2020-10-28T17:59:26.249976+00:00'
+  # - receiver_bank_code [string, default nil]: receiver's bank institution code. Defaults to the workspace's primary institution when omitted. ex: '20018183'
+  # - reference_code [string, default nil]: commercial-relation identifier. May be a contract number, order id, or client code. ex: 'contract-123'
+  # - pull_retry_limit [integer, default nil]: max number of retries the receiver may issue for a single failed pull cycle. ex: 3
+  # - sender_city_code [string, default nil]: IBGE code of the payer's city. ex: '3550308'
+  # - sender_final_name [string, default nil]: final sender name when the sender differs from the originating institution. ex: 'Edward Stark'
+  # - sender_final_tax_id [string, default nil]: final sender tax ID. Same format rules as sender_tax_id. ex: '01234567890' or '20.018.183/0001-80'
+  # - tags [list of strings, default nil]: list of strings for tagging. ex: ['employees', 'monthly']
+  #
+  # ## Attributes (return-only):
+  # - id [string]: unique id returned when the PixPullSubscription is created. ex: '5656565656565656'
+  # - status [string]: current PixPullSubscription status. Options: 'created', 'pending', 'failed', 'denied', 'approved', 'active', 'expired', 'canceled'
+  # - flow [string]: direction of money flow. Options: 'in', 'out'
+  # - created [DateTime]: creation datetime for the PixPullSubscription. ex: DateTime.new(2020, 3, 10, 10, 30, 0, 0)
+  # - updated [DateTime]: latest update datetime for the PixPullSubscription. ex: DateTime.new(2020, 3, 10, 10, 30, 0, 0)
+  class PixPullSubscription < StarkCore::Utils::Resource
+    attr_reader :bacen_id, :external_id, :installment_start, :interval, :receiver_name, :receiver_tax_id,
+                :sender_account_number, :sender_bank_code, :sender_branch_code, :sender_tax_id, :type,
+                :amount, :amount_min_limit, :description, :due, :installment_end, :receiver_bank_code,
+                :reference_code, :pull_retry_limit, :sender_city_code, :sender_final_name, :sender_final_tax_id,
+                :tags, :id, :status, :flow, :created, :updated
+    def initialize(
+      bacen_id:, external_id:, installment_start:, interval:, receiver_name:, receiver_tax_id:,
+      sender_account_number:, sender_bank_code:, sender_branch_code:, sender_tax_id:, type:,
+      amount: nil, amount_min_limit: nil, description: nil, due: nil, installment_end: nil,
+      receiver_bank_code: nil, reference_code: nil, pull_retry_limit: nil, sender_city_code: nil,
+      sender_final_name: nil, sender_final_tax_id: nil, tags: nil, id: nil, status: nil, flow: nil,
+      created: nil, updated: nil
+    )
+      super(id)
+      @bacen_id = bacen_id
+      @external_id = external_id
+      @installment_start = StarkCore::Utils::Checks.check_datetime(installment_start)
+      @interval = interval
+      @receiver_name = receiver_name
+      @receiver_tax_id = receiver_tax_id
+      @sender_account_number = sender_account_number
+      @sender_bank_code = sender_bank_code
+      @sender_branch_code = sender_branch_code
+      @sender_tax_id = sender_tax_id
+      @type = type
+      @amount = amount
+      @amount_min_limit = amount_min_limit
+      @description = description
+      @due = StarkCore::Utils::Checks.check_datetime(due == '' ? nil : due)
+      @installment_end = StarkCore::Utils::Checks.check_datetime(installment_end == '' ? nil : installment_end)
+      @receiver_bank_code = receiver_bank_code
+      @reference_code = reference_code
+      @pull_retry_limit = pull_retry_limit
+      @sender_city_code = sender_city_code
+      @sender_final_name = sender_final_name
+      @sender_final_tax_id = sender_final_tax_id
+      @tags = tags
+      @status = status
+      @flow = flow
+      @created = StarkCore::Utils::Checks.check_datetime(created)
+      @updated = StarkCore::Utils::Checks.check_datetime(updated)
+    end
+
+    # # Create PixPullSubscriptions
+    #
+    # Send a list of PixPullSubscription objects for creation in the Stark Infra API
+    #
+    # ## Parameters (required):
+    # - subscriptions [list of PixPullSubscription objects]: list of PixPullSubscription objects to be created in the API
+    #
+    # ## Parameters (optional):
+    # - user [Organization/Project object, default nil]: Organization or Project object. Not necessary if StarkInfra.user was set before function call
+    #
+    # ## Return:
+    # - list of PixPullSubscription objects with updated attributes
+    def self.create(subscriptions, user: nil)
+      StarkInfra::Utils::Rest.post(entities: subscriptions, user: user, **resource)
+    end
+
+    # # Retrieve a specific PixPullSubscription
+    #
+    # Receive a single PixPullSubscription object previously created in the Stark Infra API by passing its id
+    #
+    # ## Parameters (required):
+    # - id [string]: object unique id. ex: '5656565656565656'
+    #
+    # ## Parameters (optional):
+    # - user [Organization/Project object, default nil]: Organization or Project object. Not necessary if StarkInfra.user was set before function call
+    #
+    # ## Return:
+    # - PixPullSubscription object with updated attributes
+    def self.get(id, user: nil)
+      StarkInfra::Utils::Rest.get_id(id: id, user: user, **resource)
+    end
+
+    # # Retrieve PixPullSubscriptions
+    #
+    # Receive a generator of PixPullSubscription objects previously created in the Stark Infra API
+    #
+    # ## Parameters (optional):
+    # - limit [integer, default nil]: maximum number of objects to be retrieved. Unlimited if nil. ex: 35
+    # - after [Date or string, default nil]: date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)
+    # - before [Date or string, default nil]: date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)
+    # - status [list of strings, default nil]: filter for status of retrieved objects. ex: ['active', 'canceled']
+    # - tags [list of strings, default nil]: tags to filter retrieved objects. ex: ['employees', 'monthly']
+    # - ids [list of strings, default nil]: list of ids to filter retrieved objects. ex: ['5656565656565656', '4545454545454545']
+    # - user [Organization/Project object, default nil]: Organization or Project object. Not necessary if StarkInfra.user was set before function call
+    #
+    # ## Return:
+    # - generator of PixPullSubscription objects with updated attributes
+    def self.query(limit: nil, after: nil, before: nil, status: nil, tags: nil, ids: nil, user: nil)
+      after = StarkCore::Utils::Checks.check_date(after)
+      before = StarkCore::Utils::Checks.check_date(before)
+      StarkInfra::Utils::Rest.get_stream(
+        limit: limit,
+        after: after,
+        before: before,
+        status: status,
+        tags: tags,
+        ids: ids,
+        user: user,
+        **resource
+      )
+    end
+
+    # # Retrieve paged PixPullSubscriptions
+    #
+    # Receive a list of up to 100 PixPullSubscription objects previously created in the Stark Infra API and the cursor to the next page.
+    # Use this function instead of query if you want to manually page your subscriptions.
+    #
+    # ## Parameters (optional):
+    # - cursor [string, default nil]: cursor returned on the previous page function call
+    # - limit [integer, default 100]: maximum number of objects to be retrieved. Max = 100. ex: 35
+    # - after [Date or string, default nil]: date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)
+    # - before [Date or string, default nil]: date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)
+    # - status [list of strings, default nil]: filter for status of retrieved objects. ex: ['active', 'canceled']
+    # - tags [list of strings, default nil]: tags to filter retrieved objects. ex: ['employees', 'monthly']
+    # - ids [list of strings, default nil]: list of ids to filter retrieved objects. ex: ['5656565656565656', '4545454545454545']
+    # - user [Organization/Project object, default nil]: Organization or Project object. Not necessary if StarkInfra.user was set before function call
+    #
+    # ## Return:
+    # - list of PixPullSubscription objects with updated attributes
+    # - cursor to retrieve the next page of PixPullSubscription objects
+    def self.page(cursor: nil, limit: nil, after: nil, before: nil, status: nil, tags: nil, ids: nil, user: nil)
+      after = StarkCore::Utils::Checks.check_date(after)
+      before = StarkCore::Utils::Checks.check_date(before)
+      StarkInfra::Utils::Rest.get_page(
+        cursor: cursor,
+        limit: limit,
+        after: after,
+        before: before,
+        status: status,
+        tags: tags,
+        ids: ids,
+        user: user,
+        **resource
+      )
+    end
+
+    # # Update PixPullSubscriptions
+    #
+    # A PixPullSubscription can be patched to approve, deny or activate it. As the payer (sender), you may set
+    # status to 'approved' or 'denied'. As the receiver, you may set status to 'active' once approved. When
+    # confirming (approving), include sender_city_code.
+    #
+    # ## Parameters (required):
+    # - id [string]: PixPullSubscription unique id. ex: '5656565656565656'
+    # - patch_data [hash]: hash containing the attributes to be updated. ex: { status: 'approved', sender_city_code: '3550308' }
+    #     ## Parameters (required):
+    #     - status [string]: new status of the Pix Subscription.
+    #     ## Parameters (conditionally-required):
+    #     - sender_city_code [string]: IBGE code of the payer's city. Required if you are confirming the subscription.
+    #     - reason [string]: reason why the PixPullSubscription is being patched. Options: 'invalidSenderAccountNumber', 'accountClosed', 'accountBlocked', 'invalidBranchCode', 'notRecognizedBySender', 'userRejected', 'notOffered'.
+    #
+    # ## Parameters (optional):
+    # - user [Organization/Project object, default nil]: Organization or Project object. Not necessary if StarkInfra.user was set before function call
+    #
+    # ## Return:
+    # - updated PixPullSubscription object
+    def self.update(id, patch_data: nil, user: nil)
+      patch_data ||= {}
+      StarkInfra::Utils::Rest.patch_id(id: id, user: user, **patch_data, **resource)
+    end
+
+    # # Cancel a PixPullSubscription entity
+    #
+    # Cancel a PixPullSubscription entity previously created in the Stark Infra API.
+    # The reason is sent as a query parameter, not in the request body.
+    #
+    # ## Parameters (required):
+    # - id [string]: PixPullSubscription unique id. ex: '5656565656565656'
+    # - reason [string, default nil]: reason for the cancellation. Options: 'accountClosed', 'receiverOrganizationClosed', 'receiverInternalError', 'senderDeceased', 'fraud', 'senderUserRequested', 'receiverUserRequested', 'paymentNotFound'.
+    #
+    # ## Parameters (optional):
+    # - user [Organization/Project object, default nil]: Organization or Project object. Not necessary if StarkInfra.user was set before function call
+    #
+    # ## Return:
+    # - canceled PixPullSubscription object
+    def self.cancel(id, reason:, user: nil)
+      response = StarkInfra::Utils::Rest.delete_raw(
+        path: "/pix-pull-subscription/#{id}",
+        query: { reason: reason },
+        user: user,
+        raiseException: true
+      )
+      maker = resource[:resource_maker]
+      StarkCore::Utils::API.from_api_json(maker, response.json['subscription'])
+    end
+
+    # # Create a single verified PixPullSubscription object from a content string
+    #
+    # Create a single PixPullSubscription object from a content string received from a handler listening at the subscription url.
+    # If the provided digital signature does not check out with the StarkInfra public key, a
+    # StarkInfra::Error::InvalidSignatureError will be raised.
+    #
+    # ## Parameters (required):
+    # - content [string]: response content from request received at user endpoint (not parsed)
+    # - signature [string]: base-64 digital signature received at response header 'Digital-Signature'
+    #
+    # ## Parameters (optional):
+    # - user [Organization/Project object, default nil]: Organization or Project object. Not necessary if StarkInfra.user was set before function call
+    #
+    # ## Return:
+    # - Parsed PixPullSubscription object
+    def self.parse(content:, signature:, user: nil)
+      StarkInfra::Utils::Parse.parse_and_verify(
+        content: content,
+        signature: signature,
+        user: user,
+        key: nil,
+        resource: resource
+      )
+    end
+
+    def self.resource
+      {
+        resource_name: 'PixPullSubscription',
+        resource_maker: proc { |json|
+          PixPullSubscription.new(
+            id: json['id'],
+            bacen_id: json['bacen_id'],
+            external_id: json['external_id'],
+            installment_start: json['installment_start'],
+            interval: json['interval'],
+            receiver_name: json['receiver_name'],
+            receiver_tax_id: json['receiver_tax_id'],
+            sender_account_number: json['sender_account_number'],
+            sender_bank_code: json['sender_bank_code'],
+            sender_branch_code: json['sender_branch_code'],
+            sender_tax_id: json['sender_tax_id'],
+            type: json['type'],
+            amount: json['amount'],
+            amount_min_limit: json['amount_min_limit'],
+            description: json['description'],
+            due: json['due'],
+            installment_end: json['installment_end'],
+            receiver_bank_code: json['receiver_bank_code'],
+            reference_code: json['reference_code'],
+            pull_retry_limit: json['pull_retry_limit'],
+            sender_city_code: json['sender_city_code'],
+            sender_final_name: json['sender_final_name'],
+            sender_final_tax_id: json['sender_final_tax_id'],
+            tags: json['tags'],
+            status: json['status'],
+            flow: json['flow'],
+            created: json['created'],
+            updated: json['updated']
+          )
+        }
+      }
+    end
+  end
+end

data/lib/pix_request/pix_request.rb

@@ -35,18 +35,23 @@ module StarkInfra
   # - cashier_bank_code [string]: Cashier's bank code. Required if the cash_amount is different from 0. ex: '20018183'
   #
   # ## Parameters (optional):
-  # - cash_amount [integer, default nil]: Amount to be withdrawal from the cashier in cents. ex: 1000 (= R$ 10.00)
+  # - cash_amount [integer, default nil]: amount to be withdrawn from the cashier in cents for Pix Saque/Troco; must be less than or equal to amount. ex: 1000 (= R$ 10.00)
   # - receiver_key_id [string, default nil]: Receiver's dict key. Example: tax id (CPF/CNPJ).
   # - description [string, default nil]: optional description to override default description to be shown in the bank statement. ex: 'Payment for service #1234'
   # - reconciliation_id [string, default nil]: Reconciliation ID linked to this payment. ex: 'b77f5236-7ab9-4487-9f95-66ee6eaf1781'
   # - initiator_tax_id [string, default nil]: Payment initiator's tax id (CPF/CNPJ). ex: '01234567890' or '20.018.183/0001-80'
   # - tags [list of strings, default nil]: list of strings for reference when searching for PixRequests. ex: ['employees', 'monthly']
   # - method [string, default nil]: execution method of creation of the Pix. ex: 'manual', 'payerQrcode', 'dynamicQrcode'.
+  # - priority priority [string, default 'high']: Specifies the message channel used to send the Pix Request. If set to 'high', the request is sent through the primary channel; if set to 'low', it uses the secondary channel. Options: 'high' or 'low'
+  # - reason [string, default 'customerRequest']: underlying reason for the payment transaction. Options: 'customerRequest', 'subscriptionFlaw', 'fraud'. When reason is 'fraud' (returning funds from a PixDispute), dispute_id is required and sender_tax_id must be your institution's organization tax ID (CNPJ).
+  #
+  # ## Parameters (conditionally-required):
+  # - dispute_id [string, default nil]: Id of the Pix Dispute being refunded. Required when reason is 'fraud' and not allowed with any other reason. The dispute must be one you received and must be awaiting the refund, otherwise the request is refused with invalidDisputeId.
   #
   # ## Attributes (return-only):
   # - id [string]: unique id returned when the PixRequest is created. ex: '5656565656565656'
   # - fee [integer]: fee charged when PixRequest is paid. ex: 200 (= R$ 2.00)
-  # - status [string]: current PixRequest status. ex: 'registered' or 'paid'
+  # - status [string]: current PixRequest status. Options: 'created', 'processing', 'success', 'failed'.
   # - flow [string]: direction of money flow. ex: 'in' or 'out'
   # - sender_bank_code [string]: code of the sender bank institution in Brazil. ex: '20018183'
   # - created [DateTime]: creation datetime for the PixRequest. ex: DateTime.new(2020, 3, 10, 10, 30, 0, 0)
@@ -56,13 +61,14 @@ module StarkInfra
                 :sender_account_type, :receiver_name, :receiver_tax_id, :receiver_bank_code, :receiver_account_number,
                 :receiver_branch_code, :receiver_account_type, :end_to_end_id, :cashier_type,
                 :cashier_bank_code, :cash_amount, :receiver_key_id, :description, :reconciliation_id, :initiator_tax_id,
-                :tags, :method, :id, :fee, :status, :flow, :sender_bank_code, :created, :updated
+                :tags, :method, :priority, :reason, :dispute_id, :id, :fee, :status, :flow, :sender_bank_code, :created, :updated
     def initialize(
       amount:, external_id:, sender_name:, sender_tax_id:, sender_branch_code:, sender_account_number:, 
       sender_account_type:, receiver_name:, receiver_tax_id:, receiver_bank_code:, receiver_account_number:, 
       receiver_branch_code:, receiver_account_type:, end_to_end_id:, cashier_type: nil, cashier_bank_code: nil,
       cash_amount: nil, receiver_key_id: nil, description: nil, reconciliation_id: nil, initiator_tax_id: nil,
-      tags: nil, method: nil, id: nil, fee: nil, status:nil, flow: nil, sender_bank_code: nil, created: nil, updated: nil
+      tags: nil, method: nil, priority: nil, reason: nil, dispute_id: nil, id: nil, fee: nil, status:nil, flow: nil, sender_bank_code: nil,
+      created: nil, updated: nil
     )
       super(id)
       @amount = amount
@@ -88,6 +94,9 @@ module StarkInfra
       @initiator_tax_id = initiator_tax_id
       @tags = tags
       @method = method
+      @priority = priority
+      @reason = reason
+      @dispute_id = dispute_id
       @fee = fee
       @status = status
       @flow = flow
@@ -216,7 +225,7 @@ module StarkInfra
     # ## Return:
     # - Parsed PixRequest object
     def self.parse(content:, signature:, user: nil)
-      request = StarkCore::Utils::Parse.parse_and_verify(content: content, signature: signature, user: user, resource: resource)
+      request = StarkInfra::Utils::Parse.parse_and_verify(content: content, signature: signature, user: user, resource: resource)
 
       !request.fee.nil? ? request.fee : 0
       !request.tags.nil? ? request.tags : []
@@ -226,7 +235,8 @@ module StarkInfra
       request
     end
 
-    # Helps you respond to a PixRequest authorization
+    # Helps you respond to a PixRequest authorization. You must answer within 1 second with HTTP status 200,
+    # or the request is denied by default.
     #
     ## Parameters (required):
     # - status [string]: response to the authorization. ex: 'approved' or 'denied'
@@ -276,6 +286,9 @@ module StarkInfra
             initiator_tax_id: json['initiator_tax_id'],
             tags: json['tags'],
             method: json['method'],
+            priority: json['priority'],
+            reason: json['reason'],
+            dispute_id: json['dispute_id'],
             fee: json['fee'],
             status: json['status'],
             flow: json['flow'],

data/lib/pix_reversal/pix_reversal.rb

@@ -18,7 +18,7 @@ module StarkInfra
   # - amount [integer]: amount in cents to be reversed from PixRequest. ex: 1234 (= R$ 12.34)
   # - external_id [string]: string that must be unique among all your PixReversals. Duplicated external IDs will cause failures. By default, this parameter will block any PixReversal that repeats amount and receiver information on the same date. ex: 'my-internal-id-123456'
   # - end_to_end_id [string]: central bank's unique transaction ID. ex: 'E79457883202101262140HHX553UPqeq'
-  # - reason [string]: reason why the PixRequest is being reversed. Options are 'bankError', 'fraud', 'pixWithdrawError', 'refund3ByEndCustomer'
+  # - reason [string]: reason why the PixReversal is being reversed. Options are 'bankError', 'fraud', 'cashierError', 'customerRequest'.
   #
   # ## Parameters (optional):
   # - tags [list of strings, default nil]: list of strings for reference when searching for PixReversals. ex: ['employees', 'monthly']
@@ -27,16 +27,17 @@ module StarkInfra
   # - id [string]: unique id returned when the PixReversal is created. ex: '5656565656565656'.
   # - return_id [string]: central bank's unique reversal transaction ID. ex: 'D20018183202202030109X3OoBHG74wo'.
   # - fee [string]: fee charged by this PixReversal. ex: 200 (= R$ 2.00)
-  # - status [string]: current PixReversal status. ex: 'registered' or 'paid'
+  # - status [string]: current PixReversal status. Options are 'created', 'processing', 'success' or 'failed'.
   # - flow [string]: direction of money flow. ex: 'in' or 'out'
   # - created [DateTime]: creation datetime for the PixReversal. ex: DateTime.new(2020, 3, 10, 10, 30, 0, 0)
   # - updated [DateTime]: latest update datetime for the PixReversal. ex: DateTime.new(2020, 3, 10, 10, 30, 0, 0)
+  # - description [string]: description of the reversal.
   class PixReversal < StarkCore::Utils::Resource
     attr_reader :amount, :external_id, :end_to_end_id, :reason, :tags, :id, :return_id,
-                :fee, :status, :flow, :created, :updated
+                :fee, :status, :flow, :created, :updated, :description
     def initialize(
       amount:, external_id:, end_to_end_id:, reason:, tags: nil, id: nil, return_id: nil, fee: nil,
-      status: nil, flow: nil, created: nil, updated: nil
+      status: nil, flow: nil, created: nil, updated: nil, description: nil
     )
       super(id)
       @amount = amount
@@ -50,11 +51,13 @@ module StarkInfra
       @flow = flow
       @created = StarkCore::Utils::Checks.check_datetime(created)
       @updated = StarkCore::Utils::Checks.check_datetime(updated)
+      @description = description
     end
 
     # # Create PixReversals
     #
-    # Send a list of PixReversal objects for creation in the Stark Infra API
+    # Send a list of PixReversal objects for creation in the Stark Infra API. Reversals can only be created
+    # for inbound PixRequests with status 'success'; reference the original request by its end_to_end_id.
     #
     # ## Parameters (required):
     # - reversals [list of PixReversal objects]: list of PixReversal objects to be created in the API
@@ -170,7 +173,7 @@ module StarkInfra
     # ## Return:
     # - Parsed PixReversal object
     def self.parse(content:, signature:, user: nil)
-      reversal = StarkCore::Utils::Parse.parse_and_verify(
+      reversal = StarkInfra::Utils::Parse.parse_and_verify(
         content: content,
         signature: signature,
         user: user,
@@ -185,7 +188,9 @@ module StarkInfra
       reversal
     end
 
-    # Helps you respond to a PixReversal authorization
+    # Helps you respond to a PixReversal authorization sent to your pixReversalUrl (must differ from your
+    # pixRequestUrl). Answer within 1 second with HTTP 200, or it is denied by default; if no pixReversalUrl
+    # is registered, inbound reversals are accepted by default.
     #
     ## Parameters (required):
     # - status [string]: response to the authorization. ex: 'approved' or 'denied'
@@ -222,7 +227,8 @@ module StarkInfra
             status: json['status'],
             flow: json['flow'],
             created: json['created'],
-            updated: json['updated']
+            updated: json['updated'],
+            description: json['description']
           )
         }
       }

data/lib/pix_statement/pix_statement.rb

@@ -22,13 +22,17 @@ module StarkInfra
   #
   # ## Attributes (return-only):
   # - id [string]: unique id returned when the PixStatement is created. ex: '5656565656565656'
-  # - status [string]: current PixStatement status. ex: 'success' or 'failed'
+  # - status [string]: current PixStatement status. Options: 'created', 'looking', 'success', 'failed'.
   # - transaction_count [integer]: number of transactions that happened during the day that the PixStatement was requested. ex: 11
   # - created [DateTime]: creation datetime for the PixStatement. ex: DateTime.new(2020, 3, 10, 10, 30, 0, 0)
   # - updated [DateTime]: latest update datetime for the PixStatement. ex: DateTime.new(2020, 3, 10, 10, 30, 0, 0)
+  # - chunk_count [integer]: number of chunks the statement file is split into. ex: 2
   class PixStatement < StarkCore::Utils::Resource
-    attr_reader :after, :before, :type, :id, :status, :transaction_count, :created, :updated
-    def initialize(after:, before:, type:, id: nil, status: nil, transaction_count: nil, created: nil, updated: nil)
+    attr_reader :after, :before, :type, :id, :status, :transaction_count, :created, :updated, :chunk_count
+    def initialize(
+      after:, before:, type:, id: nil, status: nil, transaction_count: nil, created: nil, updated: nil,
+      chunk_count: nil
+    )
       super(id)
       @after = StarkCore::Utils::Checks.check_date(after)
       @before = StarkCore::Utils::Checks.check_date(before)
@@ -37,6 +41,7 @@ module StarkInfra
       @transaction_count = transaction_count
       @created = StarkCore::Utils::Checks.check_datetime(created)
       @updated = StarkCore::Utils::Checks.check_datetime(updated)
+      @chunk_count = chunk_count
     end
 
     # # Create a PixStatement object
@@ -117,7 +122,7 @@ module StarkInfra
 
     # # # Retrieve a .cvs PixStatement
     #
-    # Retrieve a specific PixStatement by its ID in a .csv file.
+    # Retrieve a specific PixStatement's CSV file by its ID. The file is returned compressed in gzip format.
     #
     # ## Parameters (required):
     # - id [string]: object unique id. ex: '5656565656565656'
@@ -143,7 +148,8 @@ module StarkInfra
             status: json['status'],
             transaction_count: json['transaction_count'],
             created: json['created'],
-            updated: json['updated']
+            updated: json['updated'],
+            chunk_count: json['chunk_count']
           )
         }
       }

data/lib/pix_user/pix_user.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require('starkcore')
+require_relative('../utils/rest')
+
+module StarkInfra
+  # # PixUser object
+  #
+  # Pix Users are used to get fraud statistics of a user.
+  #
+  # ## Parameters (required):
+  # - id [string]: user tax ID (CPF or CNPJ) with or without formatting. ex: '01234567890' or '20.018.183/0001-80'
+  #
+  # ## Attributes (return-only):
+  # - statistics [list of PixUser::Statistics, default []]: list of PixUser::Statistics objects. ex: [PixUser::Statistics.new(after: '2023-11-06T18:57:08.325090+00:00', source: 'pix-key')]
+  class PixUser < StarkCore::Utils::Resource
+    attr_reader :id, :statistics
+    def initialize(id:, statistics: nil)
+      super(id)
+      @statistics = StarkInfra::PixUser::Statistics.parse_statistics(statistics)
+    end
+
+    # # Retrieve a PixUser object
+    #
+    # Receive a single PixUser object information by passing its taxId
+    #
+    # ## Parameters (required):
+    # - id [string]: user tax ID (CPF or CNPJ) with or without formatting. ex: '01234567890' or '20.018.183/0001-80'
+    #
+    # ## Parameters (optional):
+    # - key_id [string, default nil]: marked PixKey id. ex: '+5511989898989'
+    # - user [Organization/Project object, default nil]: Organization or Project object. Not necessary if StarkInfra.user was set before function call
+    #
+    # ## Return:
+    # - PixUser object that corresponds to the given id.
+    def self.get(id, key_id: nil, user: nil)
+      StarkInfra::Utils::Rest.get_id(id: id, key_id: key_id, user: user, **resource)
+    end
+
+    def self.resource
+      {
+        resource_name: 'PixUser',
+        resource_maker: proc { |json|
+          PixUser.new(
+            id: json['id'],
+            statistics: json['statistics']
+          )
+        }
+      }
+    end
+  end
+end

data/lib/pix_user/statistics.rb

@@ -0,0 +1,64 @@
+require_relative('../utils/rest')
+
+module StarkInfra
+  class PixUser
+    # # PixUser::Statistics object
+    #
+    # The PixUser::Statistics object stores fraud statistics data of a Pix user.
+    #
+    # ## Attributes (return-only):
+    # - value [integer]: aggregated value of the statistic. ex: 3
+    # - type [string]: type of the statistic. ex: 'infractions'
+    # - source [string]: source of the statistic. ex: 'keyManagement'
+    # - after [DateTime]: start datetime considered for the statistic aggregation. ex: DateTime.new(2020, 4, 23, 23, 0, 0)
+    # - updated [DateTime]: latest update datetime for the statistic. ex: DateTime.new(2020, 4, 23, 23, 0, 0)
+    class Statistics < StarkCore::Utils::SubResource
+      attr_reader :value, :type, :source, :after, :updated
+      def initialize(value: nil, type: nil, source: nil, after: nil, updated: nil)
+        @value = value
+        @type = type
+        @source = source
+        @after = StarkCore::Utils::Checks.check_datetime(after)
+        @updated = StarkCore::Utils::Checks.check_datetime(updated)
+      end
+
+      # # Parse PixUser::Statistics
+      #
+      # Converts a list of hashes (or Statistics objects) received from the API into a list of PixUser::Statistics objects.
+      #
+      # ## Parameters (required):
+      # - statistics [list of hashes or PixUser::Statistics objects]: list to be parsed.
+      #
+      # ## Return:
+      # - list of parsed PixUser::Statistics objects
+      def self.parse_statistics(statistics)
+        resource_maker = StarkInfra::PixUser::Statistics.resource[:resource_maker]
+        return statistics if statistics.nil?
+
+        parsed_statistics = []
+        statistics.each do |statistic|
+          unless statistic.is_a? Statistics
+            statistic = StarkCore::Utils::API.from_api_json(resource_maker, statistic)
+          end
+          parsed_statistics << statistic
+        end
+        return parsed_statistics
+      end
+
+      def self.resource
+      {
+        resource_name: 'Statistics',
+        resource_maker: proc { |json|
+          Statistics.new(
+            value: json['value'],
+            type: json['type'],
+            source: json['source'],
+            after: json['after'],
+            updated: json['updated']
+          )
+        }
+      }
+      end
+    end
+  end
+end