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')

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

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]

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]

Get payment information.

Parameters:

• payment_id – Specific payment ID to retrieve (optional)

• limit – Limit for payment listing (optional, used when payment_id is None)

Returns:

Payment data or list of payments

Return type:

Dict[str, Any]

Raises:

APIError – If the API request fails

finalize_payment(payment_id: str, **kwargs: Any) → Dict[str, Any]

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]

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]

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]

Get refund information.

Parameters:

• payment_id – ID of the payment

• refund_id – Specific refund ID (optional, lists all if None)

Returns:

Refund data or list of refunds

Return type:

Dict[str, Any]

Raises:

APIError – If the API request fails

create_settlement(payment_id: str, **kwargs: Any) → Dict[str, Any]

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]

Get settlement information.

Parameters:

• payment_id – ID of the payment

• settlement_id – Specific settlement ID (optional, lists all if None)

Returns:

Settlement data or list of settlements

Return type:

Dict[str, Any]

Raises:

APIError – If the API request fails

create_void(payment_id: str, **kwargs: Any) → Dict[str, Any]

Create a void for a payment.

Parameters:

• payment_id – ID of the payment to void

• **kwargs – Optional void data including description

Returns:

Void response

Return type:

Dict[str, Any]

Raises:

APIError – If the API request fails

get_void(payment_id: str, void_id: str | None = None) → Dict[str, Any]

Get void information.

Parameters:

• payment_id – ID of the payment

• void_id – Specific void ID (optional, lists all if None)

Returns:

Void data or list of voids

Return type:

Dict[str, Any]

Raises:

APIError – If the API request fails

get_chargeback(payment_id_or_limit: str | int | None = None, chargeback_id: str | None = None) → Dict[str, Any]

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”)

Parameters:

• payment_id_or_limit – Payment ID (str) or limit (int) for global listing

• chargeback_id – Specific chargeback ID (optional)

Returns:

Chargeback data or list of chargebacks

Return type:

Dict[str, Any]

Raises:

APIError – If the API request fails

create_payment_link(**kwargs: Any) → Dict[str, Any]

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]

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_payment_link(link_id: str) → Dict[str, Any]

Get payment link information.

Parameters:

link_id – ID of the payment link to retrieve

Returns:

Payment link data

Return type:

Dict[str, Any]

Raises:

APIError – If the API request fails

get_client() → CardinityClient

Get the underlying HTTP client for advanced usage.

Returns:

The HTTP client instance

Return type:

CardinityClient

get_auth() → CardinityAuth

Get the authentication instance.

Returns:

The authentication instance

Return type:

CardinityAuth

Authentication

Cardinity Authentication

This module handles OAuth 1.0 authentication for the Cardinity API.

class cardinity.auth.CardinityAuth(consumer_key: str, consumer_secret: str)

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

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

Get the OAuth1 authentication object for requests.

Returns:

Configured OAuth1 authentication object that can be used

with the requests library

Return type:

OAuth1

get_auth_headers(method: str, url: str, body: str = '') → Dict[str, str]

Get authentication headers for a specific request.

This is an alternative method to get_auth() that returns the headers directly instead of an OAuth1 object.

Parameters:

• method – HTTP method (GET, POST, PATCH, etc.)

• url – Full URL for the request

• body – Request body (for POST/PATCH requests)

Returns:

Dictionary containing OAuth authentication headers

Return type:

Dict[str, str]

__repr__() → str

Return a string representation of the auth object.

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)

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

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]

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]

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]

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]

Make a DELETE request to the API.

Parameters:

endpoint – API endpoint path

Returns:

API response data

Return type:

Dict[str, Any]

execute_request(model) → Dict[str, Any]

Execute a request using a model object.

Parameters:

model – Model object with get_method(), get_endpoint(), and to_dict() methods

Returns:

Parsed API response data

Return type:

Dict[str, Any]

Raises:

CardinityError – If the request fails

close() → None

Close the HTTP session and clean up resources.

__enter__()

Context manager entry.

__exit__(exc_type, exc_val, exc_tb)

Context manager exit.

__repr__() → str

Return a string representation of the client.

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)

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

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]

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

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:

str

Raises:

NotImplementedError – If not implemented by subclass

abstractmethod get_method() → str

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:

str

Raises:

NotImplementedError – If not implemented by subclass

