Stripe Developer Documentation

Complete development toolkit for Stripe payment integrations

What this skill does

Stripe Developer Resources provides the complete toolkit for building payment processing systems and financial applications. The platform offers server-side SDKs for processing payments, client-side libraries for secure data collection, webhooks for real-time event handling, and comprehensive testing environments. Developers use this to implement everything from simple one-time payments to complex subscription billing, marketplace transactions, and multi-party payment flows.

The ecosystem includes the Stripe CLI for local development, Dashboard tools for monitoring and debugging, Workbench for integration management, and AI-powered tools including LLM integration helpers and Model Context Protocol servers. This enables both traditional integration approaches and modern AI-driven development workflows.

Prerequisites

• Stripe account with API keys (publishable and secret)
• Development environment setup with HTTPS (use ngrok for local development)
• Node.js 14+, Python 3.6+, PHP 7.3+, Ruby 2.5+, or other supported runtime
• Webhook endpoint capability for real-time event handling
• SSL certificate for production environments
• Understanding of payment card industry (PCI) compliance basics

Quick start

# Install Stripe CLI
npm install -g stripe-cli

# Install SDK (Node.js example)
npm install stripe

# Authenticate CLI
stripe login

# Listen for webhooks locally
stripe listen --forward-to localhost:4242/webhook

// Basic payment processing
const stripe = require('stripe')('sk_test_...');

const paymentIntent = await stripe.paymentIntents.create({
  amount: 2000,
  currency: 'usd',
  metadata: {order_id: '6735'},
});

console.log(paymentIntent.client_secret);

Core concepts

Payment Intents represent the lifecycle of a payment from creation to completion. They handle authentication challenges, retries, and status tracking automatically. Use PaymentIntents for one-time payments requiring confirmation.

Setup Intents collect payment method details for future use without charging immediately. Essential for subscription setups, card-on-file scenarios, and two-step payment flows where authorization happens separately from capture.

Webhooks provide real-time notifications when events occur in your Stripe account. Critical for handling asynchronous events like successful payments, failed charges, subscription updates, and dispute notifications. Always verify webhook signatures to prevent fraud.

Test Mode vs Live Mode environments are completely isolated. Test mode uses special card numbers and bank accounts that simulate various scenarios without real money movement. API keys determine which mode you're operating in.

Idempotency prevents duplicate operations by using idempotency keys. Stripe automatically handles retries and network failures when you provide consistent keys for repeated requests.

Key API surface

Common patterns

Accepting a payment with confirmation

const paymentIntent = await stripe.paymentIntents.create({
  amount: 1999,
  currency: 'usd',
  confirm: true,
  payment_method: 'pm_card_visa',
  return_url: 'https://example.com/return',
});

Saving a card for future use

const setupIntent = await stripe.setupIntents.create({
  customer: 'cus_123',
  payment_method_types: ['card'],
});
// Use setupIntent.client_secret on frontend

Creating a subscription

const subscription = await stripe.subscriptions.create({
  customer: 'cus_123',
  items: [{price: 'price_123'}],
  payment_behavior: 'default_incomplete',
  expand: ['latest_invoice.payment_intent'],
});

Webhook endpoint verification

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['stripe-signature'];
  const event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
  
  if (event.type === 'payment_intent.succeeded') {
    const paymentIntent = event.data.object;
    // Fulfill order
  }
  res.json({received: true});
});

Marketplace payment split

const paymentIntent = await stripe.paymentIntents.create({
  amount: 10000,
  currency: 'usd',
  application_fee_amount: 1000,
  transfer_data: {
    destination: 'acct_connected_account',
  },
});

Configuration

• STRIPE_PUBLISHABLE_KEY: Frontend client authentication (starts with pk_)
• STRIPE_SECRET_KEY: Backend server authentication (starts with sk_)
• STRIPE_WEBHOOK_SECRET: Webhook signature verification (starts with whsec_)
• API_VERSION: API version date (default: account default, recommend latest)
• MAX_NETWORK_RETRIES: Automatic retry attempts (default: 0, recommend 2)
• TIMEOUT: Request timeout in milliseconds (default: 80000)
• APP_INFO: Application metadata for request tracking
• TELEMETRY: Usage analytics (default: true)

Best practices

Always use idempotency keys for payment creation to handle network failures gracefully. Generate unique keys per logical operation, not per request attempt.

Validate webhook signatures before processing to prevent malicious requests. Use stripe.webhooks.constructEvent() with your endpoint secret.

Handle 3D Secure authentication by checking PaymentIntent status and providing return_url for redirect-based authentication flows.

Use test mode extensively with Stripe's test card numbers to simulate successful payments, declined cards, authentication challenges, and various error conditions.

Implement proper error handling for network issues, card declines, and rate limits. Stripe errors include specific codes and user-friendly messages.

Store Stripe IDs, not objects in your database. Objects can change; IDs are permanent references you can use to fetch current data.

Use metadata fields to link Stripe objects to your internal systems. Metadata appears in Dashboard and webhook events.

Set up monitoring using Stripe's health alerts and Dashboard request logs to catch integration issues early.

Gotchas and common mistakes

• Webhook endpoints must return 2xx status codes within 30 seconds or Stripe will retry. Always respond quickly, queue heavy processing.
• Test and live API keys are completely separate environments. Data doesn't transfer between modes.
• PaymentIntent amounts are in cents for zero-decimal currencies like USD, but some currencies use different subunits.
• Webhook events can arrive out of order and be delivered multiple times. Design handlers to be idempotent.
• Client-side publishable keys can't create charges directly. Use PaymentIntents flow for security.
• Stripe CLI webhook forwarding generates new endpoint secrets each time. Don't hardcode the secret in production.
• Connected accounts require separate API authentication using the account ID header or by using their keys.
• Subscription billing happens asynchronously. Monitor invoice.payment_failed webhooks for dunning management.
• Refunds aren't instant and may take 5-10 business days to appear on customer statements.
• API versioning affects object structure. Pin to specific versions in production and test upgrades thoroughly.
• Rate limits apply per account and increase with processing volume. Implement exponential backoff for 429 errors.
• PCI compliance requirements vary based on integration type. Card data must never touch non-PCI compliant servers.
• Disputes and chargebacks have strict response deadlines. Set up automated monitoring and response workflows.