Stripe Setup
Stripe is Vivreal's primary payment integration. Once connected, you can sync your Stripe products into a collection, manage pricing, and view sales data directly from the portal.
Prerequisites
- A Stripe account (test or live mode)
- Admin or owner role in your Vivreal group
- A Vivreal group (Stripe is available on all tiers)
Connecting Stripe
Get your Stripe API key
Log in to the Stripe Dashboard. Copy your Secret key — this is the key Vivreal needs to access your Stripe data. For testing, use the key that starts with sk_test_. For production, use sk_live_.
Open the Stripe integration
In the Vivreal portal, go to Channels from the bottom navigation bar and tap Stripe. This opens the Stripe configuration page.
Enter your API key
Click Configure and paste your Stripe secret key into the API Key field. Click Save to store the credentials. Vivreal encrypts the key using AES-256-GCM before storing it.
Sync your products
After connecting, go to the Settings tab and click Sync from Stripe. Vivreal will pull all your active products and their prices into a linked collection.
Keep your secret key secure
Your Stripe secret key grants full access to your Stripe account. Never share it publicly. Vivreal stores it encrypted, and it is never exposed to the browser — all Stripe API calls happen server-side.
The Stripe Integration Page
Once connected, the Stripe integration page has several tabs:
Products Tab
Displays all synced Stripe products as collection objects. Each product card shows:
- Product name and description
- Price (with currency)
- Active/archived status
- Product image (if set in Stripe)
You can click any product to view its full details, edit its metadata within Vivreal, or archive it.
Sales Overview
The overview tab shows key metrics from your Stripe account:
- Total revenue
- Number of transactions
- Active subscriptions (if applicable)
Settings Tab
From here you can:
- Re-sync products — Pull the latest product data from Stripe.
- Update your API key — Rotate to a new key if needed.
- Disconnect Stripe — Remove the integration from your group.
How Product Sync Works
When you trigger Sync from Stripe, Vivreal calls the Stripe Products API and upserts collection objects in your integration collection. New products created inside the Vivreal portal are pushed the other way — Vivreal creates the product and prices in Stripe, then stores the resulting IDs locally — so the connection is bidirectional in practice, with Stripe holding the canonical product/price IDs.
Each synced product maps to a collection object whose objectValue is populated from these Stripe fields:
Vivreal field (objectValue.*) | Stripe source | Notes |
|---|---|---|
name | product.name | |
description | product.description | |
price | product.default_price.unit_amount | Stored as integer cents (e.g. 7999 for $79.99). The portal UI converts to/from dollars on display + on push to Stripe. |
productImage | product.images[0] | First image only. |
images | product.images | Full array. |
default_price | product.default_price.id (or the raw string if not expanded) | Stripe price ID — used by the storefront to create checkout sessions. |
object | product.object (always product) | |
active | product.active | Archived products in Stripe still sync; the storefront filters them. |
livemode | product.livemode | true for live-mode products, false for test-mode. |
created / updated | product.created / product.updated | Unix timestamps from Stripe. |
Top-level (outside objectValue):
| Vivreal field | Stripe source |
|---|---|
id (also stored as the externalId for upsert dedup) | product.id (e.g. prod_ABC123) |
platform | Always "stripe" |
No currency field is stored
The current sync does not record price.currency. All portal-originated Stripe products are created in usd, and the storefront assumes USD. If you need multi-currency support, do not rely on a currency field being present on the synced object today.
Prices are stored as integer cents, not dollars
Both the Stripe sync and the portal's create-product path store objectValue.price in cents (the same unit Stripe uses internally). Display layers (the portal product cards, the storefront, the MCP tools) convert to a decimal dollar amount on the way out. If you read a synced product directly via the API, treat price as cents.
Sync is on-demand
Product sync does not happen automatically. Click the Sync from Stripe button whenever you want to pull the latest data from Stripe. Edits made in the portal push to Stripe on save (no manual sync needed for that direction).
Stripe on Your Deployed Site
When you deploy a site with Vivreal, the Stripe integration key is injected into the site's environment automatically. Your storefront template uses this key server-side to create checkout sessions — the key is never exposed to the browser.
Products displayed on your site are served through the Client API, which reads from the same synced collection objects.
Test mode first
Start with a Stripe test key (sk_test_...) to verify the integration works before switching to your live key. You can update the key at any time from the Settings tab.
Troubleshooting
- "Invalid API key" error — Double-check that you copied the full secret key including the
sk_test_orsk_live_prefix. - Products not appearing after sync — Ensure your Stripe products are marked as active in the Stripe Dashboard. Archived products are not synced.
- Sync shows 0 products — Confirm that the API key has permission to access Products. Restricted keys may need the
Products: Readpermission enabled.