🚧 WARNING 🚧 Work In Progress
You're looking at the source for
solidus_stripe v5, which will only support the starter frontend
but at the moment it is not ready to be used.
solidus_stripe v4 on the corresponding branch.
🚧 WARNING 🚧 Supporting
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
gem 'solidus_stripe', git: 'https://github.com/solidusio/solidus_stripe.git', branch: 'v4'
Add solidus_stripe to your Gemfile:
Bundle your dependencies and run the installation generator:
bin/rails generate solidus_stripe:install
This library makes use of some Stripe webhooks.
Every Solidus Stripe payment method you create will get a slug assigned. You need to append it to a generic webhook endpoint to get the URL for that payment method. For example:
SolidusStripe::PaymentMethod.last.slug # "365a8435cd11300e87de864c149516e0"
For the above example, and if you mounted the
SolidusStripe::Engine routes on
the default scope, the webhook endpoint would look like:
Besides, you also need to configure the webhook signing secret for that payment
method. You can do that through the
preference on the payment method.
Before going to production, you'll need to register the webhook endpoint with
Stripe, and make sure to subscribe
to the events listed in the
On development, you can test webhooks by using Stripe CLI.
Showing reusable sources in the checkout
When saving stripe payment methods for future usage the checkout requires a partial for each supported payment method type.
For the full list of types see: https://stripe.com/docs/api/payment_methods/object#payment_method_object-type.
The extension will only install a partial for the
card type, located in
and fall back to a
default partial otherwise (see
As an example, in order to show a wallet source connected to a SEPA Debit payment method the following partial should be added:
<% sepa_debit = stripe_payment_method.sepa_debit %> 🏦 <%= sepa_debit.bank_code %> / <%= sepa_debit.branch_code %><br> IBAN: **** **** **** **** **** <%= sepa_debit.last4 %>
Showing reusable sources in the admin interface
Refer to the previous section for information on how to set up a new payment method type. However, it's important to note that if you have to display a wallet source connected to a Stripe Payment Method other than "card" on the admin interface, you must include the partial in:
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
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 the associated Solidus Stripe payment method. It will delegate all unknown methods to the underlying stripe event object. 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
Payment state-machine vs. PaymentIntent statuses
When compared to the Payment state machine, Stripe payment intents have different set of states and transitions. The most important difference is that on Stripe a failure is not a final state, rather just a way to start over.
In order to map these concepts SolidusStripe will match states in a slightly unexpected way, as shown below.
|Stripe PaymentIntent Status||Solidus Payment State|
Retrieve your API Key and Publishable Key from your Stripe testing dashboard. You can
get your webhook signing secret executing the
stripe listen command.
variables (e.g. via
direnv), this will trigger the default initializer to create a static preference for SolidusStripe.
bin/dev to start both the sandbox rail server and the file watcher through Foreman. That will update the sandbox whenever
a file is changed. When using
bin/dev you can safely add
debugger statements, even if Foreman won't provide a TTY, by connecting
to the debugger session through
rdbg --attach from another terminal.
/admin/payments and create a new Stripe payment using the static preferences.
See the Webhooks section to learn how to configure Stripe webhooks.
Testing the extension
First bundle your dependencies, then run
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
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
Or, if you are using
FactoryBot.definition_file_paths, you can load Solidus core
factories along with this extension's factories using this statement:
Running the sandbox
To run this extension in a sandboxed Solidus application, you can run
bin/sandbox. The path for
the sandbox app is
bin/rails will forward any Rails commands to
Here's an example:
$ bin/rails server => Booting Puma => Rails 220.127.116.11 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.
Copyright (c) 2014 Spree Commerce Inc., released under the New BSD License Copyright (c) 2021 Solidus Team, released under the New BSD License.