Utilities API

Exception Classes

class fastapi_payments.utils.exceptions.PaymentError(message, code=None)

Bases: Exception

Base class for payment-related exceptions.

Methods:

__init__(message[, code])

Parameters:

• message (str)

• code (str)

__init__(message, code=None)

Parameters:

• message (str)

• code (str)

class fastapi_payments.utils.exceptions.ProviderError(message, code=None, provider=None, provider_error=None)

Bases: PaymentError

Exception raised when a payment provider returns an error.

Methods:

__init__(message[, code, provider, ...])

Parameters:

• message (str)

• code (str)

• provider (str)

• provider_error (str)

__init__(message, code=None, provider=None, provider_error=None)

Parameters:

• message (str)

• code (str)

• provider (str)

• provider_error (str)

class fastapi_payments.utils.exceptions.ConfigurationError(message, code=None)

Bases: PaymentError

Exception raised when there is a configuration error.

Parameters:

• message (str)

• code (str)

class fastapi_payments.utils.exceptions.ValidationError(message, code=None)

Bases: PaymentError

Exception raised when there is a validation error.

Parameters:

• message (str)

• code (str)

class fastapi_payments.utils.exceptions.ResourceNotFoundError(message, code=None)

Bases: PaymentError

Exception raised when a resource is not found.

Parameters:

• message (str)

• code (str)

class fastapi_payments.utils.exceptions.AuthenticationError(message, code=None)

Bases: PaymentError

Exception raised when there is an authentication error with the payment provider.

Parameters:

• message (str)

• code (str)

class fastapi_payments.utils.exceptions.WebhookError(message, code=None)

Bases: PaymentError

Exception raised when there is an error processing a webhook.

Parameters:

• message (str)

• code (str)

class fastapi_payments.utils.exceptions.PaymentRequiresActionError(message, action_url=None, action_type=None)

Bases: PaymentError

Exception raised when a payment requires additional action.

Methods:

__init__(message[, action_url, action_type])

Parameters:

• message (str)

• action_url (str)

• action_type (str)

__init__(message, action_url=None, action_type=None)

Parameters:

• message (str)

• action_url (str)

• action_type (str)

Helper Functions

fastapi_payments.utils.helpers.generate_random_string(length=16)

Generate a random string of specified length.

Parameters:

length (int) – Length of the random string

Return type:

str

Returns:

Random string

fastapi_payments.utils.helpers.generate_idempotency_key()

Generate an idempotency key for API requests.

Return type:

str

Returns:

Idempotency key

fastapi_payments.utils.helpers.format_amount(amount, currency)

Format amount according to currency’s smallest unit.

Parameters:

• amount (Union[int, float]) – Amount in decimal form (e.g., 10.99)

• currency (str) – Currency code (e.g., USD)

Return type:

int

Returns:

Amount in smallest unit (e.g., cents)

fastapi_payments.utils.helpers.parse_amount(amount, currency)

Parse amount from smallest unit to decimal form.

Parameters:

• amount (int) – Amount in smallest unit (e.g., cents)

• currency (str) – Currency code (e.g., USD)

Return type:

float

Returns:

Amount in decimal form (e.g., 10.99)

fastapi_payments.utils.helpers.sanitize_metadata(metadata=None)

Sanitize metadata to ensure it’s valid and safe to store or transmit.

Parameters:

metadata (Optional[Dict[str, Any]]) – Optional dictionary of metadata

Return type:

Dict[str, Any]

Returns:

Sanitized metadata dictionary (empty dict if input was None)

fastapi_payments.utils.helpers.calculate_subscription_period_end(period_start, interval, interval_count=1)

Calculate subscription period end date.

Parameters:

• period_start (datetime) – Period start date

• interval (str) – Billing interval (day, week, month, year)

• interval_count (int) – Number of intervals

Return type:

datetime

Returns:

Period end date