Complete Stripe Payment Integration Guide: from basic checkout to subscription management

Complete Stripe Payment Integration Guide: from basic checkout to subscription management

Stripe is one of the most popular online payment processing platforms, serving millions of businesses worldwide. Known for clean APIs, comprehensive documentation, and global payment capabilities. This guide walks through complete Stripe integration from scratch.

1. Account Setup

Create Account

Visit Stripe website to register. Stripe supports merchants in most countries and regions worldwide, including Hong Kong and Singapore. You'll need:

• Basic personal or business information
• Bank account details for settlement
• Identity verification documents

Get API Keys

In Stripe Dashboard → Developers → API Keys, you can get two sets of keys:

# Test mode keys (development)
STRIPE_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxx
STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxx

# Live mode keys (production)
STRIPE_PUBLISHABLE_KEY=pk_live_xxxxxxxxxxxx
STRIPE_SECRET_KEY=sk_live_xxxxxxxxxxxx

Important: Never expose Secret Key in client-side code or public repositories.

2. Basic Payment Flow

Frontend (Checkout Mode)

Stripe Checkout is the simplest integration — Stripe hosts the payment page:

<script src="https://js.stripe.com/v3/"></script>
<button id="checkout-button">Pay $20.00</button>

<script>
const stripe = Stripe('pk_test_xxxxxxxxxxxx');

document.getElementById('checkout-button').addEventListener('click', async () => {
  const response = await fetch('/api/create-checkout-session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ product: 'premium-plan', quantity: 1 })
  });
  const session = await response.json();
  const result = await stripe.redirectToCheckout({ sessionId: session.id });
});
</script>

Backend (Node.js)

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

app.post('/api/create-checkout-session', async (req, res) => {
  const session = await stripe.checkout.sessions.create({
    line_items: [{
      price_data: {
        currency: 'usd',
        product_data: { name: 'Premium Plan' },
        unit_amount: 2000,
      },
      quantity: 1,
    }],
    mode: 'payment',
    success_url: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
    cancel_url: 'https://example.com/cancel',
  });
  res.json({ id: session.id });
});

Supported Payment Methods

3. Subscription Management

// Create product
const product = await stripe.products.create({
  name: 'Monthly Pro',
  description: 'All premium features'
});

// Create pricing ($29.99/month)
const price = await stripe.prices.create({
  product: product.id,
  unit_amount: 2999,
  currency: 'usd',
  recurring: { interval: 'month' }
});

// Create subscription
app.post('/api/create-subscription', async (req, res) => {
  const { customerId, priceId } = req.body;
  const subscription = await stripe.subscriptions.create({
    customer: customerId,
    items: [{ price: priceId }],
    payment_behavior: 'default_incomplete',
    expand: ['latest_invoice.payment_intent'],
  });
  res.json({ subscriptionId: subscription.id });
});

4. Webhook Handling

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['stripe-signature'];
  let event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body, sig, process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  switch (event.type) {
    case 'checkout.session.completed':
      // Handle successful payment
      break;
    case 'invoice.payment_succeeded':
      // Subscription renewal
      break;
    case 'customer.subscription.deleted':
      // Subscription cancelled
      break;
  }
  res.json({received: true});
});

5. Cross-border Considerations

1. Currency conversion: 135+ currencies supported
2. Settlement: Standard 7-day cycle (2-day available for fee)
3. Fees: 2.9% + $0.30 (domestic), +1.5% (international cards)
4. Refunds: Fee non-refundable, refund itself is free
5. Fraud prevention: Stripe Radar ML-powered detection

6. Troubleshooting

16IDC Takeaway

Stripe is the top choice for cross-border websites, especially those serving US/European users. For China-focused sites, integrate Alipay and WeChat Pay as well. Stripe's pay-as-you-go model (no monthly fee) is ideal for startups.