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 resource can be used to charge customers with credit or debit cards. If a card hasn't been used before, a Merchant Session Purchase must be created and approved with that specific card before it can be used directly in a Merchant Purchase.
     - [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,146 @@ 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="Margaery Tyrell",
+  holder_email="[email protected]",
+  holder_phone="11998663456",
+  funding_type="credit",
+  billing_country_code="BRA",
+  billing_city="São Paulo",
+  billing_state_code="SP",
+  billing_street_line1="Rua do Jardim de cima, 123",
+  billing_street_line2="1 andar",
+  billing_zip_code="11111-111",
+  metadata={
+    "extraData": "extraData",
+    "language": "pt-BR",
+    "timezoneOffset": 3,
+    "userAgent": "Mozilla",
+    "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 resource can be used to charge customers with credit or debit cards.
+If a card hasn't been used before, a Merchant Session Purchase must be created and approved with that specific card before it can be used directly in a Merchant Purchase.
+
+### Create a MerchantPurchases
+```python
+import starkbank
+
+merchant_purchase = starkbank.merchantpurchase.create(
+            starkbank.MerchantPurchase(
+                amount=10000,
+                installment_count=5,
+                card_id="6295415968235520",
+                funding_type="credit",
+                challenge_mode="disabled",
+                billing_city="Sao Paulo",
+                billing_country_code="BRA",
+                billing_state_code="SP",
+                billing_street_line_1="Rua Casterly Rock, 2000",
+                billing_street_line_2="1 andar",
+                billing_zip_code="11111-111",
+                holder_email="[email protected]",
+                holder_phone="11985923451",
+                metadata={
+                    "userAgent": "userAgent",
+                    "userIp": "255.255.255.255",
+                    "language": "pt-BR",
+                    "timezoneOffset": 3,
+                    "extraData": "extraData"
+                },
+                tags=["teste"]
+            )
+        )
+```
+
+### 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, check_datetime_or_date
+
+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 = check_datetime_or_date(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,49 @@
+from starkcore.utils.resource import Resource
+from ...utils import rest
+from starkcore.utils.api import from_api_json
+from starkcore.utils.checks import check_date
+from ..__merchantcard import _resource as _merchant_card_resource
+
+
+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 = from_api_json(_merchant_card_resource, 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