Set up and use Stripe
To enable payments and receive commissions in your marketplace, you need a free Stripe account. This guide will help you in creating a Stripe account and adding Stripe API keys to Console and Sharetribe Web Template.
Table of Contents
- 1. Create and confirm your free Stripe account
- 2. Enable Stripe Connect in your platform
- 3. Account types and connect onboarding settings
- 4. Get your API keys from Stripe and add them to your Sharetribe marketplace
- 5. Add your Stripe secret API key to Console
- 6. Add you Stripe publishable key to your client application
- 7. Test the Stripe account in Sharetribe Web Template
- Test adding payout details
- Test checkout
- 8. Advanced: Adding new country to supported Stripe countries
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":
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.
Sharetribe uses the Stripe Connect features with custom accounts.
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.
Stripe Connect Onboarding,
you need to navigate to
Connect settings page
in your Stripe Dashboard. For the Connect onboarding to work, you need
icon for your marketplace.
Great! You now have to get your API keys and input them into your 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. Sharetribe Web Template) 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>
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.
- 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.
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 Sharetribe Web Template, 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 the template in Getting started with Sharetribe Web Template
If you are using the Sharetribe Web Template, refer to these instructions on testing your Stripe account.
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!
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 Sharetribe Web Template, 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.
After payout details are saved, they can not be edited directly in the template, 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 is also good to know that in the template, 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.
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.
By default, the template 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.
Add new marketplace text keys to the marketplace text file you are using (e.g.
translations/en.json). Add at least
PayoutDetailsForm.companyTaxIdLabel.COUNTRYCODEkeys but there might be also other keys needed.
If you add new fields or you want to edit the existing ones, see
forms/PayoutDetailsFormand the subcomponents in the folder. E.g. to enable personal ID number field you need to add the new country in
forms/PayoutDetailsForm/PayoutDetailsPersonalDetails.jsfile where showing the ID number field is handled.
The Sharetribe Web Template does 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 Sharetribe setup.
- The Sharetribe 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 Sharetribe 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.