Integrating Stripe sdk with React Native - part II - Multiparty payments
As I discussed integrating stripe sdk with react native in one of my previous articles, this time I decided to write on how to do multiparty payments using stripe. The knowledge from the previous article is useful here since we use the stripe payment sheet here also to complete the payment by entering card details.
What are multiparty payments ?
Stripe multiparty payment is used to route payments between multiple parties. For example consider a online hotel booking system where hotel owners can come into the platform and register while people can book hotels through the platform. Once a customer books a hotel and makes the payment through the platform,the payment should split and a part of the payment should go to hotel and another part(may be a percentage from the payment) to the platform (service provider). To route this kind of payments stripe has came up with stripe connect which we are going to integrate now with a react native application using node.js backend.
Stripe connect
To split the paymet and debit relavant amount we need to onboard users to stripe with their business and bank details. Stripe connect is used to handle multiparty payments and there are 3 types of connected accounts that we can create while onboarding users to stripe,
Standard account: A conventional Stripe account controlled directly by the account holder (that is, your platform’s user)and has a relationship with Stripe, is able to log into the Stripe Dashboard, can process charges on their own, and can disconnect their account from your platform. Once the user is onboarded, user can login to their account using their credentials.
Express account: After onboarded with this type of connected account the platform can manage payout schedules, customize the flow of funds, and control branding. An express dashboard is also available for express accounts, but you need to get a url from platform to view this.
Custom account: This account is almost completely invisible to the account holder and Stripe has no direct contact with them. Custom accounts require the most integration effort and are suitable for platforms who want to control the entire user experience.
The platform’s stripe account can see all these accounts under connected accounts of platform.
To start the coding you need to setup a node backend and react native application with stripe sdk integrated. For that kindly follow my previous article integrating stripe sdk with react native.
Account creation (onboarding users)
Following prerequisites is needed to be completed with the platform’s stripe account before creating connected accounts.
- Register your platform.
- Add business details to activate your account.
- Complete your platform profile.
- Customize brand settings. Adding a business name, icon, and brand color is required for Connect Onboarding.
I am not going to go through above prerequisites since they are pretty straightforward once you go to the relavant web pages linked above.
To get a user onboarded, we need to create an account in stripe with the type. Then with that account id created, we generate a link where the user can load into browser and enter their business and bank details.
To generate account creation link we should write rest APIs in backend and return account link to frontend.
I have written 3 APIs above which differs each other on the account type. In every API we use 2 common APIs provided by stripe namely accounts API and accountLinks API.
If you’ve already collected information for your connected accounts, you can prefill that information on the account object for the user at account creation and it won’t be collected again in the onboarding flow. Any information on the account can be prefilled, including company or individual information, external account information, and more.For more details refer accounts API.
We must save the account id in our db to make payments in future on that account.
return_url
Stripe issues a redirect to this URL when the user completes the Connect Onboarding flow. We can use a deep link here to navigate back to the app but url schemes are not working since account creation API throws error. In test mode we can use http but in live mode we must use https universal link.
refresh_url
Your user redirects to the refresh_url in these cases:
- The link expired (a few minutes went by since the link was created)
- The user already visited the link (they refreshed the page, or clicked back or forward in the browser)
- Your platform is no longer able to access the account
- The account has been rejected
Your refresh_url should trigger a method on your server to call Account Links again with the same parameters, and redirect the user to the Connect Onboarding flow to create a seamless experience.
For expres and custom accounts you need to request capabilities while creating the account.For standard accounts you will get all the capabilities automatically. The capabilities you request for a connected account determine the information you need to collect for that account.
Now you need to call above APIs from frontend(React native), get the account link and open it with phone browser to get user onboarded.
You will see a similar screen as follows once link is opened with mobile browser which starts the user onboarding flow.
Receive payments
Now to receive a payment for the connected account a user should make a payment on that account. For that we have 3 charge types.
Direct charges are recommended to use with standard accounts while other 2 charge types are recommended to use with express and custom accounts by stripe.
Create a direct charge
We have to create the payment intent in backend side with connected stripe account, amount, application fee and currency.Application fee is the amout that goes to service provider’s (platform) account.
From the frontend we should proceed the payment as we discussed in previous article.
You have to add connected account’s id in StripeProvider to perform a direct charge on that account as follows.
<StripeProvider stripeAccountId='CONNECTED_STRIPE_ACCOUNT_ID' publishableKey={publishableKey}>
Once you call initializePaymentSheet(), backend returns the client_secret to the frontend and with that we initialize payment sheet. Then to present the payment sheet to the user to enter card details call openPaymentSheet().
Direct charge flow
Note that stripe fee is deducted from connected accounts amount.
Create a destination charge
We have to create the payment intent with connected transfer data, amount, application fee and currency.
Proceeding payment with payment intent in the frontend doesn’t change.It’s similar to the direct charge implementation above.
you don’t need to add account id in StripeProvider since you can do destination charge with your platform account publishable key and secret key.
Destination charge flow
Note that stripe fee is deducted from platform account.
Create separate charges and transfers
With this you can make charges on your platform account on behalf of connected accounts, perform transfers separately, and retain funds in the process. Separate charges and transfers are recommended for Express or Custom accounts where you collect charges that can be a different amount than what’s paid out to your connected accounts. Here also we should write an API to create the payment intent with amount, currency, and transfer group.
This payment intent is returned to the frontend, and we can complete the charge as we did in above direct charge scenario. But to transfer the payments to connected accounts we must write an API.
With transfer group you can return all the transfers
associated with that transfer_group.
const transfers = await stripe.transfers.list({
transfer_group: bookingId
})
Separate charges and transfers flow
Unlike the other 2 scenarios, with separate charges you do not transfer the amount to connected accounts when you make the payment.Stripe fee also deducted from platform account. You must have positive stripe balance to do the transfers to connected accounts.
You can see all your connected accounts under connect tab of platform account. Accounts that successfully completed the onboarding flow can be seen with status “complete”.
You can click on each account and go to a detailed view.
All the payments come to the platform account or connected standard account can be seen under payments tab of relavant account.
To view payments of express accounts you can use the express dashboard or go to conneted account’s detailed view from platform account.
All the application fees that collected to the platform can be seen under “collected fees” tab.
Hit on clap, share and comment if this helped.Your feedback is appreciated. 😊