Providers API

Provider Base Class

class fastapi_payments.providers.base.PaymentProvider(config)[source]

Bases: ABC

Base payment provider class.

Methods:

`__init__`(config)	Initialize the payment provider.
`initialize`()	Initialize the provider with configuration.
`create_customer`(email[, name, meta_info, ...])	Create a customer in the provider's system.
`retrieve_customer`(provider_customer_id)	Retrieve customer data from the provider.
`update_customer`(provider_customer_id, data)	Update customer data in the provider's system.
`delete_customer`(provider_customer_id)	Delete a customer from the provider's system.
`create_payment_method`(provider_customer_id, ...)	Create a payment method for a customer.
`create_setup_intent`(provider_customer_id[, ...])	Create a SetupIntent or equivalent object used to initiate client-side confirmation flows for saving payment methods (e.g. Stripe SetupIntent).
`list_payment_methods`(provider_customer_id)	List payment methods for a customer.
`delete_payment_method`(payment_method_id)	Delete a payment method.
`create_product`(name[, description, meta_info])	Create a product in the provider's system.
`create_price`(product_id, amount, currency[, ...])	Create a price for a product.
`create_subscription`(provider_customer_id, ...)	Create a subscription for a customer.
`retrieve_subscription`(provider_subscription_id)	Retrieve subscription details.
`update_subscription`(...)	Update subscription details.
`cancel_subscription`(provider_subscription_id)	Cancel a subscription.
`process_payment`(amount, currency[, ...])	Process a one-time payment.
`refund_payment`(provider_payment_id[, amount])	Refund a payment.
`webhook_handler`(payload[, signature])	Handle webhook events from the provider.
`record_usage`(subscription_item_id, quantity)	Record usage for usage-based billing.

__init__(config)[source]

Initialize the payment provider.

Parameters:: config – Configuration object or dictionary

abstractmethod initialize()[source]: Initialize the provider with configuration.

abstractmethod async create_customer(email, name=None, meta_info=None, address=None)[source]

Create a customer in the provider’s system.

Parameters:

email (str) – Customer email
name (Optional[str]) – Customer name
meta_info (Optional[Dict[str, Any]]) – Additional customer meta_info
address (Optional[Dict[str, Any]]) – optional structured address to store on provider (line1, line2, city, state, postal_code, country)

Return type:

Dict[str, Any]

Returns:

Customer data dictionary

abstractmethod async retrieve_customer(provider_customer_id)[source]

Retrieve customer data from the provider.

Parameters:: provider_customer_id (str) – Customer ID in the provider’s system
Return type:: Dict[str, Any]
Returns:: Customer data dictionary

abstractmethod async update_customer(provider_customer_id, data)[source]

Update customer data in the provider’s system.

Parameters:

provider_customer_id (str) – Customer ID in the provider’s system
data (Dict[str, Any]) – Updated customer data

Return type:

Dict[str, Any]

Returns:

Updated customer data

abstractmethod async delete_customer(provider_customer_id)[source]

Delete a customer from the provider’s system.

Parameters:: provider_customer_id (str) – Customer ID in the provider’s system
Return type:: Dict[str, Any]
Returns:: Deletion confirmation

abstractmethod async create_payment_method(provider_customer_id, payment_details)[source]

Create a payment method for a customer.

Parameters:

provider_customer_id (str) – Customer ID in the provider’s system
payment_details (Dict[str, Any]) – Payment method details

Return type:

Dict[str, Any]

Returns:

Payment method data

async create_setup_intent(provider_customer_id, usage=None, **kwargs)[source]

Create a SetupIntent or equivalent object used to initiate client-side confirmation flows for saving payment methods (e.g. Stripe SetupIntent).

Return a dict with at least ‘id’ and ‘client_secret’ keys when supported.

Return type:

Dict[str, Any]

Parameters:

provider_customer_id (str)
usage (str | None)

abstractmethod async list_payment_methods(provider_customer_id)[source]

List payment methods for a customer.

Parameters:: provider_customer_id (str) – Customer ID in the provider’s system
Return type:: List[Dict[str, Any]]
Returns:: List of payment methods

