himosoft-payment-client 1.0.0

A Python client library for integrating with the Himosoft Payment Logging API

Himosoft Payment Client

A Python client library for integrating with the Himosoft Payment Logging API. This package provides a simple and robust way to log payment transactions from your applications to a centralized payment monitoring system.

Features

• Simple Integration: Easy-to-use client library for logging payments
• Comprehensive Validation: Built-in validation for all payment data
• Error Handling: Detailed error handling with custom exceptions
• Environment Configuration: Support for environment variable configuration
• Multiple Data Types: Support for float, Decimal, and string amounts
• Connection Testing: Built-in connection testing functionality
• Django Integration: Ready-to-use Django integration examples
• Comprehensive Testing: Full test coverage with pytest

Installation

Using pip

pip install himosoft-payment-logging-client

From source

git clone https://github.com/Swe-HimelRana/payment-logging-client.git
cd payment-client
pip install -e .

Quick Start

1. Set up environment variables

export PAYMENT_RECORD_SERVER_URL="http://your-payment-server.com"
export PAYMENT_RECORD_PLATFORM_API_KEY="your-platform-api-key-here"

2. Basic usage

from himosoft_payment_client import PaymentLogger

# Initialize the client
logger = PaymentLogger()

# Log a successful payment
result = logger.log_payment(
    user="[e-mail]",
    package="Premium Plan",
    amount=99.99,
    status="paid",
    trx_id="TXN123456789",
    payment_method="credit_card",
    gateway_name="Stripe",
    gateway_log={
        "payment_intent_id": "pi_1234567890",
        "charge_id": "ch_1234567890",
        "amount": 9999,
        "currency": "usd",
        "status": "succeeded"
    }
)

print(f"Payment logged: {result}")

Configuration

Environment Variables

The package uses the following environment variables:

• PAYMENT_RECORD_SERVER_URL: The URL of your payment logging server
• PAYMENT_RECORD_PLATFORM_API_KEY: Your platform's API key

Manual Configuration

You can also pass configuration directly to the client:

logger = PaymentLogger(
    server_url="http://your-server.com",
    api_key="your-api-key"
)

API Reference

PaymentLogger Class

Constructor

PaymentLogger(server_url=None, api_key=None)

Parameters:

• server_url (str, optional): Payment server URL
• api_key (str, optional): Platform API key

If not provided, these values will be read from environment variables.

Methods

log_payment()

log_payment(
    user,
    package,
    amount,
    status,
    trx_id=None,
    payment_method=None,
    gateway_name=None,
    gateway_log=None
)

Parameters:

• user (str): User identifier (email, username, or phone)
• package (str): Package or plan name
• amount (float/Decimal/str): Payment amount (positive number)
• status (str): Payment status ('paid', 'failed', 'canceled', 'refunded')
• trx_id (str, optional): Transaction ID (required for 'paid' and 'refunded' status)
• payment_method (str, optional): Payment method used
• gateway_name (str, optional): Payment gateway name
• gateway_log (dict, optional): Complete gateway response

Returns:

• dict: API response containing status and message

Raises:

• PaymentLoggerValidationError: If input validation fails
• PaymentLoggerAPIError: If the API returns an error
• PaymentLoggerNetworkError: If there's a network error

test_connection()

test_connection()

Returns:

• bool: True if connection is successful

Raises:

• PaymentLoggerNetworkError: If connection fails

Payment Statuses

The following payment statuses are supported:

• paid: Payment was successful (requires trx_id)
• failed: Payment failed
• canceled: Payment was canceled
• refunded: Payment was refunded (requires trx_id)

Error Handling

The package provides several custom exceptions for different error types:

PaymentLoggerError

Base exception for all payment logger errors.

PaymentLoggerValidationError

Raised when input validation fails.

try:
    logger.log_payment(
        user="",
        package="Basic Plan",
        amount=19.99,
        status="paid"
    )
except PaymentLoggerValidationError as e:
    print(f"Validation error: {e}")

PaymentLoggerAPIError

Raised when the API returns an error response.

try:
    result = logger.log_payment(...)
