Skip to main content

Stripe Integration Overview

Open Admin → Stripe (https://admin.finmatch.io/stripe/). The H1 is Stripe. The subtitle is Manage Stripe billing and customer relationships.

Do not paste Stripe secret keys into these docs.

Click the toolbar​

Toolbar, left to right:

  1. Search placeholder Search by Customer ID, Name, or Email.... Filters the table locally as you type (or Enter). It does not hit Stripe again. Matching also includes Subscription ID. The placeholder text is unchanged.
  2. Last billing snapshot is the label. The line under it (#snapshotInfo) shows live listing info after a live load, a snapshot timestamp after an archive load, or No snapshot available when empty.
  3. Create Snapshot is optional archive only. The table does not load billed customers from that file. Do not click it to see Access Training or any other customer. Do not keep pressing it.

Opening Stripe loads paginated GET /api/customers (every live customer, not the newest 100). While the tab stays open it refreshes about every 60 seconds. Stripe webhooks upsert one customer so a billing change can appear on the next poll. Do not wait on a docs cache.

The button label stays Create Snapshot (no busy label on the button). If you archive anyway, a toast shows Creating snapshot..., then on success Snapshot created successfully! When the response includes created_at, that toast adds a parenthetical weekday plus the timestamp. The table then reloads from live GET /api/customers, not from the archive file.

Failure toast is the API message / error, or Failed to create snapshot. Please try again. Non-JSON 404: Snapshot endpoint not found. The Stripe API service may need to be deployed with the latest code. Unparseable success body: Invalid response from server.

Read the table​

Idle table: Loading Stripe customers.... Empty table after fetch: No Stripe customers found.

ColumnWhat you get
Customer IDStripe customer identifier
NameCustomer name or description
EmailCustomer email address
Subscription PlanActive subscription plan name
StatusActive, Past Due, Canceled, or None
Next BillingNext billing date
CreatedCustomer creation date
FinMatch MerchantLinked names are clickable and open that merchant page. Unlinked rows show Not linked. Clicking elsewhere on the row does not open a customer detail view.
ActionsA ⋯ button. It is wired to a connection manager that is not loaded on this page, so the control does nothing today.

Link or unlink from the merchant Stripe Billing card or the merchants table Stripe Customer column (Link Customer). James-only Settings preview (not general operator chrome): FinMatch Account → Stripe first row is Link / Unlink and opens the same picker. The Stripe tab ⋯ and Not linked do not open a merchant picker. See Managing Merchants.

Status colours: Active green (#10b981), Past Due red (#ef4444), Canceled gray (#6b7280), None light gray (#9ca3af). Missing plan/date cells show N/A.

Data Flow​

Admin Dashboard (admin/stripe/index.html)
    ↓
    Calls: Stripe API Service
    ↓
Stripe API Service (Cloud Run)
    ↓
    Uses: Secret Manager (stripe-restricted-key)
    ↓
Stripe API (External)
    ↓
    Returns: Customer data with subscriptions
    ↓
Admin Dashboard displays customer table

Technical Details​

The Stripe table loads paginated GET /api/customers (every live customer, not the newest 100). While the tab is open it polls about every 60 seconds. Stripe webhooks upsert one row so a billing change can show on the next poll. Create Snapshot writes an optional GCS archive; it is not the display path.

The API returns customers with expanded subscription data. The dashboard extracts the active subscription (or the first subscription if none is active), the plan name from subscription items, and next billing from current_period_end.

Troubleshooting​

If the table shows Loading Stripe customers... or No Stripe customers found:

  1. Check stripe-api: gcloud run services describe finmatch-stripe-api --region europe-west2 then hit that service’s /health.
  2. Browser developer tools (F12) — Console and Network for GET /api/customers.
  3. Same Cloud Run host, GET /api/customers.
  4. Ensure admin/js/merchants.js is deployed to GCS. Do not keep pressing Create Snapshot to force a load.

If customers show but subscription details are N/A, the customer may not have an active subscription. Check the console for transformation errors and confirm the API returned expanded subscription data.