Connecting Stripe

Maven uses Stripe Connect to process payments on your Stripe account. The setup uses OAuth — you authorize Maven to create charges on your behalf.

Running a multi-merchant platform with many connected accounts under your own Stripe key? Skip the OAuth flow and use Platform Mode instead.

Prerequisites

A Stripe account (test or live)
A Maven app

Setup Steps

Go to Payments

In the Maven Dashboard, navigate to your app and click the Payments tab.

Click Connect Stripe

Click the Connect Stripe button. You’ll be redirected to Stripe’s OAuth authorization page.

Authorize Maven

On the Stripe page, review the permissions and click Connect. Maven requests the ability to create charges and customers on your account.

Return to Dashboard

After authorization, you’ll be redirected back to the Maven Dashboard. Your Stripe account will show as connected.

Test vs Live

Maven stores separate credentials for test and live modes:

Test mode (mvn_test_ keys): Uses your Stripe test mode. No real charges.
Live mode (mvn_live_ keys): Uses your Stripe live mode. Real charges.

Connect both test and live Stripe accounts for full functionality.

Processor Response Fields

When a payment succeeds via Stripe, the processor object in the GET session response includes:

Charge Mode

Field	Description
`stripe_payment_intent_id`	PaymentIntent ID (e.g., `pi_xxx`)
`stripe_charge_id`	Charge ID (e.g., `ch_xxx`)
`receipt_url`	Stripe-hosted receipt URL
`payment_method_id`	PaymentMethod ID (e.g., `pm_xxx`)
`card_brand`	Card brand (visa, mastercard, etc.)
`card_last4`	Last 4 digits

Tokenize Mode

Field	Description
`stripe_customer_id`	Customer on your connected account (e.g., `cus_xxx`)
`payment_method_id`	PaymentMethod on your connected account, already attached to that customer (e.g., `pm_xxx`)
`card_brand`	Card brand
`card_last4`	Last 4 digits

Both stripe_customer_id and payment_method_id live on your own connected Stripe account — not on Maven’s platform account. Query and charge them with your own Stripe secret key (no stripe_account header needed, because they’re already on your account). Each tokenize creates a dedicated customer with exactly one saved card, so the customer + payment_method pair uniquely identifies the card — you never have to guess among multiple payment methods.

Using Tokenized Cards

After tokenizing, use the returned stripe_customer_id and payment_method_id to create charges via the Stripe API. Run this with your own Stripe secret key — the customer and payment method are on your account:

import stripe

stripe.api_key = "sk_live_...your_account_key..."

stripe.PaymentIntent.create(
    amount=4999,
    currency="usd",
    customer="cus_xxx",      # from processor.stripe_customer_id
    payment_method="pm_xxx", # from processor.payment_method_id (on your account)
    confirm=True,
    off_session=True,
)

Pass both customer and payment_method. Stripe treats the customer as optional in general, but because the card is saved to that customer, passing it is the reliable way to charge the intended card. As an extra safeguard you can verify card_last4 before charging.

Disconnecting

To disconnect Stripe, go to the Payments tab in your app and click Disconnect. Existing sessions won’t be affected, but new sessions using the stripe gateway will fail.

Platform Mode (Multi-Merchant Platforms)

If you are yourself a Stripe Connect platform — many connected accounts under your own platform API key — connecting each merchant to Maven individually doesn’t scale. Platform Mode inverts the relationship: Maven calls Stripe with your platform key and routes each payment to the connected account you name per session.

This is different from the standard connection above. Standard mode links one Stripe account to Maven’s platform via OAuth. Platform Mode uses your own platform key and never touches Maven’s Stripe platform — charges, tokens, and customers are created entirely under your accounts, and Maven takes no Stripe application fee.

Setup

In your app’s Payments tab, expand the Stripe card and find the Platform Mode section.
Add your platform API key per environment (test / live). A restricted key is recommended — scope it to write access for PaymentIntents, PaymentMethods, and Customers, with connected-account access enabled.
That’s it — no per-merchant onboarding, no OAuth links.

Creating sessions

Pass the target connected account on every session:

curl -X POST https://api.trymaven.com/v1/sessions \
  -H "Authorization: Bearer mvn_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-platform",
    "caller": "+14155551234",
    "amount": 125.00,
    "mode": "charge",
    "gateway": "stripe",
    "stripe_account": "acct_1ABC..."
  }'

stripe_account is required on every session when Platform Mode is configured (the API returns stripe_account_required otherwise).
In tokenize mode, the card is vaulted as a Customer + PaymentMethod on that connected account — the token is yours on your platform, permanently, independent of Maven.
Test-mode API keys use your test platform key; live keys use your live platform key.

Notes

The moto flag is set on PaymentIntents (phone payments are MOTO transactions) — ask Stripe support to enable MOTO on your platform if it isn’t already.
Maven never takes an application_fee in Platform Mode.

Getting Started

Chat Payments

Voice Payments

Payment Gateways

Stripe Connect

Connecting Stripe

Prerequisites

Setup Steps

Test vs Live

Processor Response Fields

Charge Mode

Tokenize Mode

Using Tokenized Cards

Disconnecting

Platform Mode (Multi-Merchant Platforms)

Setup

Creating sessions

Notes

​Connecting Stripe

​Prerequisites

​Setup Steps

​Test vs Live

​Processor Response Fields

​Charge Mode

​Tokenize Mode

​Using Tokenized Cards

​Disconnecting

​Platform Mode (Multi-Merchant Platforms)

​Setup

​Creating sessions

​Notes

Connecting Stripe

Prerequisites

Setup Steps

Test vs Live

Processor Response Fields

Charge Mode

Tokenize Mode

Using Tokenized Cards

Disconnecting

Platform Mode (Multi-Merchant Platforms)

Setup

Creating sessions

Notes