Stripe Payment Hub

Stripe is the payment processing platform available for RERI deal fees, subscription billing, and BetterBets transaction flows. Current status: not yet actively integrated in OpenClaw — the KB doc and hub exist to define the integration pattern before implementation. Auth: API key (Bearer sk_live_...). Webhook signature: Stripe-Signature header — HMAC-SHA256 with timestamp tolerance. Read this hub before wiring any Stripe payment flow, subscription, or webhook handler. Credentials live exclusively in 1password. Payment events table writes to supabase (CCP project).

---

Quick reference

Field	Value
Vendor	Stripe
URL	https://dashboard.stripe.com / https://docs.stripe.com/api
KB doc	API
Auth method	API key — Bearer token (Authorization: Bearer sk_live_...)
Auth credential	op://Aurora/stripe/secret-key (live) · op://Aurora/stripe/secret-key-test (test)
Webhook secret	op://Aurora/stripe/webhook-secret
Publishable key	op://Aurora/stripe/publishable-key (client-side Stripe.js only)
Cred-proxy port	n/a (until B1-B6 ratified per nemoclaw-audit-2026-05-03)
Webhook port	not yet assigned — see G-SERVICE-PRE-START-DOC before binding
Webhook handler	not yet created — must be added to port-registry + ARCHITECTURE.md first
Webhook path	/webhook/stripe (proposed — must be registered in FUNNEL-REGISTRY before go-live)
Webhook dedup table	processed_webhook_events (24h TTL) — dedup key: evt_... event id
Tunnel path	webhook.reri.co/webhook/stripe via cloudflare (not yet registered)
Outbound API base	https://api.stripe.com
API version	2024-06-20 (pin explicitly; auto-upgrade prevention)
Rate limits	100 req/s (live) · 25 req/s (test) · Updates on PI: 1,000/hr
Rate-limit action	429 → check retry-after header → exponential backoff + Discord ops alert
Idempotency	Idempotency-Key: <uuid> header on all POST requests
Cost	2.9% + $0.30 per successful card charge · Subscriptions: +0.5%
Backup/recovery	Stripe-managed; full event history queryable via API (30 days free, longer via Sigma)
Discord alert channel	ops (errors, disputes)
Drift cadence	on-integration (not yet live — no weekly audit needed until first endpoint registered)
Status	staging (not yet integrated)

---

Stripe MCP server (available)

A Stripe MCP server exists in the MCP inventory (mcp-registry — listed among the 21 documented vs 8 active servers). This means Stripe API calls can be made directly from Claude Code sessions without hand-writing curl commands. Before using:

1. Confirm the Stripe MCP server is active: claude mcp list
2. Retrieve key from 1Password: op read "op://Aurora/stripe/secret-key"
3. The MCP server accepts standard Stripe API calls (customers, payment_intents, subscriptions)

---

Components

• workspace/knowledge-base/stripe/API.md — payment intents, customers, subscriptions, products/prices, refunds, invoices, webhooks, pagination, error handling
• workspace/knowledge-base/stripe/examples/ — code samples (Node.js + Python)
• workspace/FUNNEL-REGISTRY.md — Stripe webhook endpoint NOT YET REGISTERED (required before first event)
• Proposed handler path: workspace/webhooks/stripe-handler.js (not yet created)
• Proposed Supabase table: stripe_payment_events in CCP project (svueekfvfrvhylxygktb) — not yet created

---

How it’s used (planned / not yet live)

• Primary use case: Invoice agents, deal fees, BetterBets subscription management, RERI portal payments
• Outbound flow: Create Customer → Create Subscription or Payment Intent → Stripe sends to recipient → Stripe POSTs webhook events
• Inbound webhook: Stripe POSTs signed events to /webhook/stripe; handler verifies Stripe-Signature header
• Agents involved: _summary (financial tracking), _summary (deal payments per KB note)
• Key events to handle: payment_intent.succeeded, invoice.payment_failed, customer.subscription.deleted, charge.dispute.created
• On payment_intent.succeeded: Write to stripe_payment_events in supabase · update HubSpot deal if linked · notify Discord ops
• On invoice.payment_failed: Dunning flow — alert ops; retry logic or manual intervention
• Failure mode: Webhook signature failure if req.body is parsed JSON (not raw Buffer) — must use express.raw({ type: 'application/json' }) middleware
• Success criteria: HTTP 200 within Stripe timeout; event id deduped; stripe_payment_events row written

---

Webhook signature verification

Stripe’s Stripe-Signature header format: t=TIMESTAMP,v1=SIGNATURE

Critical implementation note: req.body MUST be a raw Buffer — not parsed JSON. Parsed JSON will fail signature verification. Use Express middleware:

app.post('/webhook/stripe',
  express.raw({ type: 'application/json' }),
  handleStripeWebhook
);

