finsilabs/stripe-integration

Stripe Integration

Overview

Stripe is the most widely supported payment processor across ecommerce platforms. On Shopify, it powers Shopify Payments natively. On WooCommerce and BigCommerce, official plugins provide full Stripe Checkout with minimal configuration. Custom code is only required for headless storefronts — and even then, Stripe's hosted Checkout page and Elements components remove most of the complexity.

When to Use This Skill

• When adding Stripe as a payment processor to an existing store
• When setting up Stripe on a new WooCommerce or BigCommerce store
• When implementing SCA-compliant checkout for European customers
• When setting up webhook handlers for order fulfillment automation
• When building a custom or headless storefront that needs Stripe payment processing

Core Instructions

Step 1: Create and configure your Stripe account

1. Sign up at stripe.com — business verification takes 1–3 business days
2. Complete Stripe Dashboard → Activate account to start accepting live payments
3. Configure your Statement descriptor (how you appear on customers' bank statements) under Settings → Public details
4. Set up Stripe Tax under Dashboard → Tax if you want Stripe to handle tax calculation automatically

Step 2: Install Stripe on your platform

---

Shopify

Shopify Payments is powered by Stripe. It is the simplest possible Stripe integration:

1. Go to Settings → Payments → Shopify Payments → Complete account setup
2. Verify your business details and banking information
3. Shopify Payments automatically handles: card processing, Apple Pay, Google Pay, Shop Pay, and (with configuration) Klarna and Afterpay
4. No additional plugins or API keys are needed — Shopify Payments handles everything

If you need to use Stripe directly (e.g., for features Shopify Payments does not support):

1. Install the Stripe payment provider under Settings → Payments → Add payment methods → Stripe
2. Note: third-party payment providers on Shopify incur an additional transaction fee (0.5%–2%); Shopify Payments does not

Configure Stripe webhooks for Shopify: Shopify handles webhook processing internally for Shopify Payments. If using Stripe directly, register your webhook endpoint under Stripe Dashboard → Developers → Webhooks.

WooCommerce

1. Install the WooCommerce Stripe Payment Gateway plugin (free, from WordPress.org — by WooCommerce)
2. Go to WooCommerce → Settings → Payments → Stripe and click Enable
3. Enter your Publishable key and Secret key from Stripe Dashboard → Developers → API Keys
4. Enable Payment Request Buttons (Apple Pay, Google Pay) — these appear automatically on product pages and checkout

Enable additional payment methods:

• Go to WooCommerce → Settings → Payments → Stripe and enable:
  • Express Checkout (Apple Pay, Google Pay, Link)
  • SEPA Direct Debit (for European customers)
  • iDEAL (Netherlands), Bancontact (Belgium), Sofort (Germany/Austria)
  • Klarna and Afterpay (if eligible)

Set up webhooks:

1. In the Stripe plugin settings, click Configure webhooks
2. The plugin automatically registers the required webhook endpoint with Stripe
3. Verify the webhook is active in Stripe Dashboard → Developers → Webhooks

Enable Stripe Radar (fraud prevention): Stripe Radar is enabled by default. Configure rules under Stripe Dashboard → Radar → Rules to block or review high-risk transactions.

BigCommerce

1. Go to Settings → Payment Methods → Online Payment Methods
2. Find Stripe and click Set Up
3. Enter your Stripe API keys (Publishable and Secret) from the Stripe Dashboard
4. Enable the payment methods you want to offer under the Stripe configuration panel
5. BigCommerce automatically registers the required Stripe webhooks

Enable Stripe Link (saved cards): In the BigCommerce Stripe settings, enable Stripe Link to allow returning customers to pay with one click using their saved payment details.

---

Custom / Headless

Install the Stripe SDK:

npm install stripe @stripe/stripe-js @stripe/react-stripe-js

Option A: Stripe Checkout (hosted page — simplest)

For the fastest integration with no payment form to build:

// Server: create a Checkout Session
const session = await stripe.checkout.sessions.create({
  line_items: [{
    price_data: {
      currency: 'usd',
      product_data: { name: 'Order #' + orderNumber },
      unit_amount: Math.round(orderTotal * 100), // cents
    },
    quantity: 1,
  }],
  mode: 'payment',
  success_url: `${YOUR_DOMAIN}/orders/{CHECKOUT_SESSION_ID}/confirmation`,
  cancel_url: `${YOUR_DOMAIN}/cart`,
  metadata: { order_id: orderId },
});

// Redirect customer to session.url
res.redirect(session.url);

Option B: Payment Intents with Stripe Elements (custom checkout form)

// Server: create a Payment Intent
const paymentIntent = await stripe.paymentIntents.create({
  amount: Math.round(orderTotal * 100), // cents
  currency: 'usd',
  automatic_payment_methods: { enabled: true }, // Enables all eligible methods
  metadata: { order_id: orderId, customer_email: customerEmail },
});
res.json({ clientSecret: paymentIntent.client_secret });

// Client: render the payment form using Stripe Elements
import { Elements, PaymentElement, useStripe, useElements } from '@stripe/react-stripe-js';
import { loadStripe } from '@stripe/stripe-js';

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY);

