Skip to main content
This tutorial was written by Claude Code (an AI) and has not yet been reviewed. Follow along with caution. If the tutorial was helpful or a specific part was not clear/correct, please provide feedback at the bottom of the page. Thank you.
This guide covers integrating Stripe with CoCart Preview API. Requires CoCart v4.6+ and a configured Stripe payment gateway.
Plugin Compatibility: This tutorial covers the WooCommerce Stripe Payment Gateway plugin, not WooCommerce Payments (WCPay/WooPay).
  • WooCommerce Stripe Gateway (payment_method: 'stripe') - Available in 45+ countries, full API access, direct Stripe account ✅
  • WooCommerce Payments / WooPay (payment_method: 'woocommerce_payments') - Available in 39 countries, managed solution with WooPay features
Using WooCommerce Payments? If you want to use WooCommerce Payments, see the WooPay tutorial instead.Why use Stripe Gateway?
  • More countries supported (45+ vs 39)
  • Full control over your Stripe account
  • Direct access to Stripe dashboard and features
  • Better for businesses needing advanced Stripe features
  • Available in countries not supported by WooCommerce Payments (e.g., Brazil, India, Indonesia, Malaysia, Mexico, Thailand)

Overview

Stripe integration with CoCart follows a secure client-side payment flow using Stripe Elements and Payment Intents. This ensures sensitive payment data never touches your server while providing a seamless checkout experience. Geographic Availability: The WooCommerce Stripe Gateway plugin works in all countries where Stripe is available (45+ countries including U.S., Canada, UK, EU, Australia, Japan, Singapore, and many more). View all supported countries.

Prerequisites

Before implementing Stripe checkout, ensure you have:
  1. Stripe account - Create a direct account at stripe.com (must be in a supported country)
  2. WooCommerce Stripe Gateway plugin installed and configured
  3. Stripe JavaScript SDK loaded in your frontend
  4. A valid cart with items added via CoCart API
  5. Customer billing address information

Integration Flow

1

Initialize Stripe Elements

Set up Stripe SDK with your store’s publishable key and create payment form
2

Collect Payment Details

Let customers securely enter their payment information using Stripe Elements
3

Create Payment Method

Generate a payment method using Stripe’s client-side API
4

Complete Checkout

Submit the checkout with payment method reference to CoCart

Step 1: Initialize Stripe Elements

First, set up Stripe with your store’s publishable key and create the payment form:
Important: The publishable key in your JavaScript code must exactly match the one configured in your WooCommerce Stripe settings.

Step 2: Create Payment Method

When the customer submits the form, create a payment method using Stripe:

Step 3: Complete Checkout

Process the checkout with the payment method reference:

Complete Example

Here’s a complete working example that puts it all together:

Step 5: Process Checkout with Payment Data

Submit the checkout with Stripe payment information:

Complete Integration Example

Here’s a complete working example:

Error Handling

Handle common Stripe and checkout errors:

Testing

Use Stripe’s test card numbers for development:
  • Successful payment: 4242424242424242
  • Declined card: 4000000000000002
  • Insufficient funds: 4000000000009995
  • Expired card: 4000000000000069

Troubleshooting

Common Issues

Problem: Stripe.js hasn’t loaded before your code executes.Solution: Ensure Stripe.js loads before initialization:
Problem: Backend doesn’t recognize the payment method.Solution: Verify your configuration:
  • Use 'stripe' as payment_method (not 'woocommerce_payments')
  • Ensure WooCommerce Stripe Gateway plugin is active
  • Check that Stripe is enabled in WooCommerce → Settings → Payments
  • Verify your Stripe account supports your currency
Problem: Stripe Elements don’t appear on the page.Solution: Check these common issues:
  • Verify mount selector matches HTML: cardElement.mount('#card-element')
  • Ensure the container exists in DOM before mounting
  • Check browser console for JavaScript errors
  • Verify no CSS is hiding the element (check display, visibility, height)
  • Try mounting with explicit styling:
Problem: “This API key cannot be used” or authentication errors.Solution:
  • Ensure frontend publishable key matches WooCommerce Stripe settings exactly
  • Check if you’re using test key (pk_test_) in test mode or live key (pk_live_) in live mode
  • Verify the key belongs to the correct Stripe account
  • Go to WooCommerce → Settings → Payments → Stripe to confirm your keys
Problem: Error when creating payment intent via CoCart.Solution: Check your setup:
  • Verify your cart has items and a valid total
  • Ensure Stripe secret key is configured correctly in WooCommerce
  • Check PHP error logs for server-side issues
Problem: Legitimate cards are being declined.Solution: Check multiple factors:
  • Test Mode: Use official Stripe test cards (not real cards)
  • Live Mode: Common causes:
    • Insufficient funds
    • Card issuer blocking the transaction
    • International cards blocked by Stripe Radar rules
    • Incorrect CVV or expiration date
    • Address verification (AVS) failure
Enable detailed decline codes in your error handling:
Problem: 3DS authentication modal doesn’t appear or fails.Solution: Ensure proper 3DS implementation:
  • Ensure popups are not blocked by browser
  • Test with 3DS test cards: 4000002500003155
  • Verify your return_url is configured correctly
Problem: Not receiving payment confirmation webhooks.Solution: Configure webhooks properly:
  1. Go to Stripe Dashboard → Developers → Webhooks
  2. Add endpoint: https://yoursite.com/wc-api/wc_stripe/
  3. Select events: payment_intent.succeeded, payment_intent.payment_failed
  4. Test webhook delivery in Stripe Dashboard
  5. Check webhook signing secret matches WooCommerce settings
  6. Verify your server can receive HTTPS requests from Stripe IPs
Problem: “Invalid currency” or “Invalid amount” errors.Solution: Check amount formatting:
  • Verify your Stripe account supports the currency
  • Check minimum amount requirements per currency
  • Ensure no decimal values for zero-decimal currencies
Problem: Payment succeeds but WooCommerce order is not created.Solution: Debug the checkout flow:
  • Check PHP error logs on server
  • Verify WooCommerce stock levels
  • Check for plugin conflicts
  • Ensure customer data is valid

Debug Mode

Enable Stripe debug logging for detailed troubleshooting:
In WooCommerce:
  1. Go to WooCommerce → Settings → Payments → Stripe
  2. Enable “Log debug messages”
  3. Check logs at WooCommerce → Status → Logs

Getting Help

If issues persist:
  1. Check Stripe Dashboard: View recent payment attempts and error details
  2. Review Logs: Check both browser console and server logs
  3. Test Mode: Always test thoroughly in Stripe test mode first
  4. Stripe Documentation: Visit Stripe’s troubleshooting guide
  5. WooCommerce Support: Check WooCommerce Stripe Gateway plugin documentation

Best Practices

Security

  • Never expose secret keys client-side
  • Use HTTPS for all requests
  • Validate data server-side
  • Handle PCI compliance properly

User Experience

  • Show loading states during processing
  • Provide clear error messages
  • Enable real-time form validation
  • Support mobile-friendly interfaces

Error Handling

  • Handle network failures gracefully
  • Implement retry mechanisms
  • Log errors for debugging
  • Provide fallback options

Performance

  • Load Stripe.js asynchronously
  • Cache payment contexts when possible
  • Minimize API calls
  • Use request timeouts
Always test your Stripe integration thoroughly using Stripe’s test mode before going live. Ensure your webhook endpoints are properly configured to handle payment updates.