abstractmethod async delete_payment_method(payment_method_id)[source]

Delete a payment method.

Parameters:: payment_method_id (str) – Payment method ID
Return type:: Dict[str, Any]
Returns:: Deletion confirmation

abstractmethod async create_product(name, description=None, meta_info=None)[source]

Create a product in the provider’s system.

Parameters:

name (str) – Product name
description (Optional[str]) – Product description
meta_info (Optional[Dict[str, Any]]) – Additional product meta_info

Return type:

Dict[str, Any]

Returns:

Product data

abstractmethod async create_price(product_id, amount, currency, interval=None, interval_count=None, meta_info=None)[source]

Create a price for a product.

Parameters:

product_id (str) – Product ID
amount (float) – Price amount
currency (str) – Price currency
interval (Optional[str]) – Billing interval (month, year, etc.)
interval_count (Optional[int]) – Number of intervals
meta_info (Optional[Dict[str, Any]]) – Additional price meta_info

Return type:

Dict[str, Any]

Returns:

Price data

abstractmethod async create_subscription(provider_customer_id, price_id, quantity=1, trial_period_days=None, meta_info=None)[source]

Create a subscription for a customer.

Parameters:

provider_customer_id (str) – Customer ID in the provider’s system
price_id (str) – Price ID
quantity (int) – Subscription quantity
trial_period_days (Optional[int]) – Number of trial days
meta_info (Optional[Dict[str, Any]]) – Additional subscription meta_info

Return type:

Dict[str, Any]

Returns:

Subscription data

abstractmethod async retrieve_subscription(provider_subscription_id)[source]

Retrieve subscription details.

Parameters:: provider_subscription_id (str) – Subscription ID in the provider’s system
Return type:: Dict[str, Any]
Returns:: Subscription data

abstractmethod async update_subscription(provider_subscription_id, data)[source]

Update subscription details.

Parameters:

provider_subscription_id (str) – Subscription ID in the provider’s system
data (Dict[str, Any]) – Updated subscription data

Return type:

Dict[str, Any]

Returns:

Updated subscription data

abstractmethod async cancel_subscription(provider_subscription_id, cancel_at_period_end=True)[source]

Cancel a subscription.

Parameters:

provider_subscription_id (str) – Subscription ID in the provider’s system
cancel_at_period_end (bool) – Whether to cancel at the end of the current period

Return type:

Dict[str, Any]

Returns:

Canceled subscription data

abstractmethod async process_payment(amount, currency, provider_customer_id=None, payment_method_id=None, description=None, meta_info=None, mandate_id=None)[source]

Process a one-time payment.

Parameters:

amount (float) – Payment amount
currency (str) – Payment currency
provider_customer_id (Optional[str]) – Customer ID in the provider’s system
payment_method_id (Optional[str]) – Payment method ID
description (Optional[str]) – Payment description
meta_info (Optional[Dict[str, Any]]) – Additional payment meta_info
mandate_id (str | None)

Return type:

Dict[str, Any]

Returns:

Payment data

abstractmethod async refund_payment(provider_payment_id, amount=None)[source]

Refund a payment.

Parameters:

provider_payment_id (str) – Payment ID in the provider’s system
amount (Optional[float]) – Amount to refund

Return type:

Dict[str, Any]

Returns:

Refund data

abstractmethod async webhook_handler(payload, signature=None)[source]

Handle webhook events from the provider.

Parameters:

payload (Dict[str, Any]) – Webhook payload
signature (Optional[str]) – Webhook signature

Return type:

Dict[str, Any]

Returns:

Processed event data with standardized fields

async record_usage(subscription_item_id, quantity, timestamp=None)[source]

Record usage for usage-based billing.

Parameters:

subscription_item_id (str) – Subscription item ID
quantity (int) – Usage quantity
timestamp (Optional[datetime]) – Usage timestamp

Return type:

Dict[str, Any]

Returns:

Usage record data

Stripe Provider

class fastapi_payments.providers.stripe.StripeProvider(config)[source]

Bases: PaymentProvider

Stripe payment provider backed by the official SDK.