function CheckoutForm({ onSuccess }) {
  const stripe = useStripe();
  const elements = useElements();

  async function handleSubmit(e) {
    e.preventDefault();
    const { error } = await stripe.confirmPayment({
      elements,
      confirmParams: { return_url: `${window.location.origin}/orders/confirmation` },
    });
    if (error) showError(error.message);
    // On success, Stripe redirects to return_url automatically
  }

  return (
    <form onSubmit={handleSubmit}>
      <PaymentElement />
      <button type="submit" disabled={!stripe}>Pay Now</button>
    </form>
  );
}

export function PaymentPage({ clientSecret }) {
  return (
    <Elements stripe={stripePromise} options={{ clientSecret }}>
      <CheckoutForm />
    </Elements>
  );
}

Handle webhooks for order fulfillment:

// POST /api/webhooks/stripe
// IMPORTANT: use raw body parser — do not parse as JSON
export async function handleStripeWebhook(req, res) {
  const sig = req.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(
      req.rawBody,   // raw buffer — not JSON.parse'd
      sig,
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  switch (event.type) {
    case 'payment_intent.succeeded':
      await fulfillOrder(event.data.object);
      break;
    case 'payment_intent.payment_failed':
      await handlePaymentFailed(event.data.object);
      break;
    case 'charge.refunded':
      await handleRefund(event.data.object);
      break;
    case 'charge.dispute.created':
      await handleDispute(event.data.object);
      break;
  }

  res.json({ received: true });
}

// Always check if already fulfilled — webhooks can arrive multiple times
async function fulfillOrder(paymentIntent) {
  const orderId = paymentIntent.metadata.order_id;
  const order = await db.orders.findUnique({ where: { id: orderId } });
  if (order.status !== 'pending') return; // Idempotency check

  await db.orders.update({ where: { id: orderId }, data: { status: 'confirmed', paidAt: new Date() } });
  await sendOrderConfirmationEmail(orderId);
}

Local webhook testing:

# Install Stripe CLI and forward events to your local server
stripe listen --forward-to localhost:3000/api/webhooks/stripe
# Copy the webhook signing secret printed by the CLI into your .env

Step 3: PCI compliance and SCA

PCI DSS scope: Using Stripe Elements or Stripe Checkout significantly reduces your PCI DSS compliance burden:

• SAQ A (22 requirements): applicable when using Stripe Checkout (hosted page) — card data never touches your servers or your page
• SAQ A-EP (191 requirements): applicable when your checkout page is served from your own domain and Stripe.js tokenizes cards in the browser

The WooCommerce Stripe plugin and BigCommerce's Stripe integration both use Stripe.js for tokenization, qualifying most merchants for SAQ A-EP.

SCA (Strong Customer Authentication) for European customers: Using automatic_payment_methods: { enabled: true } on Payment Intents automatically handles 3D Secure challenges when required by the customer's bank. No additional configuration needed.

Best Practices

• Always use Payment Intents — the legacy Charges API does not support SCA and is not recommended for new integrations
• Never log or store raw card numbers — use Stripe Elements or Checkout to stay out of PCI scope
• Use webhook events for fulfillment — do not rely on the client-side redirect alone; customers can close the browser window
• Make all webhook handlers idempotent — Stripe may deliver the same event multiple times; always check the current order status before processing
• Attach order_id to every Payment Intent metadata — this enables reconciliation and dispute management
• Use Stripe Tax if selling to multiple jurisdictions — configure under Stripe Dashboard → Tax rather than building tax calculation yourself

Common Pitfalls

| Problem | Solution | |---------|----------| | Webhook signature verification fails | Pass the raw request body (not JSON-parsed) to constructEvent; configure your framework to skip JSON parsing for the webhook route | | 3DS challenges not triggering | Use automatic_payment_methods: { enabled: true } instead of manually listing payment method types | | WooCommerce Stripe plugin shows blank payment form | Check for JavaScript console errors; often caused by a CSP (Content Security Policy) blocking Stripe.js; add js.stripe.com to your CSP allowlist | | Stripe payment shows as succeeded but order not confirmed | Webhooks are the authoritative signal — if the webhook handler has an error, the order will not be confirmed; check your webhook logs in Stripe Dashboard → Developers → Webhooks → [Event] | | Test mode charges appearing in live data | Verify you are using live API keys in production; Stripe's Dashboard has a separate live/test toggle — confirm you are in the correct mode | | Currency amount wrong | Stripe uses the smallest currency unit — $20.00 = 2000 cents; JPY ¥3,000 = 3000 (no multiplication needed) |

Related Skills

• @checkout-flow-optimization
• @subscription-billing
• @paypal-integration
• @order-processing-pipeline
• @buy-now-pay-later