README.md

🚧 WARNING: WORK IN PROGRESS 🚧

You're looking at the source for solidus_stripe v5, which will only support the starter frontend and not the classic frontend You can find the source for v4 on the corresponding branch

🚧 WARNING: WORK IN PROGRESS 🚧

Solidus Stripe

Installation

Add solidus_stripe to your Gemfile:

gem 'solidus_stripe'

⚠️ WARNING ⚠️

If you need support for solidus_frontend please add < 5 as a version requirement in your gemfile:

gem 'solidus_stripe', '< 5'

or if your tracking the github version please switch to the v4 branch:

gem 'solidus_stripe', git: 'https://github.com/solidusio/solidus_stripe.git', branch: 'v4'

Bundle your dependencies and run the installation generator:

bin/rails generate solidus_stripe:install

Webhooks

This library makes use of some Stripe webhooks.

On development, you can test them by using Stripe CLI.

Before going to production, you'll need to register the /solidus_stripe/webhooks endpoint with Stripe, and make sure to subscribe to the following events:

[TBD]

In both environments, you'll need to create a solidus_stripe.webhook_endpoint_secret credential with the webhook signing secret:

# For development, add `--environment development`
bin/rails credentials:edit

# config/credentials.yml.enc
solidus_stripe:
  webhook_endpoint_secret: "whsec_..."

Usage

Custom webhooks

You can also use Stripe webhooks to trigger custom actions in your application.

First, you need to register the event you want to listen to, both in Stripe and in your application:

# config/initializers/solidus_stripe.rb
SolidusStripe.configure do |config|
  config.webhook_events = %i[charge.succeeded]
end

That will register a new :"stripe.charge.succeeded" event in the Solidus bus. The Solidus event will be published whenever a matching incoming webhook event is received. You can subscribe to it as regular:

# app/subscribers/update_account_balance_subscriber.rb
class UpdateAccountBalanceSubscriber
  include Omnes::Subscriber

  handle :"stripe.charge.succeeded", with: :call

  def call(event)
    # ...
  end
end

# config/initializers/solidus_stripe.rb
# ...
Rails.application.config.to_prepare do
  UpdateAccountBalanceSubscriber.new.subscribe_to(Spree::Bus)
end

The passed event object is a thin wrapper around the Stripe event and will delegate all methods to it. It can also be used in async adapters, which is recommended as otherwise the response to Stripe will be delayed until subscribers are done.

You can also configure the signature verification tolerance in seconds (it defaults to the same value as Stripe default):

# config/initializers/solidus_stripe.rb
SolidusStripe.configure do |config|
  config.webhook_signature_tolerance = 150
end

Development

Retrieve your API Key and Publishable Key from your Stripe testing dashboard.

Set SOLIDUS_STRIPE_API_KEY and SOLIDUS_STRIPE_PUBLISHABLE_KEY environment variables (e.g. via direnv), this will trigger the default initializer to create a static preference for SolidusStripe.

Run bin/dev to start both the sandbox rail server and the file watcher that will update the sandbox whenever a file is changed.

Visit /admin/payments and create a new Stripe payment using the static preferences.

Testing the extension

First bundle your dependencies, then run bin/rake. bin/rake will default to building the dummy app if it does not exist, then it will run specs. The dummy app can be regenerated by using bin/rake extension:test_app.

bin/rake

To run Rubocop static code analysis run

bundle exec rubocop

When testing your application's integration with this extension you may use its factories. Simply add this require statement to your spec/spec_helper.rb:

require 'solidus_stripe/testing_support/factories'

Or, if you are using FactoryBot.definition_file_paths, you can load Solidus core factories along with this extension's factories using this statement:

SolidusDevSupport::TestingSupport::Factories.load_for(SolidusStripe::Engine)

Running the sandbox

To run this extension in a sandboxed Solidus application, you can run bin/sandbox. The path for the sandbox app is ./sandbox and bin/rails will forward any Rails commands to sandbox/bin/rails.

Here's an example:

$ bin/rails server
=> Booting Puma
=> Rails 6.0.2.1 application starting in development
* Listening on tcp://127.0.0.1:3000
Use Ctrl-C to stop

Releasing new versions

Please refer to the dedicated page on Solidus wiki.

License

Copyright (c) 2014 Spree Commerce Inc., released under the New BSD License Copyright (c) 2021 Solidus Team, released under the New BSD License.