Cardinity Python SDK
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.
🚀 Features
- 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
📦 Installation
Install the Cardinity Python SDK using pip:
pip install cardinity-python
Or using uv (recommended):
uv add cardinity-python
🏁 Quick Start
Basic Setup
from cardinity import Cardinity
# Initialize the client
cardinity = Cardinity(
consumer_key="your_consumer_key",
consumer_secret="your_consumer_secret"
)
Create a Payment
# Create a simple payment
payment = 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']}")
Handle 3D Secure Authentication
# Create payment that may require 3DS
payment = cardinity.create_payment(**payment_data)
if payment['status'] == 'pending':
# 3DS authentication required
auth_url = payment['authorization_information']['url']
print(f"Please complete 3DS authentication: {auth_url}")
# After customer completes 3DS, finalize the payment
finalized = cardinity.finalize_payment(
payment['id'],
authorize_data="auth_data_from_3ds_callback"
)
print(f"Final status: {finalized['status']}")
📚 Documentation
- 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
💡 Examples
Basic Payment Processing
from cardinity import Cardinity, CardinityError
cardinity = 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"
}
)
if payment['status'] == 'approved':
print("✅ Payment successful!")
elif payment['status'] == 'pending':
print("⏳ Awaiting 3DS authentication")
except CardinityError as e:
print(f"❌ Payment failed: {e}")
Recurring Payments
# Create initial payment for future recurring use
initial_payment = cardinity.create_payment(
amount="0.00", # Authorization only
currency="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 payment
recurring_payment = cardinity.create_recurring_payment(
amount="29.99",
currency="EUR",
description="Monthly subscription",
country="LT",
payment_instrument={
"payment_id": initial_payment['id']
}
)
Refund Processing
# Create a refund
refund = 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']}")
🧪 Testing
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
Test Credentials
To get test credentials for development and testing:
- Log in to your Cardinity account
- Navigate to the API settings or developer section
- Generate or retrieve your test/sandbox credentials
- Use these credentials for testing:
CONSUMER_KEY = "your_test_consumer_key"
CONSUMER_SECRET = "your_test_consumer_secret"
Test Cards
- Visa Success: 4111111111111111
- MasterCard Success: 5555555555554444
- 3DS Required: 4444333322221111
- American Express: 378282246310005
Test Amounts:
- Success: Any amount < 150.00
- Failure: Any amount >= 150.00
🔐 Security & Authentication
The SDK uses OAuth 1.0 with HMAC-SHA1 signatures for secure API communication:
# Production setup with environment variables
import os
cardinity = 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
🌍 Environment Configuration
Production Environment
cardinity = Cardinity(
consumer_key="your_live_consumer_key",
consumer_secret="your_live_consumer_secret",
base_url="https://api.cardinity.com/v1" # Default
)
Sandbox/Test Environment
cardinity = Cardinity(
consumer_key="your_test_consumer_key",
consumer_secret="your_test_consumer_secret"
)
📋 API Operations
The SDK supports all Cardinity API operations:
Payments
create_payment()- Create new paymentsget_payment()- Retrieve payment informationfinalize_payment()- Complete 3DS authenticationcreate_recurring_payment()- Create recurring payments
Refunds
create_refund()- Process refundsget_refund()- Retrieve refund information
Additional Operations
create_settlement()- Create settlementscreate_void()- Void paymentscreate_payment_link()- Create payment linksget_chargeback()- Retrieve chargeback information
⚡ Performance
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
🛠️ Development
Setup Development Environment
# 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
Contributing
We welcome contributions! Please see our Contributing Guide for:
- Development setup instructions
- Code style guidelines
- Testing requirements
- Pull request process
📖 API Reference
For complete API documentation, see:
🆘 Support
- Documentation: Read the Docs
- Issues: GitHub Issues
- Support: kyalo@trendpro.co.ke
- API Documentation: developers.cardinity.com/api/v1/#introduction
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🏷️ Versioning
We use Semantic Versioning for version management. For available versions, see the tags on this repository.
🎯 Roadmap
- Enhanced logging and debugging
- Performance monitoring integration
🙏 Acknowledgments
- Built with ❤️ by Kyalo Kitili
- Inspired by the Node.js SDK
- Thanks to all contributors and users
Ready to start processing payments?
- Sign up for a Cardinity account
- Get your API credentials
- Install the SDK:
pip install cardinity-python - Follow the Quick Start Guide
For questions or support, don't hesitate to contact me!
Metadata
Release files for cardinity-python 1.0.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cardinity_python-1.0.4.tar.gz | 8.5 MB | Without provenance | Details for cardinity_python-1.0.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cardinity_python-1.0.4-py3-none-any.whl | Python 3 | none | any | Details for cardinity_python-1.0.4-py3-none-any.whl |
Total release size: 8.6 MB
Release files / cardinity_python-1.0.4.tar.gz
| Download URL | cardinity_python-1.0.4.tar.gz |
|---|---|
| Size | 8.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c45991128005a6d798895e74f59f9b7582c440c9c5e900576ae87bcbc855f0f4
|
|
BLAKE2b-256 checksum How to use checksums |
7abd09d67118d72d0389bb2de0ace7b71416c6d7dbccaed5c49575d113d94a5a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.7.18
|
Release files / cardinity_python-1.0.4-py3-none-any.whl
| Download URL | cardinity_python-1.0.4-py3-none-any.whl |
|---|---|
| Size | 31.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
60f48eea0b71068b028097b3be0c66d5fb28f0879ee48f85c195976740808a30
|
|
BLAKE2b-256 checksum How to use checksums |
9b715c7fd93f3696ec6b56a992c4370ed50427d9f481b144478e5badf1c210c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.7.18
|
Security for cardinity-python 1.0.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.