Support

Troubleshooting

Common issues and how to resolve them. If you're stuck after trying these steps, reach out to support@recurcite.com.

Webhooks not arriving

RecurCite receives dispute events via Stripe webhooks. If disputes aren't appearing in your dashboard, check the following:

Verify Stripe connection

Go to Dashboard → Settings → Stripe and confirm your Stripe account shows as connected. If disconnected, re-authorize via OAuth.

Check webhook endpoint

In your Stripe Dashboard, go to Developers → Webhooks and verify there's an endpoint pointing to your RecurCite instance. The endpoint should be receiving:

• charge.dispute.created
• charge.dispute.updated
• charge.dispute.closed

Test with Stripe CLI

Use the Stripe CLI to forward webhooks to your local environment:

stripe listen --forward-to localhost:3000/api/webhooks/stripe

# Trigger a test dispute
stripe trigger charge.dispute.created

Webhook signature mismatch

If you see 400 Webhook signature verification failed in your logs, your webhook signing secret doesn't match. Common causes:

• Using a test-mode secret in production (or vice versa)
• Using the Stripe CLI secret instead of the dashboard webhook secret
• Secret not updated after rotating in Stripe Dashboard

Events not linking to disputes

Evidence events must include stripe_refs to be matched to disputes. If events aren't appearing on a dispute:

Check stripe_customer_id

The primary matching key is stripe_refs.stripe_customer_id. Verify that:

• The customer ID in your events matches the customer on the disputed charge
• You're using the correct format: cus_xxxx (not a database ID)
• Events were sent before the dispute was created (post-dispute events have less weight)

Verify events were received

Check your evidence timeline in the dashboard. If events don't appear at all:

• Check your API key is valid — a 401 response means invalid key
• Check for 400 validation errors — the SDK may be sending malformed payloads
• Verify the event was sent to the correct organization (each API key is org-scoped)

Submission failed

Evidence submission can fail for several reasons. Check the error in Dashboard → Disputes → Submission History.

Dispute already closed

Stripe only accepts evidence while a dispute is open. If the dispute was already resolved (won, lost, or accepted), submission will fail with a Stripe API error. This is not recoverable — the dispute window has passed.

Stripe token expired

If your Stripe access token has been revoked or expired, submissions will fail with a 401 from Stripe. Reconnect your Stripe account in Dashboard → Settings → Stripe.

PDF upload failed

Before submitting evidence, RecurCite uploads the PDF Packet to Stripe's Files API. If this fails:

• Check if the PDF was generated successfully (view it in the Bundle details)
• Stripe has a 16MB file size limit — very large Packets may exceed this
• Retry the submission — transient Stripe API errors are common

Idempotency conflict

A 409 response means evidence was already submitted for this dispute with the same idempotency key. This is safe — it means your previous submission went through.

PDF cache issues

Generated PDFs are cached in S3-compatible storage. The response includes an X-Cache header:

• X-Cache: HIT — PDF served from cache
• X-Cache: MISS — PDF freshly generated

Stale PDF

If new evidence events aren't reflected in the PDF, you need to regenerate the Bundle. Click Regenerate Bundle on the dispute page — this creates a new Bundle with updated evidence and invalidates the cached PDF.

PDF download not working

PDF downloads use pre-signed S3 URLs that expire after 5 minutes. If a download link has expired, refresh the dispute page to get a new URL.

Common error codes

Still stuck?

If these steps don't resolve your issue:

• Check your Dashboard → Audit Log for detailed error context
• Review the Dashboard → Jobs page for failed background jobs
• Email support@recurcite.com with your organization ID and a description of the issue