Skip to main content
Docs/Stripe
More Stripe documentation

Stripe Integration Architecture in ERPClaw

Technical architecture of the ERPClaw Stripe connector. Direct API access from your machine. No middleware. Optional webhook event processing.

This page explains what runs where, what data is held where, and why the design eliminates the typical “middleware syncs Stripe to QuickBooks” pattern.

Two components

The Stripe integration is simpler than the Shopify one. There are only two moving parts:

  1. Your ERPClaw. Holds the API key (encrypted), talks to the Stripe API directly through the official stripe Python library, and writes journal entries to its local database (SQLite or PostgreSQL).
  2. Stripe API at api.stripe.com. Source of truth for charges, refunds, payouts, customers, subscriptions.
  Your ERPClaw  <===Stripe API===>  Stripe
  (SQLite or PostgreSQL on your machine)

Optional: webhook events. ERPClaw does not run a web server of its own. If you already receive Stripe webhooks (for example with a small receiver you host), pass each event to stripe-process-webhook. ERPClaw records it, skips any event ID it has already processed, and re-syncs the affected object type from the API. No third-party middleware, no message queues.

If you do not want to expose anything to the internet, skip webhooks and run syncs on a schedule you choose (cron or similar).

What ERPClaw stores

Dedicated tables:

Table Records
stripe_account One per Stripe account you connect, with its GL mapping
stripe_charge Every charge, success or failure
stripe_refund Every refund, partial or full
stripe_dispute Every dispute, including won/lost outcomes
stripe_payout Every payout to your bank
stripe_balance_transaction The Stripe ledger view, including per-transaction fees
stripe_fee_detail Fee breakdown per balance transaction
stripe_customer_map Stripe customers and the ERPClaw customer each maps to
stripe_subscription Every subscription, with status, plan amount, and interval
stripe_invoice Subscription and one-off invoices
stripe_credit_note Credit notes issued in Stripe
stripe_application_fee Connect application fees
stripe_transfer Connect transfers to connected accounts
stripe_deep_webhook_event Webhook events received, for deduplication and audit
stripe_sync_job Sync run history with timing
stripe_gl_rule Configurable routing rules per event type
stripe_reconciliation_run Per-payout reconciliation runs

Plus GL accounts auto-created when you add the Stripe account:

  • Stripe Clearing, funds Stripe holds before payout
  • Stripe Processing Fees, Stripe processing fees
  • Stripe Payout, where payouts land
  • Stripe Dispute Losses, disputed charges you lose
  • Stripe Unearned Revenue, the ASC 606 deferred revenue liability

Connect platforms also set a platform revenue account for application fees, with stripe-configure-gl-mapping.

Sync modes

Full sync: stripe-start-full-sync pulls customers, charges, refunds, disputes, payouts, balance transactions, invoices, subscriptions, transfers, and credit notes, in that order, into the tables above.

Single object type: stripe-start-sync --object-type charge (or any other type) pulls just that one.

Webhook: stripe-process-webhook takes a Stripe event and re-syncs the object type it concerns.

Syncing fills the mirror tables. Journal entries post when you run the posting actions (stripe-post-charge-gl, stripe-post-refund-gl, stripe-post-payout-gl, and the others) or stripe-bulk-post-gl, or simply ask your agent to post the new Stripe activity.

You can combine the modes. Event IDs are deduplicated, and each sync upserts by Stripe ID, so overlapping runs do not double-count.

Webhook signatures

stripe-process-webhook works on the event body you pass it; it does not check the Stripe-Signature header itself. Verify the signature in your receiver before handing the event over (Stripe’s own libraries do this in one call). You can keep the webhook signing secret encrypted on the Stripe account record with --webhook-secret.

API rate limits

Stripe rate-limits API calls per account. ERPClaw lists objects through the Stripe library’s pagination, 100 objects per page, and does not add a retry layer of its own. If a sync fails partway (a rate limit or a network error), the sync job is marked failed with the error, and you run it again.

Connect platforms

If you run a marketplace on Stripe Connect, ERPClaw records the three standard patterns:

  • Direct charges with application_fee_amount
  • Destination charges with transfer_data.destination
  • Separate charges and transfers for full control

Application fees post to your platform revenue account; transfers are synced and reported by month. See Connect platform fees.

ASC 606 revenue recognition

If you sell subscriptions, create a recognition schedule for each one and ERPClaw posts its charges to Deferred Revenue (a liability) instead of immediate revenue, then recognizes revenue each month you run recognition. See ASC 606 reference.

Source

See Stripe features