Skip to content

Latest commit

 

History

History
319 lines (243 loc) · 10.1 KB

README.md

File metadata and controls

319 lines (243 loc) · 10.1 KB
Raw

Solidus Stripe

CircleCI codecov

Stripe Payment Method for Solidus. It works as a wrapper for the ActiveMerchant Stripe gateway.

Installation

Run from the command line:

bundle add solidus_stripe
bundle exec rails g solidus_stripe:install

Usage

Navigate 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
  )
end

Once 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.

Using Stripe Payment Intents API

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
  )
end

When 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.

Apple Pay and Google Pay

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.

Customizing the V3 API javascript

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.');
  }
}

Customizing Stripe Elements

Styling input fields

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;
  }

Customizing individual input fields

If you want to customize individual input fields, you can override these methods

  • SolidusStripe.Elements.prototype.cardNumberElementOptions
  • SolidusStripe.Elements.prototype.cardExpiryElementOptions
  • SolidusStripe.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!"
  }
}

Passing options to the Stripe Elements instance

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'
      }
    ]
  };
};

Migrating from solidus_gateway

If you were previously using solidus_gateway gem you might want to check out our Wiki page that describes how to handle this migration.

Development

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_helper:

require '<%= file_name %>/factories'

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

Updating the changelog

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"

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