to_dict() → Dict[str, Any]

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]

Get the raw model data.

Returns:

Copy of the internal model data

Return type:

Dict[str, Any]

update_data(**kwargs: Any) → None

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

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

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:

bool

validate() → Dict[str, Any] | None

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

Check if the current model data is valid.

Returns:

True if valid, False otherwise

Return type:

bool

__repr__() → str

Return a string representation of the model.

Returns:

String representation showing class name and key fields

Return type:

str

__eq__(other: object) → bool

Check equality with another model instance.

Parameters:

other – Other object to compare with

Returns:

True if equal, False otherwise

Return type:

bool

__hash__() → int

Generate hash for the model instance.

Returns:

Hash value based on class and data

Return type:

int

class cardinity.models.base.ReadOnlyModel(**kwargs: Any)

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

Prevent data updates on read-only models.

Parameters:

**kwargs – Ignored

Raises:

ValidationError – Always raised for read-only models

get_method() → str

Default HTTP method for read-only models.

Returns:

Always returns “GET” for read-only models

Return type:

str

Payment Models

Cardinity Payment Model

This module contains the Payment model for creating payment requests.

class cardinity.models.payment.Payment(**kwargs: Any)

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

Initialize Payment model.

Parameters:

**kwargs – Payment data as keyword arguments

get_constraints() → Dict[str, Any]

Get validation constraints for payment creation.

Returns:

Cerberus validation schema for payment data

Return type:

Dict[str, Any]

get_endpoint() → str

Get the API endpoint for payment creation.

Returns:

The payments endpoint

Return type:

str

get_method() → str

Get the HTTP method for payment creation.

Returns:

Always returns POST for payment creation

Return type:

str

to_dict() → Dict[str, Any]

Convert payment data to API-compatible dictionary.

Returns:

Payment data formatted for API submission

Return type:

Dict[str, Any]

get_amount() → str

Get the payment amount.

Returns:

Payment amount in decimal format (e.g., “10.50”)

Return type:

str

get_currency() → str

Get the payment currency.

Returns:

Three-letter ISO currency code (e.g., “EUR”)

Return type:

str

get_payment_instrument() → Dict[str, Any]

Get the payment instrument (card) data.

Returns:

Payment instrument data including PAN, expiry, etc.

Return type:

Dict[str, Any]

has_threeds2_data() → bool

Check if 3D Secure v2 data is present.

Returns:

True if 3DS v2 data is present

Return type:

bool

has_billing_address() → bool

Check if billing address is present.

Returns:

True if billing address is present

Return type:

bool

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)

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)

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]

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

Get the API endpoint for payment retrieval.

Returns:

The appropriate endpoint based on retrieval mode

Return type:

str

get_method() → str

Get the HTTP method for payment retrieval.

Returns:

Always returns GET for payment retrieval

Return type:

str

is_listing() → bool

Check if this is a payment listing request.

Returns:

True if listing payments, False if retrieving single payment

Return type:

bool

get_payment_id() → str | None

Get the payment ID for single payment retrieval.

Returns:

Payment ID or None if listing mode

Return type:

Optional[str]

get_limit() → int | None

Get the limit for payment listing.

Returns:

Limit value or None if single retrieval mode

Return type:

Optional[int]

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)

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)

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]

Get validation constraints for payment finalization.

Returns:

Cerberus validation schema for finalization data

Return type:

Dict[str, Any]

get_endpoint() → str

Get the API endpoint for payment finalization.

Returns:

The payment-specific endpoint for PATCH operations

Return type:

str

get_method() → str

Get the HTTP method for payment finalization.

Returns:

Always returns PATCH for payment finalization

Return type:

str

is_threedsv2() → bool

Check if this is a 3D Secure v2 flow.

Returns:

True if 3DS v2, False if 3DS v1

Return type:

bool

get_payment_id() → str

Get the payment ID being finalized.

Returns:

The payment ID

Return type:

str

get_cres() → str | None

Get the Challenge Response for 3DS v2.

Returns:

The cres value or None if not 3DS v2

Return type:

Optional[str]

get_authorize_data() → str | None

Get the authorization data for 3DS v1.

Returns:

The authorize_data value or None if 3DS v2

Return type:

Optional[str]

to_dict() → Dict[str, Any]

