Instant settlement service

InstantSettlementService

Bases: BaseAPIWrapper

Source code in pykuda2/wrappers/sync_wrappers/instant_settlement_service.py

class InstantSettlementService(BaseAPIWrapper):
    def __init__(self, secret_key: str, client_password: str, mode=Mode.DEVELOPMENT):
        super().__init__(email="", api_key="", mode=mode)
        self.secret_key = secret_key
        self.client_password = client_password

    @property
    def _base_url(self) -> str:
        """Returns the base url.

        The url returned depends on the mode in which the class was instantiated."""
        return {
            Mode.DEVELOPMENT: "https://partners-uat.kudabank.com",
            Mode.PRODUCTION: "https://partners.kuda.com",
        }[self._mode]

    @property
    def _token(self) -> str:
        if self._token:
            return self._token
        else:
            response = self._api_call(
                service_type=ServiceType.NO_OP,
                data={
                    "secretKey": self.secret_key,
                    "clientPassword": self.client_password,
                },
                endpoint_path="/api/Auth/authenticate",
                exclude_auth_header=True,
            )
            if response.data:
                self._token = response.data["auth_token"]
                return self._token
            raise TokenException(
                "Unable to get access token for InstantSettlementService. "
                f"{response.message}. Please ensure valid credentials were provided"
            )

    def create_terminal(
        self,
        terminal_id: str,
        merchant_id: str,
        kuda_account_number: int,
        serial_number: str,
        is_receiving_payment: bool,
        is_active: bool,
    ) -> APIResponse:
        """Gives the partner the ability to add certain parameters to a POS device.

        It allows the partner to anchor routing communications between the processor and the Kuda settlement system.

        Args:
            terminal_id: The terminal identifier.
            merchant_id: The merchant identifier.
            kuda_account_number: The client's Kuda account number.
            serial_number: The serial number.
            is_receiving_payment: Set to `True` for receiving payment or `False` for otherwise.
            is_active: Set to `True` for an active terminal or `False` for otherwise.

        Returns:
            An `APIResponse` which is basically just a dataclass containing the data returned by the server as result
                of calling this function.

        Raises:
            ConnectionException: when the request times out or in the absence of an internet connection.
        """
        payload = {
            "terminalId": terminal_id,
            "merchantId": merchant_id,
            "kudaAccountNumber": kuda_account_number,
            "serialNumber": serial_number,
            "isReceivingPayment": is_receiving_payment,
            "isActive": is_active,
        }
        return self._api_call(
            service_type=ServiceType.NO_OP,
            data=payload,
            endpoint_path="/api/terminal/api/terminal/createterminal",
        )

    def update_terminal(
        self,
        kuda_merchant_id: str,
        terminal_id: str,
        kuda_account_number: int,
        kuda_account_name: str,
        serial_number: str,
        is_active: bool,
        is_receiving_payment: bool,
        fee_percentage: float,
        date_created: str,
    ) -> APIResponse:
        """Allows a partner to swap the location and user of a POS device.

        Args:
            kuda_merchant_id: The client's Kuda merchant identifier
            terminal_id: The  terminal unique identifier
            kuda_account_number: The client's Kuda account number
            kuda_account_name: The client's account name
            serial_number: The terminal's serial number
            is_active: Set to `True` for an active terminal or otherwise.
            is_receiving_payment: Set to `True` if the terminal is receiving payment else otherwise.
            fee_percentage: Fee percentage
            date_created: The date the terminal was created

        Returns:
            An `APIResponse` which is basically just a dataclass containing the data returned by the server as result
                of calling this function.

        Raises:
            ConnectionException: when the request times out or in the absence of an internet connection.
        """
        payload = {
            "id": id,
            "kudaMerchantId": kuda_merchant_id,
            "terminalId": terminal_id,
            "kudaAccountNumber": kuda_account_number,
            "kudaAccountName": kuda_account_name,
            "serialNumber": serial_number,
            "isActive": is_active,
            "isReceivingPayment": is_receiving_payment,
            "feePercentage": fee_percentage,
            "dateCreated": date_created,
        }
        return self._api_call(
            service_type=ServiceType.NO_OP,
            data=payload,
            endpoint_path="/api/terminal/EditTerminal",
        )

    def all(self, page_size: int, page_number: int) -> APIResponse:
        """Allows a user to get all merchants and the terminals assigned to them.

        Args:
            page_size: This specifies the maximum number of terminals to be retrieved.
            page_number: This specifies the index of the paginated results retrieved.

        Returns:
            An `APIResponse` which is basically just a dataclass containing the data returned by the server as result
                of calling this function.

        Raises:
            ConnectionException: when the request times out or in the absence of an internet connection.
        """
        payload = {"pageSize": page_size, "pageNumber": page_number}
        return self._api_call(
            service_type=ServiceType.NO_OP,
            data=payload,
            endpoint_path="/RetrieveMerchantTerminals",
        )

    def get_settlement_status(self, transaction_id: str) -> APIResponse:
        """Retrieves insight on the status of a particular/all settlements for a terminal.

        Args:
            transaction_id: The transaction reference number or unique identifier.

        Returns:
            An `APIResponse` which is basically just a dataclass containing the data returned by the server as result
                of calling this function.

        Raises:
            ConnectionException: when the request times out or in the absence of an internet connection.
        """
        payload = {"transactionId": transaction_id}
        return self._api_call(
            service_type=ServiceType.NO_OP,
            data=payload,
            endpoint_path="/api/terminal/settlementstatus",
        )

    def log_transaction(
        self, amount: Union[int, float], transaction_id: str, terminal_id: str
    ) -> APIResponse:
        """Logs a complete transaction.

        For complete transaction fulfilment, a user will call this method with the transaction amount
        that needs to be fulfilled. This way, the terminal management system is updated with the transaction
        status in real-time and completes settlement to the specified user's account.

        Logging a transaction sends a notification to Kuda which triggers instant settlement.

        Args:
            amount: The transaction amount. Note care should be taken when performing calculations as money is involved.
                a `Decimal` would have been the preferred type compared to `Union[int, float]` that was used.
                it is advisable that static values are passed for this parameter. see
                https://stackoverflow.com/questions/3730019/why-not-use-double-or-float-to-represent-currency
            transaction_id: The transaction reference number or unique identifier.
            terminal_id: The terminal unique identifier.

        Returns:
            An `APIResponse` which is basically just a dataclass containing the data returned by the server as result
                of calling this function.

        Raises:
            ConnectionException: when the request times out or in the absence of an internet connection.
        """
        payload = {
            "amount": amount,
            "transactionId": transaction_id,
            "terminalId": terminal_id,
        }
        return self._api_call(
            service_type=ServiceType.NO_OP,
            data=payload,
            endpoint_path="/api/terminal/logtransaction",
        )

    def transactions(
        self, terminal_id: str, from_: str, to: str, page_size: int, page_number: int
    ) -> APIResponse:
        """Retrieves transactions.

        This method allows a user to do back office operations while searching for transactions disputes.

        Args:
            terminal_id: The terminal unique identifier
            from_: The start date
            to: The end date
            page_size: This specifies the maximum number of transactions to be retrieved.
            page_number: This specifies the index of the paginated results retrieved.

        Returns:
            An `APIResponse` which is basically just a dataclass containing the data returned by the server as result
                of calling this function.

        Raises:
            ConnectionException: when the request times out or in the absence of an internet connection.
        """
        payload = {
            "terminalId": terminal_id,
            "dateFrom": from_,
            "dateTo": to,
            "pageSize": page_size,
            "pageNumber": page_number,
        }
        return self._api_call(
            service_type=ServiceType.NO_OP,
            data=payload,
            endpoint_path="/api/terminal/searchtransaction",
        )

