Introduction & Scenario

The scenario covers a reader (you!) that wants to:

• create a marketplace;
• take some fee on every transaction between users of its website/app and a connected vendor;
• guarantee a user-friendly experience for its vendors, in order to not let them front the procedures on the Stripe platform, but directly through its website/app communicating through APIs.

If this is not your case, maybe it’s better to evaluate different types of Stripe Connect because they provide an easier experience for you, both from the technical side and the “bureaucratic” side (with Custom all the disputes – and relative fees – are faced by the platform).

If this is your case, please continue!

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;
• {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.

Create & verify a connected account

We are going to create an account and all the required fields.

The second sub-paragraph is just a note to not be unprepared if your country acts a little bit differently from the one used in this example.

Connected Account creation process

We will start creating an account with some information in it.

Then we will update the account with other required information. To create a verified account that will be able to process payments, please refer to the next sub-paragraph.

Account creation

curl https://api.stripe.com/v1/accounts \
 -u {API_KEY}: \
 -d country=IT \
 -d type=custom \
 -d legal_entity[first_name]="John" \
 -d legal_entity[last_name]="Doe" \
 -d legal_entity[type]=individual \
 -d legal_entity[dob][day]=12 \
 -d legal_entity[dob][month]=12 \
 -d legal_entity[dob][year]=1992 \
 -d legal_entity[address][city]=Rome \
 -d legal_entity[address][country]=IT \
 -d legal_entity[address][line1]="Via Nazionale" \
 -d legal_entity[address][postal_code]=00184

Let’s have a look.
We have now created a connected account passing custom as the type (we are creating it for a Connect Custom solution).

The entity type is individual because the example is for an individual, but it can be company, too.

There is no need to analyse the rest of the params, so let’s go on.

The output of this procedure is an Account Object.

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

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

ID document upload

Now, we have to associate an ID document copy to the account. Assuming that you have a PNG file on your desktop called id.png that contains the copy of the document, let’s launch the command:

curl https://uploads.stripe.com/v1/files \
 -u {API_KEY}: \
 -H "Stripe-Account: {ACC_ID}" \
 -F purpose=identity_document \
 -F file="@/Users/lorenzo/Desktop/id.png"

Please note the line -H “Stripe-Account: {ACC_ID}”.

The output of this process is a File Upload Object.

Let’s take note of the id, that we call {FILE_ID}.

Now, we have to attach this file to the verification document section of the connected account:

curl https://api.stripe.com/v1/accounts/{ACC_ID} \
 -u {API_KEY}: \
 -d legal_entity[verification][document]={FILE_ID}

Now the account is verified. We need to associate a bank account where the connected account will be payed.

adsense

Bank account creation and association

The example shows an Italian account, so we are going to associate an Italian bank account that accepts Euros as its currency:

curl https://api.stripe.com/v1/accounts/{ACC_ID}/external_accounts \
 -u {API_KEY}: \
 -d external_account[object]=bank_account \
 -d external_account[account_number]='IT89370400440532013000' \
 -d external_account[country]=IT \
 -d external_account[currency]=eur

The account number is taken from the bank numbers indicated by Stripe in its testing section.

Accepting conditions

The last step is to accept the conditions, please be sure to correctly inform the vendor about  the Stripe Terms of Service before performing this API call:

curl https://api.stripe.com/v1/accounts/{ACC_ID} \
 -u {API_KEY}: \
 -d tos_acceptance2024=1503302212 \
 -d tos_acceptance[ip]="VV.XX.YY.ZZ"

Where date represents the timestamp when the account owner accepted Stripe’s terms, and ip represents the IP address from which the account owner accepted Stripe’s terms.

Connected Account verification process

When building a Connect platform using Custom accounts, you’ll need to collect the required verification information for each of your accounts, which varies by the Custom account’s country.

That’s what the official documentation states about the verification process. So what we did before it’s for the Italian (but most part of European countries) accounts. Check the official documentation for the list for each country.

Direct charges on the connected account and collect fees

Now it’s time to let a customer pay a connected account.

The easiest option here is to tokenise a card using Stripe Elements or Stripe Checkout.

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

curl https://api.stripe.com/v1/charges \
 -u {API_KEY}: \
 -d amount=10000 \
 -d currency=eur \
 -d source={TOK_ID} \
 -d application_fee=123 \
 -H "Stripe-Account: {ACC_ID}"

The application_fee is capped at the total transaction amount minus any Stripe fees.

Please note here that, when directly charging on the connected account, you can provide a token created using either your platform’s or the connected account’s publishable key.

Conclusion

That’s it.

You should be now able to go to the dashboard and review connect accounts, fees, and so on.

The next article in the series is about Stripe Shared Customers.

Stay tuned!