Warning
You are viewing the technical documentation for the Sharetribe Developer Platform. If you are looking for our no-code documentation, see our help center.

Last updated

Providers and customers on your Stripe Platform

This article describes how providers and customers show up on your Stripe platform account.

Table of Contents

Introduction

If your marketplace handles payments through the Sharetribe Stripe integration, your providers and customers will show up in different ways on your Stripe platform account. The main ways this happens is through Stripe Connect accounts and Stripe Customers.

The Sharetribe Stripe integration uses Stripe Custom Connect accounts for providers. When a provider first creates a listing, they need to onboard to Stripe Connect before they can receive payouts. For customers, on the other hand, a Stripe Customer does not need to be created by default.

Stripe for providers: Stripe Connect Onboarding

When your marketplace handles payments, it is important to have a provider verification process where providers can enter all necessary and required information for them to receive payments. Provider verification is a requirement from Stripe's side for identity verification, risk assessment, and avoiding money laundering and other types of financial crime.

Regulatory aspects of provider onboarding can be challenging and changing rapidly. Stripe Connect Onboarding provides ready tools for meeting the requirements and reducing the operational complexity of self-managing the onboarding flow and identity verification.

For both Sharetribe Web Template and custom implementations, your marketplace will first need to set up Stripe for payments and enable Connect Onboarding. You can review the instructions in our Help Center for more details.

Stripe Connect Custom Accounts

Sharetribe uses Stripe Connect with Custom Accounts as the default payment integration. These enable your sellers to process payments through your marketplace. Stripe Connect also has other types of accounts, such as Standard and Express, but those are not compatible with the Sharetribe Stripe integration.

When you use the Sharetribe Stripe integration, you need to create Custom Connect accounts for your users through the Sharetribe Marketplace API Stripe Account creation endpoint. It is not possible to associate an existing Custom Connect account with a Sharetribe user profile.

When you need to update the Stripe Account, you can either use the Marketplace API Stripe Account updating endpoint or directly through Stripe API.

Fetching an existing Stripe Connect Account

If the provider already has a Stripe account, the currentUser resource has a stripeConnected boolean flag set to true. To fetch the provider's existing Stripe Connect account details, we can use the Marketplace API Stripe Account fetch endpoint. This will allow you to alert the provider if there is some required information missing from their Stripe Account.

Stripe account data is returned after each create and update Stripe Account API call, so there is no need for separate fetch API call in these cases.

After the Stripe Account has been fetched, you need to check requirements in the stripeAccountData attribute, which contains the related Stripe Account Object. If there are any fields in past_due or currently_due it means that those fields need to be collected to keep the account enabled. In other words, there are requirements missing. If there are no fields in past_due or currently_due, it means that the verification is completed for now. It is still possible that there might be new fields to be collected if the account reaches the next volume thresholds.

Creating a new Stripe Connect Account

If the current user's stripeConnected flag is false, the current user does not have a Stripe account, and you need to create a new Stripe Connect account for the user.

If you collect bank account information in the client, create a Stripe bank account token so that you can securely pass it to the Sharetribe backend.

If you collect other information in the client, such as account type (individual vs business) or whether the user has accepted Stripe's Connected Account Agreement, create a Stripe account token to pass that information to the Sharetribe backend.

With the Sharetribe Marketplace API, create a Stripe account and pass any tokens you created in the previous steps to the endpoint. The only mandatory parameter to create a Stripe Connect account through the Marketplace API is the country of the account, and it cannot be modified after the account has been created.

In addition to the country information, we recommend passing the requestedCapabilities parameter – the required capabilities for payments to work in Sharetribe are card_payments and transfers, so you will need to define these for the account for it to work with the Sharetribe Stripe integration. There are also other optional parameters that you can collect in your application and pass to the endpoint. If you don't pass these details, the necessary information will be collected in the Stripe Connect Onboarding flow.

The account data is returned after each create and update Stripe Account API call, so there is no need for separate fetch API call in these cases.

Handling verification status – Stripe Account Links

After the Connect account exists, the user needs to complete the onboarding. The user can also update the information related to their Stripe Connect account by refilling the Stripe Connect Onboarding flow. This might be necessary if there are new requirements in the user's existing account, or if they want to for example update their contact information.

