Stripe Marketplace Express Plugin

Demo to preview the settings

Introduction

Creating a web app pretty much always requires an integration of a payment system. These systems might be rather simple or very complex, depending on your type of app. Stripe is one of the best software platforms for that, whether you’re creating a subscription service, an on-demand marketplace, an e-commerce store, or a crowdfunding platform. Stripe’s meticulously designed APIs and unmatched functionality help you create the best possible product for your users.
Right now the solutions regarding Stripe API that are offered for Bubble users are very limited and require additional development for the functionalities you want your platform to have. Not to mention that the existing solutions are not very well optimized when it comes to developing a more complex service.
This is where we decided to create a plugin that offers pretty much all the tools for setting up a medium to high complexity payment system with optimization and high performance in mind. You won't need to install multiple plugins or developing additional basic functionalities that other plugins are lacking. Also, we minimized the number of action calls to the minimum for achieving a faster performance and a more clean workflow. And if you still don't find what you need don't worry we are constantly updating the plugin with new functionalities.
Stripe Marketplace is SCA -Ready plugin that comes with the SCA element token to authenticate, the online payments flow requires the use of 3D Secure for card payments.

Prerequisites

You must have an account with Stripe to interact with the Stripe API. Create your development account at https://dashboard.stripe.com/

Tutorial

Setup requirements

First, you will need to go to stripe.com and register an account.
After you have successfully verified your email address and activated your account, under the Activate your account tab, you can start setting up stripe features you need.
Image without caption
After that, you will need to set up the keys for the plugin. To find the keys go to your stripe dashboard and find API keys under the Developers tab. You need to copy the Publishable and Secret keys both for live and development versions.
Make sure when adding the secret keys to the plugin to add text 'Bearer' before the key (do this just for the secret key) to use it in plugin settings.
Image without caption
Also, make sure you have enabled stripe Connect (Build a platform or marketplace).
Image without caption
Once you've got the keys from Stripe dashboard, for both Live and Development versions place them in Plugins Settings Tab for the Stripe Marketplace Plugin, which should look like this:
Image without caption

Plugin calls & elements

Elements

This plugin has 2 elements:
  • One is called Stripe Marketplace Token. It is used for creating a bank account or card token.
Image without caption
Note: You just have to place the Stripe Marketplace Token on the page and call it from within the workflow when you are trying to convert a form into the token.
Using the Stripe Marketplace Token you can create:
  • a credit card token
  • a bank account token
  • PII token
Image without caption
Note: To use the token you will have to add another workflow that will run when the token is created.
Create ID Number Token Use Create ID Number Token action to convert personally identifiable information (PII) into a single-use token for account identity verification.
Fields:
Title
Description
Type
Personal ID number
The personal ID number. Example: 123131185
text
There you can use the token to create a customer and assign him a credit card, create a stripe seller, or make a payment using the token you have created.
Image without caption
Also, you can add an additional workflow that will check for errors during the token creation thus giving you the option to set up a custom solution for the users.
  • Another element is called SCA. It is primarily used to meet Strong Customer Authentication requirements when setting up the payment process.
Image without caption
Note: To use the SCA actions you will need to place the SCA element on the page.
Using the SCA you can:
  • access a previously created Session which is related to pretty much all other SCA-related action calls

Stripe Marketplace Token Action Calls

