Documentation

Getting Started with PaymentsDB

PaymentsDB syncs your Stripe data to a dedicated PostgreSQL database in real-time. Query with SQL, connect BI tools, and build dashboards — all without managing infrastructure.

1Quick Start

Install from Stripe Marketplace

Go to the Stripe App Marketplace and install PaymentsDB. Authorize via OAuth — we never see your secret keys.

Subscribe & Provision

After installing, subscribe ($30/month) and we'll provision a dedicated PostgreSQL database for your account. This takes 3-5 minutes, then historical data backfills automatically.

Start Querying

Once provisioned, use the built-in SQL editor, or connect with psql, Metabase, Tableau, or any PostgreSQL-compatible tool.

2Querying Your Data

All Stripe data lives in the stripe schema. Tables are named after Stripe objects.

Example: Get total revenue by customer

SELECT c.email, SUM(i.amount_paid) AS total

FROM stripe.customers c

JOIN stripe.invoices i ON c.id = i.customer

WHERE i.status = 'paid'

GROUP BY c.email

ORDER BY total DESC;

Example: MRR calculation

SELECT SUM(

CASE WHEN p.interval = 'year' THEN si.quantity * p.unit_amount / 12

ELSE si.quantity * p.unit_amount

END

) / 100.0 AS mrr

FROM stripe.subscriptions s

JOIN stripe.subscription_items si ON s.id = si.subscription

JOIN stripe.prices p ON si.price = p.id

WHERE s.status = 'active';

3Synced Stripe Objects

We sync 18 Stripe object types to your database. Data is synced in real-time via webhooks, with historical backfill on first setup.

stripe.customersCustomer records with email, metadata, and billing details

stripe.subscriptionsActive and canceled subscriptions with plan details

stripe.subscription_itemsIndividual line items within subscriptions

stripe.invoicesAll invoices including draft, open, paid, and void

stripe.chargesPayment charges with status, amounts, and metadata

stripe.productsProduct catalog with names and descriptions

stripe.pricesPricing information for products

stripe.plansLegacy subscription plans (use prices for new integrations)

stripe.payment_intentsPayment intent objects for tracking payment lifecycle

stripe.payment_methodsStored payment methods like cards and bank accounts

stripe.setup_intentsSetup intents for saving payment methods

stripe.disputesChargebacks and disputes with evidence

stripe.refundsRefund records with amounts and reasons

stripe.credit_notesCredit notes issued against invoices

stripe.checkout_sessionsStripe Checkout session data

stripe.balance_transactionsBalance transaction history

stripe.early_fraud_warningsRadar early fraud warnings

stripe.reviewsRadar reviews for suspicious payments

4Connecting External Tools

Your database credentials are available in the PaymentsDB dashboard. Use them with any PostgreSQL-compatible tool.

Connect with psql

$ psql "postgresql://user:password@host:5432/dbname"

MetabasePostgreSQL connector

TableauPostgreSQL connector

LookerPostgreSQL connector

ModePostgreSQL connector

RedashPostgreSQL connector

SupersetPostgreSQL connector

5Security

No API key access

We use Stripe OAuth for authorization — you never share your Stripe secret API keys with us. We request read access to sync your data, plus write access to webhook endpoints (required to receive real-time updates).

Encrypted credentials

OAuth tokens and database passwords are encrypted at rest using AES-256-GCM before being stored.

Isolated databases

Each customer gets a dedicated PostgreSQL database — not a shared instance. Your data is completely isolated from other users.

Managed by Supabase

Databases are provisioned and managed through Supabase for Platforms. Supabase handles infrastructure, backups, and has their own security certifications.

?FAQ

How do I install PaymentsDB?

Visit the Stripe App Marketplace and search for "PaymentsDB", or click the "Install from Stripe" button on our homepage. You'll authorize the app via OAuth, and we'll provision your database automatically.

How long does setup take?

Database provisioning takes 3-5 minutes. After that, historical data backfills in the background. Small accounts finish in 10-30 minutes; larger accounts with thousands of customers and payments can take a few hours. You can start querying as soon as data begins syncing.

How do I connect to my database?

After setup, you'll get a PostgreSQL connection string. Use it with psql, any SQL client, or BI tools like Metabase or Tableau. Your credentials are shown in the dashboard.

Is my data secure?

Yes. We never have access to your Stripe API keys — we use Stripe OAuth, so you authorize access without sharing secrets. We request read access plus write access to webhook endpoints (needed for real-time sync). OAuth tokens are encrypted at rest with AES-256-GCM. Each customer gets a dedicated, isolated PostgreSQL database hosted on Supabase.

What happens if I disconnect?

Your database and data are deleted. We don't retain any Stripe data after you uninstall. You can export your data before disconnecting.

Can I use this with test mode?

Yes, but test mode requires a separate installation link and still requires a subscription (it costs us the same to provision). If you want to try with test mode first, reach out to us and we'll send you the test mode install link. Once you're happy, you can uninstall from test mode, then install on your live account.

How does real-time sync work?

We use Stripe webhooks to capture changes in real-time — when a customer is created or an invoice is paid, it's in your database within seconds. But webhooks can sometimes arrive out of order, be delayed, or fail to reach us. So we also run regular background sync jobs and use Stripe's Events API to catch anything that was missed. We do everything we can to keep your data accurate and up to date.

What BI tools can I connect?

Any tool that supports PostgreSQL: Metabase, Tableau, Looker, Mode, Redash, Apache Superset, and more. You can also use psql or any SQL client.

Need help?

Reach out to us and we'll get back to you quickly.

Contact Support