Convert finalization data to API-compatible dictionary.

Returns:

Only the relevant field based on 3DS version

Return type:

Dict[str, Any]

Cardinity Recurring Payment Model

This module contains the RecurringPayment model for creating recurring payments.

class cardinity.models.recurring_payment.RecurringPayment(**kwargs: Any)

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

Initialize RecurringPayment model.

Parameters:

**kwargs – Recurring payment data as keyword arguments

get_constraints() → Dict[str, Any]

Get validation constraints for recurring payment creation.

Returns:

Cerberus validation schema for recurring payment data

Return type:

Dict[str, Any]

get_endpoint() → str

Get the API endpoint for recurring payment creation.

Returns:

The payments endpoint (same as regular payments)

Return type:

str

get_method() → str

Get the HTTP method for recurring payment creation.

Returns:

Always returns POST for recurring payment creation

Return type:

str

to_dict() → Dict[str, Any]

Convert recurring payment data to API-compatible dictionary.

Returns:

Recurring payment data formatted for API submission

Return type:

Dict[str, Any]

get_amount() → str

Get the payment amount.

Returns:

Payment amount in decimal format (e.g., “10.50”)

Return type:

str

get_currency() → str

Get the payment currency.

Returns:

Three-letter ISO currency code (e.g., “EUR”)

Return type:

str

get_payment_instrument() → Dict[str, Any]

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

Get the payment description.

Returns:

Payment description

Return type:

str

get_order_id() → str

Get the order ID.

Returns:

Merchant’s order identifier

Return type:

str

is_settle() → bool

Check if payment should be automatically settled.

Returns:

True if payment should be settled immediately

Return type:

bool

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])

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

Initialize PaymentLink model.

Parameters:

data – Payment link data dictionary

get_constraints() → Dict[str, Any]

Get validation constraints for payment link creation.

Returns:

Cerberus validation schema for payment link data

Return type:

Dict[str, Any]

get_endpoint() → str

Get the API endpoint for payment link creation.

Returns:

The payment links endpoint

Return type:

str

get_method() → str

Get the HTTP method for payment link creation.

Returns:

Always returns POST for payment link creation

Return type:

str

get_amount() → str

Get the payment link amount.

Returns:

Payment amount in decimal format (e.g., “10.50”)

Return type:

str

get_currency() → str

Get the payment link currency.

Returns:

Three-letter ISO currency code (e.g., “EUR”)

Return type:

str

get_country() → str

Get the payment link country.

Returns:

Two-letter ISO country code (e.g., “LT”)

Return type:

str

get_description() → str

Get the payment link description.

Returns:

Payment link description

Return type:

str

get_expiration_date() → str | None

Get the payment link expiration date.

Returns:

Expiration date in ISO 8601 format or None

Return type:

Optional[str]

is_multiple_use() → bool

Check if payment link allows multiple uses.

Returns:

True if multiple use is allowed

Return type:

bool

class cardinity.models.payment_link.UpdatePaymentLink(link_id: str, data: Dict[str, Any])

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

Initialize UpdatePaymentLink model.

Parameters:

• link_id – The ID of the payment link to update

• data – Update data dictionary

get_constraints() → Dict[str, Any]

Get validation constraints for payment link updates.

Returns:

Cerberus validation schema for payment link updates

Return type:

Dict[str, Any]

get_endpoint() → str

Get the API endpoint for payment link updates.

Returns:

The payment link-specific endpoint

Return type:

str

get_method() → str

Get the HTTP method for payment link updates.

Returns:

Always returns PATCH for payment link updates

Return type:

str

get_link_id() → str

Get the payment link ID being updated.

Returns:

The payment link ID

Return type:

str

get_expiration_date() → str | None

Get the updated expiration date.

Returns:

Expiration date in ISO 8601 format or None

Return type:

Optional[str]

is_enabled() → bool | None

Get the enabled status.

Returns:

Enabled status or None if not set

Return type:

Optional[bool]

class cardinity.models.payment_link.GetPaymentLink(link_id: str)

Bases: ReadOnlyModel

Model for retrieving payment link information.

This model retrieves information about a specific payment link.

__init__(link_id: str) → None

Initialize GetPaymentLink model.

Parameters:

link_id – The ID of the payment link to retrieve

get_constraints() → Dict[str, Any]

