Skip to Content

Stripe setup

Use Sandbox and Stripe test-mode keys for testing. Use Live and the corresponding live-mode keys for real payments. The project’s Live/Sandbox mode and Stripe key mode must agree; a working test-mode connection does not configure live payments.

Connect an account

  1. Open Projects → your project → General → Payments → Stripe.
  2. Supply the account’s publishable key and secret key. Fields can use inline values or linked 1Password entries.
  3. Save the checkout redirect URLs for your app.
  4. Save the connection and check its status.
  5. Set the paid product’s SKU to the intended Stripe price ID in that same account and mode.

Keep Stripe secret keys on Modem or your server, never in frontend code. Existing saved credentials are retained when editing unrelated settings. A masked, saved connection can show Saved without rerunning a credential check using plaintext; do not equate that label with a fresh provider verification.

The backend checks key formats and modes, resolves the account using the secret key and manages the project’s Stripe webhook. Do not substitute another account’s price or payment references. Refunding a past payment requires the account and mode that originally received it.

Redirects and checkout

Configure the application’s actual success and cancellation destinations, then pass their HTTP(S) URLs to Checkout. On success, retain the Checkout Session ID and process it through Modem. Render payment and grant states from the result, not from the URL alone.

Managed webhook

Connecting or updating Stripe creates or repairs Modem’s webhook connection. Its account, signing secret and selected API-version fields are managed by the server. Avoid editing them independently in a way that breaks the saved connection. Webhook processing explains delivery checks and delayed reconciliation.

For a test-mode walkthrough, see Stripe test keys. Moving to Live requires its own account/key/price and delivery verification; it is not a frontend-only switch.

Automate with the admin SDK

Use package access and an admin API key from a trusted server. The key needs projects:write, scoped to this project and its Live/Sandbox mode; write access also permits retrieving its current state. Updating the product SKU additionally needs products:write. The deployment selected by environment is separate from the project’s billing mode.

Enable the connection

import { createAdminClient } from '@preternatural-js/admin-sdk'; function required(name: string): string { const value = process.env[name]; if (!value) throw new Error(`Missing ${name}`); return value; } // Reads PRETERNATURAL_MODEM_ADMIN_API_KEY from this server's environment. const admin = createAdminClient({ environment: 'production' }); const projectId = required('MODEM_PROJECT_ID'); const provider = await admin.externalBillingProviders.enable(projectId, { type: 'stripe', configuration: { connect: { publishableKey: required('STRIPE_PUBLISHABLE_KEY'), secretKey: required('STRIPE_SECRET_KEY'), redirectUrls: ['https://app.example.com/checkout/success'] } } });

The keys must belong to the intended Stripe account and match the project’s mode. enable() expects no active connection of that type; retrieve the project and use update() when changing an existing provider. Creating an external service account or changing ordinary project metadata is not billing configuration.

The result includes the provider’s id and ISO updatedAt. Secret fields are redacted. Do not try to recover a Stripe or webhook secret from that response, and do not submit your own webhook ID, signing secret, account ID or API version: Modem manages those fields.

Enabling billing does not map a price to a paid product. Update the intended product separately, retaining its billing interval and metadata:

const productId = required('MODEM_PAID_PRODUCT_ID'); const product = await admin.products.retrieve(projectId, productId); await admin.products.update(projectId, productId, { sku: required('STRIPE_PRICE_ID'), billingInterval: product.billingInterval, metadata: product.metadata });

products.update() replaces these fields; it is not a partial metadata patch. Use a price from the connected account and mode, then verify Checkout.

Update a saved connection

Retrieve the latest provider summary from the project before editing:

const project = await admin.projects.retrieve(projectId); const stripe = project.billingProviders.find(item => item.type === 'stripe'); if (!stripe) throw new Error('Connect Stripe before updating it'); const updated = await admin.externalBillingProviders.update(projectId, stripe.id, { type: 'stripe', expectedUpdatedAt: stripe.updatedAt, configuration: { connect: { publishableKey: '', secretKey: '', redirectUrls: ['https://app.example.com/checkout/success'], credentialSelections: { publishableKey: { source: 'unchanged' }, secretKey: { source: 'unchanged' } } } } });

