Building a Store Builder

This guide is an in-depth walkthrough to creating an e-commerce website builder using Connect. If you need help after reading this, check out our answers to common questions or chat live with other developers in #stripe on freenode.

Of the many hurdles to e-commerce, just being able to create—or afford the creation of—a website is perhaps the biggest. For those without development skills or the money to hire a programmer, obtaining an online presence is no small endeavor. Addressing that need are many sites that provide website building and hosting, often with an e-commerce component. Thanks to Connect, your service can easily provide core e-commerce capability to others.

A store builder can be implemented with different approaches, but the most important decision is whether to use standalone or Managed Accounts. While Stripe supports fully managing connected accounts, the easiest way to get started implementing this model is to have your users create and manage their own Stripe accounts. By doing so, they’ll be be responsible for their own reporting, chargeback handling, identity verification, and so forth.

Let’s look at how you’d implement this in detail. For the purpose of this recipe, let’s assume your users will:

  • Be able to log in to their Stripe account and view their Dashboard.
  • Each have their own independent shop, including their own checkout flows.
  • Be responsible for their own Stripe fees and chargebacks.

Getting prepared

The first thing you need to do is register your platform with Stripe. Next, create two pages on your website:

  • A start page that begins the connection process (i.e., where the user goes to connect to your site).
  • A destination page to which the user will be redirected after connecting their Stripe account.

This latter page is the redirect_uri value, identified in your platform’s settings.

You should also indicate to the user what you’re responsible for and what they’ll be expected to do. It’s particularly important to communicate:

  • That they’ll need to create and maintain their Stripe account.
  • That they’ll need to handle chargebacks and all customer service issues.
  • Who is responsible for paying the Stripe fees.
  • What, if any, fees the platform charges.

This last item is an oft-overlooked step, or just poorly communicated, and leads to rather unhappy users.

Connecting accounts

This scenario uses the OAuth flow to connect to a standalone Stripe account (that may or may not already exist). This option is quick to set up, as Stripe handles much of the user experience for you: your user will be redirected to Stripe, prompted to create or connect an existing Stripe account, and then returned to your site.

Connect supports connections under two different scopes: read_only and read_write. You’ll want to request read_write scope, in order to perform charges on behalf of the connected user.

At the end of the OAuth workflow, you’ll be provided with authorization credentials for the connected account:

{
  ...
  "stripe_publishable_key": "pk_live_h9xguYGf2GcfytemKs5tHrtg",
  "access_token": "sk_live_AxSI9q6ieYWjGIeRbURf6EG0",
  "stripe_user_id": "acct_ikFQS8IjcWGOf2",
  ...
}

You’ll want to store the stripe_user_id, as this is used to identify the account when making API requests. The stripe_publishable_key will be necessary for requesting tokens (see below).

Again, you can use this flow whether or not your user already has a Stripe account. If they don’t, they’ll be prompted by Stripe to create one (and agree to our Services Agreement). Alternatively, if you know your user doesn’t have a Stripe account and you want to start that process for them, you can create a deferred account to get them going immediately. All Stripe needs is a country and an email address, and we’ll email them for the remaining details later.

With the Stripe account connected, you can begin processing charges on their behalf.

Requesting tokens

For both better security and easier integration, Stripe was designed so that a customer’s payment details—most notably the credit card number, expiration date, and CVC—never touch your server, which also limits your PCI compliance burden. Instead, using Stripe.js or Checkout, the customer’s payment details are sent directly from the customer’s browser to Stripe via an iframe, bypassing your server entirely. Stripe returns to the browser a representative token, assuming the payment method appears to be valid. This token is then submitted to your server, where it can be used to process a charge.

Even though you’re enabling e-commerce for others, your site won’t have to spend a fortune to remain PCI compliant!

When performing charges on behalf of a connected account, with the connected account covering the Stripe fees, it’s important that you use the connected user’s publishable API key to create the token. If you don’t, you’ll get an error when you attempt to use that token in the charge request.

Charging through the connected account

In this scenario, with the connected account being responsible for the fees, refunds, and chargebacks (and, implicitly, the customer service duties), you’ll want to process the charges through the connected account. With Connect, this is easy to do.

With the token in hand, perform a create charge request while authenticated as the connected account.

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -H "Stripe-Account: acct_ikFQS8IjcWGOf2" \
   -d amount=1000 \
   -d currency=usd \
   -d source="{TOKEN}"

The payment itself appears as a charge in the connected account, and the connected account pays the Stripe fees. The funds then become available for transfer to a bank account on the normal rolling basis. With a standalone account, the connected user controls the bank account transfer from there (e.g., manual transfers, automatic on a schedule, or automatic as funds become available). They can log into their Dashboard to check the status of transfers, and they can email Stripe with any questions or concerns they may have.

Creating subscriptions

This e-commerce model can be expanded to support subscriptions, as well. To do so, plans need to be defined within the connected account. This is something you could do, or your connected user could do (as they control the Stripe account). Let’s assume there’s already a plan in the connected account with an ID of gold_monthly, whether you created it or your user did.

A subscription is a combination of a customer and a plan. If it’s a paid subscription, a payment method is required as well. To put all that together, the token would again be created using the connected account’s publishable key. Then, instead of creating a charge on the connected account, you’d create a customer:

curl https://api.stripe.com/v1/customers \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -H "Stripe-Account: acct_ikFQS8IjcWGOf2" \
   -d plan=gold_monthly \
   -d source="{TOKEN}"

The customer will be created in the connected account, with a stored card, and subscribed to the gold_monthly plan.

If you’re using subscriptions, you’ll probably want to also define a webhook so your platform is notified when invoices are generated and paid.

Charging for your service

With everything working properly, you have happy users, which is great. But presumably you’re not providing your service pro bono! There are two ways you can charge for your service.

The first option is to charge your users through your own Stripe account. After your customers connect their Stripe accounts, ask for their payment details and then create a subscription for them in your Stripe account. Store the created customer ID with the associated Stripe ID, and you’ll easily be able to see which of your users are paid and active, and which are not. This approach would be perfect for flat-fee arrangements (e.g., $10/month for site creation and hosting; $20/month for creation, hosting, and e-commerce).

Alternatively, via the application_fee parameter, you can take a part of each charge processed. Here, the customer is still being charged $10, and your user is still paying the Stripe fee, but you’re also receiving a $2.00 application fee:

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -H "Stripe-Account: acct_ikFQS8IjcWGOf2" \
   -d amount=1000 \
   -d currency=usd \
   -d source="{TOKEN}" \
   -d application_fee=200

On subscriptions, you can take an application fee percent—a percent of each total charge—instead of a flat amount.

Other recipes

Looking to build another type of platform? Check out these other recipes.