Get validation constraints for payment link retrieval.

Returns:

Empty constraints for read-only operations

Return type:

Dict[str, Any]

get_endpoint() → str

Get the API endpoint for payment link retrieval.

Returns:

The payment link-specific endpoint

Return type:

str

get_method() → str

Get the HTTP method for payment link retrieval.

Returns:

Always returns GET for payment link retrieval

Return type:

str

get_link_id() → str

Get the payment link ID being retrieved.

Returns:

The payment link ID

Return type:

str

Additional API Models

Cardinity Refund Models

This module contains models for refund operations.

class cardinity.models.refund.Refund(payment_id: str, **kwargs: Any)

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

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]

Get validation constraints for refund creation.

Returns:

Cerberus validation schema for refund data

Return type:

Dict[str, Any]

get_endpoint() → str

Get the API endpoint for refund creation.

Returns:

The payment-specific refund endpoint

Return type:

str

get_method() → str

Get the HTTP method for refund creation.

Returns:

Always returns POST for refund creation

Return type:

str

get_payment_id() → str

Get the payment ID being refunded.

Returns:

The payment ID

Return type:

str

get_amount() → str

Get the refund amount.

Returns:

Refund amount in decimal format (e.g., “10.50”)

Return type:

str

get_description() → str

Get the refund description.

Returns:

Refund description

Return type:

str

class cardinity.models.refund.GetRefund(payment_id: str, refund_id: str | None = None)

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

Initialize GetRefund model.

Parameters:

• payment_id – The ID of the payment

• refund_id – Optional specific refund ID to retrieve

get_constraints() → Dict[str, Any]

Get validation constraints for refund retrieval.

Returns:

Empty constraints for read-only operations

Return type:

Dict[str, Any]

get_endpoint() → str

Get the API endpoint for refund retrieval.

Returns:

The appropriate endpoint based on retrieval mode

Return type:

str

get_method() → str

Get the HTTP method for refund retrieval.

Returns:

Always returns GET for refund retrieval

Return type:

str

get_payment_id() → str

Get the payment ID.

Returns:

The payment ID

Return type:

str

get_refund_id() → str | None

Get the refund ID for single refund retrieval.

Returns:

Refund ID or None if listing mode

Return type:

Optional[str]

is_listing() → bool

Check if this is a refund listing request.

Returns:

True if listing refunds, False if retrieving single refund

Return type:

bool

Cardinity Settlement Models

This module contains models for settlement operations.

class cardinity.models.settlement.Settlement(payment_id: str, **kwargs: Any)

Bases: BaseModel

Model for creating settlement requests.

Settlements allow merchants to capture funds from previously authorized payments.

__init__(payment_id: str, **kwargs: Any) → None

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]

Get validation constraints for settlement creation.

Returns:

Cerberus validation schema for settlement data

Return type:

Dict[str, Any]

get_endpoint() → str

Get the API endpoint for settlement creation.

Returns:

The payment-specific settlement endpoint

Return type:

str

get_method() → str

Get the HTTP method for settlement creation.

Returns:

Always returns POST for settlement creation

Return type:

str

get_payment_id() → str

Get the payment ID being settled.

Returns:

The payment ID

Return type:

str

get_amount() → str

Get the settlement amount.

Returns:

Settlement amount in decimal format (e.g., “10.50”)

Return type:

str

get_description() → str

Get the settlement description.

Returns:

Settlement description

Return type:

str

class cardinity.models.settlement.GetSettlement(payment_id: str, settlement_id: str | None = None)

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

Initialize GetSettlement model.

Parameters:

• payment_id – The ID of the payment

• settlement_id – Optional specific settlement ID to retrieve

get_constraints() → Dict[str, Any]

Get validation constraints for settlement retrieval.

Returns:

Empty constraints for read-only operations

Return type:

Dict[str, Any]

get_endpoint() → str

Get the API endpoint for settlement retrieval.

Returns:

The appropriate endpoint based on retrieval mode

Return type:

str

get_method() → str

Get the HTTP method for settlement retrieval.

Returns:

Always returns GET for settlement retrieval

Return type:

str

get_payment_id() → str

Get the payment ID.

Returns:

The payment ID

Return type:

str

get_settlement_id() → str | None

Get the settlement ID for single settlement retrieval.

Returns:

Settlement ID or None if listing mode

