Stripe Integration Troubleshooting

Pick the symptom that matches.

”Stripe API authentication failed”

Either the API key is wrong, the key was rotated in the Stripe Dashboard, or you are using a pk_ key (publishable, client-side) instead of rk_ (restricted, server-side) or sk_ (secret).

Verify by listing your accounts:

erpclaw stripe-list-accounts

If your account shows but sync fails, rotate the key in Stripe Dashboard and update ERPClaw:

erpclaw stripe-update-account --account-id <id> --api-key rk_live_NEW_KEY

Sync stalls or returns 429

Stripe rate-limits at 100 read requests per second in live mode. If ERPClaw is mid-sync of a very large account and you also have other processes hammering Stripe, you will see 429s. ERPClaw retries with exponential backoff, so eventually completes. To speed up, pause other processes.

If sync is permanently stuck, check the sync job:

erpclaw stripe-list-sync-jobs --status running
erpclaw stripe-get-sync-job --sync-job-id <id>

Cancel and retry:

erpclaw stripe-cancel-sync-job --sync-job-id <id>
erpclaw stripe-start-full-sync --account-id <id>

Webhook returns 400 Bad Request

Stripe sends webhooks signed with HMAC. If your ERPClaw rejects them, either the webhook secret is wrong (key rotated, accidentally pasted the wrong one) or the request is being modified in transit (unusual proxy, MITM testing).

Re-register the webhook to issue a fresh secret:

erpclaw stripe-register-webhook --account-id <id>

This deletes the old endpoint in Stripe and creates a new one with a new signing secret stored locally.

Webhook returns 200 but events are missing

Check the deduplication table:

erpclaw stripe-list-webhook-events --account-id <id> --status processed --limit 20

If events are processed but no journal entries appear, check the GL routing rules for that event type:

erpclaw stripe-list-gl-rules --account-id <id> --transaction-type charge

If no rule exists for the event type, ERPClaw logs the event but does not post to GL. Either add a rule or use the default rules (re-add account triggers default-rule install).

Payout reconciliation does not balance

Run the three-layer reconciliation report:

erpclaw stripe-run-reconciliation --account-id <id> --period-start 2026-04-01 --period-end 2026-04-30

The report shows Layer 1 (transactions to journal entries), Layer 2 (payouts to bank deposits), and Layer 3 (clearing account net).

Common causes of imbalance:

• A bank deposit was manually entered with a different amount than the actual Stripe payout
• A transaction was posted manually before sync caught it (causing a duplicate)
• A test-mode transaction got posted in live mode (or vice versa)
• A refund was posted but the original charge sync was missed

The reconciliation report shows which specific transactions are unmatched. Fix those manually with stripe-match-bank-transaction or by deleting the duplicate journal entry and resyncing.

Clearing balance does not match Stripe Dashboard

Stripe’s “Available balance” minus “Pending balance” should equal your Stripe Clearing GL account. If it doesn’t:

• Run erpclaw stripe-clearing-balance --account-id <id> and note the value
• Check the Stripe Dashboard’s Balance overview
• Difference is usually pending payouts not yet recorded in your bank

Force a fresh payout sync:

erpclaw stripe-sync-payouts --account-id <id>

ASC 606 deferred revenue does not balance

If you have ASC 606 enabled and the Deferred Revenue account does not match the sum of unrecognized subscription periods, run the reconciliation:

erpclaw stripe-asc606-reconcile --account-id <id> --period-end 2026-04-30

Common causes:

• Mid-cycle subscription change not handled
• Refund of a partially-recognized subscription
• Multi-currency subscriptions (we support USD only in v1)
• Custom billing cycles outside the standard month/year patterns

The reconcile command shows which subscriptions are causing the imbalance.

MRR report shows wrong number

ERPClaw computes MRR from your subscription data, not from your revenue. If MRR looks wrong:

• Check that paused subscriptions are excluded
• Check that trial subscriptions are excluded (until first charge)
• Check that proration is computed at the active rate, not the initial rate
• Check that annual subscriptions are normalized to /12

Run the detailed MRR breakdown:

erpclaw stripe-mrr-breakdown --account-id <id> --as-of 2026-04-30

This shows the math line-by-line.

Where to get help

• Email [email protected] with your account-id and the error
• GitHub issues: github.com/avansaber/erpclaw-addons/issues
• Source code is public; the action implementations show exactly what runs