Stripe Payment Integration

Complete guide to integrate Stripe Checkout for processing payments in your store system.

Prerequisites

Before you begin, ensure you have:

• ✅ A Stripe account (Sign up here)
• ✅ Admin access to your dashboard
• ✅ Backend server running
• ✅ SSL certificate (HTTPS required for production)

Overview

The Stripe integration uses Checkout Sessions:

• Products are managed in your database
• Checkout sessions created via Stripe API
• Payments processed by Stripe
• Webhooks notify your system of completed payments

Architecture

[Admin Panel] → [Your Database] → [Stripe Checkout] → [Stripe Webhooks] → [Your Backend]

Step 1: Get Stripe Credentials

pk_test_51xxxxxxxxxxxxxxxxxxxxx

sk_test_51xxxxxxxxxxxxxxxxxxxxx

Step 2: Configure Webhook

Webhooks are essential for payment notifications.

https://yourdomain.com/api/store/webhook/{providerId}

checkout.session.completed              ← PRIMARY EVENT
checkout.session.expired
checkout.session.async_payment_succeeded
checkout.session.async_payment_failed
charge.refunded
charge.dispute.created
charge.dispute.updated
charge.dispute.closed

payment_intent.succeeded       ← Duplicate of checkout.session
payment_intent.payment_failed  ← Duplicate
payment_intent.canceled        ← Duplicate
charge.succeeded              ← Duplicate
charge.failed                 ← Duplicate

Step 3: Configure Provider in Admin Panel

Step 4: Create Products

Unlike Tebex, Stripe products are managed in your admin panel.

{
  "commands": ["give {player} diamond 64"],
  "permissions": ["vip.access"],
  "discord_roles": ["role-id-123"]
}

Step 5: Test the Integration

Card: 4242 4242 4242 4242
Date: 12/25 (any future date)
CVC: 123 (any 3 digits)

Card: 4000 0000 0000 0002
(Card will be declined)

Card: 4000 0027 6000 3184
(Requires authentication)

Production Setup

Webhook Signature Verification

Your backend automatically verifies webhooks using Stripe SDK.

How It Works

// Backend verifies each webhook
const stripe = new Stripe(secretKey);
const event = stripe.webhooks.constructEvent(
  rawBody,
  signature,
  webhookSecret
);

if (!event) {
  return 403; // Invalid signature
}

Security Features

✅ Signature verification using Stripe SDK ✅ Timestamp validation (prevents replay attacks) ✅ HTTPS enforcement in production ✅ Raw body preservation for verification

Troubleshooting

Products Not Showing

Problem: Shop page is empty

Solutions:

1. Check products are Active in admin panel
2. Verify Stripe provider is Active
3. Check backend logs for errors
4. Ensure products have valid prices

Invalid Signature Error

Problem: Webhooks return "Invalid signature"

Solutions:

1. Verify webhook secret in admin panel matches Stripe
2. Check you're using the correct environment (test vs live)
3. Ensure raw body is preserved (don't parse before verification)
4. Verify webhook URL has correct provider ID

Webhook Not Received

Problem: Payment successful but no transaction recorded

Solutions:

1. Check webhook URL is correct
2. Verify webhook events are selected in Stripe
3. Check backend logs: /api/store/webhook/{providerId}
4. Test webhook in Stripe Dashboard → Send test webhook

Session ID Not Found

Problem: Success page shows "Payment processing"

Solutions:

1. Wait a few seconds (webhook might be delayed)
2. Refresh the page
3. Check backend received the webhook
4. Verify transaction was created with session ID

Currency Mismatch

Problem: Prices showing wrong currency

Solutions:

1. Update provider currency setting
2. Edit existing products to use new currency
3. Create new products (they'll use provider currency)

Production Checklist

Before going live:

• Live API keys configured
• Live webhook created and tested
• All products configured with correct prices
• Test purchase with real payment completed
• HTTPS/SSL certificate active
• Webhook signature verification working
• Transaction appears in admin panel
• Success page displays correctly
• Email notifications working (if configured)
• Stripe Dashboard notifications enabled

Supported Payment Methods

Stripe supports 40+ payment methods:

Cards

• ✅ Visa
• ✅ Mastercard
• ✅ American Express
• ✅ Discover

Digital Wallets

• ✅ Apple Pay
• ✅ Google Pay
• ✅ Link

Local Methods (Region-specific)

• 🇪🇺 SEPA Direct Debit
• 🇳🇱 iDEAL
• 🇵🇱 Przelewy24
• 🇹🇷 Turkish Local Cards
• And many more...

Supported Currencies

Stripe supports 135+ currencies including:

Full currency list

API Reference

Checkout Session Creation

// Your backend creates sessions
const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [{
    price_data: {
      currency: 'usd',
      product_data: {
        name: 'VIP Rank',
      },
      unit_amount: 999, // $9.99 in cents
    },
    quantity: 1,
  }],
  success_url: 'https://yourdomain.com/shop/success?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://yourdomain.com/shop',
  metadata: {
    userId: 'user-123',
    basketId: 'basket-456',
  },
});

