Stripe

Integration

StripeService → StripeAdapter → Stripe API v1

Service Layer

StripeService

Business logic
Cursor pagination
Response mapping
Idempotency keys

14 methods

→

Adapter Layer

StripeAdapter

API key injection
Bearer auth header
Idempotency-Key header
Request serialization

starting_after / ending_before

→

External API

Stripe REST API

API version 1
api.stripe.com/v1/
Cursor-based pagination
Idempotent operations

Authorization: Bearer sk_...

API Key Authentication

Secret key in Authorization header
Authorization: Bearer sk_...
No OAuth flow required
Key scoped to Stripe account

Idempotency

POST requests accept Idempotency-Key
Safe to retry failed requests
Key stored 24 hours by Stripe
Auto-generated UUIDs recommended

What & Why

Stripe is the dominant payment and billing infrastructure platform. The Octopus Stripe integration provides direct access to financial and billing data — customers, subscriptions, invoices, payment intents, and products — through a single consistent adapter.

The StripeAdapter authenticates via API key passed as a Bearer token, handles Stripe's cursor-based pagination (starting_after / ending_before), and injects Idempotency-Key headers on mutating requests so retries are safe. Test mode and live mode are controlled entirely by key prefix: sk_test_ routes to Stripe's sandbox environment (no real charges), while sk_live_ routes to production.

Key agent use cases: lookup customer billing status before sending upgrade prompts, check whether a subscription is active or past-due before granting feature access, pull invoice history for financial reporting, and create payment intents as part of automated billing workflows.

Environment Switching

Test Mode vs Live Mode via API Key Prefix

sk_test_...

Test Environment

✓ No real charges made
✓ Safe for development & CI
✓ Test card numbers accepted
✓ Full API parity with production
✓ Separate dashboard at dashboard.stripe.com/test

STRIPE_API_KEY=sk_test_51abc...
# Always use in development

⇄

sk_live_...

Production Environment

⚠ Real charges to real cards
⚠ Irreversible financial operations
✓ Production webhook events
✓ Live customer data
✓ Real-time payment processing

STRIPE_API_KEY=sk_live_51abc...
# Production only — guard carefully

Switching environments requires only a key swap

StripeAdapter(api_key="sk_test_...") → Stripe test sandbox
StripeAdapter(api_key="sk_live_...") → Stripe production
# All method signatures identical across modes

Methods Reference

All 14 methods grouped by category. Key params listed for each.

Customers

Method	Description	Key Params
list_customers	List customers with optional filters	limit, email, starting_after
get_customer	Get full details for a single customer	customer_id
create_customer	Create a new Stripe customer	email, name, phone, metadata
update_customer	Update fields on an existing customer	customer_id, email, name, metadata

Subscriptions

Method	Description	Key Params
list_subscriptions	List subscriptions with optional filters	customer_id, status, limit, starting_after
get_subscription	Get full subscription details	subscription_id
cancel_subscription	Cancel an active subscription	subscription_id, cancel_at_period_end

Invoices

Method	Description	Key Params
list_invoices	List invoices with optional filters	customer_id, status, limit, starting_after
get_invoice	Get full invoice details	invoice_id

Payments

Method	Description	Key Params
list_payment_intents	List payment intents	customer_id, limit, starting_after
get_payment_intent	Get payment intent details	payment_intent_id
create_payment_intent	Create a new payment intent	amount, currency, customer_id, metadata

Products

Method	Description	Key Params
list_products	List products in the Stripe catalog	limit, active, starting_after
get_product	Get full product details	product_id

CLI Examples

Use test keys in development

Always configure STRIPE_API_KEY=sk_test_... in development and CI environments. A sk_live_ key will make real charges to real payment methods. Never commit live keys to source control.

# Always use test keys in development
constellation stripe list-customers --limit 10

# Look up a specific customer by ID
constellation stripe get-customer --customer-id cus_abc123

# Check subscription state for a customer
constellation stripe list-subscriptions --customer-id cus_abc123 --status active

# Get full subscription details
constellation stripe get-subscription --subscription-id sub_123

# Cancel a subscription at end of current billing period
constellation stripe cancel-subscription --subscription-id sub_123 --cancel-at-period-end

# Retrieve invoice history for a customer
constellation stripe list-invoices --customer-id cus_abc --status paid

# Get a specific invoice
constellation stripe get-invoice --invoice-id in_xyz789

# List all payment intents for a customer
constellation stripe list-payment-intents --customer-id cus_abc123

# Create a payment intent (amounts in smallest currency unit, e.g. cents)
constellation stripe create-payment-intent --amount 4999 --currency usd --customer-id cus_abc123

# Browse the product catalog
constellation stripe list-products --active true --limit 20

HTTP API

# List customers via HTTP
curl -X POST https://api.yourdomain.com/stripe/list-customers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"limit": 10}'

# Response
# {
#   "customers": [
#     {"id": "cus_abc123", "email": "customer@example.com", "name": "John Doe", "created": 1746000000}
#   ],
#   "has_more": false
# }

# Get subscription via HTTP
curl -X POST https://api.yourdomain.com/stripe/get-subscription \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"subscription_id": "sub_123"}'

# Create payment intent via HTTP
curl -X POST https://api.yourdomain.com/stripe/create-payment-intent \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"amount": 4999, "currency": "usd", "customer_id": "cus_abc123"}'

# Response
# {
#   "id": "pi_xyz789",
#   "amount": 4999,
#   "currency": "usd",
#   "status": "requires_payment_method",
#   "client_secret": "pi_xyz789_secret_..."
# }

Auth Setup

1. Log in to the Stripe Dashboard
2. Navigate to Developers → API keys
3. Copy the Secret key — use sk_test_... for development, sk_live_... for production
4. Set the key in your Octopus connection config:
   • api_key: the full secret key including prefix
5. The StripeAdapter injects Authorization: Bearer <api_key> on every request
6. To switch environments, replace the key value — no other configuration changes required