> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatcrafterai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

# Stripe Integration Troubleshooting

Common issues and solutions for ChatCrafterAI Stripe integration.

## Connection Issues

### "Invalid API Key" Error

**Symptoms:** Cannot connect to Stripe, authentication fails

**Solutions:**

* Verify API key format (secret key starts with `sk_`, publishable with `pk_`)
* Copy key directly from Stripe dashboard - avoid manual typing
* Check for extra spaces before or after the key
* Ensure you're not mixing test and production keys
* Confirm you're using the correct Stripe account
* Try regenerating keys in Stripe dashboard

### "Connection Failed"

**Symptoms:** Integration won't connect despite correct keys

**Solutions:**

* Check your internet connection
* Verify Stripe service status at status.stripe.com
* Ensure your ChatCrafterAI account has integration permissions
* Try disconnecting and reconnecting the integration
* Clear browser cache and retry
* Contact ChatCrafterAI support if issue persists

## Payment Issues

### "Payment Failed"

**Symptoms:** Transaction doesn't complete, customer sees error

**Solutions:**

* Verify not using test card in production mode (or vice versa)
* Check customer has valid payment method on file
* Ensure amount is positive and non-zero
* Confirm amount doesn't exceed maximum allowed
* Verify customer has sufficient funds/credit
* Check if card is expired or blocked
* Review Stripe dashboard for specific decline reason

### "Duplicate Charge" Error

**Symptoms:** Customer charged multiple times for same transaction

**Solutions:**

* Implement idempotency keys for all payment requests
* Each payment attempt needs unique idempotency key
* Check agent isn't retrying failed requests excessively
* Review agent logs for duplicate API calls
* If duplicate occurred, issue refund for extra charge

## Customer Issues

### "Customer Not Found"

**Symptoms:** Agent cannot locate customer in Stripe

**Solutions:**

* Verify email address spelling matches exactly
* Try using customer ID instead of email
* Check customer exists in correct Stripe account (test vs production)
* Ensure customer hasn't been deleted from Stripe
* Create customer first if new
* Use case-insensitive email matching

### "Balance Shows Incorrect Amount"

**Symptoms:** Displayed balance doesn't match actual

**Solutions:**

* Stripe may cache balance - wait 5-10 seconds and retry
* Refresh Stripe dashboard to verify actual balance
* Check for pending charges not yet settled
* Verify timezone settings match between systems
* Look for recent refunds or adjustments
* Ensure all transactions have synced (check webhook delivery)

## Webhook Issues

### "Webhook Not Received"

**Symptoms:** Agent doesn't respond to Stripe events, no payment confirmations

**Solutions:**

* Verify webhook secret in ChatCrafterAI matches Stripe
* Check webhook endpoint URL is correct: `https://api.chatcrafterai.com/stripe/webhook`
* Ensure webhook is enabled in Stripe dashboard
* Review Stripe webhook dashboard for delivery failures
* Check required events are subscribed: `payment_intent.succeeded`, `customer.subscription.updated`
* Test webhook manually using Stripe dashboard "Send test webhook" feature
* Verify no firewall blocking incoming webhooks
* Re-create webhook if repeatedly failing

### "Webhook Signature Invalid"

**Symptoms:** Webhooks received but rejected by ChatCrafterAI

**Solutions:**

* Copy webhook signing secret exactly from Stripe (starts with `whsec_`)
* Ensure no extra spaces in webhook secret
* Verify webhook secret in ChatCrafterAI matches current Stripe webhook
* If webhook recently recreated in Stripe, update secret in ChatCrafterAI
* Check webhook secret hasn't expired (rotate if old)

## Refund Issues

### "Refund Not Processing"

**Symptoms:** Refund request fails or hangs

**Solutions:**

* Verify original charge is completed (not pending)
* Check refund amount doesn't exceed original charge amount
* Ensure charge is within refund window (typically 120 days)
* Confirm charge hasn't already been fully refunded
* Some payment methods have processing delays (up to 10 days)
* Review Stripe dashboard for refund status
* Check for Stripe account refund restrictions

## Subscription Issues

### "Cannot Create Subscription"

**Symptoms:** Subscription creation fails

**Solutions:**

* Verify customer has default payment method
* Check price ID exists and is active in Stripe
* Ensure price and product are in same Stripe account
* Confirm customer doesn't already have this subscription
* Verify subscription settings allow new signups
* Check for trial period conflicts

### "Subscription Status Incorrect"

**Symptoms:** Subscription shows wrong status in agent

**Solutions:**

* Wait for webhook sync (can take 30 seconds)
* Check webhook delivery for subscription.updated events
* Manually refresh subscription data in agent
* Verify subscription exists in Stripe dashboard
* Check for recent changes not yet synced

## Debug Steps

When troubleshooting any issue:

1. **Enable debug mode** in Chatlab to see raw API responses
2. **Check Stripe dashboard** - go to Developers → Logs
3. **Review agent logs** in ChatCrafterAI for error details
4. **Copy full error message** including error codes
5. **Check webhook delivery** in Stripe dashboard
6. **Verify mode** - test vs production consistency
7. **Test in isolation** - try action directly in Stripe API
8. **Compare timestamps** - ensure events arrive in correct order

## Getting Help

If you're still stuck:

1. **Check Stripe status** - Visit status.stripe.com for service outages
2. **Review error code** - Search Stripe docs for specific error codes
3. **Gather information:**
   * Full error message
   * Transaction/customer/subscription ID
   * Timestamp when error occurred
   * Steps to reproduce
   * Screenshots if applicable
4. **Contact ChatCrafterAI support** with:
   * Agent logs showing the error
   * Relevant Stripe transaction IDs
   * Description of what you were trying to do
5. **Stripe support** - For Stripe-specific issues (contact through Stripe dashboard)

## Common Error Codes

* **authentication\_required** - 3D Secure needed, agent should redirect customer
* **card\_declined** - Generic decline, ask customer to use different card
* **insufficient\_funds** - Card has insufficient balance
* **invalid\_amount** - Amount is negative, zero, or too large
* **payment\_method\_unavailable** - Payment method not available in region
* **resource\_missing** - Customer/charge/subscription not found, check ID