Swarmauri Billing Stripe

swarmauri_billing_stripe provides a Stripe-backed billing provider for the Swarmauri SDK. It connects Swarmauri billing interfaces to the official Stripe Python SDK for products, prices, Checkout Sessions, Payment Intents, captures, cancellations, refunds, subscriptions, invoices, Stripe Connect destination charges, disputes, and webhook signature verification.

Why Swarmauri Billing Stripe?

Use swarmauri_billing_stripe when a Swarmauri application needs production Stripe billing workflows while keeping application code behind provider-neutral billing interfaces. The provider maps Stripe Billing, Checkout, Payment Intents, Refunds, Invoicing, Subscriptions, Connect, and Disputes into Swarmauri refs and specs.

FAQ

Q: Does this package call live Stripe APIs?

A: Yes. The provider configures the official stripe Python SDK with api_key and calls Stripe resources such as Product, Price, checkout.Session, PaymentIntent, Refund, Subscription, Invoice, and Dispute.

Q: Which Stripe workflows are supported?

A: It supports product and price creation, hosted checkout, payment intent creation, manual capture, payment intent cancellation, refund create/retrieve, subscription create/cancel, invoice create/finalize/void/mark-uncollectible, Connect destination charges with application fees, webhook signature validation, and dispute listing.

Q: What credential is required?

A: Pass a Stripe secret key as api_key, such as a test key beginning with sk_test_. Production keys should be provided through secure deployment secrets.

Features

• Stripe-backed provider class registered as StripeBillingProvider.
• Product and price creation with metadata support.
• Hosted Checkout Session creation for one-time payments.
• Payment Intent creation with automatic or manual capture.
• Payment capture and cancellation through Stripe Payment Intents.
• Refund creation and lookup through Stripe Refunds.
• Subscription creation and cancellation with Stripe prices.
• Invoice item creation plus invoice lifecycle operations.
• Stripe Connect destination-charge support with application fees.
• Webhook signature verification through stripe.Webhook.construct_event.
• Dispute listing for operational review workflows.
• Python 3.10, 3.11, 3.12, 3.13, and 3.14 support.

Installation

Install with uv:

uv add swarmauri_billing_stripe

Install with pip:

pip install swarmauri_billing_stripe

Usage

Create a product, price, and Stripe Checkout Session:

from swarmauri_billing_stripe import StripeBillingProvider
from swarmauri_base.billing import CheckoutRequest, PriceSpec, ProductSpec

provider = StripeBillingProvider(api_key="sk_test_123")

product = provider.create_product(
    ProductSpec(name="Starter", description="Starter subscription"),
    idempotency_key="stripe-prod-001",
)
price = provider.create_price(
    product,
    PriceSpec(currency="USD", unit_amount_minor=1000, nickname="Starter monthly"),
    idempotency_key="stripe-price-001",
)
checkout = provider.create_checkout(
    price,
    CheckoutRequest(
        quantity=1,
        success_url="https://example.com/success",
        cancel_url="https://example.com/cancel",
        customer_email="buyer@example.com",
        idempotency_key="stripe-checkout-001",
    ),
)

print(product.id, price.id, checkout.url)

Create and capture a manual Payment Intent:

from swarmauri_billing_stripe import StripeBillingProvider
from swarmauri_base.billing import PaymentIntentRequest

provider = StripeBillingProvider(api_key="sk_test_123")

payment = provider.create_payment_intent(
    PaymentIntentRequest(
        amount_minor=2500,
        currency="USD",
        payment_method_id="pm_card_visa",
        confirm=True,
        capture=False,
        idempotency_key="stripe-payment-001",
    )
)
captured = provider.capture_payment(payment.id, idempotency_key="stripe-capture-001")

print(payment.status, captured.status)

Verify a Stripe webhook signature:

from swarmauri_billing_stripe import StripeBillingProvider

provider = StripeBillingProvider(api_key="sk_test_123")

valid = provider.verify_webhook_signature(
    raw_body=b'{"id":"evt_test","object":"event"}',
    headers={"Stripe-Signature": "t=...,v1=..."},
    secret="whsec_...",
)

print(valid)

Important Scope Notes

This package uses live Stripe SDK calls. Runtime behavior depends on Stripe account settings, API version, enabled payment methods, test or live mode, Checkout configuration, Connect account setup, and webhook endpoint secrets.

Entry Point

The package exposes a Swarmauri billing provider entry point:

[project.entry-points.'swarmauri.billing_providers']
StripeBillingProvider = "swarmauri_billing_stripe.provider:StripeBillingProvider"

Related Packages

Billing provider packages:

• swarmauri_billing_adyen
• swarmauri_billing_authorize_net
• swarmauri_billing_braintree
• swarmauri_billing_mock
• swarmauri_billing_paypal
• swarmauri_billing_paystack
• swarmauri_billing_razorpay
• swarmauri_billing_square

Foundational packages:

• swarmauri_core defines billing capabilities and interfaces.
• swarmauri_base provides billing specs, refs, mixins, and BillingProviderBase.
• swarmauri provides namespace imports and plugin discovery.

Documentation

• Stripe provider source
• Swarmauri SDK repository
• Stripe API documentation

License

Apache-2.0

Contributing

When expanding Stripe coverage, keep each Swarmauri billing method aligned with the official Stripe Python SDK, document required Stripe account configuration, and add tests for each changed runtime path.