Return type:

Optional[str]

is_listing() → bool

Check if this is a settlement listing request.

Returns:

True if listing settlements, False if retrieving single settlement

Return type:

bool

Cardinity Void Models

This module contains models for void operations.

class cardinity.models.void.Void(payment_id: str, **kwargs: Any)

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

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]

Get validation constraints for void creation.

Returns:

Cerberus validation schema for void data

Return type:

Dict[str, Any]

get_endpoint() → str

Get the API endpoint for void creation.

Returns:

The payment-specific void endpoint

Return type:

str

get_method() → str

Get the HTTP method for void creation.

Returns:

Always returns POST for void creation

Return type:

str

get_payment_id() → str

Get the payment ID being voided.

Returns:

The payment ID

Return type:

str

get_description() → str

Get the void description.

Returns:

Void description

Return type:

str

class cardinity.models.void.GetVoid(payment_id: str, void_id: str | None = None)

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

Initialize GetVoid model.

Parameters:

• payment_id – The ID of the payment

• void_id – Optional specific void ID to retrieve

get_constraints() → Dict[str, Any]

Get validation constraints for void retrieval.

Returns:

Empty constraints for read-only operations

Return type:

Dict[str, Any]

get_endpoint() → str

Get the API endpoint for void retrieval.

Returns:

The appropriate endpoint based on retrieval mode

Return type:

str

get_method() → str

Get the HTTP method for void retrieval.

Returns:

Always returns GET for void retrieval

Return type:

str

get_payment_id() → str

Get the payment ID.

Returns:

The payment ID

Return type:

str

get_void_id() → str | None

Get the void ID for single void retrieval.

Returns:

Void ID or None if listing mode

Return type:

Optional[str]

is_listing() → bool

Check if this is a void listing request.

Returns:

True if listing voids, False if retrieving single void

Return type:

bool

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)

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

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]

Get validation constraints for chargeback retrieval.

Returns:

Empty constraints for read-only operations

Return type:

Dict[str, Any]

get_endpoint() → str

Get the API endpoint for chargeback retrieval.

Returns:

The appropriate endpoint based on retrieval mode

Return type:

str

get_method() → str

Get the HTTP method for chargeback retrieval.

Returns:

Always returns GET for chargeback retrieval

Return type:

str

get_payment_id() → str | None

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

Get the chargeback ID for single chargeback retrieval.

Returns:

Chargeback ID or None if listing mode

Return type:

Optional[str]

get_limit() → int | None

Get the limit for global chargeback listing.

Returns:

Limit value or None if not applicable

Return type:

Optional[int]

is_global_listing() → bool

Check if this is a global chargeback listing request.

Returns:

True if global listing, False if payment-specific

Return type:

bool

is_payment_specific() → bool

Check if this is a payment-specific chargeback request.

Returns:

True if payment-specific, False if global

Return type:

bool

is_single_chargeback() → bool

Check if this is a single chargeback retrieval request.

Returns:

True if retrieving single chargeback, False if listing

Return type:

bool

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

Bases: object

Collection of validation constraints for Cardinity API fields.

static amount() → Dict[str, Any]

Constraint for monetary amounts.

Returns:

Cerberus schema for amount validation

Return type:

Dict

static currency() → Dict[str, Any]

Constraint for currency codes.

Returns:

Cerberus schema for currency validation

Return type:

Dict

static country() → Dict[str, Any]

Constraint for country codes.

Returns:

Cerberus schema for country validation

Return type:

Dict

static description() → Dict[str, Any]

Constraint for payment descriptions.

Returns:

Cerberus schema for description validation

Return type:

Dict

static order_id() → Dict[str, Any]

Constraint for order IDs.

Returns:

Cerberus schema for order_id validation

Return type:

Dict

static payment_id() → Dict[str, Any]

Constraint for payment IDs (UUIDs).

Returns:

Cerberus schema for payment_id validation

Return type:

Dict

static payment_instrument() → Dict[str, Any]

Constraint for payment instrument (card) data.

Returns:

Cerberus schema for payment instrument validation

Return type:

Dict

static billing_address() → Dict[str, Any]

Constraint for billing address data.

Returns:

Cerberus schema for billing address validation

Return type:

Dict

static threeds2_data() → Dict[str, Any]

Constraint for 3D Secure v2 data.