Webhook Event Structure

{
  "id": "evt_xxxxxx",
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "id": "cs_test_xxxxxx",
      "amount_total": 999,
      "currency": "usd",
      "customer_details": {
        "email": "[email protected]",
        "name": "John Doe"
      },
      "payment_intent": "pi_xxxxxx",
      "payment_status": "paid",
      "metadata": {
        "userId": "user-123",
        "basketId": "basket-456"
      }
    }
  }
}

Environment Variables

Backend .env configuration:

# Required
BETTER_AUTH_URL=https://yourdomain.com
NODE_ENV=production

# Optional (for development)
SKIP_WEBHOOK_IP_CHECK=true  # If using Cloudflare

Best Practices

Product Management

✅ Do:

• Use clear, descriptive product names
• Add detailed descriptions with rich text
• Upload high-quality images (512x512px recommended)
• Set appropriate prices for your market
• Organize products logically
• Use stock limits for limited items

❌ Don't:

• Use confusing abbreviations
• Leave descriptions empty
• Skip product images
• Set incorrect prices
• Mix unrelated products

Security

✅ Do:

• Always verify webhook signatures
• Use HTTPS in production
• Keep secret keys secure
• Rotate keys periodically
• Monitor failed webhooks
• Enable Stripe Radar (fraud detection)

❌ Don't:

• Commit secrets to git
• Use HTTP in production
• Skip signature verification
• Share secret keys
• Ignore webhook failures

Testing

✅ Do:

• Test thoroughly in test mode
• Try different payment methods
• Test failed payments
• Verify webhook delivery
• Check all transaction states
• Test success/cancel flows

❌ Don't:

• Skip test mode
• Test with real money initially
• Ignore webhook tests
• Deploy without testing

Customer Experience

✅ Do:

• Use clear product descriptions
• Show prices in customer's currency
• Provide email receipts
• Display order confirmation
• Handle errors gracefully

❌ Don't:

• Hide pricing
• Use confusing checkout flow
• Skip confirmation pages
• Ignore payment failures

Monitoring & Analytics

Stripe Dashboard

Monitor your store performance:

1. Home: Overview of recent activity
2. Payments: All payment transactions
3. Customers: Customer database
4. Analytics: Revenue reports

Your Admin Panel

Track transactions:

1. Store → Overview: Sales statistics
2. Store → Transactions: Detailed transaction list
3. Store → Packages: Product performance

Key Metrics

Monitor these important metrics:

• 📊 Conversion Rate: Checkout starts vs completions
• 💰 Revenue: Daily/weekly/monthly sales
• 🔄 Refund Rate: Percentage of refunded transactions
• ⚠️ Dispute Rate: Chargebacks and disputes
• ✅ Success Rate: Successful vs failed payments

Advanced Features

Customer Portal (Future)

Allow customers to:

• View purchase history
• Download receipts
• Request refunds
• Manage subscriptions

Recurring Payments (Future)

Enable subscription products:

• Monthly/yearly billing
• Automatic renewals
• Trial periods
• Tiered pricing

Actions Automation (Work in Progress)

When actions feature is complete:

• Automatic command execution
• Role assignments
• Discord integrations
• Email notifications

Migration Guide

From Tebex to Stripe

1. Export Data:

   • Export product list from Tebex
   • Save product images
   • Note product configurations

2. Recreate Products:

   • Create each product in admin panel
   • Upload images
   • Set same prices
   • Configure actions

3. Test:

   • Run parallel for 1 week
   • Compare transaction volumes
   • Verify all features work

4. Switch:

   • Disable Tebex provider
   • Enable Stripe provider
   • Announce to customers

From Other Providers

Similar process:

1. Document current setup
2. Recreate in admin panel
3. Test thoroughly
4. Gradual migration

Support Resources

• 📚 Stripe Documentation
• 💬 Stripe Discord
• 🎫 Support Center
• 📧 Email: [email protected]
• 📞 Phone: Available for verified businesses

FAQ

Why aren't products in Stripe Dashboard?

Our integration manages products in your database, not Stripe. This gives you more flexibility and faster updates.

Can I use both Tebex and Stripe?

Yes! You can have multiple providers active. Customers choose at checkout.

What about taxes?

Stripe Tax is available in select regions. Configure in Stripe Dashboard → Settings → Tax.

Are subscriptions supported?

Coming soon! The actions field will support recurring payments.

How do refunds work?

Refunds are processed through Stripe Dashboard. Webhooks will update your system automatically.

Next Steps

After successful integration:

1. ✅ Configure email notifications
2. ✅ Set up product categories
3. ✅ Create promotional campaigns
4. ✅ Monitor analytics regularly
5. ✅ Optimize product offerings

Need help? Check our Troubleshooting Guide or Contact Support.