This is a full configuration input, not a partial patch. The explicit unchanged selections preserve the saved values and their credential sources; blank redacted response fields are not replacement secrets. To rotate a credential, select source: 'inline' with its new value. To replace a linked 1Password field with an inline key, make that selection explicit rather than changing only the string field. For a vault-backed billing field, use the complete credentialSelections input below; it is different from an external service account’s credentialSource input.

Pass expectedUpdatedAt exactly as returned, not as epoch milliseconds. A stale revision refuses the edit. Reload, compare the current settings and decide whether your change is still appropriate; do not overwrite a concurrent edit blindly.

Credential sources

Each billing credential can keep its stored value (source: 'unchanged'), replace it (source: 'inline', value: newValue) or resolve a 1Password reference (source: 'onepassword'). A billing credentialSelections entry uses ProviderCredentialSelectionInput, not the account replacement payload.

For example, replace Stripe’s secret-key source with a field from an existing 1Password integration, preserving the publishable key:

const beforeVaultUpdate = await admin.projects.retrieve(projectId); const stripeBeforeVault = beforeVaultUpdate.billingProviders.find( item => item.type === 'stripe' ); if (!stripeBeforeVault) throw new Error('Connect Stripe before updating it'); await admin.externalBillingProviders.update(projectId, stripeBeforeVault.id, { type: 'stripe', expectedUpdatedAt: stripeBeforeVault.updatedAt, configuration: { connect: { publishableKey: '', secretKey: '', redirectUrls: stripeBeforeVault.configuration.connect.redirectUrls, credentialSelections: { publishableKey: { source: 'unchanged' }, secretKey: { source: 'onepassword', secretsIntegrationId: required('MODEM_1PASSWORD_INTEGRATION_ID'), secretReference: 'op://Engineering/Stripe/secretKey', secretReferenceLabel: 'op://Engineering/Stripe/secretKey' } } } } });

Replace the example references with your integration’s actual vault/item/field reference. secretsIntegrationId identifies the existing Modem integration; secretReference identifies the field to resolve. secretReferenceLabel is required and is a display reference, not the secret value; it can equal secretReference when you have no separate readable reference. The integration must have access to that field. Modem resolves and saves the credential on its server, so the client does not need to read the Stripe key out of 1Password.

For App Store credentials, place the same selection shape under configuration.appStoreConnect.credentialSelections.privateKey or .sharedSecret. Response-side credentialSources and materialization metadata are not substitutes for these input selections.

Disconnect

Retrieve the project again, select the current Stripe summary and request disconnection explicitly:

const latest = await admin.projects.retrieve(projectId); const current = latest.billingProviders.find(item => item.type === 'stripe'); if (!current) throw new Error('Stripe is already disconnected'); const disconnected = await admin.externalBillingProviders.disconnect( projectId, current.id, { expectedUpdatedAt: current.updatedAt } );

The returned disconnected record has tombstoned: true and configuration: null; active summaries disappear from project.billingProviders. Sending empty credential strings to update() is not the disconnect API.

Stripe configuration changes wait for unfinished purchases to settle or expire. Changing the account or mode, or removing the connection, also requires linked subscriptions to reach a final state. Resolve the refusal rather than canceling subscriptions as an automatic retry strategy. App Store provider configuration uses the same revision-based resource methods but does not acquire Stripe’s account/webhook behavior; see App Store automation.

A timeout or lost response can leave a Stripe change or its webhook cleanup in progress. Retrieve current project state before resubmitting. See payment webhooks for receipt versus completed processing and the billing-provider SDK reference for input and result types.

Changing or disconnecting billing

Resolve unfinished checkout/upgrade operations and linked active subscriptions before removing their billing connection. Keep historical account/mode information available for refunds. A credential change cannot move an existing Stripe payment to a different account.

If a save or provider action times out, inspect the connection or payment state before repeating it. A network failure can leave an accepted operation whose response was lost.

API reference

Last updated on