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

Step 2: Configure Monk Secrets

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

Multi-Product SaaS Platform

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"}'

Test mode vs Live mode confusion:

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

SaaS Platform

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

Stripe Documentation: Complete API Reference
Webhook Guide: Testing Webhooks
Recipes & Examples: Stripe Samples
Community Support: Stripe Developer Forum

​Stripe Integration

​Why Stripe?

​What Monk Manages

​Step-by-Step Integration Guide

​Step 1: Set Up Stripe Account

​Step 2: Configure Monk Secrets

​Step 3: Create Your Stripe Configuration

​Step 4: Deploy and Test

​Advanced Configuration Examples

​Multi-Product SaaS Platform

​E-commerce Integration

​Webhook Event Handling

​Subscription Management

​Handling Subscription Lifecycle

​Trial and Onboarding

​Troubleshooting & Best Practices

​Common Issues

​Best Practices

​Security Considerations

​Real-World Use Cases

​SaaS Platform

​E-commerce Store

​Marketplace

​Mobile App

​Integration with Other Services

​Support & Resources