🍔 Single Slider: Direct Charges on Multiple Accounts with Cloning

Find out how to collect payment information once and then use it for multiple direct charges across multiple connected accounts with cloning!

What is TSE?

TSE is short for Technical Solutions Engineering, a team of engineers at who help developers like you build amazing things with Stripe. We help people both inside and outside of Stripe by answering questions, investigating bugs, working on various projects, and teaching others what we know. (Perhaps you'd like to join us)?)

What's a 🍔 Single Slider?

🍔 Single Sliders are similar to one-pagers, except they take the form of a single-slide presentation and have a punny name.

🍔 Single Sliders originally started as short conversation starters at the beginning of our internal TSE Office Hours sessions. We eventually started to publish them internally as videos with transcripts so everyone at Stripe could view them without needing to attend Office Hours.

We realized some 🍔 Single Sliders would be valuable for everyone if we published them outside of Stripe as well, so here we are. 🙂

Transcript

Welcome to another TSE Single Slider!

This one's all about direct charges on multiple accounts with cloning. I'll explain how to collect payment details from a customer once and use them for multiple direct charges on multiple connected accounts.

Getting set up on the platform

Let's start on the platform, where we either create or use an existing Customer. We'll create a SetupIntent associated with this Customer, and when we confirm the SetupIntent client-side we get a PaymentMethod that's been set up for future use. When confirmed successfully, SetupIntents automatically attach the associated PaymentMethod to the associated Customer, which allows the PaymentMethod to be reused.

One quick note before we proceed: for this slide I'm using example object IDs with sequential numbers (e.g., pm_1, pm_2, and so on). Usually I use random example IDs to approximate the random IDs Stripe will generate, but using sequential IDs for this slide will make things easier to understand. Just remember, when you're actually using Stripe, the IDs generated for these objects will be random, and none of them will be sequential or related in any way.

Send in the clones

Okay, now that we have a PaymentMethod set up for future use on the platform, we can clone it to a connected account. Let's start with connected account acct_a, where we want to make our first direct charge.

To clone the PaymentMethod to this connected account we need to make a POST request to /v1/payment_methods. We set the value of the Stripe-Account header to the connected account's ID, and in the body of the request we'll specify the ID of the PaymentMethod we want to clone and, because that PaymentMethod is attached to a Customer, we also need to specify the Customer ID.

When this API request succeeds, a new PaymentMethod object on the connected account is created. Like pm_1 on the platform, this new PaymentMethod (pm_2) represents the same payment information, but other than that it's an entirely new and independent object.

We can now use this cloned PaymentMethod to create a direct charge on the connected account by creating and confirming a PaymentIntent!

Ensure proper set up

Note the cloned PaymentMethod on the connected account inherited the setup for future use performed by the SetupIntent on the platform. This means there's no need to set it up again on the connected account.

One thing to keep in mind here are the countries of the platform and connected accounts. You may need to use on_behalf_of on the SetupIntent to properly set up the PaymentMethod for use with your connected accounts. For example, if your platform account is in the United States, where 3D Secure rarely or never happens, the setup performed by the SetupIntent will likely not prompt for 3D Secure authentication, and will thus be insufficient if you want to make a direct charge on a European connected account, where SCA is enforced.

If you're going to create direct charges in a country that differs from your platform account, you can use on_behalf_of on the SetupIntent to specify a connected account in the same country where the charges will be made to ensure the proper setup is performed.

Second connected account, more direct charges

Now let's look at a second connected account, acct_b. What if we also want to use the same PaymentMethod from the platform to create a direct charge on this other account? It works basically the same way, starting with the same API request to clone the PaymentMethod, with the only change being the account ID we specify in the Stripe-Account header.

Once this API request succeeds we have another new cloned PaymentMethod (pm_3) on acct_b. This PaymentMethod has also inherited the setup from the platform, so we can then create a direct charge the same way.

Let's imagine now that we want to create a second direct charge on acct_b. You might be thinking we can reuse pm_3 for that, but there are two reasons that won't work.

First, we're not attaching the cloned PaymentMethods on the connected accounts to Customers (which enables reuse), which means they can only be used once, and we've already used pm_3 for a direct charge.

Second, even if we did attach pm_3 to a Customer, if some time passed between the two direct charges on acct_b, pm_3 might be out of date. You should think of the PaymentMethod on the platform as the canonical one. If the Customer wants to update their PaymentMethod on file (such as providing a new expiration date for their card) you would update the PaymentMethod on the platform with those changes. That means pm_3 wouldn't be up to date for the next direct charge unless you went to the trouble of keeping track of and updating every cloned copy of pm_1 manually.

The best approach is to clone the canonical PaymentMethod from the platform again, at the time of each transaction. This will always provide an up-to-date copy and avoid the need to manage and update reusable PaymentMethod objects on various connected accounts.

Other things to note

There are a few other things to note about cloning PaymentMethods.

First, it's important to understand that cloned PaymentMethods are separate, completely independent objects with their own IDs, and they have no link back to the original PaymentMethod on the platform. There's no synchronization of any kind, so if you update the PaymentMethod on the platform the clones you've already made are not affected.

Second, only certain types of PaymentMethod objects can be cloned, such as cards and ACH debit PaymentMethods. No other objects, like Invoices or Customers, can be cloned. If you want to copy an object like a Customer to a connected account you need to do so manually.

Third, if you want to use a cloned PaymentMethod for recurring Billing, such as with a Subscription, you must attach it to a Customer on the connected account so it can be reused.

So that's direct charges on multiple accounts with cloning! Once you have a reusable PaymentMethod on your platform you can clone it an unlimited number of times to an unlimited number of connected accounts in order to enable the direct charge workflow of your dreams!

Next steps

We have useful documentation about cloning and Connect which will come in handy as you build your integration:

• Cloning PaymentMethods
• Creating direct charges
• Making API calls for connected accounts

📣 Follow us on Twitter
💬 Join the official Discord server
📺 Subscribe to our Youtube channel
📧 Sign up for the Dev Digest

About the author

Justin Michael helps developers like you build amazing things with Stripe as a Technical Solutions Engineer.

Comments

[Frazer McLeod]

hey @violetpixel

We've configured Stripe Connect to clone customers payment information from a platform account to a connected account. We've been following the guide here in order to do this: stripe.com/docs/connect/cloning-cu...

We're able to successfully clone both the payment method & customer in most instances but it seems that sometimes the api call to clone the customer fails with an error card_declined "Your card was declined.".

In this instance the call to clone the payment method for the customer succeeds but not the call to clone the customer. To be clear this is a POST call to "v1/customers" passing the payment_method parameter.

Is it the case that it is not possible to clone a customer that has an issue with a card attached to their payment method? It seems strange to me that the clone of the payment method succeeds but the clone of the customer fails.

We can't seem to find any posts about this specific scenario and wondered if you knew the answer?

Thanks!

Frazer