except PaymentLoggerAPIError as e:
    print(f"API error: {e}")
    print(f"Status code: {e.status_code}")
    print(f"Response data: {e.response_data}")

PaymentLoggerNetworkError

Raised when there's a network-related error.

try:
    result = logger.log_payment(...)
except PaymentLoggerNetworkError as e:
    print(f"Network error: {e}")

PaymentLoggerConfigError

Raised when there's a configuration error.

try:
    logger = PaymentLogger()
except PaymentLoggerConfigError as e:
    print(f"Configuration error: {e}")

Examples

Basic Usage

from himosoft_payment_client import PaymentLogger

logger = PaymentLogger()

# Successful payment
result = logger.log_payment(
    user="[e-mail]",
    package="Premium Plan",
    amount=99.99,
    status="paid",
    trx_id="TXN123456",
    payment_method="credit_card",
    gateway_name="Stripe",
    gateway_log={"charge_id": "ch_123"}
)

# Failed payment
result = logger.log_payment(
    user="[e-mail]",
    package="Basic Plan",
    amount=19.99,
    status="failed",
    payment_method="credit_card",
    gateway_name="Stripe",
    gateway_log={"error": "card_declined"}
)

Django Integration

# settings.py
PAYMENT_RECORD_SERVER_URL = 'http://your-payment-server.com'
PAYMENT_RECORD_PLATFORM_API_KEY = 'your-api-key-here'

# views.py
from himosoft_payment_client import PaymentLogger
from django.conf import settings

def process_payment(request):
    logger = PaymentLogger(
        server_url=settings.PAYMENT_RECORD_SERVER_URL,
        api_key=settings.PAYMENT_RECORD_PLATFORM_API_KEY
    )
    
    try:
        result = logger.log_payment(
            user=request.user.email,
            package="Premium Plan",
            amount=99.99,
            status="paid",
            trx_id=transaction_id,
            payment_method="credit_card",
            gateway_name="Stripe",
            gateway_log=gateway_response
        )
        return JsonResponse({"status": "success", "result": result})
    except PaymentLoggerError as e:
        return JsonResponse({"status": "error", "message": str(e)})

Testing Connection

logger = PaymentLogger()

try:
    if logger.test_connection():
        print("Connection successful")
    else:
        print("Connection failed")
except PaymentLoggerNetworkError as e:
    print(f"Connection error: {e}")

Validation Rules

The package enforces the following validation rules:

1. User: Required, cannot be empty
2. Package: Required, cannot be empty
3. Amount: Required, must be a positive number
4. Status: Must be one of: 'paid', 'failed', 'canceled', 'refunded'
5. TRX ID: Required for 'paid' and 'refunded' statuses
6. Gateway Log: Must be a dictionary if provided

Development

Setting up development environment

# Clone the repository
git clone https://github.com/Swe-HimelRana/payment-logging-client.git
cd payment-logging-client

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements-dev.txt

# Install package in development mode
pip install -e .

Running tests

# Run all tests
pytest

# Run tests with coverage
pytest --cov=payment-logging-client

# Run specific test file
pytest tests/test_client.py

# Run tests with verbose output
pytest -v

Code formatting

# Format code with black
black payment-logging-client/ tests/ examples/

# Check code style with flake8
flake8 payment-logging-client/ tests/ examples/

Running examples

# Run basic usage example
python examples/basic_usage.py

# Run Django integration example (requires Django)
python examples/django_integration.py

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow PEP 8 style guidelines
• Write comprehensive tests for new features
• Update documentation for any API changes
• Ensure all tests pass before submitting a PR

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support and questions:

• Check the documentation
• Review the examples directory
• Open an issue on GitHub
• Contact [e-mail]

Changelog

Version 1.0.0

• Initial release
• Basic payment logging functionality
• Comprehensive validation
• Error handling with custom exceptions
• Environment variable configuration
• Django integration examples
• Full test coverage

Acknowledgments

• Built for the Himosoft Payment Logging System
• Inspired by modern Python package development practices
• Thanks to all contributors and users