HMAC construction: HMAC-SHA256(secret, "${timestamp}.${rawBody}") — compare v1= value. Timestamp tolerance: 5 minutes (reject if |now - t| > 300s). Use stripe.webhooks.constructEvent(body, sig, secret) from the official Stripe Node.js SDK.

Dedup by Stripe event id (evt_...) — stable across retries. Stripe retries on non-2xx for up to 72 hours with exponential backoff.

---

Supabase integration (payment events)

All Stripe webhook events should be persisted to supabase CCP project (svueekfvfrvhylxygktb). Proposed schema:

-- Migration: workspace/migrations/YYYY-MM-DD-NNN-stripe-payment-events.sql
CREATE TABLE stripe_payment_events (
  id uuid DEFAULT gen_random_uuid() PRIMARY KEY,
  stripe_event_id text UNIQUE NOT NULL,  -- evt_... for dedup
  event_type text NOT NULL,
  amount_cents integer,
  currency text,
  customer_id text,                       -- Stripe cus_...
  hubspot_deal_id text,                   -- from metadata if set
  payload jsonb NOT NULL,
  processed_at timestamptz DEFAULT now(),
  status text DEFAULT 'received'
);

Cross-reference: supabase — CCP project tables, CHOKEPOINT-1 compliance.

---

Cross-links

Agents that touch this

• _summary — financial tracking; would consume Stripe payment events
• _summary — deal payment tracking when Stripe integrated

Skills that invoke this

• (none yet — Stripe not yet integrated)
• Future: stripe-billing skill (planned) — manage subscriptions and invoices

Plans that govern this

• openclaw-self-improvement-layer-2026-05-03 — Atlas financial intelligence layer may wire Stripe
• openclaw-fragmentation-fix-2026-05-01 — G-SERVICE-PRE-START-DOC, G-NO-PLAINTEXT-CREDS gates apply

Feedback rules

• feedback_no_plaintext_creds — sk_live_... keys must NEVER appear in tracked files; use op://Aurora/stripe/secret-key
• feedback_service_pre_start_doc — webhook port + handler must be in FUNNEL-REGISTRY + ARCHITECTURE.md before first start
• feedback_blocker_surfacing — “Stripe not yet integrated” is a known open state; surface if unblocked
• feedback_verify_schema_before_designing — check CCP Supabase tables before creating payment_events schema
• feedback_dual_write_required — CHOKEPOINT-2: config changes write infra_config_changes row first

KB / source docs

• API — full reference: payment intents, customers, subscriptions, webhooks, idempotency, pagination, error codes

System maps

• external-integrations — Stripe as external payment platform node (planned)
• request-lifecycle — future Stripe webhook enters at inbound webhook layer
• ports-topology — port TBD (not yet registered)
• cost-flow — Stripe is the outbound payment flow for RERI deal economics

---

Related: Document signing + payment cluster

DocuSign and Stripe form the loose “Doc-signing + payment” cluster (Wave 2 taxonomy, WAVE-2-DISPATCH-SPEC). Two members:

• docusign — e-signature for contracts; currently approved-inactive (0 Connect configs live)
• stripe — this file — payment processing; not yet integrated

Deal lifecycle relationship: DocuSign captures the signed contract → Stripe processes the associated payment. HubSpot is the CRM that links both (deal stage = “Docs Signed” → payment trigger).

---

1Password credential structure

Stripe credentials are stored in 1password vault Aurora:

Reference	Content
op://Aurora/stripe/secret-key	Live secret key (sk_live_...) — server-side only
op://Aurora/stripe/secret-key-test	Test secret key (sk_test_...) — development only
op://Aurora/stripe/publishable-key	Live publishable key (pk_live_...) — client-side Stripe.js
op://Aurora/stripe/webhook-secret	Webhook endpoint signing secret (whsec_...)
op://Aurora/stripe/restricted-key	Scoped key for specific operations if created

G-NO-PLAINTEXT-CREDS: Zero plaintext keys in any tracked file. All access via op read CLI or process.env loaded at runtime from master.env (chmod 600). The Stripe KB API.md mentions storing in .credentials — this is superseded by the 1Password pattern.

---

Open issues / TODOs

• P1: Stripe webhook handler not yet created — before creating: register port in port-registry + ARCHITECTURE.md + FUNNEL-REGISTRY (G-SERVICE-PRE-START-DOC)
• P1: Create stripe_payment_events Supabase migration — use workspace/migrations/YYYY-MM-DD-NNN-stripe-payment-events.sql pattern
• P1: Confirm Stripe MCP server status: claude mcp list | grep stripe
• P2: Decide integration scope — which agents consume Stripe events? Atlas? Betteracquisitions? Clarify with Henry before building
• P2: Wire hubspot_deal_id into Stripe Payment Intent metadata so webhooks can update HubSpot deal stage
• P3: BetterBets entity (Estonia OÜ / Binance.com plan) may require separate Stripe account — verify before wiring

Recent activity

• 2026-05-03: Hub created (Wave 2 W2-S6). Status: staging (not yet integrated). MCP server noted as available.