Set up and use Stripe

1. Create and confirm your free Stripe account

Register to Stripe. After filling the form you will be asked the question "How do you want to get started with Stripe?". You can click "Skip for now" link at the bottom of the page to get directly to Stripe dashboard. Remember to confirm your email address after the registration.

As you will receive money from your users via your Stripe account, you have to provide some details such as your address and your bank account. In the Stripe dashboard, click the "Activate your account" link in the top bar and fill in all the fields according to the instructions. The activation form varies based on your country.

Once activated, your dashboard should display the message "Your account is now active":

Note: Stripe requires US accounts to add their EIN for their accounts to be fully activated. If you don't have an EIN, it's okay to use your personal name and SSN. Read more about signing up without a tax ID or employer ID number here.

2. Enable Stripe Connect in your platform

Sharetribe uses the Stripe Connect features with custom accounts.

Note! Stripe might need to review your platform account before you get access.
Check this article to learn how to apply for Stripe Connect review.

If you're in any another country, follow these instructions to enable Stripe Connect:

• Click the Connect menu item, and the Get started button.

• This will open a popup. Click the Continue button.

3. Account types and connect onboarding settings

To enable Stripe Connect Onboarding, you need to navigate to Connect settings page in your Stripe Dashboard. For the Connect onboarding to work, you need to provide name, color, and icon for your marketplace.

Great! You now have to get your API keys and input them into your marketplace.

4. Get your API keys from Stripe and add them to your Sharetribe marketplace

• Click the Developers left menu item and go to Developers → API Keys.
• In the section "Standard API keys" you will see two keys: publishable key and secret key. The publishable key (with prefix pk) is one used in frontend application (e.g. Flex Template for Web) and secret key (with prefix sk) is the one you need to add to Console. If you want to use test data make sure the value of the key is eg. pk_test<somethinghere> and not pk_live<somethinghere>

Note: If you want to use test data in development make sure that "View test data" toggle is on. This way no real money will be used. In the live environment, make sure that the toggle is off.

5. Add your Stripe secret API key to Console

• Log in to Console and go to Build → Payments
• In the section Stripe configuration paste your secret key to "Stripe secret key" field and save the changes.

6. Add you Stripe publishable key to your client application

In your client application, you need to use Stripe publishable key, when you create accountTokens or call other Stripe API endpoints. If you are using Flex Template for Web, calls to Stripe API are already there, but you need to add the Stripe publishable key to your .env file. You can do this by running yarn run config or editing the file directly in a text editor.

Read more about configurations in FTW from Getting started with FTW

7. Test the Stripe account in Flex Template for Web

If you are using Flex Template for Web (FTW) here is some instructions how you can test you Stripe account.

Note: When testing Stripe, make sure you are using the test API keys. To ensure that make sure the keys have prefix sk_test and pk_test. When checking the Stripe dashboard, make sure "View test data" toggle is on!

Test adding payout details

Every provider needs to add payout details to their account before they are able to publish listings. Stripe provides test values for identity verification and bank numbers. In FTW you can add payout details for the account in Account Settings → Payments. After filling the form you should see a new account when you go to Stripe Dashboard and to Connect → Accounts.

Note: After payout details are saved they can not be edited directly from FTW so you might need to create multiple accounts for testing purposes.

The form of the bank number and other required information depends on which country you have chosen. For example, most of the countries in Europe use IBAN form which is asked in one field. However, for example in Hong Kong clearing code, branch code and bank account number are all needed.

It's also good to know that in FTW these are all separate fields but in Stripe clearing code and branch code are mapped together as routing number.

With company accounts, Stripe might require information of every person that owns at least 25% of the company or exercise significant control over your company. This requirement is country specific. For more information, see Stripe support.

Note: if a company/provider doesn't include enough owners to cover most of the shares, you might need to manually state that there are no more persons that own 25% or more.

Test checkout

Stripe provides various test card numbers for testing the checkout. There are also test numbers for specific responses and errors so e.g. testing different error scenarios is possible.

8. Advanced: Adding new country to supported Stripe countries

By default FTW already supports most of the countries that are available when using Stripe custom accounts. If you are not sure if your country is already supported, please contact to Stripe support before proceeding.

1. Add a new country to stripe-config.js file (use other country configurations as an example). See Stripe documentation for minimum verification requirements and bank account format.

2. Add new microcopy keys to the microcopy file you are using (e.g. translations/en.json). Add at least PayoutDetailsForm.countryNames.COUNTRYCODE and PayoutDetailsForm.companyTaxIdLabel.COUNTRYCODE keys but there might be also other keys needed.

3. If you add new fields or you want to edit the existing ones, see forms/PayoutDetailsForm and the subcomponents in the folder. E.g. to enable personal ID number field you need to add the new country in forms/PayoutDetailsForm/PayoutDetailsPersonalDetails.js file where showing the ID number field is handled.

Information

The current FTW templates do not support Brazil (BR), India (IN) and Hungary (HU), even though all three countries are mentioned as available Stripe countries in Stripe's documentation. If you want to support one of these three regions, you will need to do a fair amount of customization on top of the default Flex setup.

• The Flex transaction engine uses manual payouts, which are not supported for Brazil and India.
• India has restrictions on cross-border payments.
• Stripe treats the Hungarian currency HUF as a zero-decimal currency for payouts. This means that even though the Flex engine can create charges in two-decimal amounts (e.g. HUF 20.38), payouts can only be created in integer amounts evenly divisible by 100 (e.g. HUF 20.00). Additionally, if Stripe needs to do currency conversions from another currency to HUF, the resulting amount may have decimals which can cause the payout to fail.