Attributes:

`ZERO_DECIMAL_CURRENCIES`
`EVENT_TYPE_MAP`

Methods:

`initialize`()	Initialize Stripe with configuration.
`create_customer`(email[, name, meta_info, ...])	Create a customer in Stripe.
`retrieve_customer`(provider_customer_id)	Retrieve customer from Stripe.
`update_customer`(provider_customer_id, data)	Update customer data in Stripe.
`delete_customer`(provider_customer_id)	Delete a customer from Stripe.
`create_payment_method`(provider_customer_id, ...)	Create a payment method in Stripe and attach it to the customer.
`create_setup_intent`(provider_customer_id[, ...])	Create a Stripe SetupIntent to be confirmed client-side by the browser.
`list_payment_methods`(provider_customer_id)	List payment methods for a customer in Stripe.
`delete_payment_method`(payment_method_id)	Detach a payment method from Stripe.
`create_product`(name[, description, meta_info])	Create a product in Stripe.
`create_price`(product_id, amount, currency[, ...])	Create a price in Stripe.
`create_subscription`(provider_customer_id, ...)	Create a subscription in Stripe.
`retrieve_subscription`(provider_subscription_id)	Retrieve subscription details from Stripe.
`retrieve_product`(provider_product_id)	Retrieve product from Stripe and return a normalized dict.
`retrieve_price`(provider_price_id)	Retrieve price/price_id from Stripe and return normalized dict.
`retrieve_payment`(provider_payment_id)	Retrieve a payment intent from Stripe and return normalized dict.
`update_subscription`(...)	Update subscription in Stripe.
`cancel_subscription`(provider_subscription_id)	Cancel a subscription in Stripe.
`process_payment`(amount, currency[, ...])	Process a one-time payment with Stripe using PaymentIntents.
`refund_payment`(provider_payment_id[, amount])	Refund a payment in Stripe.
`webhook_handler`(payload[, signature])	Handle webhook events from Stripe.
`record_usage`(subscription_item_id, quantity)	Record usage for metered billing with Stripe.

ZERO_DECIMAL_CURRENCIES = {'BIF', 'CLP', 'DJF', 'GNF', 'JPY', 'KMF', 'KRW', 'MGA', 'PYG', 'RWF', 'UGX', 'VND', 'VUV', 'XAF', 'XOF', 'XPF'}

EVENT_TYPE_MAP = {'charge.refunded': 'payment.refunded', 'customer.subscription.created': 'subscription.created', 'customer.subscription.deleted': 'subscription.canceled', 'customer.subscription.updated': 'subscription.updated', 'invoice.payment_failed': 'invoice.payment_failed', 'invoice.payment_succeeded': 'invoice.payment_succeeded', 'payment_intent.payment_failed': 'payment.failed', 'payment_intent.succeeded': 'payment.succeeded'}

initialize()[source]: Initialize Stripe with configuration.

async create_customer(email, name=None, meta_info=None, address=None)[source]

Create a customer in Stripe.

Return type:

Dict[str, Any]

Parameters:

email (str)
name (str | None)
meta_info (Dict[str, Any] | None)
address (Dict[str, Any] | None)

async retrieve_customer(provider_customer_id)[source]

Retrieve customer from Stripe.

Return type:: Dict[str, Any]
Parameters:: provider_customer_id (str)

async update_customer(provider_customer_id, data)[source]

Update customer data in Stripe.

Return type:

Dict[str, Any]

Parameters:

provider_customer_id (str)
data (Dict[str, Any])

async delete_customer(provider_customer_id)[source]

Delete a customer from Stripe.

Return type:: Dict[str, Any]
Parameters:: provider_customer_id (str)

async create_payment_method(provider_customer_id, payment_details)[source]

Create a payment method in Stripe and attach it to the customer.

Return type:

Dict[str, Any]

Parameters:

provider_customer_id (str)
payment_details (Dict[str, Any])

async create_setup_intent(provider_customer_id, usage=None, **kwargs)[source]

Create a Stripe SetupIntent to be confirmed client-side by the browser. Returns the SetupIntent id and client_secret so the client can call stripe.confirmCardSetup(…) to complete 3DS flows required in certain regions (e.g. India).