All the calls that have multiple fields to be filled in were developed to contain all the necessary parameters stripe requires. Some of them might have a lot of fields but the idea is that you can choose what you want to be filled in while leaving the others blank. This way we maximized the performance of sending requests by having at maximum only 1 being sent while still giving you to option to choose what your request will contain. Also when using an action call, check the documentation for each field it has, for a better understanding of how it works.
Connect express/standard account
This call is used to create an Oauth link for users who already have a stripe account and want to connect to your platform.
It also gives the option for users to register if they don't have an account and after completing the registration to be linked to your platform. It works both for express and standard account types.
In order to fully set up the Oauth flow, you will also have to use the Complete express/standard account connection to complete the onboarding.
Complete express/standard account connection
This action call is used to complete the express/standard onboarding. After the stripe login/registration the user lands back on the platform with a URL parameter "code" of text type which you should send to stripe to complete the onboarding.
Also, you should save the resulted "stripe_user_id" to the database for future use.
Image without caption
Create a seller - Individual
So this is one of the main calls that was kept in mind during the developing of the plugin. It provides the ability to create a stripe custom account with all the necessary fields needed for it to be verified from the start, tho you have the choice of not filling in all the fields present there.
This action call should be used only when creating accounts for individuals.
Before creating a custom account you might want to create a bank account token first and use it so the created account has a bank account attached to it from the start.
💡
Also, some of the fields are region related (should be filled in for US only accounts) so check each field's documentation.
Added the option to submit a personal ID number in the new PII token field. You can either create a token, using the Create a number ID token action call and submit the token ID or simply submit the personal ID without tokenizing it.
Update a seller - Individual
It's almost the same as the Create a seller - Individual the difference being that it is used for updating an account.
Also, it has one extra field which is required and that is the ID of the account you want to update. Use this action call for setting up an account verification flow, so users could create an account but if some of their submitted info failed stripe verification they could resubmit it again.
Added the option to submit a personal ID number in the new PII token field. You can either create a token, using the Create a number ID token action call and submit the token ID or simply submit the personal ID without tokenizing it.
Create a seller - Company
This action call is also used for creating a stripe custom account but it should be used only when creating accounts for companies.
Also it is required you use the Create a person action call so you can add executives, representatives and owners to the created account.
Update a seller - Company
It's almost the same as the Create a seller - Company the difference being that it is used for updating a company account.
Also it has one extra field which is required and that is the ID of the company account you want to update. Use this action call for setting up a company account verification flow, so users could create a company account but if some of their submitted info failed stripe verification they could resubmit it again.
Create a person
As described above this action call is used to add executives, representatives and owners to a custom account that is of a company type.
Added the option to submit a personal ID number in the new PII token field. You can either create a token, using the Create a number ID token action call and submit the token ID or simply submit the personal ID without tokenizing it.
Update a person
This action call is used to update details of a person linked to a specific company. You need to provide the ID of the company and of the person that must be linked to the specified company.
Added the option to submit a personal ID number in the new PII token field. You can either create a token, using the Create a number ID token action call and submit the token ID or simply submit the personal ID without tokenizing it.
Delete a seller
This action call gives the option for the admin to delete users that are connected to the platform. Tho it should be used only when deleting testing sellers and not the real ones.
Create a file
Using this action call you can encrypt a government issued identification document of a user to be sent with the Create a seller/Update a seller action call for verification.
You will need to use this call two times to create two versions of the document, one from the front and one from behind and use the resulted ID in the Create a seller/Update a seller action call.
Create a customer
This action creates a customer on the platform. Before creating the customer you should create a card token to be used in this action call, that will become the customer's default source, tho you can do it later using the Update a customer call.
You need to store the ID of the added card source for later use.
Update a customer
Update a customer action call gives the option to change the details of a customer. It's main use would be to change the default source of a customer (which means that a card from a user that has multiple cards will be selected to become his new default source).
Create a card
This action call is used to add a card to a customer. The added card will just be added to the list of cards the customer has without replacing others (it will become the default source card only if the customer has no cards). You need to store the ID of the created card for later use.
Delete a card
Delete a card - action call is used to delete a card from a customer. If you delete a card that is currently the default source, then the most recently added source will become the new default.
Delete a bank account
Using this action call you can delete destination bank accounts from a custom account. Make sure to add another bank account using the Update a seller call.
Create a charge
This action call is used for charging customers as the platform. It means that you as the platform owner will charge other people and the money will be sent to your account.
Create a refund
Create a refund action is used to refund a payment either to a seller by passing the "Stripe-account" parameter or to a platform if leaving that parameter empty. Also you may want to pass the "amount" of a value of the total payment amount minus stripe's fee which you will have to calculate.
Seller charge a customer
This action call gives the option for stripe accounts connected to your platform to charge customers while you as the platform owner will receive a fee from that transaction. The source for this action call needs to be the resulted ID from the Link a customer to seller call.
Link a customer to a seller
As described above this action call is used when a connected custom account needs to charge a customer. If the customer doesn't have a card source you should add one first and then use its ID in this action call. Also, this call gives the option for customers to use a card from their list of saved cards. To retrieve the list of a customer's cards uses the Retrieve a customer action call.
Retrieve a customer
Retrieves the details of an existing customer. You need only supply the unique customer identifier that was returned upon customer creation.
Retrieve a seller
Retrieves the details of an account. The type of the stripe account doesn't matter you can also get information about standard or express accounts that are connected to your platform.
Retrieve all charges
Returns a list of charges of a connected account. The charges are returned in sorted order, with the most recent charges appearing first.
Image without caption
Retrieve all payouts
Returns a list of existing payouts sent to third-party bank accounts or that Stripe has sent to a connected account. The payouts are returned in sorted order, with the most recently created payouts appearing first.
Image without caption
Retrieve a seller's balance
This action call is used to retrieve a user's balance if the "Stripe-account" field is filled in. Otherwise, it will retrieve the current balance of the platform.
Create a subscription
Creates a new subscription for an existing customer. Before subscribing customers to plans make sure you have created some plans in your Stripe dashboard and use the ID of the plan you want the customer to subscribe to. To create a plan you need to go to Stripe dashboard -> Billing -> Products and create a product to which you can then attach a plan.
When creating a subscription make sure to store the resulted Subscription ID, Subscription item ID for later use.
Update a subscription
Updates an existing subscription to match the specified parameters. This action call has multiple uses depending on what fields you fill in.
Update a subscription action call gives you the option to:
  • Change the plan /* If you want to replace the current plan of a customer with another you will have to fill in these fields: Subscription ID, Subscription item ID, and the Plan ID of the new plan you want to subscribe a customer to.*/
  • Add additional plans /* A customer can be subscribed to multiple plans. To add an additional plan to a customer you will need to fill in these fields: Subscription ID, and the Plan ID. This will create another Subscription item ID so make sure you store it somewhere for later use.*/
  • Change the billing source /* If you want to change the default billing source for a customer's subscription you will need to fill in the Card ID field with an existing card ID from that customer.
  • Cancel the subscription /* To cancel an existing subscription at the end of the current billing period just fill in the Subscription ID and Cancel at the period end fields.*/
