Add merchant resources

CHANGELOG.md

@@ -13,6 +13,8 @@ Given a version number MAJOR.MINOR.PATCH, increment:
 
 
 ## [Unreleased]
+### Added
+- merchantSession, merchantPurchase, merchantCard, merchantInstallment
 
 ## [2.13.0] - 2025-03-17
 ### Added

README.md

@@ -49,6 +49,10 @@ is as easy as sending a text message to your client!
     - [CorporateBalance](#get-your-corporatebalance): View your corporate balance
     - [CorporateTransactions](#query-corporatetransactions): View the transactions that have affected your corporate balance
     - [CorporateEnums](#corporate-enums): Query enums related to the corporate purchases, such as merchant categories, countries and card purchase methods
+    - [MerchantSession](#merchant-session): The Merchant Session allows you to create a session prior to a purchase. Sessions are essential for defining the parameters of a purchase, including funding type, expiration, 3DS, and more.
+    - [MerchantCard](#merchant-card): The Merchant Card resource stores information about cards used in approved purchases.
+    - [MerchantInstallment](#merchant-installment): Merchant Installments are created for every installment in a purchase.
+    - [MerchantPurchase](#merchant-purchase): The Merchant Purchase section allows users to retrieve detailed information of the purchases.
     - [Webhooks](#create-a-webhook-subscription): Configure your webhook endpoints and subscriptions
     - [WebhookEvents](#process-webhook-events): Manage webhook events
     - [WebhookEventAttempts](#query-failed-webhook-event-delivery-attempts-information): Query failed webhook event deliveries
@@ -2221,6 +2225,157 @@ methods.each do |method|
 end
 ```
 
+## Merchant Session
+
+The Merchant Session allows you to create a session prior to a purchase.
+Sessions are essential for defining the parameters of a purchase, including funding type, expiration, 3DS, and more.
+
+## Create a MerchantSession
+
+```ruby
+require('starkbank')
+
+session = {
+  allowed_funding_types: ['debit', 'credit'],
+  allowed_installments: [
+    { total_amount: 0, count: 1 },
+    { total_amount: 120, count: 2 },
+    { total_amount: 180, count: 12 }
+  ],
+  expiration: 3600,
+  challenge_mode: challenge_mode,
+  tags: ['yourTags']
+}
+
+merchant_session = StarkBank::MerchantSession.create(session)
+
+puts merchant_session
+```
+
+You can create a MerchantPurchase through a MerchantSession by passing its UUID.
+**Note**: This method must be implemented in your front-end to ensure that sensitive card data does not pass through the back-end of the integration.
+
+### Create a MerchantSession Purchase
+
+```ruby
+require('starkbank')
+
+session_purchase = {
+  amount: 180,
+  installment_count: 12,
+  card_expiration: '2035-01',
+  card_number: '5277696455399733',
+  card_security_code: '123',
+  holder_name: 'Holder Name',
+  holder_email: 'holdeName@email.com',
+  holder_phone: '11111111111',
+  funding_type: 'credit',
+  billing_country_code: 'BRA',
+  billing_city: 'São Paulo',
+  billing_state_code: 'SP',
+  billing_street_line_1: 'Rua do Holder Name, 123',
+  billing_street_line_2: '',
+  billing_zip_code: '11111-111',
+  metadata: {
+    user_agent: 'Postman',
+    user_ip: '255.255.255.255',
+    language: 'pt-BR',
+    timezone_offset: 3,
+    extra_data: 'extraData'
+  }
+}
+
+purchase = StarkBank::MerchantSession.purchase(
+  uuid: "c32f9d2385974957a777f8351921afd7",
+  payload: session_purchase
+)
+
+puts purchase
+```
+
+### Query MerchantSessions
+```ruby
+require('starkbank')
+
+merchant_sessions = StarkBank::MerchantSession.query(limit: 3).to_a
+merchant_sessions.each do |merchant_session|
+  puts merchant_session
+end
+```
+
+### Get a MerchantSession
+```ruby
+require('starkbank')
+
+merchant_session = StarkBank::MerchantSession.get("5130086357401600")
+puts merchant_session
+```
+## Merchant Purchase
+The Merchant Purchase section allows users to retrieve detailed information of the purchases.
+
+### Query MerchantPurchases
+```ruby
+require('starkbank')
+
+merchant_purchases = StarkBank::MerchantPurchase.query(limit: 3).to_a
+merchant_purchases.each do |session|
+  puts session
+end
+```
+### Get a MerchantPurchase
+```ruby
+require('starkbank')
+
+merchant_purchase = StarkBank::MerchantPurchase.get("5130086357401600")
+puts merchant_purchase
+```
+
+## Merchant Card
+
+The Merchant Card resource stores information about cards used in approved purchases.
+These cards can be used in new purchases without the need to create a new session.
+
+### Query MerchantCards
+```ruby
+require('starkbank')
+
+merchant_cards = StarkBank::MerchantCard.query(limit: 3).to_a
+merchant_cards.each do |card|
+  puts card
+end
+```
+
+### Get a MerchantCard
+```ruby
+require('starkbank')
+
+merchant_card = StarkBank::MerchantCard.get("5130086357401600")
+puts merchant_card
+```
+
+## Merchant Installment
+
+Merchant Installments are created for every installment in a purchase.
+These resources will track its own due payment date and settlement lifecycle.
+
+### Query MerchantInstallments
+```ruby
+require('starkbank')
+
+merchant_installments = StarkBank::MerchantInstallment.query(limit: 3).to_a
+merchant_installments.each do |installment|
+  puts installment
+end
+```
+
+### Get a MerchantInstallment
+```ruby
+require('starkbank')
+
+merchant_installment = StarkBank::MerchantCard.get("5130086357401600")
+puts merchant_installment
+```
+
 ## Create a webhook subscription
 
 To create a webhook subscription and be notified whenever an event occurs, run:

lib/merchant_card/log.rb

@@ -0,0 +1,68 @@
+require('starkcore')
+require_relative('../utils/rest')
+require_relative('merchant_card')
+
+
+module StarkBank
+    class MerchantCard
+        class Log < StarkCore::Utils::Resource
+            attr_reader :id, :created, :type, :errors, :card
+            def initialize(id:, created:, type:, errors:, card:)
+                super(id)
+                @created = StarkCore::Utils::Checks.check_datetime(created)
+                @type = type
+                @errors = errors
+                @card = card
+            end
+
+            def self.get(id, user: nil)
+                StarkBank::Utils::Rest.get_id(id: id, user: user, **resource)
+            end
+
+            def self.query(limit: nil, after: nil, before: nil, types: nil, card_ids: nil, user: nil)
+                after = StarkCore::Utils::Checks.check_date(after)
+                before = StarkCore::Utils::Checks.check_date(before)
+                StarkBank::Utils::Rest.get_stream(
+                limit: limit,
+                after: after,
+                before: before,
+                types: types,
+                card_ids: card_ids,
+                user: user,
+                **resource
+                )
+            end
+
+            def self.page(cursor: nil, limit: nil, after: nil, before: nil, types: nil, card_ids: nil, user: nil)
+                after = StarkCore::Utils::Checks.check_date(after)
+                before = StarkCore::Utils::Checks.check_date(before)
+                return StarkBank::Utils::Rest.get_page(
+                cursor: cursor,
+                limit: limit,
+                after: after,
+                before: before,
+                types: types,
+                card_ids: card_ids,
+                user: user,
+                **resource
+                )
+            end
+
+            def self.resource
+                card_maker = StarkBank::MerchantCard.resource[:resource_maker]
+                {
+                resource_name: 'MerchantCardLog',
+                resource_maker: proc { |json|
+                    Log.new(
+                    id: json['id'],
+                    created: json['created'],
+                    type: json['type'],
+                    errors: json['errors'],
+                    card: StarkCore::Utils::API.from_api_json(card_maker, json['card'])
+                    )
+                }
+                }
+            end
+        end
+    end
+end

lib/merchant_card/merchant_card.rb

@@ -0,0 +1,71 @@
+require 'starkcore'
+require_relative '../utils/rest'
+
+
+module StarkBank
+    class MerchantCard < StarkCore::Utils::Resource
+        attr_reader :created, :ending, :expiration, :fundingType, :holderName, :id, :network, :status, :tags, :updated
+
+        def initialize(ending:, expiration:, fundingType:, holderName:, id: nil, created: nil, network: nil, status: nil, tags: nil, updated: nil)
+            super(id)
+            @ending = ending
+            @expiration = expiration
+            @fundingType = fundingType
+            @holderName = holderName
+            @created = StarkCore::Utils::Checks.check_datetime(created)
+            @network = network
+            @status = status
+            @tags = tags
+            @updated = StarkCore::Utils::Checks.check_datetime(updated)
+        end
+
+        def self.resource
+            {
+                resource_name: 'MerchantCard',
+                resource_maker: proc { |json|
+                    MerchantCard.new(
+                        ending: json['ending'],
+                        expiration: json['expiration'],
+                        fundingType: json['fundingType'],
+                        holderName: json['holderName'],
+                        id: json['id'],
+                        created: json['created'],
+                        network: json['network'],
+                        status: json['status'],
+                        tags: json['tags'],
+                        updated: json['updated']
+                    )
+                }
+            }
+        end
+
+        def self.get(id, user: nil)
+            StarkBank::Utils::Rest.get_id(id: id, user: user, **resource)
+        end
+
+        def self.query(limit: nil, status: nil, tags: nil, ids: nil, after: nil, before: nil, user: nil)
+            StarkBank::Utils::Rest.get_stream(
+                limit: limit,
+                after: after,
+                before: before,
+                status: status,
+                tags: tags,
+                ids: ids,
+                user: user,
+                **resource
+            )
+        end
+
+        def self.page(limit: nil, cursor: nil, status: nil, tags: nil, ids: nil, user: nil)
+            StarkBank::Utils::Rest.get_page(
+                limit: limit,
+                cursor: cursor,
+                status: status,
+                tags: tags,
+                ids: ids,
+                user: user,
+                **resource
+            )
+        end
+    end
+end

lib/merchant_installment/log.rb

@@ -0,0 +1,68 @@
+require('starkcore')
+require_relative('../utils/rest')
+require_relative('merchant_installment')
+
+
+module StarkBank
+    class MerchantInstallment
+        class Log < StarkCore::Utils::Resource
+            attr_reader :id, :created, :type, :errors, :installment
+            def initialize(id:, created:, type:, errors:, installment:)
+                super(id)
+                @created = StarkCore::Utils::Checks.check_datetime(created)
+                @type = type
+                @errors = errors
+                @installment = installment
+            end
+
+            def self.get(id, user: nil)
+                StarkBank::Utils::Rest.get_id(id: id, user: user, **resource)
+            end
+
+            def self.query(limit: nil, after: nil, before: nil, types: nil, installment_ids: nil, user: nil)
+                after = StarkCore::Utils::Checks.check_date(after)
+                before = StarkCore::Utils::Checks.check_date(before)
+                StarkBank::Utils::Rest.get_stream(
+                limit: limit,
+                after: after,
+                before: before,
+                types: types,
+                installment_ids: installment_ids,
+                user: user,
+                **resource
+                )
+            end
+
+            def self.page(cursor: nil, limit: nil, after: nil, before: nil, types: nil, installment_ids: nil, user: nil)
+                after = StarkCore::Utils::Checks.check_date(after)
+                before = StarkCore::Utils::Checks.check_date(before)
+                return StarkBank::Utils::Rest.get_page(
+                cursor: cursor,
+                limit: limit,
+                after: after,
+                before: before,
+                types: types,
+                installment_ids: installment_ids,
+                user: user,
+                **resource
+                )
+            end
+
+            def self.resource
+                installment_maker = StarkBank::MerchantInstallment.resource[:resource_maker]
+                {
+                resource_name: 'MerchantInstallmentLog',
+                resource_maker: proc { |json|
+                        Log.new(
+                            id: json['id'],
+                            created: json['created'],
+                            type: json['type'],
+                            errors: json['errors'],
+                            installment: StarkCore::Utils::API.from_api_json(installment_maker, json['installment'])
+                        )
+                    }
+                }
+            end
+        end
+    end
+end