Add solidus_stripe to your bundle and run the installation generator:
bundle add solidus_stripe
bin/rails generate solidus_stripe:install
Then set the following environment variables both locally and in production in order
to setup the solidus_stripe_env_credentials
static preference as defined in the initializer:
SOLIDUS_STRIPE_API_KEY # will prefill the `api_key` preference
SOLIDUS_STRIPE_PUBLISHABLE_KEY # will prefill the `publishable_key` preference
SOLIDUS_STRIPE_WEBHOOK_SIGNING_SECRET # will prefill the `webhook_signing_secret` preference
Once those are available you can create a new Stripe payment method in the /admin interface
and select the solidus_stripe_env_credentials
static preference.
The webhooks URLs are automatically generated based on the enviroment,
by default it will be scoped to live
in production and test
everywhere else.
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 SolidusStripe::Webhook::Event::CORE
constant.
So in your Stripe dashboard you'll need to set the webhook URL to:
https://store.example.com/solidus_stripe/live/webhooks
While for development you should use the stripe CLI to forward the webhooks to your local server:
# Please refer to `stripe listen --help` for more options
stripe listen --forward-to https://localhost:3000/solidus_stripe/test/webhooks
If you need support for solidus_frontend
please refer to the README of solidus_stripe v4.
If you're using a custom frontend you'll need to adjust the code copied to your application by the installation generator. Given frontend choices can vary wildly, we can't provide a one-size-fits-all solution, but we are providing this simple integration with solidus_starter_frontend
as a reference implementation. The amount of code is intentionally kept to a minimum, so you can easily adapt it to your needs.
The gem includes an API interface with two endpoints: create_setup_intent
and create_payment_intent
.
After configuring the gem, both endpoints will be accessible.
This endpoint allows you to create an intent for configuring a saved payment method. It can be executed before making an actual payment to set up a card for future use.
POST /solidus_stripe/api/create_setup_intent
Params
payment_method_id
- ID of the SolidusStripe::PaymentMethod
record
This endpoint creates a payment intent for an order and returns a client secret that can be used to initialize Stripe's widget. Stripe later confirms the payment via a webhook call.
POST /solidus_stripe/api/create_payment_intent
This endpoint loads the last incomplete Spree order via the last_incomplete_spree_order method
for a logged-in user, or it takes an optional guest_token
parameter for a guest user.
Params
payment_method_id
- ID of the SolidusStripe::PaymentMethod
record
stripe_payment_method_id
- ID of the payment method, obtained by frontend from Stripe
guest_token
- optional
Stripe supports two different flows for payments: authorization and capture and immediate payment.
Both flows are supported by this extension, but you should be aware that they will happen before the order finalization, just before the final confirmation. At that moment if the payment method of choice will require additional authentication (e.g. 3D Secure) the extra authentication will be shown to the user.
This extension is a complete rewrite of the previous version, and it's not generally compatible with v4.
That being said, if you're upgrading from v4 you can check out this guide to help you with the transition from payment tokens to payment intents: https://stripe.com/docs/payments/payment-intents/migration.
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 app/views/checkouts/existing_payment/stripe/_card.html.erb
,
and fall back to a default
partial otherwise (see app/views/checkouts/existing_payment/stripe/_default.html.erb
).
As an example, in order to show a wallet source connected to a SEPA Debit payment method the following partial should be added:
app/views/checkouts/existing_payment/stripe/_sepa_debit.html.erb
<% sepa_debit = stripe_payment_method.sepa_debit %>
π¦ <%= sepa_debit.bank_code %> / <%= sepa_debit.branch_code %><br>
IBAN: **** **** **** **** **** <%= sepa_debit.last4 %>
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:
app/views/spree/admin/payments/source_forms/existing_payment/stripe/
Solidus Stripe comes with support for a few webhook events, to which there's a default handler. You can customize the behavior of those handlers by or add to their behavior by replacing or adding subscribers in the internal Solidus event bus.
Each event will have the original Stripe name, prefixed by stripe.
. For example, the payment_intent.succeeded
event will be published as stripe.payment_intent.succeeded
.
Here's the list of events that are supported by default:
payment_intent.succeeded
payment_intent.payment_failed
payment_intent.canceled
charge.refunded
In order to add a new handler 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 usual:
# app/subscribers/update_account_balance_subscriber.rb
class UpdateAccountBalanceSubscriber
include Omnes::Subscriber
handle :"stripe.charge.succeeded", with: :call
def call(event)
# Please refere to the Stripe gem and API documentation for more details on the
# structure of the event object. All methods called on `event` will be forwarded
# to the Stripe event object:
# - https://www.rubydoc.info/gems/stripe/Stripe/Event
# - https://stripe.com/docs/webhooks/stripe-events
Rails.logger.info "Charge succeeded: #{event.data.to_json}"
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
By default, the extension will show all the payment methods that are supported by Stripe in the current currency and for the merchant country.
You can customize the list of available payment methods by overriding the payment_method_types
option in the app/views/checkouts/payment/_stripe.html.erb
partial. Please refer to the Stripe documentation for the full list of supported payment methods.
Solidus payment methods are configured with a auto_capture
option, which is used to determine if the payment should be captured immediately or not. If you intend to use a non-card payment method, it's likely that you'll need to set auto_capture
to true
in the payment method configuration. Please refer to the Stripe documentation for more details.
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 |
---|---|
requires_payment_method | checkout |
requires_action | checkout |
processing | processing |
requires_confirmation | checkout |
requires_capture | pending |
succeeded | completed |
Reference:
- https://stripe.com/docs/payments/intents?intent=payment
- https://github.com/solidusio/solidus/blob/main/core/lib/spree/core/state_machines/payment.rb
This extensions is using the two-step payment confirmation flow. This means that at the payment step the payment form will just collect the basic payment information (e.g. credit card details) and any additional confirmation is deferred to the confirmation step.
Retrieve your API Key and Publishable Key from your Stripe testing dashboard. You can
get your webhook signing secret executing the stripe listen
command.
Set SOLIDUS_STRIPE_API_KEY
, SOLIDUS_STRIPE_PUBLISHABLE_KEY
and SOLIDUS_STRIPE_WEBHOOK_SIGNING_SECRET
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 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.
Visit /admin/payments
and create a new Stripe payment using the static preferences.
See the Webhooks section to learn how to configure Stripe webhooks.
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)
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:https://127.0.0.1:3000
Use Ctrl-C to stop
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.