Stripe Account Links are a mechanism for enabling your providers to access Stripe Connect Onboarding UI. You need to create an account link and provide the return URLs for success and failure cases. The response value is a URL where you can then redirect the provider to complete their Stripe Connect Onboarding. Do note that the Account Link has an expiration time, so you should fetch the link only when the user indicates they want to fill out the details.

When creating the account link, you need to specify the type of the account link. You can also pass an optional collectionOptions parameter to define which requirements you want to collect at that point. You can determine that you want your providers to fill out

  • only the information that is currently required for this account (fields: currently_due)
  • or also information that might become required for this account later if it reaches certain thresholds (fields: eventually_due)
  • and optionally information that is not yet required for any accounts, but will become required in the future (future_requirements: include)

See the available values for these options in Stripe's own documentation:

If the user returns to the success URL, it is still a good idea to check the status of the Stripe Account again. Returning to success URL does not automatically mean that the account has all the required information.

Stripe Connect Account and Onboarding in Sharetribe Web Template

The Sharetribe Web Template uses the Stripe Connect Onboarding flow by default. You can find the practical details in our help center:

On the code level, the Stripe Connect Account creation and Connect Onboarding is mainly handled in the following files:

Using custom flow for Stripe provider onboarding

It's also possible to implement the onboarding flow in your own application, if using Stripe Connect Onboarding is not an option. This way the user will stay in your application throughout the whole onboarding. The downside with this approach is that you are responsible for collecting all the required information and keeping the UI up-to-date also with the possible future changes. In general, we strongly recommend that you always use Stripe Connect Onboarding to onboard your providers, regardless of your front-end application.

In our older legacy templates, Stripe onboarding was implemented with a custom flow. There are some now deprecated components you can use as a starting point if you want to implement your own flow. You should keep in mind that these components will not be updated by our team since Sharetribe Web Template uses Connect Onboarding by default.

You can find the deprecated files still from v.3.7.0

Stripe for customers: saved payment methods

Providers always need a Stripe Connect account to receive a payout from a transaction. For a customer, you can make a payment either with a Stripe Customer or without one.

When you make a payment without a Stripe Customer, you create the PaymentIntent in the Sharetribe backend transaction process without passing payment method information to the transition. In that situation, you then need to attach the payment method to the PaymentIntent by making an API call to Stripe directly.

If you want to create a Stripe Customer and save the payment card as you make the payment, you need to create the payment intent with a setupPaymentMethodForSaving: true parameter. This sets up the PaymentIntent so that its PaymentMethod can later be attached to a Stripe Customer.

In this flow, you

  1. Create the PaymentIntent as a part of the transaction process
  2. Pass the card information to Stripe API when you confirm the PaymentIntent
  3. Use the Sharetribe API to create the Stripe Customer and pass the PaymentIntent's paymentMethodId as a parameter.

You can also create a Stripe Customer without handling a payment at the same time. In that case, you need to create a Stripe Setup Intent with the Sharetribe API, and then use the setup intent to call Stripe handleCardSetup.

Read more:

Changing a marketplace's Stripe platform account

Marketplaces sometimes need to change their Stripe platform account for one reason or another. Since Stripe Connect accounts and Stripe Customers are both associated with your Stripe platform account, it is not possible to change your Stripe keys if Connect accounts or Customers exist on your marketplace. You can reach out to Sharetribe support, and we can help you clear the Stripe Connect accounts and Customers from your marketplace.

In practice, removing all Stripe Connect accounts and Stripe Customers means that all payout details (bank accounts) are lost from the marketplace users, and all providers will need to complete Stripe onboarding again before other users can start transactions against their listings. In addition, existing transactions that have an upcoming Stripe related action are not able to move forward. This means that if you need to change the Stripe keys for your Live marketplace, you will need to either cancel in Console all ongoing transactions that have upcoming Stripe actions, and then manage the necessary payouts and refunds manually on your old Stripe platform for transactions that cannot be canceled.

Can't find what you're looking for?

Reach out to our support team by email, or consult the Sharetribe Developer Community at Sharetribe Developers Slack Channel. You can also contact our support team through the chat widget in Console.