all(page_size, page_number)

Allows a user to get all merchants and the terminals assigned to them.

Parameters:

Name	Type	Description	Default
page_size	int	This specifies the maximum number of terminals to be retrieved.	required
page_number	int	This specifies the index of the paginated results retrieved.	required

Returns:

Type	Description
APIResponse	An APIResponse which is basically just a dataclass containing the data returned by the server as result of calling this function.

Raises:

Type	Description
ConnectionException	when the request times out or in the absence of an internet connection.

Source code in pykuda2/wrappers/sync_wrappers/instant_settlement_service.py

def all(self, page_size: int, page_number: int) -> APIResponse:
    """Allows a user to get all merchants and the terminals assigned to them.

    Args:
        page_size: This specifies the maximum number of terminals to be retrieved.
        page_number: This specifies the index of the paginated results retrieved.

    Returns:
        An `APIResponse` which is basically just a dataclass containing the data returned by the server as result
            of calling this function.

    Raises:
        ConnectionException: when the request times out or in the absence of an internet connection.
    """
    payload = {"pageSize": page_size, "pageNumber": page_number}
    return self._api_call(
        service_type=ServiceType.NO_OP,
        data=payload,
        endpoint_path="/RetrieveMerchantTerminals",
    )

create_terminal(terminal_id, merchant_id, kuda_account_number, serial_number, is_receiving_payment, is_active)

Gives the partner the ability to add certain parameters to a POS device.

It allows the partner to anchor routing communications between the processor and the Kuda settlement system.

Parameters:

Name	Type	Description	Default
terminal_id	str	The terminal identifier.	required
merchant_id	str	The merchant identifier.	required
kuda_account_number	int	The client's Kuda account number.	required
serial_number	str	The serial number.	required
is_receiving_payment	bool	Set to True for receiving payment or False for otherwise.	required
is_active	bool	Set to True for an active terminal or False for otherwise.	required