Image without caption
Create dashboard link (for express accounts only!)
Creates a link for a connected account of express type to access their stripe dashboard. Here users can update their accounts, view payments, and payouts.
Retrieve all invoices (New Call)
This action call returns the existing invoices on the platform or of a specific customer or subscription. To retrieve invoices of a specific customer just fill in the customer field, to retrieve invoices related to a specific subscription just fill in the subscription field, and to retrieve all the invoices on the platform just leave the mentioned fields above empty.
The other fields are used for sorting and pagination.

SCA Action Calls

Create a session (SCA related)
This action call is used to create a Checkout Session that represents your customer's session as they pay for one-time purchases or subscriptions. It should be used to start the process of collecting card details and creating a customer, to pay for an item or a subscription.
Specifically, there are 3 modes that can be used: setup, payment, and subscription. Right now the SCA part of the plugin is built around setup and payment modes. The App fee parameter is no longer obligatory when sending the Seller ID in the request.
Go to checkout (SCA related)
Use this to redirect a user to the checkout page using a previously created session. For doing this the element SCA should be on the page.
Clone a customer's payment method (SCA related)
It is used for creating a payment source for a transaction between a connected account (seller) and the platform's customer.
Attach a payment method to a customer (SCA related)
Used to attach a payment method to a customer so it could be saved for later uses. To get the payment method ID, first, a session should be created, and right after it saves the Intent ID it returns. After the user will successfully exit the session, the action call Retrieve Setup Intent should be used to get the payment method ID which then can be attached to a customer.
Detach a payment method from a customer (SCA related)
Used to detach a payment method from a customer.
Create a payment intent (SCA related)
This action call creates a payment intent. Use this when you want to make a payment without the user entering the checkout form (Create a session action call).
Confirm a payment intent (SCA related)
Use this action to confirm a payment intent. You may set the payment intenedt to be confirmed later when using Create a payment intent action call with the parameter "confirm" set to "true".
Capture a payment intent (SCA related)
Use this action to confirm a payment intent. You may set the payment intented to be confirmed later when using Create a payment intent action call or Create a session call with parameter "capture" set to "manual". Added the option to set the App fee when capturing a payment intent.
Retrieve a session (SCA related)
This action call is used to get the details of a session that has previously been created.
Retrieve setup intent (SCA related)
This action call is used to get the details of a setup intent that has previously been created. For example, you can get the payment method ID to attach it to a customer.
Retrieve a customer's payment methods (SCA related)
Retrieves all the payment methods a customer has.
Retrieve all payment intents (SCA related)
Returns a list of payment intents of a connected account or of the platform.
Image without caption
Create a billing portal session (SCA related)
This action call is similar to "Create a session" taking place on the same checkout page but it is different by providing the customer a different set of options which are mostly related to plans. For example, the user can upgrade or cancel his subscription plan there.

Data Calls

Retrieve a customer's cards: This call is used to list all the cards of a known stripe customer. Retrieve a customer's payment methods: This call is used to list all the payment methods of a known stripe customer.

Changelogs

Update 30/10/20 -

  • Added the retrieve of invoices functionality, improved capture of payment intents, and creation of a session action calls

Update 09/02/21-

  • Improvement calls with PII Token

Update 06/04/21 -

  • Added separate calls for retrieving customers’ cards & payment methods.

Update 04/10/21 - Version: 1.42.0.

  • Added the option to use coupons when creating a session in payment mode & other minor fixes

Update 28/07/22 - Version: 1.47.0.

  • "Fixed Error event"

Update 13.11.22 - Version: 1.55.0.

  • Fixed the "Create a transfer" action

Update 19.12.22 - Version: 1.56.0.

  • Added "Creating destination charges" action

Update 03.01.23 - Version: 1.57.0

  • Fixed "Creating destination charges" action

Update 10.01.23 - Version: 1.58.0

  • Fixed "Creating destination charges", and "Go to checkout" actions

Update 20.01.23 - Version: 1.59.0

  • Fixed "Connect express/standard account" action

Update 23.01.23 - Version: 1.61.0

  • Fixed "Creating destination charges" action

Update 23.01.23 - Version: 1.62.0

  • minor edits

Update 1.02.23 - Version: 1.63.0

  • minor fixes