Stripe Integration Install Walkthrough

This guide takes you from a fresh Stripe account to your first synced charge with proper journal entries. Most SaaS founders finish in under five minutes.

Prerequisites

You need three things: a Stripe account where you have at least read-only access to the Dashboard, a computer or small server where ERPClaw will run, and basic terminal access on that machine.

If you have not installed ERPClaw yet, see the ERPClaw install guide first.

1. Get a Stripe restricted key (recommended)

We strongly recommend a restricted API key rather than a secret key. ERPClaw needs read access to the following resources:

• Charges, refunds, disputes (read)
• Payouts (read)
• Customers (read)
• Subscriptions, invoices (read)
• Connect: Application fees, transfers (read; only if using Connect)

In the Stripe Dashboard, go to Developers > API Keys > Create restricted key. Name it erpclaw-readonly. Set the permission matrix to read-only on the resources above. Save and copy the rk_live_xxxxxxxxxxxxxxxx token.

For testing, use a rk_test_xxxxx key from your test mode.

2. Add the Stripe account to ERPClaw

Store the key in ERPClaw’s encrypted credential store first, so it never sits in your shell history:

erpclaw set-credential --integration stripe --from-stdin --user-confirmed

Paste the key, press Enter, then Ctrl-D. Then add the account:

erpclaw stripe-add-account \
  --company-id 1 \
  --account-name "Acme SaaS" \
  --mode live

ERPClaw creates the account record with the key encrypted, and creates its Stripe GL accounts: Stripe Clearing, Stripe Processing Fees, Stripe Payout, Stripe Dispute Losses, and Stripe Unearned Revenue. Confirm the key works:

erpclaw stripe-test-connection --stripe-account-id <id-from-step-2>

3. Run the first sync

erpclaw stripe-start-full-sync --stripe-account-id <id-from-step-2>

ERPClaw pulls customers, charges, refunds, disputes, payouts, balance transactions, invoices, subscriptions, transfers, and credit notes, in that order. A small SaaS finishes in seconds. A larger account with hundreds of thousands of transactions can take a few minutes.

4. Post and verify GL entries

The sync fills ERPClaw’s Stripe tables. Post the journal entries for everything not yet posted:

erpclaw stripe-bulk-post-gl --stripe-account-id <id>

Then check them:

erpclaw stripe-list-charges --stripe-account-id <id> --limit 5
erpclaw stripe-list-payouts --stripe-account-id <id>
erpclaw stripe-verify-gl-balance --stripe-account-id <id>

The clearing balance should be very close to your in-flight Stripe balance (charges that have not yet been paid out). If it matches within rounding, your books are correct.

5. Keep it current

Run the sync (and the posting) on a schedule you choose, such as a cron job, or ask your agent to “sync Stripe and post anything new.”

If you already receive Stripe webhooks with a receiver you host, you can hand each event to stripe-process-webhook: ERPClaw records it, skips duplicates by event ID, and re-syncs the object it concerns. ERPClaw does not verify the webhook signature itself, so verify it in your receiver first.

6. Set up ASC 606 revenue recognition (SaaS only)

If you sell subscriptions, you almost certainly need ASC 606 treatment. Create a recognition schedule for each subscription:

erpclaw stripe-create-rev-rec-schedule --stripe-account-id <id> \
  --company-id 1 --subscription-stripe-id sub_xxxxx

ERPClaw will:

• Post that subscription’s payments to Deferred Revenue instead of Revenue
• Recognize a portion of revenue each month when you run stripe-recognize-subscription-revenue for the period
• Reprice the months not yet recognized when you record an upgrade, downgrade, or cancellation with stripe-handle-subscription-change

See ASC 606 reference for the details.

7. Set up Connect (platforms only)

If you run a marketplace on Stripe Connect, add the account with --is-connect-platform 1 and set the account that receives your application fees:

erpclaw stripe-configure-gl-mapping --stripe-account-id <id> \
  --platform-revenue-account-id <account-id>

Application fees then post to that account, and transfers to connected accounts are synced and reported by month. See Connect platform fees for the accounting treatment of each Connect pattern.

Where your data lives

Your charges, customers, payouts, and general ledger live in a SQLite database at ~/.openclaw/erpclaw/data.sqlite on your own machine. Back it up like any other file. AvanSaber never sees this data.

Next steps

• Architecture overview, what runs where
• Troubleshooting, common issues
• ASC 606 deep dive, revenue recognition
• MRR reports, SaaS metrics

Source code: github.com/avansaber/erpclaw-addons