Quick Start Guide
This guide will help you get started with the Cardinity Python SDK quickly. We’ll cover everything from getting your API credentials to making your first payment.
Getting API Credentials
Before you can use the SDK, you need to obtain API credentials from Cardinity:
Sign up for a Cardinity account at https://cardinity.com/
Login to your Cardinity dashboard
Navigate to Settings → API keys
Generate your Consumer Key and Consumer Secret
Save these credentials securely (you’ll need them for authentication)
Warning
Keep your API credentials secure and never commit them to version control. Use environment variables or secure configuration files.
Test vs Live Environment
Cardinity provides separate environments:
Test Environment: For development and testing
Live Environment: For production transactions
Test credentials are prefixed with test_
and only work with test card numbers.
Basic Setup
Import and Initialize
from cardinity import Cardinity
# Initialize with your credentials
cardinity = Cardinity(
consumer_key="your_consumer_key",
consumer_secret="your_consumer_secret"
)
Environment Configuration
For better security, use environment variables:
export CARDINITY_CONSUMER_KEY="your_consumer_key"
export CARDINITY_CONSUMER_SECRET="your_consumer_secret"
import os
from cardinity import Cardinity
cardinity = Cardinity(
consumer_key=os.getenv("CARDINITY_CONSUMER_KEY"),
consumer_secret=os.getenv("CARDINITY_CONSUMER_SECRET")
)
Your First Payment
Create a Simple Payment
from cardinity import Cardinity
cardinity = Cardinity(
consumer_key="test_jlol6sogrlvje2zwwsfb6kjajuyy7h",
consumer_secret="1h7j6rvwlpvuwbzrobo6bjbcqv1m3khnlqojpkkwh9wzbrlkmu"
)
try:
# Create a payment
payment = cardinity.create_payment(
amount="10.00",
currency="EUR",
description="Test payment",
country="LT",
payment_instrument={
"pan": "4111111111111111", # Test Visa card
"exp_month": 12,
"exp_year": 2025,
"cvc": "123",
"holder": "John Doe"
}
)
print(f"Payment created successfully!")
print(f"Payment ID: {payment['id']}")
print(f"Status: {payment['status']}")
print(f"Amount: {payment['amount']} {payment['currency']}")
except Exception as error:
print(f"Payment failed: {error}")
Test Card Numbers
For testing, use these card numbers:
Visa Success: 4111111111111111
MasterCard Success: 5555555555554444
Visa 3DS Success: 4444333322221111
Failure (any amount >150): Any valid card number
Handle 3D Secure Authentication
Some payments may require 3D Secure authentication:
# Create payment that might require 3DS
payment = cardinity.create_payment(
amount="50.00",
currency="EUR",
description="3DS test payment",
country="LT",
payment_instrument={
"pan": "4444333322221111", # 3DS test card
"exp_month": 12,
"exp_year": 2025,
"cvc": "123",
"holder": "John Doe"
}
)
if payment['status'] == 'pending':
# 3DS authentication required
auth_url = payment['authorization_information']['url']
print(f"Complete 3DS authentication at: {auth_url}")
# After user completes 3DS, finalize the payment
# You'll receive the authorization data via callback/redirect
# Example finalization (you'll get this data from your callback)
finalized_payment = cardinity.finalize_payment(
payment['id'],
authorize_data="auth_data_from_3ds_callback"
)
print(f"Finalized payment status: {finalized_payment['status']}")
Common Operations
Retrieve a Payment
# Get payment by ID
payment = cardinity.get_payment("payment_id_here")
print(f"Payment status: {payment['status']}")
Create a Refund
# Refund a payment (partial or full)
refund = cardinity.create_refund(
payment_id="payment_id_here",
amount="5.00", # Optional: defaults to full amount
description="Customer requested refund"
)
print(f"Refund created: {refund['id']}")
Create a Payment Link
from datetime import datetime, timedelta
# Create a payment link that expires in 1 hour
payment_link = cardinity.create_payment_link(
amount="25.00",
currency="EUR",
description="Payment for order #12345",
country="LT",
expiration_date=(datetime.now() + timedelta(hours=1)).isoformat()
)
print(f"Payment link: {payment_link['url']}")
Error Handling
Always handle errors appropriately:
from cardinity import Cardinity, CardinityError, ValidationError, APIError
cardinity = Cardinity(
consumer_key="your_key",
consumer_secret="your_secret"
)
try:
payment = cardinity.create_payment(
amount="invalid_amount", # This will cause a validation error
currency="EUR",
description="Test payment",
country="LT",
payment_instrument={}
)
except ValidationError as e:
print(f"Validation error: {e}")
except APIError as e:
print(f"API error: {e}")
print(f"Status code: {e.status_code}")
except CardinityError as e:
print(f"General Cardinity error: {e}")
except Exception as e:
print(f"Unexpected error: {e}")
Best Practices
Security
Never hardcode credentials in your source code
Use environment variables or secure configuration management
Validate all inputs before sending to the API
Log errors but never log sensitive payment data
Use HTTPS for all webhook endpoints
Performance
Reuse the client instance instead of creating new ones
Implement proper retry logic for network failures
Use connection pooling for high-volume applications
Cache payment results when appropriate
Testing
Always test with sandbox credentials first
Use provided test card numbers
Test all payment scenarios (success, failure, 3DS)
Implement proper error handling
Test webhook handling thoroughly
Next Steps
Now that you’ve learned the basics:
Explore the Examples for more detailed scenarios
Read the API Reference for complete API reference
Check out the Migration from Node.js SDK guide if you’re coming from Node.js
Learn about Authentication for advanced configurations
Need Help?
Visit the GitHub repository for troubleshooting common issues
Visit our GitHub Issues
Contact support at contact@cardinity.com