# 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](https://docs.stripe.com/get-started/account/orgs/sharing/customers-payment-methods/how-sharing-works.md), including supported payment methods, limitations, and event behavior.

## Enable sharing for accounts within your organization

### Before you begin

1. [Create an organization](https://docs.stripe.com/get-started/account/orgs/build.md#create-org) across your [multiple standalone accounts](https://docs.stripe.com/get-started/account/orgs/setup.md#standalone-accounts).
2. [Create a sandbox environment](https://docs.stripe.com/sandboxes/dashboard/organizations.md#create-an-organization-sandbox) 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](https://dashboard.stripe.com/org/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](https://support.stripe.com/contact/email?question=other&topic=account&subject=Customer+sharing+eligibility+-+duplicate+customers+found&body=I+am+trying+to+enable+customer+and+payment+method+sharing+for+my+organization+but+the+eligibility+check+found+duplicate+customers+across+my+accounts.+I+need+help+resolving+these+conflicts+so+I+can+proceed+with+sharing) 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:

A standard organization setup with three standalone accounts. (See full diagram at https://docs.stripe.com/get-started/account/orgs/sharing/customers-payment-methods)

```text
[Rocket, Inc.Organization] --> [Rocket RidesAccount 1]
[Rocket, Inc.Organization] --> [Rocket DeliveriesAccount 2]
[Rocket, Inc.Organization] --> [Rocket RepairsAccount 3]
[Rocket RidesAccount 1] --> [Jenny Rosen Customer 123]
[Rocket DeliveriesAccount 2] --> [Jenny Rosen Customer 123]
[Rocket RepairsAccount 3] --> [Jenny Rosen Customer 123]
[Jenny Rosen Customer 123] --> [Visa Credit CardPayment Method 456]
[Jenny Rosen Customer 123] --> [Jenny Rosen Customer 123]
[Jenny Rosen Customer 123] --> [Jenny Rosen Customer 123]
[Jenny Rosen Customer 123] --> [Visa Credit CardPayment Method 456]
[Jenny Rosen Customer 123] --> [Visa Credit CardPayment Method 456]
```

### Create a Customer during checkout

A customer makes a payment to one of the accounts in a sharing group (Rocket Rides). The [CheckoutSession](https://docs.stripe.com/api/checkout/sessions/create.md) enables `customer_creation` and `payment_method_save`.

```javascript
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_page',
  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

When receiving webhooks, [verify event signatures](https://docs.stripe.com/webhooks.md#verify-events) and use [Stripe’s public IP address list](https://docs.stripe.com/ips.md).

### Update shared customer data from another account

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

```javascript
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.

```javascript
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.

```javascript
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).

```javascript
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_page',
  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. 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.

```javascript
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_page',
  return_url: 'https://checkout.rocket-repairs.com/checkout/return?session_id={CHECKOUT_SESSION_ID}',
  saved_payment_method_options: {
    payment_method_save: 'enabled',
  },
});
```