Documentation Index
Fetch the complete documentation index at: https://docs.monk.io/llms.txt
Use this file to discover all available pages before exploring further.
Stripe Integration
Build complete payment flows, subscription systems, and revenue management with Stripe and Monk.
Why Stripe?
Stripe is the complete payments platform for internet business, offering:
- Global payments - Accept cards, digital wallets, bank transfers in 135+ currencies
- Subscription management - Handle recurring billing, trials, coupons, and churn
- No-code integrations - Pre-built checkout flows and customer portals
- Enterprise security - PCI DSS Level 1 compliance and advanced fraud protection
- Developer experience - Excellent APIs, SDKs, and webhook handling
Perfect for:
- SaaS applications with subscription billing
- E-commerce platforms and marketplaces
- Mobile apps with in-app purchases
- B2B software with complex pricing models
- Platforms handling payments at scale
What Monk Manages
This integration ships the following Stripe entities:
- Credentials (stripe/credentials): Validates API key, derives mode (test/live), exposes
account_id and optional publishable_key.
- Product (stripe/product): Creates or adopts a product by
product_id or name; supports product_description and metadata.
- Price (stripe/price): Resolves by
lookup_key or creates a price with currency, unit_amount, optional recurring_interval, and product_id.
- Webhook endpoint (stripe/webhook-endpoint): Creates an endpoint at
destination_url, subscribes to event_types, stores signing secret in signing_secret_ref (default stripe-webhook-secret).
Step-by-Step Integration Guide
Step 1: Set Up Stripe Account
- Create a Stripe account at stripe.com
- Get your API keys from the dashboard (Publishable key and Secret key)
- Configure webhooks in your Stripe dashboard for payment events
Add your Stripe credentials as Monk secrets:
# Test environment
monk secrets add -g stripe-secret-key-test "sk_test_..."
# Live environment (when ready for production)
monk secrets add -g stripe-secret-key-live "sk_live_..."
# Webhook signing secret (stored by entity on create, or set manually)
monk secrets add -g stripe-webhook-secret "whsec_..."
Step 3: Create Your Stripe Configuration
Create a file named payment-system.yaml:
namespace: my-saas-payments
# Stripe credentials for different environments
stripe-creds-test:
defines: stripe/credentials
secret_ref: stripe-secret-key-test
publishable_key: "pk_test_..." # optional, convenience only
stripe-creds-live:
defines: stripe/credentials
secret_ref: stripe-secret-key-live
publishable_key: "pk_live_..." # optional, convenience only
# SaaS product with multiple pricing tiers
saas-product:
defines: stripe/product
secret_ref: stripe-secret-key-live
name: "My SaaS Platform"
product_description: "Complete business management platform"
images: ["https://myapp.com/product-image.jpg"]
metadata:
category: "productivity"
tier: "enterprise"
# Monthly subscription price
monthly-price:
defines: stripe/price
secret_ref: stripe-secret-key-live
product_id: <- connection-target("saas-product") entity-state get-member("product_id")
lookup_key: "monthly_basic"
currency: usd
unit_amount: 2900 # $29.00
recurring_interval: month
# trial periods can be configured at checkout/session level
# Annual subscription price (with discount)
annual-price:
defines: stripe/price
secret_ref: stripe-secret-key-live
product_id: <- connection-target("saas-product") entity-state get-member("product_id")
lookup_key: "annual_basic"
currency: usd
unit_amount: 29000 # $290.00 (2 months free)
recurring_interval: year
metadata:
discount: "20_percent"
# Webhook endpoint for payment events
payment-webhook:
defines: stripe/webhook-endpoint
secret_ref: stripe-secret-key-live
destination_url: "https://myapp.com/api/stripe/webhook"
event_types:
- "customer.subscription.created"
- "customer.subscription.updated"
- "customer.subscription.deleted"
- "invoice.payment_succeeded"
- "invoice.payment_failed"
- "checkout.session.completed"
signing_secret_ref: stripe-webhook-secret
# Connect to credentials for proper API access
connections:
credentials:
runnable: my-saas-payments/stripe-creds-live
service: data
Step 4: Deploy and Test
Deploy your payment infrastructure:
# Deploy in test mode first
monk update my-saas-payments/stripe-creds-test
monk update my-saas-payments/saas-product
monk update my-saas-payments/monthly-price
monk update my-saas-payments/annual-price
monk update my-saas-payments/payment-webhook
# Verify everything is working
monk describe my-saas-payments/saas-product
monk describe my-saas-payments/monthly-price
# Test webhook endpoint
stripe listen --forward-to localhost:3000/api/stripe/webhook
Advanced Configuration Examples
namespace: enterprise-saas
# Multiple products with different features
starter-product:
defines: stripe/product
secret_ref: stripe-secret-key-live
name: "Starter Plan"
product_description: "Perfect for small teams getting started"
professional-product:
defines: stripe/product
secret_ref: stripe-secret-key-live
name: "Professional Plan"
product_description: "Advanced features for growing businesses"
enterprise-product:
defines: stripe/product
secret_ref: stripe-secret-key-live
name: "Enterprise Plan"
product_description: "Complete solution for large organizations"
# Corresponding prices
starter-monthly:
defines: stripe/price
secret_ref: stripe-secret-key-live
product_id: <- connection-target("starter-product") entity-state get-member("product_id")
lookup_key: "starter_monthly"
currency: usd
unit_amount: 0 # Free tier
recurring_interval: month
pro-monthly:
defines: stripe/price
secret_ref: stripe-secret-key-live
product_id: <- connection-target("professional-product") entity-state get-member("product_id")
lookup_key: "pro_monthly"
currency: usd
unit_amount: 4900 # $49/month
recurring_interval: month
enterprise-monthly:
defines: stripe/price
secret_ref: stripe-secret-key-live
product_id: <- connection-target("enterprise-product") entity-state get-member("product_id")
lookup_key: "enterprise_monthly"
currency: usd
unit_amount: 19900 # $199/month
recurring_interval: month
metadata:
seats_included: 50
custom_features: true
E-commerce Integration
namespace: online-store
# Store products
tshirt-product:
defines: stripe/product
secret_ref: stripe-secret-key-live
name: "Premium Cotton T-Shirt"
product_description: "Comfortable, high-quality cotton t-shirt"
images: ["https://store.com/tshirt-image.jpg"]
hoodie-product:
defines: stripe/product
secret_ref: stripe-secret-key-live
name: "Zip Hoodie"
product_description: "Warm and stylish hoodie for any occasion"
# One-time purchase prices
tshirt-price-small:
defines: stripe/price
secret_ref: stripe-secret-key-live
product_id: <- connection-target("tshirt-product") entity-state get-member("product_id")
lookup_key: "tshirt_small"
currency: usd
unit_amount: 2500 # $25.00
# No recurring fields for one-time purchases
hoodie-price-large:
defines: stripe/price
secret_ref: stripe-secret-key-live
product_id: <- connection-target("hoodie-product") entity-state get-member("product_id")
lookup_key: "hoodie_large"
currency: usd
unit_amount: 6500 # $65.00
Webhook Event Handling
Monk helps you handle Stripe webhook events automatically:
# Advanced webhook configuration with event filtering
advanced-webhook:
defines: stripe/webhook-endpoint
secret_ref: stripe-secret-key-live
destination_url: "https://myapp.com/api/webhooks/stripe"
event_types:
- "payment_intent.succeeded"
- "payment_intent.payment_failed"
- "customer.subscription.trial_will_end"
- "invoice.payment_action_required"
signing_secret_ref: stripe-webhook-secret
# Custom headers for webhook verification
custom_headers:
"X-Stripe-Signature": true
Subscription Management
Handling Subscription Lifecycle
# Customer portal for self-service subscription management
customer-portal:
defines: runnable
script: |
#!/bin/bash
# Create Stripe customer portal session
stripe customer portal create \
--customer $STRIPE_CUSTOMER_ID \
--return-url https://myapp.com/dashboard
Trial and Onboarding
# Automated trial extension for users
trial-extension:
defines: runnable
script: |
#!/bin/bash
# Extend trial period for customers who need more time
stripe subscriptions update $SUBSCRIPTION_ID \
--trial-end $(date -d '+14 days' +%s)
Troubleshooting & Best Practices
Common Issues
Webhook signature verification failing:
# Ensure webhook secret is correctly configured
monk secrets list | grep stripe-webhook
# Verify the webhook endpoint URL is accessible
curl -X POST https://yourapp.com/api/webhooks/stripe \
-H "Content-Type: application/json" \
-d '{"test": "webhook"}'
- Always test with test API keys and toggle to live only when ready
- Use separate namespaces for test and live environments
- Never use live credentials in development
Subscription state synchronization:
# Check subscription status in Stripe dashboard
# Verify customer portal configuration
monk describe my-saas-payments/customer-portal
Best Practices
- Environment Separation: Use separate Stripe accounts or clear test/live toggles
- Webhook Security: Always verify webhook signatures in production
- Error Handling: Implement proper retry logic for failed payments
- Monitoring: Track payment success rates and failed payment reasons
- Compliance: Handle tax calculation and invoice generation properly
Security Considerations
- Store API keys as encrypted secrets, never in code
- Use restricted API keys with minimal required permissions
- Implement webhook signature verification
- Regularly rotate API keys
- Monitor for suspicious payment activity
Real-World Use Cases
Complete subscription billing with trial periods, multiple pricing tiers, and customer self-service portals.
E-commerce Store
Process one-time payments, handle inventory, manage coupons, and integrate with shipping providers.
Marketplace
Handle multi-party payments, platform fees, and automated payouts to sellers.
Mobile App
Implement in-app purchases, subscription renewals, and cross-platform payment processing.
Integration with Other Services
Stripe works seamlessly with:
- Monk Databases: Store customer and subscription data
- Email Services: Send payment confirmations and receipts
- Analytics: Track payment metrics and conversion funnels
- CRM Systems: Sync customer data and payment history
- Tax Services: Calculate and collect appropriate taxes
Support & Resources
