Stripe Connect & Rails — Part 1

This is Part 3 of my series on integrating Stripe Connect into a ruby on rails application

Read part 2 here

Read part 3 here

I’ve been working on an application recently that needed to present users with a marketplace where they can act as both buyers and sellers of goods/services. The most daunting challenge for me was immediately how we’re going to handle payments, booking fees, discounts, and whatever else might be thrown at us when handling money.

More importantly, how do we roll this all up into a nice central system? To the rescue came Stripe’s connect platform. An all-in-one solution to handling marketplace style payments that flow from user to user, via a platform.

So I thought I’d do a bit of writing and try to explain how all the concepts and features could fit together in series of blogs. In this first post, I’ll dive into the concepts and requirements you’ll need to familiarise yourself with. Then from part two onwards, we’ll build a rails application that puts it all into practice!

If you’d like to just jump into the tutorial head over to part 2!

Shoutout to the community!

I honestly cannot praise the Stripe developer community, and the impeccable Stripe documentation enough. Get involved and you’ll find all the help you need.

So let’s start, the requirements/features

1. Users should be able to verify their credit cards, and we should be able to identify them as unique customers from within Stripe
2. Hosts should be able to register their businesses in order to receive payments or process refunds
3. The platform should be able to charge a fee on each booking.
4. The platform should allow us to credit users on the platform

Setting up the platform

So let’s get started and create a Stripe account. Once that’s good to go navigate to your settings, and head over to the Connect tab.

PEW

The first thing you’ll need to understand is the difference between what Stripe refers to as Standalone & Managed Accounts:

A standalone Stripe account is a normal Stripe account that is controlled by the account holder: your platform’s user.

By contrast, managed accounts are fully controlled by the platform.

After evaluating my needs, I decided to set Hosts up as standalone accounts.

You’re probably most interested in Standalone Accounts if you:

• Want to get started as quickly as possible. (Platforms that don’t manage accounts are much easier to set up and require far less custom code.)
• Have users who are already existing Stripe users.
• Live in a country that doesn’t support managed accounts yet.

Standalone Accounts

Basically these are the account types that your Hosts will need to use to receive payments. And for this Stripe recommends using their oAuth flow. Just so we’re clear on what this might look like:

1. As an already signed up user on our app, I want to connect my business to Stripe by either creating a new stripe account, or attaching an existing one.
2. Starting on a page at your site, the Host will click a button/link/something that will take them through to Stripe, passing along your platform’s client_id.
3. On Stripe’s website, the user will be prompted to connect or create their businesses Stripe account.
4. The user will then be redirected back to your site (your redirect_uri), passing along either an authorization code or an error (if the connection request was denied).
5. Your application then consumes this OAuth token information, and adds the needed data to their record.
6. Subsequent API requests can be made on behalf of the connected account using the previously mentioned credentials from the token.

At the end of the day you should have a publishable_key associated with that host, which is it’s reference in Stripe to that users business.

In Summary

• we’ll have a unique ID for our platform (STRIPE_CONNECT_CLIENT_ID)
• our users (sellers) will have a unique ID connected to the stripe account of their respective business (UID)
• Our sellers will have a key attached to our Stripe account, that in combination with their UID, enables API requests (PUBLISHABLE_KEY)
• our users (buyers) will have a customer ID (that references their saved credit card details internally), via a customer object that stripe gives us (we have indirect access to their credit cards, BUT WE DON’T STORE THEM, STRIPE DOES). (STRIPE_CUSTOMER_ID)
• You’ll also have regularAPI keys for your application (STRIPE_PRIVATE_KEY)

Let’s get started

Adding Users

So we need to get our user’s Credit Cards into the stripe system as customers. So have a look at stripe.js, which has awesome documentation on grabbing user data out of a form, validating it via Stripe, and if successful, returning a reference to that credit card, which we can then use to create a customer object within Stripe.

But it’ll basically return a temporary token that looks somewhat like this:

“tok_0XXXXXXX0XXXxxxxXXxX0xX0”

We can use this token to create a single once-off charge, or alternatively we can consume this token to create our users in stripe as customers. Once this is done Stripe will return a stripe_customer_id which we can use in the future for far more than just a charge.

It’ll look something like this:

stripe_customer_id: “cus_X1XXXxXxXxX1Xx”

Keep in mind that this is not a credit card, this is a reference to a customer object, in Stripe’s custody, that in combination with our platform ID, we can use to request that a charge be made by Stripe.

Adding Hosts

For this I’d recommend making use of the omniauth-stripe-connect gem. If you use Devise for your authentication needs, you’ll have found the perfect match.

Now this portion will require you to head over to the settings within the Connect tab in Stripe, and to set a redirect_uri for your environments. Basically once a user hits the omniauth process, and successfully registers their business, Stripe will use this URI to pass back the merchant object, which contains a whole host of save-able account details.

The most important part here is the Merchants UID, because it is critical to creating charges, but trust me, you can pull a lot of information out of the returned object. Check out the API reference.

Creating a charge

In essence we now have everything we need to make a charge.

• A customer to charge
• A merchant to credit
• A reference to the marketplace or platform (which is dealt with separately, but important if you decide to charge a platform fee)

But what else can we string into a charge? What options do we have? The Stripe API gives you plenty of options.

But here’s an example of what that could look like, with a bit of light error handling:

So hopefully this post has clarified some of the concepts you’ll need to become familiar with while implementing the Connect Platform. In Part 2 we’ll create a little application for those of you who prefer hands on learning ;)

Thanks for reading and let me know if you spot any mistakes or oddities.