API Reference
This section provides detailed API reference documentation for all classes and methods in the Cardinity Python SDK.
Main SDK Class
- class cardinity.Cardinity(consumer_key: str, consumer_secret: str, base_url: str = 'https://api.cardinity.com/v1')[source]
Bases:
object
Main Cardinity SDK class.
This class provides a convenient interface for all Cardinity API operations. It handles authentication, HTTP communication, and provides methods for all supported payment operations.
Example
Basic usage example:
cardinity = Cardinity( consumer_key="your_consumer_key", consumer_secret="your_consumer_secret" ) # Create a payment payment = cardinity.create_payment( amount="10.50", currency="EUR", description="Test payment" )
- __init__(consumer_key: str, consumer_secret: str, base_url: str = 'https://api.cardinity.com/v1') None [source]
Initialize the Cardinity SDK.
- Parameters:
consumer_key – Your Cardinity consumer key
consumer_secret – Your Cardinity consumer secret
base_url – Base URL for the Cardinity API (default: production)
- create_payment(**kwargs: Any) Dict[str, Any] [source]
Create a new payment.
- Parameters:
**kwargs – Payment data including amount, currency, description, etc.
- Returns:
Payment response from the API
- Return type:
Dict[str, Any]
- Raises:
ValidationError – If payment data is invalid
APIError – If the API request fails
- get_payment(payment_id: str | None = None, limit: int | None = None) Dict[str, Any] [source]
Get payment information.
- finalize_payment(payment_id: str, **kwargs: Any) Dict[str, Any] [source]
Finalize a payment (complete 3D Secure authentication).
- Parameters:
payment_id – ID of the payment to finalize
**kwargs – Finalization data (authorize_data or cres)
- Returns:
Finalized payment response
- Return type:
Dict[str, Any]
- Raises:
ValidationError – If finalization data is invalid
APIError – If the API request fails
- create_recurring_payment(**kwargs: Any) Dict[str, Any] [source]
Create a recurring payment.
- Parameters:
**kwargs – Recurring payment data including payment_id reference
- Returns:
Recurring payment response
- Return type:
Dict[str, Any]
- Raises:
ValidationError – If recurring payment data is invalid
APIError – If the API request fails
- create_refund(payment_id: str, **kwargs: Any) Dict[str, Any] [source]
Create a refund for a payment.
- Parameters:
payment_id – ID of the payment to refund
**kwargs – Refund data including amount and description
- Returns:
Refund response
- Return type:
Dict[str, Any]
- Raises:
ValidationError – If refund data is invalid
APIError – If the API request fails
- get_refund(payment_id: str, refund_id: str | None = None) Dict[str, Any] [source]
Get refund information.
- create_settlement(payment_id: str, **kwargs: Any) Dict[str, Any] [source]
Create a settlement for a payment.
- Parameters:
payment_id – ID of the payment to settle
**kwargs – Settlement data including amount and description
- Returns:
Settlement response
- Return type:
Dict[str, Any]
- Raises:
ValidationError – If settlement data is invalid
APIError – If the API request fails
- get_settlement(payment_id: str, settlement_id: str | None = None) Dict[str, Any] [source]
Get settlement information.
- get_void(payment_id: str, void_id: str | None = None) Dict[str, Any] [source]
Get void information.
- get_chargeback(payment_id_or_limit: str | int | None = None, chargeback_id: str | None = None) Dict[str, Any] [source]
Get chargeback information.
This method supports multiple modes: - Global chargeback listing: get_chargeback() or get_chargeback(limit=10) - Payment-specific chargebacks: get_chargeback(“payment_id”) - Single chargeback: get_chargeback(“payment_id”, “chargeback_id”)
- create_payment_link(**kwargs: Any) Dict[str, Any] [source]
Create a payment link.
- Parameters:
**kwargs – Payment link data including amount, currency, description, etc.
- Returns:
Payment link response
- Return type:
Dict[str, Any]
- Raises:
ValidationError – If payment link data is invalid
APIError – If the API request fails
- update_payment_link(link_id: str, **kwargs: Any) Dict[str, Any] [source]
Update an existing payment link.
- Parameters:
link_id – ID of the payment link to update
**kwargs – Update data including expiration_date and enabled status
- Returns:
Updated payment link response
- Return type:
Dict[str, Any]
- Raises:
ValidationError – If update data is invalid
APIError – If the API request fails
- get_client() CardinityClient [source]
Get the underlying HTTP client for advanced usage.
- Returns:
The HTTP client instance
- Return type:
- get_auth() CardinityAuth [source]
Get the authentication instance.
- Returns:
The authentication instance
- Return type:
Authentication
Cardinity Authentication
This module handles OAuth 1.0 authentication for the Cardinity API.
- class cardinity.auth.CardinityAuth(consumer_key: str, consumer_secret: str)[source]
Bases:
object
OAuth 1.0 authentication handler for Cardinity API.
This class manages OAuth 1.0 authentication using HMAC-SHA1 signature method as required by the Cardinity API. It provides authentication headers for HTTP requests.
- __init__(consumer_key: str, consumer_secret: str) None [source]
Initialize the Cardinity authentication handler.
- Parameters:
consumer_key – The OAuth consumer key provided by Cardinity
consumer_secret – The OAuth consumer secret provided by Cardinity
- Raises:
ValueError – If consumer_key or consumer_secret is empty
- get_auth() OAuth1 [source]
Get the OAuth1 authentication object for requests.
- Returns:
- Configured OAuth1 authentication object that can be used
with the requests library
- Return type:
OAuth1
HTTP Client
Cardinity HTTP Client
This module contains the HTTP client for making requests to the Cardinity API.
- class cardinity.client.CardinityClient(auth: CardinityAuth, base_url: str = 'https://api.cardinity.com/v1', timeout: int = 30, max_retries: int = 3)[source]
Bases:
object
HTTP client for the Cardinity Payment Gateway API.
This client handles all HTTP communication with the Cardinity API, including OAuth 1.0 authentication, request/response handling, error processing, and retry logic for transient failures.
- BASE_URL = 'https://api.cardinity.com/v1'
- DEFAULT_TIMEOUT = 30
- MAX_RETRIES = 3
- RETRY_DELAY = 1
- __init__(auth: CardinityAuth, base_url: str = 'https://api.cardinity.com/v1', timeout: int = 30, max_retries: int = 3) None [source]
Initialize the Cardinity HTTP client.
- Parameters:
auth – CardinityAuth instance for authentication
base_url – Base URL for the Cardinity API
timeout – Request timeout in seconds
max_retries – Maximum number of retries for failed requests
- get(endpoint: str, params: Dict[str, Any] | None = None) Dict[str, Any] [source]
Make a GET request to the API.
- Parameters:
endpoint – API endpoint path
params – URL query parameters
- Returns:
API response data
- Return type:
Dict[str, Any]
- post(endpoint: str, data: Dict[str, Any]) Dict[str, Any] [source]
Make a POST request to the API.
- Parameters:
endpoint – API endpoint path
data – Request payload data
- Returns:
API response data
- Return type:
Dict[str, Any]
- patch(endpoint: str, data: Dict[str, Any]) Dict[str, Any] [source]
Make a PATCH request to the API.
- Parameters:
endpoint – API endpoint path
data – Request payload data
- Returns:
API response data
- Return type:
Dict[str, Any]
- delete(endpoint: str) Dict[str, Any] [source]
Make a DELETE request to the API.
- Parameters:
endpoint – API endpoint path
- Returns:
API response data
- Return type:
Dict[str, Any]
Data Models
Base Model
Cardinity Base Model
This module defines the abstract base class for all Cardinity API models.
- class cardinity.models.base.BaseModel(**kwargs: Any)[source]
Bases:
ABC
Abstract base class for all Cardinity API models.
This class provides common functionality for data validation, serialization, and API endpoint configuration that all model classes inherit.
- __init__(**kwargs: Any) None [source]
Initialize the model with data validation.
- Parameters:
**kwargs – Model data to validate and store
- Raises:
ValidationError – If the provided data fails validation
- abstractmethod get_constraints() Dict[str, Any] [source]
Get the validation constraints for this model.
This method must be implemented by each model class to define the validation rules for its specific data structure.
- Returns:
Cerberus validation schema for this model
- Return type:
Dict[str, Any]
- Raises:
NotImplementedError – If not implemented by subclass
- abstractmethod get_endpoint() str [source]
Get the API endpoint for this model’s operations.
This method must be implemented by each model class to define which API endpoint should be used for operations.
- Returns:
API endpoint path (e.g., “/payments”, “/refunds”)
- Return type:
- Raises:
NotImplementedError – If not implemented by subclass
- abstractmethod get_method() str [source]
Get the HTTP method for this model’s primary operation.
This method must be implemented by each model class to define which HTTP method should be used for the primary operation.
- Returns:
HTTP method (e.g., “POST”, “GET”, “PATCH”)
- Return type:
- Raises:
NotImplementedError – If not implemented by subclass
- to_dict() Dict[str, Any] [source]
Convert the model to a dictionary for API serialization.
This method serializes the model data to a format suitable for sending to the Cardinity API.
- Returns:
Dictionary representation of the model data
- Return type:
Dict[str, Any]
- get_data() Dict[str, Any] [source]
Get the raw model data.
- Returns:
Copy of the internal model data
- Return type:
Dict[str, Any]
- update_data(**kwargs: Any) None [source]
Update the model data with new values.
- Parameters:
**kwargs – New data values to update
- Raises:
ValidationError – If the updated data fails validation
- get_field(field_name: str, default: Any = None) Any [source]
Get a specific field value from the model data.
- Parameters:
field_name – Name of the field to retrieve
default – Default value if field doesn’t exist
- Returns:
Field value or default
- Return type:
Any
- has_field(field_name: str) bool [source]
Check if a field exists in the model data.
- Parameters:
field_name – Name of the field to check
- Returns:
True if field exists, False otherwise
- Return type:
- validate() Dict[str, Any] | None [source]
Validate the current model data against its constraints.
- Returns:
Validation errors if any, None if valid
- Return type:
Optional[Dict[str, Any]]
- is_valid() bool [source]
Check if the current model data is valid.
- Returns:
True if valid, False otherwise
- Return type:
- __repr__() str [source]
Return a string representation of the model.
- Returns:
String representation showing class name and key fields
- Return type:
- class cardinity.models.base.ReadOnlyModel(**kwargs: Any)[source]
Bases:
BaseModel
Base class for read-only models that don’t support data updates.
This class is used for models that represent data retrieved from the API that shouldn’t be modified locally (e.g., payment status, transaction history).
- update_data(**kwargs: Any) None [source]
Prevent data updates on read-only models.
- Parameters:
**kwargs – Ignored
- Raises:
ValidationError – Always raised for read-only models
Payment Models
Cardinity Payment Model
This module contains the Payment model for creating payment requests.
- class cardinity.models.payment.Payment(**kwargs: Any)[source]
Bases:
BaseModel
Model for creating payment requests.
This model handles standard card payments with support for 3D Secure v2, billing addresses, and all required payment data validation.
- __init__(**kwargs: Any) None [source]
Initialize Payment model.
- Parameters:
**kwargs – Payment data as keyword arguments
- get_constraints() Dict[str, Any] [source]
Get validation constraints for payment creation.
- Returns:
Cerberus validation schema for payment data
- Return type:
Dict[str, Any]
- get_endpoint() str [source]
Get the API endpoint for payment creation.
- Returns:
The payments endpoint
- Return type:
- get_method() str [source]
Get the HTTP method for payment creation.
- Returns:
Always returns POST for payment creation
- Return type:
- to_dict() Dict[str, Any] [source]
Convert payment data to API-compatible dictionary.
- Returns:
Payment data formatted for API submission
- Return type:
Dict[str, Any]
- get_amount() str [source]
Get the payment amount.
- Returns:
Payment amount in decimal format (e.g., “10.50”)
- Return type:
- get_currency() str [source]
Get the payment currency.
- Returns:
Three-letter ISO currency code (e.g., “EUR”)
- Return type:
- get_payment_instrument() Dict[str, Any] [source]
Get the payment instrument (card) data.
- Returns:
Payment instrument data including PAN, expiry, etc.
- Return type:
Dict[str, Any]
Cardinity Get Payment Model
This module contains the GetPayment model for retrieving payment information.
- class cardinity.models.get_payment.GetPayment(payment_id: str | None = None, limit: int | None = None)[source]
Bases:
ReadOnlyModel
Model for retrieving payment information.
This model supports two retrieval modes: 1. Single payment retrieval by payment ID 2. Payment listing with optional limit parameter
- __init__(payment_id: str | None = None, limit: int | None = None)[source]
Initialize GetPayment model.
- Parameters:
payment_id – Specific payment ID to retrieve (optional)
limit – Limit for payment listing (optional, used when payment_id is None)
- get_constraints() Dict[str, Any] [source]
Get validation constraints for payment retrieval.
For retrieval operations, minimal validation is needed.
- Returns:
Empty constraints for read-only operations
- Return type:
Dict[str, Any]
- get_endpoint() str [source]
Get the API endpoint for payment retrieval.
- Returns:
The appropriate endpoint based on retrieval mode
- Return type:
- get_method() str [source]
Get the HTTP method for payment retrieval.
- Returns:
Always returns GET for payment retrieval
- Return type:
- is_listing() bool [source]
Check if this is a payment listing request.
- Returns:
True if listing payments, False if retrieving single payment
- Return type:
Cardinity Finalize Payment Model
This module contains the FinalizePayment model for completing 3D Secure authentication.
- class cardinity.models.finalize_payment.FinalizePayment(payment_id: str, **kwargs: Any)[source]
Bases:
BaseModel
Model for finalizing payment after 3D Secure authentication.
This model supports both 3D Secure v1 and v2 authentication flows: - 3DS v1: Uses authorize_data parameter - 3DS v2: Uses cres (Challenge Response) parameter
- __init__(payment_id: str, **kwargs: Any)[source]
Initialize FinalizePayment model.
- Parameters:
payment_id – The ID of the payment to finalize
**kwargs – Finalization data as keyword arguments containing either cres or authorize_data
- get_constraints() Dict[str, Any] [source]
Get validation constraints for payment finalization.
- Returns:
Cerberus validation schema for finalization data
- Return type:
Dict[str, Any]
- get_endpoint() str [source]
Get the API endpoint for payment finalization.
- Returns:
The payment-specific endpoint for PATCH operations
- Return type:
- get_method() str [source]
Get the HTTP method for payment finalization.
- Returns:
Always returns PATCH for payment finalization
- Return type:
- is_threedsv2() bool [source]
Check if this is a 3D Secure v2 flow.
- Returns:
True if 3DS v2, False if 3DS v1
- Return type:
- get_payment_id() str [source]
Get the payment ID being finalized.
- Returns:
The payment ID
- Return type:
- get_cres() str | None [source]
Get the Challenge Response for 3DS v2.
- Returns:
The cres value or None if not 3DS v2
- Return type:
Optional[str]
Cardinity Recurring Payment Model
This module contains the RecurringPayment model for creating recurring payments.
- class cardinity.models.recurring_payment.RecurringPayment(**kwargs: Any)[source]
Bases:
BaseModel
Model for creating recurring payment requests.
Recurring payments use a previously stored payment instrument from a successful payment to process new charges.
- __init__(**kwargs: Any) None [source]
Initialize RecurringPayment model.
- Parameters:
**kwargs – Recurring payment data as keyword arguments
- get_constraints() Dict[str, Any] [source]
Get validation constraints for recurring payment creation.
- Returns:
Cerberus validation schema for recurring payment data
- Return type:
Dict[str, Any]
- get_endpoint() str [source]
Get the API endpoint for recurring payment creation.
- Returns:
The payments endpoint (same as regular payments)
- Return type:
- get_method() str [source]
Get the HTTP method for recurring payment creation.
- Returns:
Always returns POST for recurring payment creation
- Return type:
- to_dict() Dict[str, Any] [source]
Convert recurring payment data to API-compatible dictionary.
- Returns:
Recurring payment data formatted for API submission
- Return type:
Dict[str, Any]
- get_amount() str [source]
Get the payment amount.
- Returns:
Payment amount in decimal format (e.g., “10.50”)
- Return type:
- get_currency() str [source]
Get the payment currency.
- Returns:
Three-letter ISO currency code (e.g., “EUR”)
- Return type:
- get_payment_instrument() Dict[str, Any] [source]
Get the payment instrument reference.
For recurring payments, this contains the reference to the previously stored payment instrument.
- Returns:
Payment instrument reference data
- Return type:
Dict[str, Any]
- get_description() str [source]
Get the payment description.
- Returns:
Payment description
- Return type:
Payment Link Models
Cardinity Payment Link Models
This module contains models for payment link operations.
- class cardinity.models.payment_link.PaymentLink(data: Dict[str, Any])[source]
Bases:
BaseModel
Model for creating payment link requests.
Payment links allow merchants to generate URLs that customers can use to complete payments without direct integration.
- __init__(data: Dict[str, Any]) None [source]
Initialize PaymentLink model.
- Parameters:
data – Payment link data dictionary
- get_constraints() Dict[str, Any] [source]
Get validation constraints for payment link creation.
- Returns:
Cerberus validation schema for payment link data
- Return type:
Dict[str, Any]
- get_endpoint() str [source]
Get the API endpoint for payment link creation.
- Returns:
The payment links endpoint
- Return type:
- get_method() str [source]
Get the HTTP method for payment link creation.
- Returns:
Always returns POST for payment link creation
- Return type:
- get_amount() str [source]
Get the payment link amount.
- Returns:
Payment amount in decimal format (e.g., “10.50”)
- Return type:
- get_currency() str [source]
Get the payment link currency.
- Returns:
Three-letter ISO currency code (e.g., “EUR”)
- Return type:
- get_country() str [source]
Get the payment link country.
- Returns:
Two-letter ISO country code (e.g., “LT”)
- Return type:
- get_description() str [source]
Get the payment link description.
- Returns:
Payment link description
- Return type:
- class cardinity.models.payment_link.UpdatePaymentLink(link_id: str, data: Dict[str, Any])[source]
Bases:
BaseModel
Model for updating existing payment links.
This model allows updating the expiration date and enabled status of existing payment links.
- __init__(link_id: str, data: Dict[str, Any]) None [source]
Initialize UpdatePaymentLink model.
- Parameters:
link_id – The ID of the payment link to update
data – Update data dictionary
- get_constraints() Dict[str, Any] [source]
Get validation constraints for payment link updates.
- Returns:
Cerberus validation schema for payment link updates
- Return type:
Dict[str, Any]
- get_endpoint() str [source]
Get the API endpoint for payment link updates.
- Returns:
The payment link-specific endpoint
- Return type:
- get_method() str [source]
Get the HTTP method for payment link updates.
- Returns:
Always returns PATCH for payment link updates
- Return type:
- get_link_id() str [source]
Get the payment link ID being updated.
- Returns:
The payment link ID
- Return type:
- class cardinity.models.payment_link.GetPaymentLink(link_id: str)[source]
Bases:
ReadOnlyModel
Model for retrieving payment link information.
This model retrieves information about a specific payment link.
- __init__(link_id: str) None [source]
Initialize GetPaymentLink model.
- Parameters:
link_id – The ID of the payment link to retrieve
- get_constraints() Dict[str, Any] [source]
Get validation constraints for payment link retrieval.
- Returns:
Empty constraints for read-only operations
- Return type:
Dict[str, Any]
- get_endpoint() str [source]
Get the API endpoint for payment link retrieval.
- Returns:
The payment link-specific endpoint
- Return type:
Additional API Models
Cardinity Refund Models
This module contains models for refund operations.
- class cardinity.models.refund.Refund(payment_id: str, **kwargs: Any)[source]
Bases:
BaseModel
Model for creating refund requests.
Refunds allow merchants to return funds to customers for previously processed payments.
- __init__(payment_id: str, **kwargs: Any) None [source]
Initialize Refund model.
- Parameters:
payment_id – The ID of the payment to refund
**kwargs – Refund data as keyword arguments containing amount and description
- get_constraints() Dict[str, Any] [source]
Get validation constraints for refund creation.
- Returns:
Cerberus validation schema for refund data
- Return type:
Dict[str, Any]
- get_endpoint() str [source]
Get the API endpoint for refund creation.
- Returns:
The payment-specific refund endpoint
- Return type:
- get_method() str [source]
Get the HTTP method for refund creation.
- Returns:
Always returns POST for refund creation
- Return type:
- get_payment_id() str [source]
Get the payment ID being refunded.
- Returns:
The payment ID
- Return type:
- class cardinity.models.refund.GetRefund(payment_id: str, refund_id: str | None = None)[source]
Bases:
ReadOnlyModel
Model for retrieving refund information.
This model supports both single refund retrieval and listing all refunds for a payment.
- __init__(payment_id: str, refund_id: str | None = None) None [source]
Initialize GetRefund model.
- Parameters:
payment_id – The ID of the payment
refund_id – Optional specific refund ID to retrieve
- get_constraints() Dict[str, Any] [source]
Get validation constraints for refund retrieval.
- Returns:
Empty constraints for read-only operations
- Return type:
Dict[str, Any]
- get_endpoint() str [source]
Get the API endpoint for refund retrieval.
- Returns:
The appropriate endpoint based on retrieval mode
- Return type:
- get_method() str [source]
Get the HTTP method for refund retrieval.
- Returns:
Always returns GET for refund retrieval
- Return type:
Cardinity Settlement Models
This module contains models for settlement operations.
- class cardinity.models.settlement.Settlement(payment_id: str, **kwargs: Any)[source]
Bases:
BaseModel
Model for creating settlement requests.
Settlements allow merchants to capture funds from previously authorized payments.
- __init__(payment_id: str, **kwargs: Any) None [source]
Initialize Settlement model.
- Parameters:
payment_id – The ID of the payment to settle
**kwargs – Settlement data as keyword arguments containing amount and description
- get_constraints() Dict[str, Any] [source]
Get validation constraints for settlement creation.
- Returns:
Cerberus validation schema for settlement data
- Return type:
Dict[str, Any]
- get_endpoint() str [source]
Get the API endpoint for settlement creation.
- Returns:
The payment-specific settlement endpoint
- Return type:
- get_method() str [source]
Get the HTTP method for settlement creation.
- Returns:
Always returns POST for settlement creation
- Return type:
- get_payment_id() str [source]
Get the payment ID being settled.
- Returns:
The payment ID
- Return type:
- class cardinity.models.settlement.GetSettlement(payment_id: str, settlement_id: str | None = None)[source]
Bases:
ReadOnlyModel
Model for retrieving settlement information.
This model supports both single settlement retrieval and listing all settlements for a payment.
- __init__(payment_id: str, settlement_id: str | None = None) None [source]
Initialize GetSettlement model.
- Parameters:
payment_id – The ID of the payment
settlement_id – Optional specific settlement ID to retrieve
- get_constraints() Dict[str, Any] [source]
Get validation constraints for settlement retrieval.
- Returns:
Empty constraints for read-only operations
- Return type:
Dict[str, Any]
- get_endpoint() str [source]
Get the API endpoint for settlement retrieval.
- Returns:
The appropriate endpoint based on retrieval mode
- Return type:
- get_method() str [source]
Get the HTTP method for settlement retrieval.
- Returns:
Always returns GET for settlement retrieval
- Return type:
Cardinity Void Models
This module contains models for void operations.
- class cardinity.models.void.Void(payment_id: str, **kwargs: Any)[source]
Bases:
BaseModel
Model for creating void requests.
Voids allow merchants to cancel previously authorized payments before they are settled.
- __init__(payment_id: str, **kwargs: Any) None [source]
Initialize Void model.
- Parameters:
payment_id – The ID of the payment to void
**kwargs – Optional void data as keyword arguments containing description
- get_constraints() Dict[str, Any] [source]
Get validation constraints for void creation.
- Returns:
Cerberus validation schema for void data
- Return type:
Dict[str, Any]
- get_endpoint() str [source]
Get the API endpoint for void creation.
- Returns:
The payment-specific void endpoint
- Return type:
- get_method() str [source]
Get the HTTP method for void creation.
- Returns:
Always returns POST for void creation
- Return type:
- class cardinity.models.void.GetVoid(payment_id: str, void_id: str | None = None)[source]
Bases:
ReadOnlyModel
Model for retrieving void information.
This model supports both single void retrieval and listing all voids for a payment.
- __init__(payment_id: str, void_id: str | None = None) None [source]
Initialize GetVoid model.
- Parameters:
payment_id – The ID of the payment
void_id – Optional specific void ID to retrieve
- get_constraints() Dict[str, Any] [source]
Get validation constraints for void retrieval.
- Returns:
Empty constraints for read-only operations
- Return type:
Dict[str, Any]
- get_endpoint() str [source]
Get the API endpoint for void retrieval.
- Returns:
The appropriate endpoint based on retrieval mode
- Return type:
- get_method() str [source]
Get the HTTP method for void retrieval.
- Returns:
Always returns GET for void retrieval
- Return type:
Cardinity Chargeback Models
This module contains models for chargeback operations.
- class cardinity.models.chargeback.GetChargeback(payment_id_or_limit: str | int | None = None, chargeback_id: str | None = None)[source]
Bases:
ReadOnlyModel
Model for retrieving chargeback information.
This model supports multiple chargeback retrieval modes: 1. Single chargeback retrieval by payment_id and chargeback_id 2. All chargebacks for a specific payment 3. Global chargeback listing with optional limit
- __init__(payment_id_or_limit: str | int | None = None, chargeback_id: str | None = None) None [source]
Initialize GetChargeback model.
- Parameters:
payment_id_or_limit – Either a payment ID (str) for payment-specific chargebacks, or limit (int) for global listing, or None for all global chargebacks
chargeback_id – Optional specific chargeback ID to retrieve
- get_constraints() Dict[str, Any] [source]
Get validation constraints for chargeback retrieval.
- Returns:
Empty constraints for read-only operations
- Return type:
Dict[str, Any]
- get_endpoint() str [source]
Get the API endpoint for chargeback retrieval.
- Returns:
The appropriate endpoint based on retrieval mode
- Return type:
- get_method() str [source]
Get the HTTP method for chargeback retrieval.
- Returns:
Always returns GET for chargeback retrieval
- Return type:
- get_payment_id() str | None [source]
Get the payment ID for payment-specific chargebacks.
- Returns:
Payment ID or None if global mode
- Return type:
Optional[str]
- get_chargeback_id() str | None [source]
Get the chargeback ID for single chargeback retrieval.
- Returns:
Chargeback ID or None if listing mode
- Return type:
Optional[str]
- get_limit() int | None [source]
Get the limit for global chargeback listing.
- Returns:
Limit value or None if not applicable
- Return type:
Optional[int]
- is_global_listing() bool [source]
Check if this is a global chargeback listing request.
- Returns:
True if global listing, False if payment-specific
- Return type:
Validation
Constraints
Cardinity Validation Constraints
This module defines all validation constraints for the Cardinity API data structures. It uses Cerberus schema format for consistent validation across the SDK.
- class cardinity.validation.constraints.Constraints[source]
Bases:
object
Collection of validation constraints for Cardinity API fields.
- static amount() Dict[str, Any] [source]
Constraint for monetary amounts.
- Returns:
Cerberus schema for amount validation
- Return type:
Dict
- static currency() Dict[str, Any] [source]
Constraint for currency codes.
- Returns:
Cerberus schema for currency validation
- Return type:
Dict
- static country() Dict[str, Any] [source]
Constraint for country codes.
- Returns:
Cerberus schema for country validation
- Return type:
Dict
- static description() Dict[str, Any] [source]
Constraint for payment descriptions.
- Returns:
Cerberus schema for description validation
- Return type:
Dict
- static order_id() Dict[str, Any] [source]
Constraint for order IDs.
- Returns:
Cerberus schema for order_id validation
- Return type:
Dict
- static payment_id() Dict[str, Any] [source]
Constraint for payment IDs (UUIDs).
- Returns:
Cerberus schema for payment_id validation
- Return type:
Dict
- static payment_instrument() Dict[str, Any] [source]
Constraint for payment instrument (card) data.
- Returns:
Cerberus schema for payment instrument validation
- Return type:
Dict
- static billing_address() Dict[str, Any] [source]
Constraint for billing address data.
- Returns:
Cerberus schema for billing address validation
- Return type:
Dict
- static threeds2_data() Dict[str, Any] [source]
Constraint for 3D Secure v2 data.
- Returns:
Cerberus schema for 3DS v2 validation
- Return type:
Dict
- static recurring_data() Dict[str, Any] [source]
Constraint for recurring payment data.
- Returns:
Cerberus schema for recurring payment validation
- Return type:
Dict
- static refund_amount() Dict[str, Any] [source]
Constraint for refund amounts.
- Returns:
Cerberus schema for refund amount validation
- Return type:
Dict
- static settlement_amount() Dict[str, Any] [source]
Constraint for settlement amounts.
- Returns:
Cerberus schema for settlement amount validation
- Return type:
Dict
- static payment_link_data() Dict[str, Any] [source]
Constraint for payment link creation data.
- Returns:
Cerberus schema for payment link validation
- Return type:
Dict
- static finalize_payment() Dict[str, Any] [source]
Constraint for payment finalization data.
- Returns:
Cerberus schema for payment finalization
- Return type:
Dict
- static create_payment_schema() Dict[str, Any] [source]
Complete schema for payment creation.
- Returns:
Complete Cerberus schema for payment creation
- Return type:
Dict
- static create_recurring_payment_schema() Dict[str, Any] [source]
Complete schema for recurring payment creation.
- Returns:
Complete Cerberus schema for recurring payment
- Return type:
Dict
- static create_refund_schema() Dict[str, Any] [source]
Complete schema for refund creation.
- Returns:
Complete Cerberus schema for refund creation
- Return type:
Dict
- static create_settlement_schema() Dict[str, Any] [source]
Complete schema for settlement creation.
- Returns:
Complete Cerberus schema for settlement creation
- Return type:
Dict
- static finalize_payment_schema(is_threedsv2: bool = False) Dict[str, Any] [source]
Complete schema for payment finalization.
- Parameters:
is_threedsv2 – Whether this is a 3D Secure v2 flow
- Returns:
Complete Cerberus schema for payment finalization
- Return type:
Dict
Validators
Cardinity Validation Engine
This module provides the validation functionality using Cerberus validator.
- class cardinity.validation.validators.CardinityValidator(*args, **kwargs)[source]
Bases:
Validator
Custom Cerberus validator for Cardinity API data.
This extends the base Cerberus validator with custom validation methods specific to Cardinity API requirements.
- checkers = ('validate_amount', 'validate_expiry_date', 'validate_payment_id')
- coercers = ()
- default_setters = ()
- normalization_rules = {'coerce': {'oneof': [{'type': 'callable'}, {'schema': {'oneof': [{'type': 'callable'}, {'allowed': (), 'type': 'string'}]}, 'type': 'list'}, {'allowed': (), 'type': 'string'}]}, 'default': {'nullable': True}, 'default_setter': {'oneof': [{'type': 'callable'}, {'allowed': (), 'type': 'string'}]}, 'purge_unknown': {'type': 'boolean'}, 'rename': {'type': 'hashable'}, 'rename_handler': {'oneof': [{'type': 'callable'}, {'schema': {'oneof': [{'type': 'callable'}, {'allowed': (), 'type': 'string'}]}, 'type': 'list'}, {'allowed': (), 'type': 'string'}]}}
- rules = {'allof': {'logical': 'allof', 'type': 'list'}, 'allow_unknown': {'oneof': [{'type': 'boolean'}, {'check_with': 'bulk_schema', 'type': ['dict', 'string']}]}, 'allowed': {'type': 'container'}, 'anyof': {'logical': 'anyof', 'type': 'list'}, 'check_with': {'oneof': [{'type': 'callable'}, {'schema': {'oneof': [{'type': 'callable'}, {'allowed': ('validate_amount', 'validate_expiry_date', 'validate_payment_id'), 'type': 'string'}]}, 'type': 'list'}, {'allowed': ('validate_amount', 'validate_expiry_date', 'validate_payment_id'), 'type': 'string'}]}, 'coerce': {'oneof': [{'type': 'callable'}, {'schema': {'oneof': [{'type': 'callable'}, {'allowed': (), 'type': 'string'}]}, 'type': 'list'}, {'allowed': (), 'type': 'string'}]}, 'contains': {'empty': False}, 'default': {'nullable': True}, 'default_setter': {'oneof': [{'type': 'callable'}, {'allowed': (), 'type': 'string'}]}, 'dependencies': {'check_with': 'dependencies', 'type': ('dict', 'hashable', 'list')}, 'empty': {'type': 'boolean'}, 'excludes': {'schema': {'type': 'hashable'}, 'type': ('hashable', 'list')}, 'forbidden': {'type': 'list'}, 'items': {'check_with': 'items', 'type': 'list'}, 'keysrules': {'check_with': 'bulk_schema', 'forbidden': ['rename', 'rename_handler'], 'type': ['dict', 'string']}, 'max': {'nullable': False}, 'maxlength': {'type': 'integer'}, 'meta': {}, 'min': {'nullable': False}, 'minlength': {'type': 'integer'}, 'noneof': {'logical': 'noneof', 'type': 'list'}, 'nullable': {'type': 'boolean'}, 'oneof': {'logical': 'oneof', 'type': 'list'}, 'purge_unknown': {'type': 'boolean'}, 'readonly': {'type': 'boolean'}, 'regex': {'type': 'string'}, 'rename': {'type': 'hashable'}, 'rename_handler': {'oneof': [{'type': 'callable'}, {'schema': {'oneof': [{'type': 'callable'}, {'allowed': (), 'type': 'string'}]}, 'type': 'list'}, {'allowed': (), 'type': 'string'}]}, 'require_all': {'type': 'boolean'}, 'required': {'type': 'boolean'}, 'schema': {'anyof': [{'check_with': 'schema'}, {'check_with': 'bulk_schema'}], 'type': ['dict', 'string']}, 'type': {'check_with': 'type', 'type': ['string', 'list']}, 'valuesrules': {'check_with': 'bulk_schema', 'forbidden': ['rename', 'rename_handler'], 'type': ['dict', 'string']}}
- validation_rules = {'allof': {'logical': 'allof', 'type': 'list'}, 'allow_unknown': {'oneof': [{'type': 'boolean'}, {'check_with': 'bulk_schema', 'type': ['dict', 'string']}]}, 'allowed': {'type': 'container'}, 'anyof': {'logical': 'anyof', 'type': 'list'}, 'check_with': {'oneof': [{'type': 'callable'}, {'schema': {'oneof': [{'type': 'callable'}, {'allowed': ('validate_amount', 'validate_expiry_date', 'validate_payment_id'), 'type': 'string'}]}, 'type': 'list'}, {'allowed': ('validate_amount', 'validate_expiry_date', 'validate_payment_id'), 'type': 'string'}]}, 'contains': {'empty': False}, 'dependencies': {'check_with': 'dependencies', 'type': ('dict', 'hashable', 'list')}, 'empty': {'type': 'boolean'}, 'excludes': {'schema': {'type': 'hashable'}, 'type': ('hashable', 'list')}, 'forbidden': {'type': 'list'}, 'items': {'check_with': 'items', 'type': 'list'}, 'keysrules': {'check_with': 'bulk_schema', 'forbidden': ['rename', 'rename_handler'], 'type': ['dict', 'string']}, 'max': {'nullable': False}, 'maxlength': {'type': 'integer'}, 'meta': {}, 'min': {'nullable': False}, 'minlength': {'type': 'integer'}, 'noneof': {'logical': 'noneof', 'type': 'list'}, 'nullable': {'type': 'boolean'}, 'oneof': {'logical': 'oneof', 'type': 'list'}, 'readonly': {'type': 'boolean'}, 'regex': {'type': 'string'}, 'require_all': {'type': 'boolean'}, 'required': {'type': 'boolean'}, 'schema': {'anyof': [{'check_with': 'schema'}, {'check_with': 'bulk_schema'}], 'type': ['dict', 'string']}, 'type': {'check_with': 'type', 'type': ['string', 'list']}, 'valuesrules': {'check_with': 'bulk_schema', 'forbidden': ['rename', 'rename_handler'], 'type': ['dict', 'string']}}
- cardinity.validation.validators.validate_data(data: Dict[str, Any], schema: Dict[str, Any]) Dict[str, List[str]] | None [source]
Validate data against a schema using Cerberus.
- Parameters:
data – The data to validate
schema – The validation schema
- Returns:
Dictionary of validation errors if any, None if validation passes
- cardinity.validation.validators.validate_required_fields(data: Dict[str, Any], required_fields: List[str]) Dict[str, List[str]] | None [source]
Validate that all required fields are present.
- Parameters:
data – The data to validate
required_fields – List of required field names
- Returns:
Dictionary of validation errors if any, None if validation passes
- cardinity.validation.validators.validate_amount_format(amount: Any) str | None [source]
Validate amount format specifically.
- Parameters:
amount – The amount value to validate
- Returns:
Error message if validation fails, None if validation passes
- cardinity.validation.validators.validate_card_number(pan: Any) str | None [source]
Validate credit card number format.
- Parameters:
pan – Primary Account Number (card number)
- Returns:
Error message if validation fails, None if validation passes
Exceptions
Cardinity SDK Exceptions
This module contains all custom exception classes used by the Cardinity SDK.
- exception cardinity.exceptions.CardinityError(message: str)[source]
Bases:
Exception
Base exception for all Cardinity SDK errors.
This is the base exception class that all other Cardinity SDK exceptions inherit from. It provides a common interface for error handling.
- exception cardinity.exceptions.ValidationError(message: str, errors: Dict[str, Any] | None = None)[source]
Bases:
CardinityError
Exception raised when input validation fails.
This exception is raised when data validation fails before making an API request. It contains details about which fields failed validation.
- exception cardinity.exceptions.APIError(message: str, status_code: int | None = None, response_data: Dict[str, Any] | None = None)[source]
Bases:
CardinityError
Exception raised when the API returns an error response.
This exception is raised when the Cardinity API returns an error response (4xx or 5xx status codes). It contains the HTTP status code and the response data from the API.
- exception cardinity.exceptions.AuthenticationError(message: str = 'Authentication failed')[source]
Bases:
APIError
Exception raised when authentication fails.
This exception is raised when the API returns a 401 Unauthorized response, indicating that the OAuth credentials are invalid or expired.
- exception cardinity.exceptions.NotFoundError(message: str = 'Resource not found')[source]
Bases:
APIError
Exception raised when a requested resource is not found.
This exception is raised when the API returns a 404 Not Found response, indicating that the requested resource (payment, refund, etc.) does not exist.
- exception cardinity.exceptions.RateLimitError(message: str = 'Rate limit exceeded')[source]
Bases:
APIError
Exception raised when API rate limits are exceeded.
This exception is raised when the API returns a 429 Too Many Requests response, indicating that the rate limit has been exceeded.
Utilities
Cardinity Utilities
This package contains utility functions and helpers.