Teller

A generalized Crystal billing library inspired by Laravel Cashier, supporting Stripe and Paddle payment providers with a fluent interface.

Teller provides a clean, expressive API for managing subscriptions, one-time payments, customers, and billing operations without framework dependencies. It's designed to work seamlessly with any Crystal application.

Table of Contents

• Background
• Install
• Usage
• Documentation
• API
• Providers
• Development
• Contributing
• License

Background

Teller was created to bring the developer-friendly experience of Laravel Cashier to the Crystal ecosystem, while remaining framework-agnostic. It provides:

• Framework-agnostic: Works with any Crystal web framework or standalone application
• Multiple providers: First-class support for Stripe and Paddle
• Fluent interface: Intuitive, chainable API for all operations
• Type safety: Leverages Crystal's type system for compile-time safety
• Comprehensive webhook handling: Built-in support for processing payment provider webhooks

Install

Add this to your application's shard.yml:

dependencies:
  teller:
    github: ButterbaseApp/teller

Then run:

shards install

Usage

Basic Configuration

require "teller"

# Configure Teller
Teller.configure do |config|
  config.provider = Teller::Provider::Stripe
  config.api_key = ENV["STRIPE_API_KEY"]
  config.webhook_secret = ENV["STRIPE_WEBHOOK_SECRET"]
  config.sandbox = true
end

Customer Management

# Create a new customer
customer = Teller.customer("user@example.com", name: "John Doe").create

# Retrieve an existing customer
customer = Teller.retrieve_customer("cus_12345")

# List customers
customers = Teller.list_customers(limit: 10, offset: 0)

Subscriptions

# Create a subscription
subscription = Teller.subscribe_customer(
  customer.id,
  "price_premium_monthly",
  trial_period_days: 14
)

# Check subscription status
puts "Active: #{subscription.active?}"
puts "Days left in trial: #{subscription.days_left_in_trial}"

# Cancel a subscription
subscription.cancel(at_period_end: true)

One-time Payments

# Create a charge
charge = Teller.charge_customer(
  customer.id,
  2000,  # $20.00 in cents
  "usd",
  "Test payment"
)

Webhook Handling

# Set up webhook handlers
result = Teller.handle_webhook(request_body, signature) do |webhook|
  webhook.customer do |events|
    events.created { |event| handle_new_customer(event) }
  end

  webhook.payment do |events|
    events.succeeded { |event| handle_successful_payment(event) }
  end
end

Documentation

Comprehensive documentation is available in the docs/ directory:

• Getting Started Guide - Complete setup guide with configuration and first steps
• API Reference - Comprehensive reference documentation
• Guides - Step-by-step tutorials for common use cases:
  • Customer Management
  • Subscriptions
  • Webhooks
• Examples - Practical implementation examples:
  • SaaS Billing - Complete SaaS billing system

API

Configuration Options

Environment Variables

# Required
export TELLER_PROVIDER=stripe
export TELLER_API_KEY=sk_test_your_stripe_key

# Optional
export TELLER_WEBHOOK_SECRET=whsec_your_webhook_secret
export TELLER_SANDBOX=true
export TELLER_DEFAULT_CURRENCY=usd

Providers

Stripe

Full API coverage including:

• Customer management
• Charges and payments
• Subscriptions and trials
• Invoices and billing
• Coupons and discounts
• Webhooks
• Payment methods
• Disputes
• Connect support

Paddle

Core feature support:

• Customer management
• Transactions and payments
• Subscriptions
• Webhook support
• Invoice and discount support

Development

# Install dependencies
shards install

# Run tests
crystal spec

# Run linting
ameba

# Run example
crystal run examples/basic_usage.cr

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For questions or discussions, please open an issue on GitHub.

1. Fork the repository
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.