Returns:

Type	Description
APIResponse	An APIResponse which is basically just a dataclass containing the data returned by the server as result of calling this function.

Raises:

Type	Description
ConnectionException	when the request times out or in the absence of an internet connection.

Source code in pykuda2/wrappers/sync_wrappers/instant_settlement_service.py

def create_terminal(
    self,
    terminal_id: str,
    merchant_id: str,
    kuda_account_number: int,
    serial_number: str,
    is_receiving_payment: bool,
    is_active: bool,
) -> APIResponse:
    """Gives the partner the ability to add certain parameters to a POS device.

    It allows the partner to anchor routing communications between the processor and the Kuda settlement system.

    Args:
        terminal_id: The terminal identifier.
        merchant_id: The merchant identifier.
        kuda_account_number: The client's Kuda account number.
        serial_number: The serial number.
        is_receiving_payment: Set to `True` for receiving payment or `False` for otherwise.
        is_active: Set to `True` for an active terminal or `False` for otherwise.

    Returns:
        An `APIResponse` which is basically just a dataclass containing the data returned by the server as result
            of calling this function.

    Raises:
        ConnectionException: when the request times out or in the absence of an internet connection.
    """
    payload = {
        "terminalId": terminal_id,
        "merchantId": merchant_id,
        "kudaAccountNumber": kuda_account_number,
        "serialNumber": serial_number,
        "isReceivingPayment": is_receiving_payment,
        "isActive": is_active,
    }
    return self._api_call(
        service_type=ServiceType.NO_OP,
        data=payload,
        endpoint_path="/api/terminal/api/terminal/createterminal",
    )

get_settlement_status(transaction_id)

Retrieves insight on the status of a particular/all settlements for a terminal.

Parameters:

Name	Type	Description	Default
transaction_id	str	The transaction reference number or unique identifier.	required

Returns:

Type	Description
APIResponse	An APIResponse which is basically just a dataclass containing the data returned by the server as result of calling this function.

Raises:

Type	Description
ConnectionException	when the request times out or in the absence of an internet connection.

Source code in pykuda2/wrappers/sync_wrappers/instant_settlement_service.py

def get_settlement_status(self, transaction_id: str) -> APIResponse:
    """Retrieves insight on the status of a particular/all settlements for a terminal.

    Args:
        transaction_id: The transaction reference number or unique identifier.

    Returns:
        An `APIResponse` which is basically just a dataclass containing the data returned by the server as result
            of calling this function.

    Raises:
        ConnectionException: when the request times out or in the absence of an internet connection.
    """
    payload = {"transactionId": transaction_id}
    return self._api_call(
        service_type=ServiceType.NO_OP,
        data=payload,
        endpoint_path="/api/terminal/settlementstatus",
    )

log_transaction(amount, transaction_id, terminal_id)

Logs a complete transaction.

For complete transaction fulfilment, a user will call this method with the transaction amount that needs to be fulfilled. This way, the terminal management system is updated with the transaction status in real-time and completes settlement to the specified user's account.

Logging a transaction sends a notification to Kuda which triggers instant settlement.

Parameters:

Name	Type	Description	Default
amount	Union[int, float]	The transaction amount. Note care should be taken when performing calculations as money is involved. a Decimal would have been the preferred type compared to Union[int, float] that was used. it is advisable that static values are passed for this parameter. see https://stackoverflow.com/questions/3730019/why-not-use-double-or-float-to-represent-currency	required
transaction_id	str	The transaction reference number or unique identifier.	required
terminal_id	str	The terminal unique identifier.	required

Returns:

Type	Description
APIResponse	An APIResponse which is basically just a dataclass containing the data returned by the server as result of calling this function.

Raises:

Type	Description
ConnectionException	when the request times out or in the absence of an internet connection.

Source code in pykuda2/wrappers/sync_wrappers/instant_settlement_service.py

def log_transaction(
    self, amount: Union[int, float], transaction_id: str, terminal_id: str
) -> APIResponse:
    """Logs a complete transaction.

    For complete transaction fulfilment, a user will call this method with the transaction amount
    that needs to be fulfilled. This way, the terminal management system is updated with the transaction
    status in real-time and completes settlement to the specified user's account.

    Logging a transaction sends a notification to Kuda which triggers instant settlement.

    Args:
        amount: The transaction amount. Note care should be taken when performing calculations as money is involved.
            a `Decimal` would have been the preferred type compared to `Union[int, float]` that was used.
            it is advisable that static values are passed for this parameter. see
            https://stackoverflow.com/questions/3730019/why-not-use-double-or-float-to-represent-currency
        transaction_id: The transaction reference number or unique identifier.
        terminal_id: The terminal unique identifier.

    Returns:
        An `APIResponse` which is basically just a dataclass containing the data returned by the server as result
            of calling this function.

    Raises:
        ConnectionException: when the request times out or in the absence of an internet connection.
    """
    payload = {
        "amount": amount,
        "transactionId": transaction_id,
        "terminalId": terminal_id,
    }
    return self._api_call(
        service_type=ServiceType.NO_OP,
        data=payload,
        endpoint_path="/api/terminal/logtransaction",
    )

