Twin Documentation

Connect Stripe to MLX with read-only OAuth and bring billing and payment evidence into your Twin.

Twin Sync by MLX is a read-only Stripe integration for organisations with a managed MLX deployment. An organisation administrator connects an approved Stripe account through Stripe's OAuth consent screen. The integration brings billing and payment evidence into the organisation's Twin while Stripe remains authoritative. Credentials and data stay scoped to the selected MLX tenant and organisation.

The integration is for data synchronisation. It does not take payments, create charges, issue refunds, move funds, manage payouts, or create Stripe connected accounts.

What is synchronised

The initial and recovery sweeps cover:

balance transactions;
charges and refunds;
Checkout Sessions;
credit notes;
customers;
disputes;
Stripe Events;
invoice items;
invoices and invoice lines;
PaymentIntents;
payouts;
prices;
products; and
subscriptions and subscription items, including cancelled subscriptions.

Stripe remains the authoritative source. MLX retains provider events and stable entity revisions in the organisation-scoped raw-event path so changes, freshness, and deletion markers remain inspectable. That source evidence can support definitions and calculations that follow the Twin's separate review and publication lifecycle.

How synchronisation stays current

MLX combines three mechanisms:

An initial list-API sweep establishes the supported records.
Scheduled incremental jobs read the Stripe Events API and refresh supported records through the normal raw-event path.
Signed Stripe webhook deliveries wake that incremental path promptly.

Webhook payloads are sync hints rather than canonical business records. A verified delivery does not bypass authenticated Stripe API reads, tenant resolution, deduplication, or the governed raw-event and revision path.

Permissions and credentials

Stripe shows the requested read permissions before an administrator authorises the connection. They cover balances, balance transactions, charges, Checkout Sessions, credit notes, customers, disputes, events, invoices, PaymentIntents, payouts, prices, products, and subscriptions.

The app requests no Stripe write permissions. Account-scoped access and refresh tokens are stored in the configured MLX tenant secret store, not in application content or prompts. MLX refreshes short-lived access tokens and rejects a token response that changes the authorised Stripe account or test/live mode.

Start in a Stripe sandbox

Test the connection with fictional Stripe data before authorising a live account. A sandbox connection and a live connection use different credentials and data.

Connect

Sign in to your organisation's MLX workspace as an administrator.
Open Settings → Plugins and choose Stripe.
Confirm the selected MLX organisation and continue to Stripe.
Review Stripe's consent screen and authorise Twin Sync by MLX.
Return to MLX and wait for the initial synchronisation to complete.

The available Stripe account and mode are fixed when the connection is created. MLX rejects an attempt to silently replace them with a different account or switch between test and live mode.

Disconnect or revoke access

Disconnect Stripe from the MLX Plugins screen to disable future synchronisation. You can also revoke the app from Stripe. Stripe's deauthorisation event disables the corresponding MLX integration.

Disconnecting stops future collection. Data already retained under your MLX agreement follows the configured retention policy. Contact MLX support to request access, correction, or deletion.

Support and privacy

For help with installation, synchronisation, or disconnection, email team@mercurylabs.io. We aim to reply within one business day.

Stripe Twin Sync