# Tutorial: Get Started with FastStripe


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Prerequisites

Before starting this tutorial, you’ll need:

- Python 3.8 or higher installed
- A Stripe account (sign up at [stripe.com](https://stripe.com))
- Your Stripe test API keys from the [Stripe
  Dashboard](https://dashboard.stripe.com/test/apikeys)

## Why FastStripe?

FastStripe offers several advantages over the official Stripe Python
SDK:

- **🔍 Self-documenting**: See all available parameters with
  descriptions in your IDE
- **🎯 Simplified workflows**: High-level methods for common payment
  patterns
- **📦 Lightweight**: Minimal dependencies (just `httpx` and `fastcore`)
- **🏗️ Consistent API**: Uniform `create`/`fetch` naming across all
  resources
- **💫 AttrDict responses**: Access response data with dot notation
  (`customer.email`)
- **🔧 Automatic data handling**: Nested dictionaries flattened for
  Stripe’s API format

## Step 1: Installation

First, install FastStripe using pip:

``` bash
pip install faststripe
```

Or install the latest development version:

``` bash
pip install git+https://github.com/AnswerDotAI/faststripe.git
```

## Versioning

FastStripe versions follow Stripe’s API versioning scheme (e.g.,
`2025.05.28`). Each FastStripe release is pinned to a specific Stripe
API version, ensuring:

- **Stability**: Your code won’t break when Stripe updates their API
- **Predictability**: Same behavior across all environments  
- **Compatibility**: Choose the Stripe API version that works for your
  application

When you install FastStripe, you get a specific snapshot of the Stripe
API that’s been tested and validated.

## Step 2: Set up your API key

For this tutorial, you’ll use your Stripe test API key. Create a `.env`
file in your project directory:

``` bash
echo "STRIPE_SECRET_KEY=sk_test_your_test_key_here" > .env
```

Then load it in your Python environment:

## Step 3: Initialize FastStripe

Now let’s import FastStripe and initialize it with your API key:

``` python
from faststripe.core import StripeApi

import os

# Initialize with your API key from environment
sapi = StripeApi(os.environ['STRIPE_SECRET_KEY'])
```

``` python
# Create a customer
customer = sapi.customers.create(email='user@example.com', name='John Doe')
print(customer.id, customer.email)
```

    cus_SMsM453Vb64XcF user@example.com

### Self-Documenting API

One of FastStripe’s key advantages is that all methods include parameter
documentation directly in your IDE. You can see what parameters are
available without checking external docs:

``` python
# Explore available methods and their parameters
sapi.customers.create?
```

    Signature:
    sapi.customers.create(
        *,
        address=None,
        balance=None,
        cash_balance=None,
        description=None,
        email=None,
        expand=None,
        invoice_prefix=None,
        invoice_settings=None,
        metadata=None,
        name=None,
        next_invoice_sequence=None,
        payment_method=None,
        phone=None,
        preferred_locales=None,
        shipping=None,
        source=None,
        tax=None,
        tax_exempt=None,
        tax_id_data=None,
        test_clock=None,
    )
    Docstring:
    Create a customer

    Parameters:
        address: The customer's address.
        balance: An integer amount in cents (or local equivalent) that represents the customer's current balance, which affect the customer's future invoices. A negative amount represents a credit that decreases the amount due on an invoice; a positive amount increases the amount due on an invoice.
        cash_balance: Balance information and default balance settings for this customer.
        description: An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.
        email: Customer's email address. It's displayed alongside the customer in your dashboard and can be useful for searching and tracking. This may be up to *512 characters*.
        expand: Specifies which fields in the response should be expanded.
        invoice_prefix: The prefix for the customer used to generate unique invoice numbers. Must be 3–12 uppercase letters or numbers.
        invoice_settings: Default invoice settings for this customer.
        metadata: Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
        name: The customer's full name or business name.
        next_invoice_sequence: The sequence to be used on the customer's next invoice. Defaults to 1.
        payment_method: 
        phone: The customer's phone number.
        preferred_locales: Customer's preferred languages, ordered by preference.
        shipping: The customer's shipping information. Appears on invoices emailed to this customer.
        source: 
        tax: Tax details about the customer.
        tax_exempt: The customer's tax exemption. One of `none`, `exempt`, or `reverse`.
        tax_id_data: The customer's tax IDs.
        test_clock: ID of the test clock to attach to the customer.
    File:      ~/aai-ws/faststripe/faststripe/core.py
    Type:      function

### High-Level Convenience Methods

FastStripe includes simplified methods for common payment workflows:

``` python
# Create a one-time payment checkout session
checkout = sapi.one_time_payment(
    product_name='My Product',
    amount_cents=2000,  # $20.00
    success_url='https://localhost:8000/success',
    cancel_url='https://localhost:8000/cancel'
)
print(f"Payment URL: {checkout.url[:64]}...")
```

    Payment URL: https://billing.answer.ai/c/pay/cs_test_a17Swg1TqARRl0ItVDkdelkR...

``` python
# Create a subscription checkout session
subscription = sapi.subscription(
    product_name='Monthly Plan',
    amount_cents=999,  # $9.99/month
    success_url='https://localhost:8000/success',
    cancel_url='https://localhost:8000/cancel',
    customer_email=customer.email
)
print(f"Subscription URL: {subscription.url[:64]}...")
```

    Subscription URL: https://billing.answer.ai/c/pay/cs_test_a1xQzvl0Qd6arXt9EKWsYDJ7...

### Complete API Coverage

FastStripe provides access to the entire Stripe API through organized
resource groups:

``` python
# Access any Stripe resource with consistent patterns
product = sapi.products.create(name='New Product')
print(f"Created product: {product.name} with ID: {product.id}")
```

    Created product: New Product with ID: prod_SMsMg2mD205PNM

``` python
# Fetch existing resources
customers = sapi.customers.fetch(limit=3)
print(f"Found {len(customers.data)} customers")
```

    Found 3 customers

``` python
# All responses are AttrDict objects for easy dot notation access
payment_intent = sapi.payment_intents.create(amount=1000, currency='usd')
print(f"Payment intent status: {payment_intent.status}, amount: ${payment_intent.amount/100}")
```

    Payment intent status: requires_payment_method, amount: $10.0
