The Python SDK for the Cardinity Payment Gateway. This library provides a simple and intuitive way to integrate Cardinity's payment processing capabilities into your Python applications.

• Complete API Coverage: Full support for all Cardinity API operations
• 3D Secure v2: Built-in support for strong customer authentication
• Type Safety: Full type hints for better development experience
• Comprehensive Testing: Extensive test suite with 92% code coverage
• Production Ready: Built for scalability and reliability
• Easy Integration: Simple, intuitive API design
• Python 3.8+: Support for modern Python versions

Install the Cardinity Python SDK using pip:

pip install cardinity-python

Or using uv (recommended):

uv add cardinity-python

fromcardinityimportCardinity# Initialize the clientcardinity=Cardinity( consumer_key="your_consumer_key", consumer_secret="your_consumer_secret" )

# Create a simple paymentpayment=cardinity.create_payment( amount="10.00", currency="EUR", description="Test payment", country="LT", payment_instrument={"pan": "4111111111111111", "exp_month": 12, "exp_year": 2025, "cvc": "123", "holder": "John Doe" } ) print(f"Payment created: {payment['id']}") print(f"Status: {payment['status']}")

# Create payment that may require 3DSpayment=cardinity.create_payment(**payment_data) ifpayment['status'] =='pending': # 3DS authentication requiredauth_url=payment['authorization_information']['url'] print(f"Please complete 3DS authentication: {auth_url}") # After customer completes 3DS, finalize the paymentfinalized=cardinity.finalize_payment( payment['id'], authorize_data="auth_data_from_3ds_callback" ) print(f"Final status: {finalized['status']}")

• Installation Guide - Detailed installation instructions
• Quick Start Guide - Get started quickly
• Authentication - OAuth setup and security
• Examples - Complete code examples
• API Reference - Full API documentation

fromcardinityimportCardinity, CardinityErrorcardinity=Cardinity( consumer_key="your_key", consumer_secret="your_secret" ) try: payment=cardinity.create_payment( amount="25.00", currency="EUR", description="Product purchase", country="LT", payment_instrument={"pan": "4111111111111111", "exp_month": 12, "exp_year": 2025, "cvc": "123", "holder": "Jane Smith" } ) ifpayment['status'] =='approved': print("✅ Payment successful!") elifpayment['status'] =='pending': print("⏳ Awaiting 3DS authentication") exceptCardinityErrorase: print(f"❌ Payment failed: {e}")

# Create initial payment for future recurring useinitial_payment=cardinity.create_payment( amount="0.00", # Authorization onlycurrency="EUR", description="Setup recurring payment", country="LT", payment_instrument={"pan": "4111111111111111", "exp_month": 12, "exp_year": 2025, "cvc": "123", "holder": "John Doe" } ) # Create recurring payment using the initial paymentrecurring_payment=cardinity.create_recurring_payment( amount="29.99", currency="EUR", description="Monthly subscription", country="LT", payment_instrument={"payment_id": initial_payment['id'] } )

# Create a refundrefund=cardinity.create_refund( payment_id="payment_id_here", amount="10.00", description="Customer requested refund" ) print(f"Refund created: {refund['id']}") print(f"Status: {refund['status']}")

The SDK includes comprehensive test coverage:

# Run all tests pytest # Run with coverage pytest --cov=cardinity # Run integration tests (requires API credentials) pytest -m integration # Run performance tests pytest -m performance

To get test credentials for development and testing:

1. Log in to your Cardinity account
2. Navigate to the API settings or developer section
3. Generate or retrieve your test/sandbox credentials
4. Use these credentials for testing:

CONSUMER_KEY="your_test_consumer_key"CONSUMER_SECRET="your_test_consumer_secret"

• Visa Success: 4111111111111111
• MasterCard Success: 5555555555554444
• 3DS Required: 4444333322221111
• American Express: 378282246310005

Test Amounts:

• Success: Any amount < 150.00
• Failure: Any amount >= 150.00

The SDK uses OAuth 1.0 with HMAC-SHA1 signatures for secure API communication:

# Production setup with environment variablesimportoscardinity=Cardinity( consumer_key=os.getenv('CARDINITY_CONSUMER_KEY'), consumer_secret=os.getenv('CARDINITY_CONSUMER_SECRET') )

Security Best Practices:

• Never commit API credentials to version control
• Use environment variables for credentials
• Validate all payment data before processing
• Implement proper error handling
• Use HTTPS in production

cardinity=Cardinity( consumer_key="your_live_consumer_key", consumer_secret="your_live_consumer_secret", base_url="https://api.cardinity.com/v1"# Default )

cardinity=Cardinity( consumer_key="your_test_consumer_key", consumer_secret="your_test_consumer_secret" )

The SDK supports all Cardinity API operations:

• create_payment() - Create new payments
• get_payment() - Retrieve payment information
• finalize_payment() - Complete 3DS authentication
• create_recurring_payment() - Create recurring payments

• create_refund() - Process refunds
• get_refund() - Retrieve refund information

• create_settlement() - Create settlements
• create_void() - Void payments
• create_payment_link() - Create payment links
• get_chargeback() - Retrieve chargeback information

The SDK is optimized for performance:

• Async Support: Built on modern Python async patterns
• Connection Pooling: Efficient HTTP connection management
• Request Optimization: Minimal overhead per API call
• Memory Efficient: Low memory footprint

Performance benchmarks (on average hardware):

• Payment creation: ~200ms
• Payment retrieval: ~150ms
• Concurrent requests: 50+ req/sec

# Clone the repository git clone https://github.com/trendpro/cardinity-python.git cd cardinity-python # Install with development dependencies uv sync --all-extras # Run tests uv run pytest # Build documentation uv run sphinx-build docs docs/_build

We welcome contributions! Please see our Contributing Guide for:

• Development setup instructions
• Code style guidelines
• Testing requirements
• Pull request process

For complete API documentation, see:

• Online Documentation
• API Reference
• Cardinity API Docs

• Documentation: Read the Docs
• Issues: GitHub Issues
• Support: [email protected]
• API Documentation: developers.cardinity.com/api/v1/#introduction

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

We use Semantic Versioning for version management. For available versions, see the tags on this repository.

• Enhanced logging and debugging
• Performance monitoring integration

• Built with ❤️ by Kyalo Kitili
• Inspired by the Node.js SDK
• Thanks to all contributors and users

Ready to start processing payments?

1. Sign up for a Cardinity account
2. Get your API credentials
3. Install the SDK: pip install cardinity-python
4. Follow the Quick Start Guide

For questions or support, don't hesitate to contact me!