Share customers and payment methods across accounts in an organizationPublic preview

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

Many growing businesses expand to multiple Stripe accounts to keep finances from different business lines separate or because the business operates in multiple regions with different legal entities. As a multi-entity business, you can share customers and payment methods across accounts in an organization to avoid:

Recollecting payment methods or contact information multiple times from the same customer
Introducing inconsistencies in a customer’s contact and payment details between accounts
Maintaining and updating duplicate records

Access

Customer and payment method sharing is currently in public preview, with the following eligibility criteria:

You have fewer than 100 million customers.
You don’t need sharing between connected accounts under a platform.
You’re not using Stripe Apps.

Limitations

Customer and payment method sharing is currently in public preview with the following restrictions:

You can’t remove an account from sharing after enabling the feature.
You can only share customers and payment methods across an organization that has multiple standalone accounts or platform accounts. You can’t share customers or payment methods across connected accounts.
You can only share payment methods across accounts if the type is card. You can save other reusable payment methods to an account but can’t share those with other accounts.
You can’t share card payment methods that originate from a wallet.
You can’t selectively share individual customers or payment methods. Enabling accounts shares all customers and payment methods.

Before you begin

Create an organization across your multiple standalone accounts.
Create a sandbox environment for your organization and its accounts so you can test your integration before putting it in production.

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

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

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.

After one account in the sharing group creates a customer, Stripe automatically creates that customer in all other accounts in the group. Each account in the sharing group maintains its own instance of the shared customer, but all instances have the same customer ID.

Any account in the sharing group can update the customer through the Dashboard or the API. Updates to the following fields of the Customer object sync across all account instances in the sharing group:

Updates to other fields within an account save to the Customer instance of the account making the update, but don’t sync to other accounts in the sharing group. It’s possible for the same customer to have different values for the same unshared field across different account instances. This protects the integrity of customer data that might be proprietary, sensitive, or only relevant to one account.

Payment methods

In contrast to Customer instances, Stripe creates the payment method only in the originating account. However, any account in the sharing group can charge, update, and even delete this single payment method instance. Updating a shared payment method (including removal) affects its attached customers on all accounts in the sharing group. However, the following activity only applies to the originating account:

Stripe generates payment_method.<action> events only for the originating account.
Stripe charges Card Account Updater (CAU) fees only to the originating account.

Event behavior

If an account updates any of the shared fields for a customer, Stripe generates separate customer.updated events for each account in the sharing group. If an account updates an unshared field for the customer, Stripe sends the customer.updated event to only that account.

If an account attaches a payment method to a customer, Stripe generates a single payment_method.attached event for only the originating account.

We recommend all accounts in a sharing group listen for events using an organization-level webhook so you’re aware of shared payment method activity.

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
const stripe = require('stripe')('{{SECRET_KEY_ROCKET_RIDES}}');

const session = await stripe.checkout.sessions.create({
  customer_creation: 'always',
  line_items: [
    {
      price_data: {
        currency: 'usd',
        product_data: {
          name: 'ride_service',
        },
        unit_amount: 2000,
      },
      quantity: 1,
    },
  ],
  mode: 'payment',
  ui_mode: 'embedded',
  return_url: 'https://checkout.rocket-rides.com/checkout/return?session_id={CHECKOUT_SESSION_ID}',
  saved_payment_method_options: {
    payment_method_save: 'enabled',
  },
});

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

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 update.
Only Rocket Delivery’s account gets the metadata_door update, since it’s not a shared field.

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
const stripe = require('stripe')('{{SECRET_KEY_ROCKET_REPAIRS}}');

const session = await stripe.checkout.sessions.create({
  customer:'{{CUSTOMER_ID}}'
,
  line_items: [
    {
      price_data: {
        currency: 'usd',
        product_data: {
          name: 'tow_service',
        },
        unit_amount: 5000,
      },
      quantity: 1,
    },
  ],
  mode: 'payment',
  ui_mode: 'embedded',
  return_url: 'https://checkout.rocket-repairs.com/checkout/return?session_id={CHECKOUT_SESSION_ID}',
  saved_payment_method_options: {
    payment_method_save: 'enabled',
  },
});

Payments appear on the Transactions page for the corresponding account and the organization. Other 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
const stripe = require('stripe')('{{SECRET_KEY_ROCKET_REPAIRS}}');

const session = await stripe.checkout.sessions.create({
  customer:'{{CUSTOMER_ID}}'
,
  line_items: [
    {
      price_data: {
        currency: 'usd',
        product_data: {
          name: 'basic-roadside-service',
        },
        unit_amount: 2500,
      },
      quantity: 1,
    },
  ],
  mode: 'subscription',
  ui_mode: 'embedded',
  return_url: 'https://checkout.rocket-repairs.com/checkout/return?session_id={CHECKOUT_SESSION_ID}',
  saved_payment_method_options: {
    payment_method_save: 'enabled',
  },
});