Share customers and payment methods across accounts in an organization

Avoid recollecting customer and payment method information from existing customers in multiple accounts.

Organizations on Stripe can share customers and payment methods across multiple accounts. Before you enable sharing, review how customer and payment method sharing works, including supported payment methods, limitations, and event behavior.

Enable sharing for accounts within your organization

Before you begin

1. Create an organization across your multiple standalone accounts .
2. Create a sandbox environment for your organization and its accounts so you can test your integration before putting it in production.
3. Get customer consent to share customer and payment method data.

Get customer consent

Your customers must consent to share customer data and payment methods before you enable sharing across your accounts and legal entities. Consent collection is the responsibility of businesses, not Stripe.

Create a new sharing group

You can enable sharing for a specific group of accounts in your organization or for all accounts.

1. From your organization settings in the Dashboard, click Customer and payment method sharing to get started.
2. Select the accounts to enable sharing for, and click Share . You must select at least two.
3. Check the box to confirm that you obtained consent from your customers to share contact and payment method information across accounts in your organization.
4. Click Enable .

Sharing is irreversible

You can enable sharing for unshared accounts at any time, but you can’t revert sharing for enabled accounts. You must contact Stripe if you want to disable sharing.

When you first enable sharing, Stripe begins syncing existing customers and payment methods across all accounts in the group. For most organizations, this completes within a few minutes to a few hours. For organizations with a very large number of customers and payment methods, the initial sync can take several days or weeks. Existing customers and payment methods can’t be used by other accounts in the sharing group until the sync is complete, but new customers and payment methods will immediately be shared.

Add an account to an existing sharing group

To add an account to an existing sharing group, open the sharing group in Organization settings and follow the prompts.

Resolve duplicate customers

When you create a new sharing group or add an account to an existing one, Stripe automatically checks for duplicate customers across the affected accounts (specifically, customer objects that share the same customer ID in multiple accounts). If duplicates are found, you’ll need to contact Stripe support to resolve them before you can proceed.

Sample integration use cases Server-side

The following sections provide code samples that illustrate how accounts in an organization sharing group might retrieve and use shared data. These examples reflect an organization with the following setup:

Create a Customer during checkout

A customer makes a payment to one of the accounts in a sharing group (Rocket Rides). The CheckoutSession enables customer_creation and payment_method_save.

server.js

After payment completion, Stripe shares the new customer and payment method to the other accounts in the sharing group. Stripe triggers the following events:

• customer. created for each account’s instance of the customer
• payment _ method. attached event for only the originating account

When receiving webhooks, verify event signatures and use Stripe’s public IP address list.

Update shared customer data from another account

Rocket Deliveries updates the shared customer originally saved by Rocket Rides.

server.js

const stripe = require('stripe')('{{SECRET_KEY_ROCKET_DELIVERIES}}');

const customer = await stripe.customers.update(
 '{{CUSTOMER_ID}}',
 {
 email: 'jenny@example.com',
 metadata: {
 door: "front"
 },
 }
);

Stripe triggers the customer.updated event for each account in the sharing group. Each account’s instance of the customer gets the email and metadata update because those customer fields are shared.

Retrieve a customer’s shared payment methods

All accounts in a sharing group can list a customer’s saved card type payment methods to use or update them.

If a customer has multiple payment methods saved across many accounts in a sharing group, Stripe limits the retrieval accounts to prioritize performance. We retrieve payment methods from only the requesting account and the four accounts with the most recently attached payment methods.

server.js

const stripe = require('stripe')('{{SECRET_KEY_ROCKET_REPAIRS}}');

const paymentMethods = await stripe.customers.listPaymentMethods('{{CUSTOMER_ID}}');

Update a customer’s shared payment methods

Updates to a shared payment method (including removal) sync to all accounts in the sharing group and trigger the payment_method.updated or payment_method.detached event.

server.js

const stripe = require('stripe')('{{SECRET_KEY_ROCKET_REPAIRS}}');

const paymentMethod = await stripe.paymentMethods.update(
 '{{PAYMENT_METHOD_ID}}',
 {
 "billing_details": {
 "address": {
 "city": "South San Francisco",
 "country": "us",
 "line1": "354 Oyster Point Boulevard",
 "line2": null,
 "postal_code": "94080",
 "state": "CA"
 }
 }
 }
);

Consider recurring payments

Changes to payment methods can affect ongoing subscriptions using that payment method, so exercise caution.

Accept a payment using a shared payment method Server-side

You can charge a payment method saved in one account (for example, Rocket Rides) for a payment created by another account in the sharing group (for example, Rocket Repairs).

server.js

Payments appear on the Transactions page for the corresponding account and the organization. Accounts can’t see each other’s payments, even when they’re part of the sharing group.

Create a subscription using a shared payment method Server-side

You can also create a subscription for a customer originally saved by another account in the sharing group.

server.js