transactions(terminal_id, from_, to, page_size, page_number)

Retrieves transactions.

This method allows a user to do back office operations while searching for transactions disputes.

Parameters:

Name	Type	Description	Default
terminal_id	str	The terminal unique identifier	required
from_	str	The start date	required
to	str	The end date	required
page_size	int	This specifies the maximum number of transactions to be retrieved.	required
page_number	int	This specifies the index of the paginated results retrieved.	required

Returns:

Type	Description
APIResponse	An APIResponse which is basically just a dataclass containing the data returned by the server as result of calling this function.

Raises:

Type	Description
ConnectionException	when the request times out or in the absence of an internet connection.

Source code in pykuda2/wrappers/sync_wrappers/instant_settlement_service.py

def transactions(
    self, terminal_id: str, from_: str, to: str, page_size: int, page_number: int
) -> APIResponse:
    """Retrieves transactions.

    This method allows a user to do back office operations while searching for transactions disputes.

    Args:
        terminal_id: The terminal unique identifier
        from_: The start date
        to: The end date
        page_size: This specifies the maximum number of transactions to be retrieved.
        page_number: This specifies the index of the paginated results retrieved.

    Returns:
        An `APIResponse` which is basically just a dataclass containing the data returned by the server as result
            of calling this function.

    Raises:
        ConnectionException: when the request times out or in the absence of an internet connection.
    """
    payload = {
        "terminalId": terminal_id,
        "dateFrom": from_,
        "dateTo": to,
        "pageSize": page_size,
        "pageNumber": page_number,
    }
    return self._api_call(
        service_type=ServiceType.NO_OP,
        data=payload,
        endpoint_path="/api/terminal/searchtransaction",
    )

update_terminal(kuda_merchant_id, terminal_id, kuda_account_number, kuda_account_name, serial_number, is_active, is_receiving_payment, fee_percentage, date_created)

Allows a partner to swap the location and user of a POS device.

Parameters:

Name	Type	Description	Default
kuda_merchant_id	str	The client's Kuda merchant identifier	required
terminal_id	str	The terminal unique identifier	required
kuda_account_number	int	The client's Kuda account number	required
kuda_account_name	str	The client's account name	required
serial_number	str	The terminal's serial number	required
is_active	bool	Set to True for an active terminal or otherwise.	required
is_receiving_payment	bool	Set to True if the terminal is receiving payment else otherwise.	required
fee_percentage	float	Fee percentage	required
date_created	str	The date the terminal was created	required

Returns:

Type	Description
APIResponse	An APIResponse which is basically just a dataclass containing the data returned by the server as result of calling this function.

Raises:

Type	Description
ConnectionException	when the request times out or in the absence of an internet connection.

Source code in pykuda2/wrappers/sync_wrappers/instant_settlement_service.py

def update_terminal(
    self,
    kuda_merchant_id: str,
    terminal_id: str,
    kuda_account_number: int,
    kuda_account_name: str,
    serial_number: str,
    is_active: bool,
    is_receiving_payment: bool,
    fee_percentage: float,
    date_created: str,
) -> APIResponse:
    """Allows a partner to swap the location and user of a POS device.

    Args:
        kuda_merchant_id: The client's Kuda merchant identifier
        terminal_id: The  terminal unique identifier
        kuda_account_number: The client's Kuda account number
        kuda_account_name: The client's account name
        serial_number: The terminal's serial number
        is_active: Set to `True` for an active terminal or otherwise.
        is_receiving_payment: Set to `True` if the terminal is receiving payment else otherwise.
        fee_percentage: Fee percentage
        date_created: The date the terminal was created

    Returns:
        An `APIResponse` which is basically just a dataclass containing the data returned by the server as result
            of calling this function.

    Raises:
        ConnectionException: when the request times out or in the absence of an internet connection.
    """
    payload = {
        "id": id,
        "kudaMerchantId": kuda_merchant_id,
        "terminalId": terminal_id,
        "kudaAccountNumber": kuda_account_number,
        "kudaAccountName": kuda_account_name,
        "serialNumber": serial_number,
        "isActive": is_active,
        "isReceivingPayment": is_receiving_payment,
        "feePercentage": fee_percentage,
        "dateCreated": date_created,
    }
    return self._api_call(
        service_type=ServiceType.NO_OP,
        data=payload,
        endpoint_path="/api/terminal/EditTerminal",
    )