Return type:

Dict[str, Any]

Parameters:

provider_customer_id (str)
usage (str | None)

async list_payment_methods(provider_customer_id)[source]

List payment methods for a customer in Stripe.

Return type:: List[Dict[str, Any]]
Parameters:: provider_customer_id (str)

async delete_payment_method(payment_method_id)[source]

Detach a payment method from Stripe.

Return type:: Dict[str, Any]
Parameters:: payment_method_id (str)

async create_product(name, description=None, meta_info=None)[source]

Create a product in Stripe.

Return type:

Dict[str, Any]

Parameters:

name (str)
description (str | None)
meta_info (Dict[str, Any] | None)

async create_price(product_id, amount, currency, interval=None, interval_count=None, meta_info=None)[source]

Create a price in Stripe.

Return type:

Dict[str, Any]

Parameters:

product_id (str)
amount (float)
currency (str)
interval (str | None)
interval_count (int | None)
meta_info (Dict[str, Any] | None)

async create_subscription(provider_customer_id, price_id, quantity=1, trial_period_days=None, meta_info=None)[source]

Create a subscription in Stripe.

Return type:

Dict[str, Any]

Parameters:

provider_customer_id (str)
price_id (str)
quantity (int)
trial_period_days (int | None)
meta_info (Dict[str, Any] | None)

async retrieve_subscription(provider_subscription_id)[source]

Retrieve subscription details from Stripe.

Return type:: Dict[str, Any]
Parameters:: provider_subscription_id (str)

async retrieve_product(provider_product_id)[source]

Retrieve product from Stripe and return a normalized dict.

Return type:: Dict[str, Any]
Parameters:: provider_product_id (str)

async retrieve_price(provider_price_id)[source]

Retrieve price/price_id from Stripe and return normalized dict.

Return type:: Dict[str, Any]
Parameters:: provider_price_id (str)

async retrieve_payment(provider_payment_id)[source]

Retrieve a payment intent from Stripe and return normalized dict.

Return type:: Dict[str, Any]
Parameters:: provider_payment_id (str)

async update_subscription(provider_subscription_id, data)[source]

Update subscription in Stripe.

Return type:

Dict[str, Any]

Parameters:

provider_subscription_id (str)
data (Dict[str, Any])

async cancel_subscription(provider_subscription_id, cancel_at_period_end=True)[source]

Cancel a subscription in Stripe.

Return type:

Dict[str, Any]

Parameters:

provider_subscription_id (str)
cancel_at_period_end (bool)

async process_payment(amount, currency, provider_customer_id=None, payment_method_id=None, description=None, meta_info=None, mandate_id=None)[source]

Process a one-time payment with Stripe using PaymentIntents.

Return type:

Dict[str, Any]

Parameters:

amount (float)
currency (str)
provider_customer_id (str | None)
payment_method_id (str | None)
description (str | None)
meta_info (Dict[str, Any] | None)
mandate_id (str | None)

async refund_payment(provider_payment_id, amount=None)[source]

Refund a payment in Stripe.

Return type:

Dict[str, Any]

Parameters:

provider_payment_id (str)
amount (float | None)

async webhook_handler(payload, signature=None)[source]

Handle webhook events from Stripe.

Return type:

Dict[str, Any]

Parameters:

payload (Dict[str, Any])
signature (str | None)

async record_usage(subscription_item_id, quantity, timestamp=None)[source]

Record usage for metered billing with Stripe.

Return type:

Dict[str, Any]

Parameters:

subscription_item_id (str)
quantity (int)
timestamp (datetime | None)

PayPal Provider

Adyen Provider

Provider Factory

fastapi_payments.providers.get_provider(provider_name, provider_config)[source]

Factory function to get a payment provider instance.

Parameters:

provider_name (str) – Name of the provider (stripe, paypal, etc.)
provider_config (Dict[str, Any]) – Configuration for the provider

Return type:

PaymentProvider

Returns:

A PaymentProvider instance

Raises:

ValueError – If provider is not supported or configuration is invalid