Setting up Stripe in your local environment

This is a quick guide to help you set up Stripe on your local environment. First, a short background on how our Stripe integration works.

What do we use Stripe for?

Generally speaking, we use Stripe to process online payments. For OFN and shops, it means, that we never see or store real credit card information from customers. We work with encrypted representations of the required entities to make payments happen.

How does it work?

In a nutshell, there are two different Stripe-layers between the OFN users and credit institutions/banks:

i) a global Stripe account -> This corresponds to the Stripe account which will be set up at the OFN instance level; it will process payments relevant to all shops on the instance. There is one such account per instance.

ii) a merchant/shop Stripe account -> This corresponds to the account OFN hubs and shops, which are able to receive payments from customers. There are several of such accounts per instance, one per shop.

Note: It might be possible and even helpful to do steps 10 and 11 of the following instructions after step 6, and then continue with step 7. But this is not tested.

To set up Stripe locally, you'll need to:

1. Log into https://dashboard.stripe.com/
2. Create at least two accounts, corresponding to i) and ii), mentioned above. For steps below, select the account you've designated to be your instance Stripe account (i).
3. Create/edit a local development file, something like .env.development.local. Changes on this file should not be tracked on git, it needs to be listed in .gitignore.
4. You'll need to add the keys:

Stripe Instance Keys

STRIPE_INSTANCE_PUBLISHABLE_KEY=pk_test_................ # This can be a test key or a live key

STRIPE_INSTANCE_SECRET_KEY=sk_test_.................... # This can be a test key or a live key

You can find both keys under the section API keys.

Stripe Client ID

STRIPE_CLIENT_ID=ca_.................................... # This can be a development ID or a production ID

This can be found under the section Testing Stripe Connect.

Stripe Endpoint Secret

STRIPE_ENDPOINT_SECRET=whsec_........................... # This can be a test endpoint secret

This can be found under the section Listen to Stripe events; make sure you have the Test mode enabled. If no key is listed, you may need to create one, or retrieve a test-key by clicking the button Test a Local Environment, and retrieving it from the code (displayed on the right side).

5. After saving the file, you can run your local app, as usual with:

bundle exec rails start

and log-in as super admin.

6. Visit /admin/stripe_connect_settings/edit. A green box should appear, confirming the values set up in the previous step. Activate the checkbox to enable Stripe for users, and click update.

Our Stripe-instance should now be set up. 🎉 We'll need to set up our local Stripe enterprise account.

7. Go to the settings of an enterprise with a shop profile, and select Payment methods. A Connect with Stripe button should appear:

8. Clicking it should ask for agreement, and then prompt you to select a Stripe account. If you logged out from Stripe, you will first be asked to log in again. Select Test mode (if not already active) and select the account you've designated before (other than the one used for the global instance), as the merchant account. Then, click, Skip this form.

9. You might be redirected to a screen requesting you to set up a Stripe redirect URI. I wasn't redirected to that page, but it looks like this:

10. To set up the redirect URI, visit your Stripe dashboard and select the account you've designated to be your global Stripe account (i). Visit the Connect Settings section. It's hard to find, so use the provided link, or click on the gearwheel in the top right corner of the screen, select 'Settings' and then find 'Connect - Settings'.

11. Scroll down and, under Integration > Redirects, click + Add URI, add http://0.0.0.0:3000/stripe/callbacks (or localhost instead of 0.0.0.0:3000 if that's suitable for your local environment), and activate the OAuth switch for Standard accounts.

12. Go back to the browser window, where the app is running, and repeat step 7. You should be able to see that your shop was successfully connected. 🚀

13. Now create a payment method using Stripe.

14. Finally: try it out. Open an order cycle, with some products, associated to that hub, the Stripe payment method and place some orders. You should be able to see payments on your Stripe Dashboard - you'll need to select the shop account (ii) under the Payments section.

Further info and a WIP: a sequence diagram representing our Stripe integration on OFN.