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
- 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:- Stripe account - Create a direct account at stripe.com (must be in a supported country)
- WooCommerce Stripe Gateway plugin installed and configured
- Stripe JavaScript SDK loaded in your frontend
- A valid cart with items added via CoCart API
- 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:- JavaScript
- HTML
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
'Stripe is not defined' Error
'Stripe is not defined' Error
Problem: Stripe.js hasn’t loaded before your code executes.Solution: Ensure Stripe.js loads before initialization:
Payment Method Not Accepted
Payment Method Not Accepted
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
Elements Not Displaying
Elements Not Displaying
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:
Publishable Key Mismatch
Publishable Key Mismatch
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
Payment Intent Creation Fails
Payment Intent Creation Fails
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
'Your card was declined' Errors
'Your card was declined' Errors
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
3D Secure Authentication Not Working
3D Secure Authentication Not Working
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
Webhook Events Not Received
Webhook Events Not Received
Problem: Not receiving payment confirmation webhooks.Solution: Configure webhooks properly:
- Go to Stripe Dashboard → Developers → Webhooks
- Add endpoint:
https://yoursite.com/wc-api/wc_stripe/ - Select events:
payment_intent.succeeded,payment_intent.payment_failed - Test webhook delivery in Stripe Dashboard
- Check webhook signing secret matches WooCommerce settings
- Verify your server can receive HTTPS requests from Stripe IPs
Currency or Amount Errors
Currency or Amount Errors
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
Checkout Completes But Order Not Created
Checkout Completes But Order Not Created
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:- Go to WooCommerce → Settings → Payments → Stripe
- Enable “Log debug messages”
- Check logs at WooCommerce → Status → Logs
Getting Help
If issues persist:- Check Stripe Dashboard: View recent payment attempts and error details
- Review Logs: Check both browser console and server logs
- Test Mode: Always test thoroughly in Stripe test mode first
- Stripe Documentation: Visit Stripe’s troubleshooting guide
- 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.