Add merchant purchase, merchant session, merchant card and merchant installment

Author: jonasborges-stark

CHANGELOG.md

@@ -13,6 +13,8 @@ Given a version number MAJOR.MINOR.PATCH, increment:
 
 
 ## [Unreleased]
+### Added
+- merchantSession and merchantSessionPurchase resources
 
 ## [2.26.1] - 2025-02-18
 ### Fixed

README.md

@@ -49,6 +49,8 @@ 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.
+    - [MerchantPurchase](#merchant-purchase): The Merchant Purchase section allows users to retrieve detailed information of the purchases.
     - [Split](#query-splits): Split received Invoice payments between different receivers
     - [SplitReceiver](#create-splitreceivers): Receiver of an Invoice split
     - [Webhooks](#create-a-webhook-subscription): Configure your webhook endpoints and subscriptions
@@ -2332,6 +2334,113 @@ log = starkbank.splitreceiver.log.get("5155165527080960")
 
 print(log)
 ```
+## 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
+
+```python
+import starkbank
+
+merchant_session = starkbank.merchantsession.create({
+    "allowedFundingTypes": [
+        "debit",
+        "credit"
+    ],
+    "allowedInstallments": [
+        {
+            "totalAmount": 0,
+            "count": 1
+        },
+        {
+            "totalAmount": 120,
+            "count": 2
+        },
+        {
+            "totalAmount": 180,
+            "count": 12
+        }
+    ],
+    "expiration": 3600,
+    "challengeMode": "disabled",
+    "tags": [
+        "yourTags"
+    ]
+})
+
+print(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
+
+```python
+import starkbank
+
+merchant_session_purchase = starkbank.merchantsession.purchase(
+  uuid="0bb894a2697d41d99fe02cad2c00c9bc",
+  amount=180,
+  installment_count=12,
+  card_expiration="2035-01",
+  card_number="5448280000000007",
+  card_security_code="123",
+  holder_name="Holder Name",
+  holder_email="[email protected]",
+  holder_phone="11111111111",
+  funding_type="credit",
+  billing_country_code="BRA",
+  billing_city="São Paulo",
+  billing_state_code="SP",
+  billing_street_line1="Rua do Holder Name, 123",
+  billing_street_line2="",
+  billing_zip_code="11111-111",
+  metadata={
+    "extraData": "extraData",
+    "language": "pt-BR",
+    "timezoneOffset": 3,
+    "userAgent": "Postman",
+    "userIp": "255.255.255.255"
+  }
+)
+
+print(merchant_session_purchase)
+```
+### Query MerchantSessions
+```python
+import starkbank
+
+merchant_sessions = starkbank.merchantsession.query(limit=3)
+for merchant_session in merchant_sessions:
+    print(merchant_session)
+```
+### Get a MerchantSession
+```python
+import starkbank
+
+merchant_session = starkbank.merchantsession.get('5950134772826112')
+print(merchant_session)
+```
+## Merchant Purchase
+The Merchant Purchase section allows users to retrieve detailed information of the purchases.
+### Query MerchantPurchases
+```python
+import starkbank
+
+merchant_purchases = starkbank.merchantpurchase.query(limit=3)
+for merchant_purchase in merchant_purchases:
+    print(merchant_purchase)
+```
+### Get a MerchantPurchase
+```python
+import starkbank
+
+merchant_purchase = starkbank.merchantpurchase.get('5950134772826112')
+print(merchant_purchase)
+```
 
 ## Create a webhook subscription
 

starkbank/__init__.py

@@ -58,12 +58,24 @@
 from . import corporaterule
 from .corporaterule.__corporaterule import CorporateRule
 
+from . import merchantcard
+from .merchantcard.__merchantcard import MerchantCard
+
 from . import merchantcategory
 from .merchantcategory.__merchantcategory import MerchantCategory
 
 from . import merchantcountry
 from .merchantcountry.__merchantcountry import MerchantCountry
 
+from . import merchantinstallment
+from .merchantinstallment.__merchantinstallment import MerchantInstallment
+
+from . import merchantpurchase
+from .merchantpurchase.__merchantpurchase import MerchantPurchase
+
+from . import merchantsession
+from .merchantsession.__merchantsession import MerchantSession
+
 from . import cardmethod
 from .cardmethod.__cardmethod import CardMethod
 

starkbank/merchantcard/__init__.py

@@ -0,0 +1,3 @@
+from .__merchantcard import get, query, page
+from .log.__log import Log
+from . import log

starkbank/merchantcard/__merchantcard.py

@@ -0,0 +1,52 @@
+from starkcore.utils.resource import Resource
+from ..utils import rest
+from starkcore.utils.checks import check_date, check_datetime
+
+class MerchantCard(Resource):
+    """# MerchantCard object
+    Check out our API Documentation at https://starkbank.com/docs/api#merchant-card
+    """
+
+    def __init__(self, id=None, ending=None , funding_type=None, holder_name=None, network=None, status=None, tags=None, expiration=None, created=None, updated=None):
+        Resource.__init__(self, id=id)
+        self.ending = ending
+        self.funding_type = funding_type
+        self.holder_name = holder_name
+        self.network = network
+        self.status = status
+        self.tags = tags
+        self.expiration = expiration
+        self.created = check_datetime(created)
+        self.updated = check_datetime(updated)
+
+_resource = {"class": MerchantCard, "name": "MerchantCard"}
+
+def get(id, user=None):
+    return rest.get_id(resource=_resource, id=id, user=user)
+
+
+def query(limit=None, after=None, before=None, status=None, tags=None, ids=None, user=None):
+    return rest.get_stream(
+        resource=_resource,
+        limit=limit,
+        after=check_date(after),
+        before=check_date(before),
+        status=status,
+        tags=tags,
+        ids=ids,
+        user=user,
+    )
+
+
+def page(cursor=None, limit=None, after=None, before=None, status=None, tags=None, ids=None, user=None):
+    return rest.get_page(
+        resource=_resource,
+        cursor=cursor,
+        limit=limit,
+        after=check_date(after),
+        before=check_date(before),
+        status=status,
+        tags=tags,
+        ids=ids,
+        user=user,
+    )

starkbank/merchantcard/log/__init__.py

@@ -0,0 +1 @@
+from .__log import query, page, get

starkbank/merchantcard/log/__log.py

@@ -0,0 +1,47 @@
+from starkcore.utils.resource import Resource
+from ...utils import rest
+from starkcore.utils.checks import check_date
+
+
+class Log(Resource):
+    """# MerchantCard object
+    Check out our API Documentation at https://starkbank.com/docs/api#merchant-card
+    """
+
+    def __init__(self, id, created, updated, type, errors, card):
+        Resource.__init__(self, id=id)
+        self.created = check_date(created)
+        self.updated = check_date(updated)
+        self.type = type
+        self.errors = errors
+        self.card = card
+
+_resource = {"class": Log, "name": "MerchantCardLog"}
+
+
+def get(id, user=None):
+    return rest.get_id(resource=_resource, id=id, user=user)
+
+
+def query(limit=None, after=None, before=None, user=None):
+    return rest.get_stream(
+        resource=_resource,
+        limit=limit,
+        after=check_date(after),
+        before=check_date(before),
+        user=user,
+    )
+
+
+def page(cursor=None, limit=None, after=None, before=None, types=None, ids=None, user=None):
+    return rest.get_page(
+        resource=_resource,
+        cursor=cursor,
+        limit=limit,
+        after=check_date(after),
+        before=check_date(before),
+        types=types,
+        ids=ids,
+        user=user,
+    )
+

starkbank/merchantinstallment/__init__.py

@@ -0,0 +1,3 @@
+from .__merchantinstallment import get, query, page
+from .log.__log import Log
+from . import log

starkbank/merchantinstallment/__merchantinstallment.py

@@ -0,0 +1,57 @@
+from starkcore.utils.resource import Resource
+from ..utils import rest
+from starkcore.utils.checks import check_date, check_datetime, check_datetime_or_date
+
+
+class MerchantInstallment(Resource):
+    """# MerchantInstallment object
+    Check out our API Documentation at https://starkbank.com/docs/api#merchant-installment
+    """
+
+    def __init__(self, id=None, amount=None, created=None, due=None, fee=None, funding_type=None, network=None, purchase_id=None, status=None, tags=None, transaction_ids=None, updated=None):
+        Resource.__init__(self, id=id)
+
+        self.amount = amount
+        self.due = check_datetime_or_date(due)
+        self.fee = fee
+        self.funding_type = funding_type
+        self.network = network
+        self.purchase_id = purchase_id
+        self.status = status
+        self.tags = tags
+        self.transaction_ids = transaction_ids
+        self.created = check_datetime(created)
+        self.updated = check_datetime(updated)
+
+_resource = {"class": MerchantInstallment, "name": "MerchantInstallment"}
+
+def get(id, user=None):
+    return rest.get_id(resource=_resource, id=id, user=user)
+
+
+def query(limit=None, after=None, before=None, status=None, tags=None, ids=None, user=None):
+    return rest.get_stream(
+        resource=_resource,
+        limit=limit,
+        after=check_date(after),
+        before=check_date(before),
+        status=status,
+        tags=tags,
+        ids=ids,
+        user=user,
+    )
+
+
+def page(cursor=None, limit=None, after=None, before=None, status=None, tags=None, ids=None, user=None):
+    return rest.get_page(
+        resource=_resource,
+        cursor=cursor,
+        limit=limit,
+        after=check_date(after),
+        before=check_date(before),
+        status=status,
+        tags=tags,
+        ids=ids,
+        user=user,
+    )
+

starkbank/merchantinstallment/log/__init__.py

@@ -0,0 +1 @@
+from .__log import query, page, get

starkbank/merchantinstallment/log/__log.py

@@ -0,0 +1,47 @@
+from starkcore.utils.resource import Resource
+from ...utils import rest
+from starkcore.utils.checks import check_date
+
+
+class Log(Resource):
+    """# MerchantInstallment object
+    Check out our API Documentation at https://starkbank.com/docs/api#merchant-installment
+    """
+
+    def __init__(self, id, created, updated, type, errors, installment):
+        Resource.__init__(self, id=id)
+        self.created = check_date(created)
+        self.updated = check_date(updated)
+        self.type = type
+        self.errors = errors
+        self.installment = installment
+
+_resource = {"class": Log, "name": "MerchantInstallmentLog"}
+
+
+def get(id, user=None):
+    return rest.get_id(resource=_resource, id=id, user=user)
+
+
+def query(limit=None, after=None, before=None, user=None):
+    return rest.get_stream(
+        resource=_resource,
+        limit=limit,
+        after=check_date(after),
+        before=check_date(before),
+        user=user,
+    )
+
+
+def page(cursor=None, limit=None, after=None, before=None, types=None, ids=None, user=None):
+    return rest.get_page(
+        resource=_resource,
+        cursor=cursor,
+        limit=limit,
+        after=check_date(after),
+        before=check_date(before),
+        types=types,
+        ids=ids,
+        user=user,
+    )
+

starkbank/merchantpurchase/__init__.py

@@ -0,0 +1,3 @@
+from .__merchantpurchase import get, query, page, create, update
+from .log.__log import Log
+from . import log