Stripe Payment Method for Solidus. It works as a wrapper for the ActiveMerchant Stripe gateway.
Run from the command line:
bundle add solidus_stripe
bundle exec rails g solidus_stripe:installNavigate to Settings > Payments > Payment Methods in the admin panel.
You can now create a new payment method that uses Stripe by selecting
Stripe credit card under Type in the New Payment Method form and saving.
The Stripe payment method's extra fields will be now shown in the form.
Configure via database configuration
If you want to store your Stripe credentials in the database just
fill the new fields in the form, selecting custom (default) in the
Preference Source field.
Configure via static configuration
If you want to store your credentials into your codebase or use ENV variables you can create the following static configuration:
# config/initializers/spree.rb
Spree.config do |config|
# ...
config.static_model_preferences.add(
Spree::PaymentMethod::StripeCreditCard,
'stripe_env_credentials',
secret_key: ENV['STRIPE_SECRET_KEY'],
publishable_key: ENV['STRIPE_PUBLISHABLE_KEY'],
stripe_country: 'US',
v3_elements: false,
v3_intents: false
)
endOnce your server has been restarted, you can select in the Preference
Source field a new entry called stripe_env_credentials. After saving,
your application will start using the static configuration to process
Stripe payments.
If you want to use the new SCA-ready Stripe Payment Intents API you need
to change the v3_intents preference from the code above to true.
Also, if you want to allow Apple Pay and Google Pay payments using the
Stripe payment request button API, you only need to set the stripe_country
preference, which represents the two-letter country code of your Stripe
account. Conversely, if you need to disable the button you can simply remove
the stripe_country preference.
Please refer to Stripe official documentation for further instructions on how to make this work properly.
The following configuration will use both Payment Intents and the payment request button API on the store payment page:
Spree.config do |config|
# ...
config.static_model_preferences.add(
Spree::PaymentMethod::StripeCreditCard,
'stripe_env_credentials',
secret_key: ENV['STRIPE_SECRET_KEY'],
publishable_key: ENV['STRIPE_PUBLISHABLE_KEY'],
stripe_country: 'US',
v3_elements: false,
v3_intents: true
)
endWhen using the Payment Intents API, be aware that the charge flow will be a bit different than when using the old V2 API or Elements. It's advisable that all Payment Intents charges are captured only by using the Solidus backend, as it is the final source of truth in regards of Solidus orders payments.
A Payment Intent is created as soon as the customer enters their credit card
data. A tentative charge will be created on Stripe, easily recognizable by its
description: Solidus Order ID: R987654321 (pending). As soon as the credit
card is confirmed (ie. when the customer passes the 3DSecure authorization, when
required) then the charge description gets updated to include the Solidus payment
number: Solidus Order ID: R987654321-Z4VYUDB3.
These charges are created uncaptured and will need to be captured in Solidus
backend later, after the customer confirms the order. If the customer never
completes the checkout, that charge must remain uncaptured. If the customer
decides to change their payment method after creating a Payment Request, then
that Payment Request charge will be canceled.
The Payment Intents API now supports also Apple Pay and Google Pay via the payment request button API. Check the Payment Intents section for setup details. Also, please refer to the official Stripe documentation for configuring your Stripe account to receive payments via Apple Pay.
It's possible to pay with Apple Pay and Google Pay directly from the cart
page. The functionality is self-contained in the view partial
_stripe_payment_request_button.html.erb. In order to use it, you need
to render that partial in the orders#edit frontend page, and pass it the
payment method configured for Stripe via the local variable
cart_checkout_payment_method:
<%= render 'stripe_payment_request_button', cart_checkout_payment_method: Spree::PaymentMethod::StripeCreditCard.first %>Of course, the rules listed in the Payment Intents section (adding the stripe country config value, for example) apply also for this feature.
Stripe V3 JS code is now managed via Sprockets. If you need to customize the JS,
you can simply override or/and add new methods to the relevant object prototype.
Make sure you load your customizations after Stripe initalization code from
spree/frontend/solidus_stripe.
For example, the following code adds a callback method in order to print a debug message on the console:
SolidusStripe.CartPageCheckout.prototype.onPrButtonMounted = function(id, result) {
if (result) {
$('#' + id).parent().show();
console.log('Payment request button is now mounted on element with id #' + id);
} else {
console.log('Payment request button failed initalization.');
}
}The default style this gem provides for Stripe Elements input fields is defined in SolidusStripe.Elements.prototype.baseStyle. You can override this method to return your own custom style (make sure it returns a valid Stripe Style
object):
SolidusStripe.Elements.prototype.baseStyle = function () {
return {
base: {
iconColor: '#c4f0ff',
color: '#fff',
fontWeight: 500,
fontFamily: 'Roboto, Open Sans, Segoe UI, sans-serif',
fontSize: '16px',
fontSmoothing: 'antialiased',
':-webkit-autofill': {
color: '#fce883',
},
'::placeholder': {
color: '#87BBFD',
},
},
invalid: {
iconColor: '#FFC7EE',
color: '#FFC7EE',
}
}
};You can also style your element containers directly by using CSS rules like this:
.StripeElement {
border: 1px solid transparent;
}
.StripeElement--focus {
box-shadow: 0 1px 3px 0 #cfd7df;
}
.StripeElement--invalid {
border-color: #fa755a;
}
.StripeElement--webkit-autofill {
background-color: #fefde5 !important;
}If you want to customize individual input fields, you can override these methods
SolidusStripe.Elements.prototype.cardNumberElementOptionsSolidusStripe.Elements.prototype.cardExpiryElementOptionsSolidusStripe.Elements.prototype.cardCvcElementOptions
and return a valid options object for the corresponding field type. For example, this code sets a custom placeholder and enables the credit card icon for the card number field
SolidusStripe.Elements.prototype.cardNumberElementOptions = function () {
return {
style: this.baseStyle(),
showIcon: true,
placeholder: "I'm a custom placeholder!"
}
}By overriding the SolidusStripe.Payment.prototype.elementsBaseOptions method and returning a valid options object, you can pass custom options to the Stripe Elements instance.
Note that in order to use web fonts with Stripe Elements, you must specify the fonts when creating the Stripe Elements instance. Here's an example specifying a custom web font and locale:
SolidusStripe.Payment.prototype.elementsBaseOptions = function () {
return {
locale: 'de',
fonts: [
{
cssSrc: 'https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,600'
}
]
};
};If you were previously using solidus_gateway gem you might want to
check out our Wiki page
that describes how to handle this migration.
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/rakeTo run Rubocop static code analysis run
bundle exec rubocopWhen testing your application's integration with this extension you may use its factories. Simply add this require statement to your spec_helper:
require '<%= file_name %>/factories'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
Before and after releases the changelog should be updated to reflect the up-to-date status of the project:
bin/rake changelog
git add CHANGELOG.md
git commit -m "Update the changelog"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