Selling Online
Vivreal takes payments through Stripe or Square. Use whichever one you already take payments through, and if you use neither yet, either one works. Once connected, your products come across into Vivreal, and you manage pricing and see your sales without leaving the portal.
The two connect slightly differently:
| How you connect it | |
|---|---|
| Stripe | Create a restricted key in your Stripe dashboard and paste it across |
| Square | Sign in to Square from the Channels page, no key to copy |
Once connected, both work the same way: products, orders, and fulfilment all come into the portal. This page walks through Stripe from start to finish.
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
Create a restricted key in Stripe
Log in to the Stripe Dashboard and go to Developers, then API keys. Click Create restricted key.
A restricted key is one you create for a specific tool, and it only does the things you tick. Stripe asks every outside tool to use one, so this is the key to give Vivreal.
Give it a name you will recognise later, such as "Vivreal", then set these permissions:
| Permission | Access |
|---|---|
| Products | Write |
| Prices | Write |
| Checkout Sessions | Write |
| Coupons | Write |
| Promotion codes | Write |
| Webhook endpoints | Write |
| Payouts | Write |
| Balance | Read |
Leave everything else set to None. Create the key and copy it. It starts with rk_live_, or rk_test_ if you are in test mode.
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 key
Click Configure and paste the key into the API Key field. Click Save to store it. Vivreal encrypts the key before storing it, and it is never sent to the browser.
Sync your products
After connecting, go to the Settings tab and tap Sync from Stripe. Vivreal pulls in all your active products and their prices.
Use a restricted key, not your secret key
Your account's Secret key (the one starting with sk_) does everything your Stripe account can do. Stripe asks you not to hand that key to an outside tool, and charges accounts that keep doing it. A restricted key does only what you ticked, and you can revoke it on its own without touching anything else.
Vivreal stores whichever key you give it encrypted, and never sends it to the browser. All calls to Stripe happen on our servers.
The Stripe Integration Page
Once connected, the Stripe integration page has several tabs:
Products Tab
Displays all synced Stripe products as items. 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 tap Sync from Stripe, Vivreal pulls your Stripe products in and keeps them up to date. It works the other way too: add a product in Vivreal and it is created in Stripe for you, with its price. The two stay in step in both directions, and Stripe stays the source of truth for products and prices.
The rest of this section is for developers reading your products programmatically. If you are not one, skip to the next heading.
Each synced product becomes an item whose objectValue is filled in 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
Products created in Vivreal are made in US dollars, and the storefront assumes US dollars. If you sell in another currency, this is a real limitation to check before you commit to a launch date, not a detail. Nothing records a per-product currency 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. Developers reading a synced product directly should 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 live site
When Vivreal publishes your site, your Stripe key goes with it automatically. Your storefront uses it on the server to create each checkout, and it is never sent to a visitor's browser.
The products on your site come from that same synced list, so your storefront and your Stripe account never drift apart.
Test mode first
Switch the Stripe Dashboard to test mode and create a test restricted key (rk_test_...) to check everything works before you go live. You can swap the key at any time from the Settings tab.
Troubleshooting
- "Invalid API key" error: check you copied the whole key, including the
rk_test_orrk_live_prefix, and that you are not mixing a test key with live products. - 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: your key is probably missing a permission. Open the key in Stripe, and check Products and Prices are both set to Write.
- Checkout fails but syncing works: the key is missing Checkout Sessions. Edit the key in Stripe and set it to Write.