Migration from Node.js SDK
This guide helps you migrate from the Cardinity Node.js SDK to the Python SDK. We’ll cover the key differences, provide side-by-side examples, and explain the migration process step by step.
Overview of Changes
The Python SDK maintains functional parity with the Node.js SDK while following Python conventions and best practices. Here are the main differences:
Language Conventions
* Python uses snake_case
for variables and functions vs JavaScript’s camelCase
* Python classes use PascalCase
(same as JavaScript)
* Dictionary access uses brackets payment['id']
vs dot notation payment.id
* Error handling uses try/except
vs try/catch
Package Structure
* Import: from cardinity import Cardinity
vs const Cardinity = require('cardinity')
* Configuration uses keyword arguments vs object properties
* Return values are Python dictionaries vs JavaScript objects
Authentication * Same OAuth 1.0 approach, but configured differently * Environment variable patterns follow Python conventions
Side-by-Side Comparison
Basic Setup
Node.js SDK:
const Cardinity = require('cardinity');
const client = Cardinity({
consumerKey: 'your_consumer_key',
consumerSecret: 'your_consumer_secret'
});
Python SDK:
from cardinity import Cardinity
client = Cardinity(
consumer_key='your_consumer_key',
consumer_secret='your_consumer_secret'
)
Environment Variables
Node.js SDK:
const client = Cardinity({
consumerKey: process.env.CARDINITY_CONSUMER_KEY,
consumerSecret: process.env.CARDINITY_CONSUMER_SECRET
});
Python SDK:
import os
client = Cardinity(
consumer_key=os.getenv('CARDINITY_CONSUMER_KEY'),
consumer_secret=os.getenv('CARDINITY_CONSUMER_SECRET')
)
Creating a Payment
Node.js SDK:
client.payments.create({
amount: '10.00',
currency: 'EUR',
description: 'Test payment',
country: 'LT',
paymentInstrument: {
pan: '4111111111111111',
expMonth: 12,
expYear: 2025,
cvc: '123',
holder: 'John Doe'
}
}).then(payment => {
console.log('Payment created:', payment.id);
}).catch(error => {
console.error('Payment failed:', error);
});
Python SDK:
try:
payment = client.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']}")
except Exception as error:
print(f"Payment failed: {error}")
Retrieving a Payment
Node.js SDK:
client.payments.get(paymentId)
.then(payment => {
console.log('Payment status:', payment.status);
})
.catch(error => {
console.error('Error:', error);
});
Python SDK:
try:
payment = client.get_payment(payment_id)
print(f"Payment status: {payment['status']}")
except Exception as error:
print(f"Error: {error}")
3D Secure Finalization
Node.js SDK:
client.payments.finalize(paymentId, {
authorizeData: 'auth_data_from_3ds'
}).then(payment => {
console.log('Payment finalized:', payment.status);
});
Python SDK:
payment = client.finalize_payment(
payment_id,
authorize_data='auth_data_from_3ds'
)
print(f"Payment finalized: {payment['status']}")
Migration Steps
Step 1: Environment Setup
Install Python SDK:
pip install cardinity-python
Update environment variables (optional but recommended):
# Keep existing names or use new Python conventions export CARDINITY_CONSUMER_KEY="your_key" export CARDINITY_CONSUMER_SECRET="your_secret"
Step 2: Update Imports and Initialization
Replace your Node.js imports:
# Replace: const Cardinity = require('cardinity');
from cardinity import Cardinity
# Replace: const client = Cardinity({...});
client = Cardinity(
consumer_key='your_key',
consumer_secret='your_secret'
)
Step 3: Convert API Calls
Use this mapping to convert your API calls:
Node.js SDK |
Python SDK |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Step 4: Test Your Migration
Test basic operations first
Verify error handling works correctly
Test 3DS flows if applicable
Check webhook handling (structure remains the same)
Validate all payment scenarios you currently use
Common Migration Pitfalls
Dictionary vs Object Access
❌ Don’t do this:
# This won't work - Python doesn't support dot notation on dicts
payment.id # AttributeError
✅ Do this instead:
# Use bracket notation for dictionary access
payment['id']
Parameter Naming
❌ Don’t do this:
# Wrong parameter names (Node.js style)
client.create_payment(paymentInstrument={...})
✅ Do this instead:
# Correct Python parameter names
client.create_payment(payment_instrument={...})