Introduction & Scenario

In a Stripe Connect scenario, a customer who makes a purchase from one of your connected sellers shouldn’t need to re-enter their credit card or bank account details to purchase from another seller.

Without Shared Customers, you will have to re-enter all the customer details, creating a Customer Object, on each connected account. With Shared Customers you are going to maintain a single reference to a customer in the platform account, and the association to a specific connected account will be accomplished by the use of a token the represent the customer.

For a Stripe Connect introduction that is needed to proceed with this article, please refer to the Stripe Connect Custom with Direct Charges article. Specifically, you have already created and verified a connected account.

Terms & Tools

Generic terms

• Platform: it’s you!
• Connected Account: that’s a vendor that will sell stuff through your platform;
• Customer: a customer that will buy from a Connected Account;

Examples terms

• {API_KEY}: That’s your key. Look at the Stripe documentation signed in with your account and they will fill it for you;
• {CUST_ID}: that’s a customer ID;
• {ACC_ID}: that’s a connected account ID;
• {CUST_TOK_ID}: that’s a token representing a customer on an connected account;
• {TOK_ID}: that’s a token representation of a payment source. Will be clearer when we are going to use it in the document.

Tools

I will use curl to perform API calls. No other special tools are used here.

Of course, a Stripe account is needed in order to try what’s written down in this article. I suggest to always have the Stripe dashboard opened in order to check in real-time the results of what we are going to do.

Shared Customer Creation

As stated before, when not using shared customers, you save the Stripe Customer objects on each individual connected Stripe account. To share customers, you instead save them on the platform Stripe account.

Platform Customer Creation

So let’s create a customer:

curl https://api.stripe.com/v1/customers \
 -u {API_KEY}: \
 -d description="Shared customer example" \
 -d email="sharedcustomer1@email.com"

The output of this procedure is an Customer Object.

For now, let’s take note only of the id that is the unique identifier for the newly created customer.

In the examples, as stated before, this will be indicated as {CUST_ID}.

Please note that there is no reference to a connected account, but we are creating it in the platform.

Associate a payment source to the customer

The easiest option to create a token that represents a customer payment method is to tokenise a card using Stripe Elements or Stripe Checkout.

Let’s refer to this token as {TOK_ID}.

We can now update the previously created customer:

curl https://api.stripe.com/v1/customers/{CUST_ID} \
 -u {API_KEY}: \
 -d source={TOK_ID}

adsense

Create a customer token

As stated in the introduction, with Shared Customers you are going to maintain a single reference to a customer in the platform account. The association to a specific connected account will be accomplished by the use of a token the represent the customer.

We can now create the customer token:

curl https://api.stripe.com/v1/tokens \
 -u {API_KEY}: \
 -d customer={CUST_ID} \
 -H "Stripe-Account: {ACC_ID}"

The output of this command will give us an id that we need to use in the next paragraph.

Let’s refer to this id with {CUST_TOK_ID}.

Create a customer in the connect account

Last step. Finally, we can create the customer to the connected account easily, with only the token.

Let’s do this:

curl https://api.stripe.com/v1/customers \
 -u {API_KEY}: \
 -d source={CUST_TOK_ID} \
 -H "Stripe-Account: {ACC_ID}"

The output of this procedure is an Customer Object.

The id in the output is the unique identifier for the newly created customer in the connected account.