kard-financial-sdk 0.0.82__py3-none-any.whl

kard/transactions/client.py

@@ -0,0 +1,639 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ..commons.types.organization_id import OrganizationId
+from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ..core.request_options import RequestOptions
+from .raw_client import AsyncRawTransactionsClient, RawTransactionsClient
+from .types.create_audit_request_data_union import CreateAuditRequestDataUnion
+from .types.create_audit_response_body import CreateAuditResponseBody
+from .types.fraudulent_transaction_data import FraudulentTransactionData
+from .types.fraudulent_transaction_object import FraudulentTransactionObject
+from .types.get_earned_rewards_response import GetEarnedRewardsResponse
+from .types.transactions import Transactions
+from .types.transactions_response import TransactionsResponse
+
+# this is used as the default value for optional parameters
+OMIT = typing.cast(typing.Any, ...)
+
+
+class TransactionsClient:
+    def __init__(self, *, client_wrapper: SyncClientWrapper):
+        self._raw_client = RawTransactionsClient(client_wrapper=client_wrapper)
+
+    @property
+    def with_raw_response(self) -> RawTransactionsClient:
+        """
+        Retrieves a raw implementation of this client that returns raw responses.
+
+        Returns
+        -------
+        RawTransactionsClient
+        """
+        return self._raw_client
+
+    def create(
+        self,
+        organization_id: OrganizationId,
+        *,
+        data: typing.Sequence[Transactions],
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> TransactionsResponse:
+        """
+        Call this endpoint to send all transactions made by all your enrolled users in your rewards program. The request body will depend on the transaction type.<br/>
+        Please use the correct type when calling the endpoint:
+        - `transaction`: These incoming transactions will be processed and matched by the Kard system. Learn more about the [Transaction CLO Matching](https://github.com/kard-financial/kard-postman#c-transaction-clo-matching) flow here.
+        - `matchedTransaction`: For pre-matched transactions that need validation on match by the Kard system.<br/>
+
+        <b>Required scopes:</b> `transaction:write`<br/>
+        <b>Note:</b> `Maximum of 500 transactions can be created per request`.
+
+        Parameters
+        ----------
+        organization_id : OrganizationId
+
+        data : typing.Sequence[Transactions]
+            Discriminated union representing the request body for submitting a transaction.
+            Use `type` to distinguish between the two:
+            - `transaction`: For transactions requiring processing and matching by the Kard system.
+            - `matchedTransaction`: For pre-matched transactions that need validation on match by the Kard system.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        TransactionsResponse
+
+        Examples
+        --------
+        import datetime
+
+        from kard import KardApi
+        from kard.transactions import (
+            Merchant,
+            ProcessorMid_Visa,
+            Transactions_Transaction,
+            TransactionsAttributes,
+            VisaMidDetails,
+        )
+
+        client = KardApi(
+            client_id="YOUR_CLIENT_ID",
+            client_secret="YOUR_CLIENT_SECRET",
+        )
+        client.transactions.create(
+            organization_id="organization-123",
+            data=[
+                Transactions_Transaction(
+                    id="309rjfoincor3icno3rind093cdow3jciwjdwcm",
+                    attributes=TransactionsAttributes(
+                        user_id="6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
+                        status="APPROVED",
+                        amount=1000,
+                        subtotal=800,
+                        currency="USD",
+                        direction="DEBIT",
+                        payment_type="CARD",
+                        description="ADVANCEAUTO",
+                        description_2="ADVANCEAUTO",
+                        mcc="1234",
+                        card_bin="123456",
+                        card_last_four="4321",
+                        authorization_date=datetime.datetime.fromisoformat(
+                            "2021-07-02 17:47:06+00:00",
+                        ),
+                        merchant=Merchant(
+                            id="12345678901234567",
+                            name="ADVANCEAUTO",
+                            addr_street="125 Main St",
+                            addr_city="Philadelphia",
+                            addr_state="PA",
+                            addr_zipcode="19147",
+                            addr_country="United States",
+                            latitude="37.9419429",
+                            longitude="-73.1446869",
+                            store_id="12345",
+                        ),
+                        authorization_code="123456",
+                        retrieval_reference_number="100804333919",
+                        acquirer_reference_number="1234567890123456789012345678",
+                        system_trace_audit_number="333828",
+                        transaction_id="2467de37-cbdc-416d-a359-75de87bfffb0",
+                        card_product_id="1234567890123456789012345678",
+                        processor_mids=ProcessorMid_Visa(
+                            mids=VisaMidDetails(
+                                vmid="12345678901",
+                                vsid="12345678",
+                            ),
+                        ),
+                    ),
+                )
+            ],
+        )
+        """
+        _response = self._raw_client.create(organization_id, data=data, request_options=request_options)
+        return _response.data
+
+    def create_fraud_markers(
+        self,
+        organization_id: OrganizationId,
+        *,
+        data: typing.Sequence[FraudulentTransactionData],
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> FraudulentTransactionObject:
+        """
+        Call this endpoint to flag a submitted transaction as fraudulent. This will prevent it from being rewarded.<br/>
+
+        <b>Required scopes:</b>&nbsp;&nbsp;`transaction:write`<br/>
+        <b>Note:</b> `Maximum of 500 fraudulent transactions can be created per request`.
+
+        Parameters
+        ----------
+        organization_id : OrganizationId
+
+        data : typing.Sequence[FraudulentTransactionData]
+            List of fraudulent transactions to report
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        FraudulentTransactionObject
+
+        Examples
+        --------
+        from kard import KardApi
+        from kard.transactions import (
+            FraudulentTransactionAttributes,
+            FraudulentTransactionData,
+        )
+
+        client = KardApi(
+            client_id="YOUR_CLIENT_ID",
+            client_secret="YOUR_CLIENT_SECRET",
+        )
+        client.transactions.create_fraud_markers(
+            organization_id="organization-123",
+            data=[
+                FraudulentTransactionData(
+                    id="myTxnId12345",
+                    type="fraudulentTransaction",
+                    attributes=FraudulentTransactionAttributes(
+                        user_id="userId123",
+                    ),
+                )
+            ],
+        )
+        """
+        _response = self._raw_client.create_fraud_markers(organization_id, data=data, request_options=request_options)
+        return _response.data
+
+    def create_audits(
+        self,
+        organization_id: OrganizationId,
+        user_id: str,
+        *,
+        data: typing.Sequence[CreateAuditRequestDataUnion],
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> CreateAuditResponseBody:
+        """
+        Call this endpoint to request that a particular transaction be audited further by the Kard system, in the event of a missing cashback claim, incorrect cashback amount claim or other mis-match claims.<br/>
+        <b>Required scopes:</b> `audit:write`
+
+        Parameters
+        ----------
+        organization_id : OrganizationId
+
+        user_id : str
+            The ID of the user as defined on the issuers system
+
+        data : typing.Sequence[CreateAuditRequestDataUnion]
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        CreateAuditResponseBody
+
+        Examples
+        --------
+        from kard import KardApi
+        from kard.transactions import AuditAttributes, CreateAuditRequestDataUnion_Audit
+
+        client = KardApi(
+            client_id="YOUR_CLIENT_ID",
+            client_secret="YOUR_CLIENT_SECRET",
+        )
+        client.transactions.create_audits(
+            organization_id="organization-123",
+            user_id="user-123",
+            data=[
+                CreateAuditRequestDataUnion_Audit(
+                    attributes=AuditAttributes(
+                        audit_code=8001,
+                        merchant_name="Caribbean Goodness",
+                        audit_description="duplicate transaction",
+                        transaction_id="issuerTransaction123",
+                    ),
+                )
+            ],
+        )
+        """
+        _response = self._raw_client.create_audits(organization_id, user_id, data=data, request_options=request_options)
+        return _response.data
+
+    def get_earned_rewards(
+        self,
+        organization_id: OrganizationId,
+        user_id: str,
+        *,
+        page_after: typing.Optional[str] = None,
+        page_before: typing.Optional[str] = None,
+        page_size: typing.Optional[int] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> GetEarnedRewardsResponse:
+        """
+        Retrieve rewarded transaction history for a specific user. Returns only SETTLED transactions within the last 12 months.
+        <br/>
+        <b>Required scopes:</b> `transaction:read`
+        <br/>
+        <b>Query Limit:</b> Maximum of 12 months of transaction data can be queried.
+
+        Parameters
+        ----------
+        organization_id : OrganizationId
+
+        user_id : str
+            The ID of the user as defined on the issuers system
+
+        page_after : typing.Optional[str]
+            Cursor for next page (base64-encoded timestamp + transaction ID)
+
+        page_before : typing.Optional[str]
+            Cursor for previous page (base64-encoded timestamp + transaction ID)
+
+        page_size : typing.Optional[int]
+            Number of results per page
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        GetEarnedRewardsResponse
+
+        Examples
+        --------
+        from kard import KardApi
+
+        client = KardApi(
+            client_id="YOUR_CLIENT_ID",
+            client_secret="YOUR_CLIENT_SECRET",
+        )
+        client.transactions.get_earned_rewards(
+            organization_id="org-123",
+            user_id="user-456",
+            page_size=10,
+        )
+        """
+        _response = self._raw_client.get_earned_rewards(
+            organization_id,
+            user_id,
+            page_after=page_after,
+            page_before=page_before,
+            page_size=page_size,
+            request_options=request_options,
+        )
+        return _response.data
+
+
+class AsyncTransactionsClient:
+    def __init__(self, *, client_wrapper: AsyncClientWrapper):
+        self._raw_client = AsyncRawTransactionsClient(client_wrapper=client_wrapper)
+
+    @property
+    def with_raw_response(self) -> AsyncRawTransactionsClient:
+        """
+        Retrieves a raw implementation of this client that returns raw responses.
+
+        Returns
+        -------
+        AsyncRawTransactionsClient
+        """
+        return self._raw_client
+
+    async def create(
+        self,
+        organization_id: OrganizationId,
+        *,
+        data: typing.Sequence[Transactions],
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> TransactionsResponse:
+        """
+        Call this endpoint to send all transactions made by all your enrolled users in your rewards program. The request body will depend on the transaction type.<br/>
+        Please use the correct type when calling the endpoint:
+        - `transaction`: These incoming transactions will be processed and matched by the Kard system. Learn more about the [Transaction CLO Matching](https://github.com/kard-financial/kard-postman#c-transaction-clo-matching) flow here.
+        - `matchedTransaction`: For pre-matched transactions that need validation on match by the Kard system.<br/>
+
+        <b>Required scopes:</b> `transaction:write`<br/>
+        <b>Note:</b> `Maximum of 500 transactions can be created per request`.
+
+        Parameters
+        ----------
+        organization_id : OrganizationId
+
+        data : typing.Sequence[Transactions]
+            Discriminated union representing the request body for submitting a transaction.
+            Use `type` to distinguish between the two:
+            - `transaction`: For transactions requiring processing and matching by the Kard system.
+            - `matchedTransaction`: For pre-matched transactions that need validation on match by the Kard system.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        TransactionsResponse
+
+        Examples
+        --------
+        import asyncio
+        import datetime
+
+        from kard import AsyncKardApi
+        from kard.transactions import (
+            Merchant,
+            ProcessorMid_Visa,
+            Transactions_Transaction,
+            TransactionsAttributes,
+            VisaMidDetails,
+        )
+
+        client = AsyncKardApi(
+            client_id="YOUR_CLIENT_ID",
+            client_secret="YOUR_CLIENT_SECRET",
+        )
+
+
+        async def main() -> None:
+            await client.transactions.create(
+                organization_id="organization-123",
+                data=[
+                    Transactions_Transaction(
+                        id="309rjfoincor3icno3rind093cdow3jciwjdwcm",
+                        attributes=TransactionsAttributes(
+                            user_id="6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
+                            status="APPROVED",
+                            amount=1000,
+                            subtotal=800,
+                            currency="USD",
+                            direction="DEBIT",
+                            payment_type="CARD",
+                            description="ADVANCEAUTO",
+                            description_2="ADVANCEAUTO",
+                            mcc="1234",
+                            card_bin="123456",
+                            card_last_four="4321",
+                            authorization_date=datetime.datetime.fromisoformat(
+                                "2021-07-02 17:47:06+00:00",
+                            ),
+                            merchant=Merchant(
+                                id="12345678901234567",
+                                name="ADVANCEAUTO",
+                                addr_street="125 Main St",
+                                addr_city="Philadelphia",
+                                addr_state="PA",
+                                addr_zipcode="19147",
+                                addr_country="United States",
+                                latitude="37.9419429",
+                                longitude="-73.1446869",
+                                store_id="12345",
+                            ),
+                            authorization_code="123456",
+                            retrieval_reference_number="100804333919",
+                            acquirer_reference_number="1234567890123456789012345678",
+                            system_trace_audit_number="333828",
+                            transaction_id="2467de37-cbdc-416d-a359-75de87bfffb0",
+                            card_product_id="1234567890123456789012345678",
+                            processor_mids=ProcessorMid_Visa(
+                                mids=VisaMidDetails(
+                                    vmid="12345678901",
+                                    vsid="12345678",
+                                ),
+                            ),
+                        ),
+                    )
+                ],
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.create(organization_id, data=data, request_options=request_options)
+        return _response.data
+
+    async def create_fraud_markers(
+        self,
+        organization_id: OrganizationId,
+        *,
+        data: typing.Sequence[FraudulentTransactionData],
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> FraudulentTransactionObject:
+        """
+        Call this endpoint to flag a submitted transaction as fraudulent. This will prevent it from being rewarded.<br/>
+
+        <b>Required scopes:</b>&nbsp;&nbsp;`transaction:write`<br/>
+        <b>Note:</b> `Maximum of 500 fraudulent transactions can be created per request`.
+
+        Parameters
+        ----------
+        organization_id : OrganizationId
+
+        data : typing.Sequence[FraudulentTransactionData]
+            List of fraudulent transactions to report
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        FraudulentTransactionObject
+
+        Examples
+        --------
+        import asyncio
+
+        from kard import AsyncKardApi
+        from kard.transactions import (
+            FraudulentTransactionAttributes,
+            FraudulentTransactionData,
+        )
+
+        client = AsyncKardApi(
+            client_id="YOUR_CLIENT_ID",
+            client_secret="YOUR_CLIENT_SECRET",
+        )
+
+
+        async def main() -> None:
+            await client.transactions.create_fraud_markers(
+                organization_id="organization-123",
+                data=[
+                    FraudulentTransactionData(
+                        id="myTxnId12345",
+                        type="fraudulentTransaction",
+                        attributes=FraudulentTransactionAttributes(
+                            user_id="userId123",
+                        ),
+                    )
+                ],
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.create_fraud_markers(
+            organization_id, data=data, request_options=request_options
+        )
+        return _response.data
+
+    async def create_audits(
+        self,
+        organization_id: OrganizationId,
+        user_id: str,
+        *,
+        data: typing.Sequence[CreateAuditRequestDataUnion],
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> CreateAuditResponseBody:
+        """
+        Call this endpoint to request that a particular transaction be audited further by the Kard system, in the event of a missing cashback claim, incorrect cashback amount claim or other mis-match claims.<br/>
+        <b>Required scopes:</b> `audit:write`
+
+        Parameters
+        ----------
+        organization_id : OrganizationId
+
+        user_id : str
+            The ID of the user as defined on the issuers system
+
+        data : typing.Sequence[CreateAuditRequestDataUnion]
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        CreateAuditResponseBody
+
+        Examples
+        --------
+        import asyncio
+
+        from kard import AsyncKardApi
+        from kard.transactions import AuditAttributes, CreateAuditRequestDataUnion_Audit
+
+        client = AsyncKardApi(
+            client_id="YOUR_CLIENT_ID",
+            client_secret="YOUR_CLIENT_SECRET",
+        )
+
+
+        async def main() -> None:
+            await client.transactions.create_audits(
+                organization_id="organization-123",
+                user_id="user-123",
+                data=[
+                    CreateAuditRequestDataUnion_Audit(
+                        attributes=AuditAttributes(
+                            audit_code=8001,
+                            merchant_name="Caribbean Goodness",
+                            audit_description="duplicate transaction",
+                            transaction_id="issuerTransaction123",
+                        ),
+                    )
+                ],
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.create_audits(
+            organization_id, user_id, data=data, request_options=request_options
+        )
+        return _response.data
+
+    async def get_earned_rewards(
+        self,
+        organization_id: OrganizationId,
+        user_id: str,
+        *,
+        page_after: typing.Optional[str] = None,
+        page_before: typing.Optional[str] = None,
+        page_size: typing.Optional[int] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> GetEarnedRewardsResponse:
+        """
+        Retrieve rewarded transaction history for a specific user. Returns only SETTLED transactions within the last 12 months.
+        <br/>
+        <b>Required scopes:</b> `transaction:read`
+        <br/>
+        <b>Query Limit:</b> Maximum of 12 months of transaction data can be queried.
+
+        Parameters
+        ----------
+        organization_id : OrganizationId
+
+        user_id : str
+            The ID of the user as defined on the issuers system
+
+        page_after : typing.Optional[str]
+            Cursor for next page (base64-encoded timestamp + transaction ID)
+
+        page_before : typing.Optional[str]
+            Cursor for previous page (base64-encoded timestamp + transaction ID)
+
+        page_size : typing.Optional[int]
+            Number of results per page
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        GetEarnedRewardsResponse
+
+        Examples
+        --------
+        import asyncio
+
+        from kard import AsyncKardApi
+
+        client = AsyncKardApi(
+            client_id="YOUR_CLIENT_ID",
+            client_secret="YOUR_CLIENT_SECRET",
+        )
+
+
+        async def main() -> None:
+            await client.transactions.get_earned_rewards(
+                organization_id="org-123",
+                user_id="user-456",
+                page_size=10,
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.get_earned_rewards(
+            organization_id,
+            user_id,
+            page_after=page_after,
+            page_before=page_before,
+            page_size=page_size,
+            request_options=request_options,
+        )
+        return _response.data

kard/transactions/errors/__init__.py

@@ -0,0 +1,40 @@
+# This file was auto-generated by Fern from our API Definition.
+
+# isort: skip_file
+
+import typing
+from importlib import import_module
+
+if typing.TYPE_CHECKING:
+    from .create_audit_multi_status import CreateAuditMultiStatus
+    from .create_incoming_transactions_multi_status import CreateIncomingTransactionsMultiStatus
+    from .fraud_multi_status import FraudMultiStatus
+_dynamic_imports: typing.Dict[str, str] = {
+    "CreateAuditMultiStatus": ".create_audit_multi_status",
+    "CreateIncomingTransactionsMultiStatus": ".create_incoming_transactions_multi_status",
+    "FraudMultiStatus": ".fraud_multi_status",
+}
+
+
+def __getattr__(attr_name: str) -> typing.Any:
+    module_name = _dynamic_imports.get(attr_name)
+    if module_name is None:
+        raise AttributeError(f"No {attr_name} found in _dynamic_imports for module name -> {__name__}")
+    try:
+        module = import_module(module_name, __package__)
+        if module_name == f".{attr_name}":
+            return module
+        else:
+            return getattr(module, attr_name)
+    except ImportError as e:
+        raise ImportError(f"Failed to import {attr_name} from {module_name}: {e}") from e
+    except AttributeError as e:
+        raise AttributeError(f"Failed to get {attr_name} from {module_name}: {e}") from e
+
+
+def __dir__():
+    lazy_attrs = list(_dynamic_imports.keys())
+    return sorted(lazy_attrs)
+
+
+__all__ = ["CreateAuditMultiStatus", "CreateIncomingTransactionsMultiStatus", "FraudMultiStatus"]

kard/transactions/errors/create_audit_multi_status.py

@@ -0,0 +1,11 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ...core.api_error import ApiError
+from ..types.create_audit_multi_status_response import CreateAuditMultiStatusResponse
+
+
+class CreateAuditMultiStatus(ApiError):
+    def __init__(self, body: CreateAuditMultiStatusResponse, headers: typing.Optional[typing.Dict[str, str]] = None):
+        super().__init__(status_code=207, headers=headers, body=body)

kard/transactions/errors/create_incoming_transactions_multi_status.py

@@ -0,0 +1,11 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ...core.api_error import ApiError
+from ..types.transactions_multi_response import TransactionsMultiResponse
+
+
+class CreateIncomingTransactionsMultiStatus(ApiError):
+    def __init__(self, body: TransactionsMultiResponse, headers: typing.Optional[typing.Dict[str, str]] = None):
+        super().__init__(status_code=207, headers=headers, body=body)