Merge pull request #131 from starkbank/feature/merchant-purchase

Add merchant session and merchant purchase

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,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
+    - [MerchantCard](#query-merchantcards): Stores information about approved purchase cards for reuse
+    - [MerchantSession](#create-a-merchantsession): Manages a session to create a purchase with a new card
+    - [MerchantPurchase](#create-a-merchantpurchase): Allows a merchant to charge their customers using debit or credit cards
+    - [MerchantInstallment](#query-merchantinstallments): Tracks the lifecycle of purchase installments
     - [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
@@ -2333,6 +2337,210 @@ log = starkbank.splitreceiver.log.get("5155165527080960")
 print(log)
 ```
 
+## Query MerchantCards
+
+Get a list of merchant cards in chunks of at most 100. If you need smaller chunks, use the limit parameter.
+
+```python
+import starkbank
+
+merchant_cards = starkbank.merchantcard.query(limit=3)
+for merchant_card in merchant_cards:
+    print(merchant_card)
+```
+
+## Get a MerchantCard
+
+Retrieve detailed information about a specific card by its id.
+
+```python
+import starkbank
+
+merchantcard = starkbank.merchantcard.get('5950134772826112')
+print(merchantcard)
+```
+
+## Create a MerchantSession
+
+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.
+
+```python
+import starkbank
+
+merchant_session = starkbank.merchantsession.create({
+    "allowedFundingTypes": [
+        "debit",
+        "credit"
+    ],
+    "allowedInstallments": [
+        {
+            "totalAmount": 0,
+            "count": 1
+        },
+        {
+            "totalAmount": 12000,
+            "count": 2
+        },
+        {
+            "totalAmount": 18000,
+            "count": 12
+        }
+    ],
+    "expiration": 3600,
+    "challengeMode": "disabled",
+    "tags": [
+        "your-tags"
+    ]
+})
+
+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
+
+This route can be used to create a Merchant Purchase directly from the payer's client application.
+The UUID of a Merchant Session that was previously created by the merchant is necessary to access this route.
+
+```python
+import starkbank
+
+merchant_session_purchase = starkbank.merchantsession.purchase(
+      uuid="0bb894a2697d41d99fe02cad2c00c9bc",
+      amount=18000,
+      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
+
+Get a list of merchant sessions in chunks of at most 100. If you need smaller chunks, use the limit parameter.
+
+```python
+import starkbank
+
+merchant_sessions = starkbank.merchantsession.query(limit=3)
+for merchant_session in merchant_sessions:
+    print(merchant_session)
+```
+
+## Get a MerchantSession
+
+Retrieve detailed information about a specific session by its id.
+
+```python
+import starkbank
+
+merchant_session = starkbank.merchantsession.get('5950134772826112')
+print(merchant_session)
+```
+
+## Create a MerchantPurchase
+
+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.
+
+```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
+
+Get a list of merchant purchases in chunks of at most 100. If you need smaller chunks, use the limit parameter.
+
+```python
+import starkbank
+
+merchant_purchases = starkbank.merchantpurchase.query(limit=3)
+for merchant_purchase in merchant_purchases:
+    print(merchant_purchase)
+```
+
+## Get a MerchantPurchase
+
+Retrieve detailed information about a specific purchase by its id.
+
+```python
+import starkbank
+
+merchant_purchase = starkbank.merchantpurchase.get('5950134772826112')
+print(merchant_purchase)
+```
+
+## Query MerchantInstallments
+
+Get a list of merchant installments in chunks of at most 100. If you need smaller chunks, use the limit parameter.
+
+```python
+import starkbank
+
+merchant_installments = starkbank.merchantinstallment.query(limit=3)
+for merchant_installment in merchant_installments:
+    print(merchant_installment)
+```
+
+## Get a MerchantInstallment
+
+Retrieve detailed information about a specific installment by its id.
+
+```python
+import starkbank
+
+merchant_installment = starkbank.merchantinstallment.get('5950134772826112')
+print(merchant_installment)
+```
+
 ## Create a webhook subscription
 
 To create a webhook subscription and be notified whenever an event occurs, run:

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,55 @@
+from ..utils import rest
+from starkcore.utils.resource import Resource
+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,53 @@
+from ...utils import rest
+from starkcore.utils.resource import Resource
+from starkcore.utils.api import from_api_json
+from starkcore.utils.checks import check_date, check_datetime
+from ..__merchantcard import _resource as _merchant_card_resource
+
+
+class Log(Resource):
+    """# merchantcard.Log 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_datetime(created)
+        self.updated = check_datetime(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, status=None, tags=None, ids=None, after=None, before=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, 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