Returns:

Cerberus schema for 3DS v2 validation

Return type:

Dict

static recurring_data() → Dict[str, Any]

Constraint for recurring payment data.

Returns:

Cerberus schema for recurring payment validation

Return type:

Dict

static refund_amount() → Dict[str, Any]

Constraint for refund amounts.

Returns:

Cerberus schema for refund amount validation

Return type:

Dict

static settlement_amount() → Dict[str, Any]

Constraint for settlement amounts.

Returns:

Cerberus schema for settlement amount validation

Return type:

Dict

static payment_link_data() → Dict[str, Any]

Constraint for payment link creation data.

Returns:

Cerberus schema for payment link validation

Return type:

Dict

static finalize_payment() → Dict[str, Any]

Constraint for payment finalization data.

Returns:

Cerberus schema for payment finalization

Return type:

Dict

static create_payment_schema() → Dict[str, Any]

Complete schema for payment creation.

Returns:

Complete Cerberus schema for payment creation

Return type:

Dict

static create_recurring_payment_schema() → Dict[str, Any]

Complete schema for recurring payment creation.

Returns:

Complete Cerberus schema for recurring payment

Return type:

Dict

static create_refund_schema() → Dict[str, Any]

Complete schema for refund creation.

Returns:

Complete Cerberus schema for refund creation

Return type:

Dict

static create_settlement_schema() → Dict[str, Any]

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]

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

static create_payment_link_schema() → Dict[str, Any]

Complete schema for payment link creation.

Returns:

Complete Cerberus schema for payment link creation

Return type:

Dict

static update_payment_link_schema() → Dict[str, Any]

Complete schema for payment link updates.

Returns:

Complete Cerberus schema for payment link updates

Return type:

Dict

Validators

Cardinity Validation Engine

This module provides the validation functionality using Cerberus validator.

class cardinity.validation.validators.CardinityValidator(*args, **kwargs)

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

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

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

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

Validate credit card number format.

Parameters:

pan – Primary Account Number (card number)

Returns:

Error message if validation fails, None if validation passes

cardinity.validation.validators.validate_currency_code(currency: Any) → str | None

Validate ISO currency code.

Parameters:

currency – Currency code to validate

Returns:

Error message if validation fails, None if validation passes

cardinity.validation.validators.validate_country_code(country: Any) → str | None

Validate ISO country code.

Parameters:

country – Country code to validate

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)

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.

__init__(message: str) → None

Initialize the CardinityError.

Parameters:

message – The error message

exception cardinity.exceptions.ValidationError(message: str, errors: Dict[str, Any] | None = None)

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.

__init__(message: str, errors: Dict[str, Any] | None = None) → None

Initialize the ValidationError.

Parameters:

• message – The error message

• errors – Dictionary containing validation errors for each field

__str__() → str

Return a string representation of the validation error.

exception cardinity.exceptions.APIError(message: str, status_code: int | None = None, response_data: Dict[str, Any] | None = None)

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.

__init__(message: str, status_code: int | None = None, response_data: Dict[str, Any] | None = None) → None

Initialize the APIError.

Parameters:

• message – The error message

• status_code – HTTP status code of the error response

• response_data – Dictionary containing the API response data

__str__() → str

Return a string representation of the API error.

exception cardinity.exceptions.AuthenticationError(message: str = 'Authentication failed')

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.

__init__(message: str = 'Authentication failed') → None

Initialize the AuthenticationError.

Parameters:

message – The error message

exception cardinity.exceptions.NotFoundError(message: str = 'Resource not found')

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.

__init__(message: str = 'Resource not found') → None

Initialize the NotFoundError.

Parameters:

message – The error message

exception cardinity.exceptions.RateLimitError(message: str = 'Rate limit exceeded')

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.

__init__(message: str = 'Rate limit exceeded') → None

Initialize the RateLimitError.

Parameters:

message – The error message

exception cardinity.exceptions.ServerError(message: str = 'Internal server error')

Bases: APIError

Exception raised when the server encounters an error.

This exception is raised when the API returns a 5xx Server Error response, indicating that there’s an issue on the server side.

__init__(message: str = 'Internal server error') → None

Initialize the ServerError.

Parameters:

message – The error message

Utilities

Cardinity Utilities

This package contains utility functions and helpers.