solidus_stripe 4.3.0 → 5.0.0.alpha.1

data/README.md

@@ -1,265 +1,200 @@
+## 🚧 **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**.
+
+Please use [`solidus_stripe` v4 on the corresponding branch](https://github.com/solidusio/solidus_stripe/tree/v4).
+
+## 🚧 **WARNING** 🚧 Supporting `solidus_frontend`
+
+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'`
+
+---
+
 # Solidus Stripe
 
 [![CircleCI](https://circleci.com/gh/solidusio/solidus_stripe.svg?style=shield)](https://circleci.com/gh/solidusio/solidus_stripe)
 [![codecov](https://codecov.io/gh/solidusio/solidus_stripe/branch/master/graph/badge.svg)](https://codecov.io/gh/solidusio/solidus_stripe)
 
-Stripe Payment Method for Solidus. It works as a wrapper for the ActiveMerchant Stripe gateway.
+<!-- Explain what your extension does. -->
 
----
+## Installation
+
+Add solidus_stripe to your Gemfile:
 
-Installation
-------------
+```ruby
+gem 'solidus_stripe'
+```
 
-Run from the command line:
+Bundle your dependencies and run the installation generator:
 
 ```shell
-bundle add solidus_stripe
-bundle exec rails g solidus_stripe:install
+bin/rails generate 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.
+### Webhooks
 
-**Configure via database configuration**
+This library makes use of some [Stripe webhooks](https://stripe.com/docs/webhooks).
 
-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.
+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:
 
-**Configure via static configuration**
+```ruby
+SolidusStripe::PaymentMethod.last.slug
+# "365a8435cd11300e87de864c149516e0"
+```
 
-If you want to store your credentials into your codebase or use ENV
-variables you can create the following static configuration:
+For the above example, and if you mounted the `SolidusStripe::Engine` routes on
+the default scope, the webhook endpoint would look like:
 
-```ruby
-# 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
+```
+/solidus_stripe/webhooks/365a8435cd11300e87de864c149516e0
 ```
 
-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.
+Besides, you also need to configure the webhook signing secret for that payment
+method. You can do that through the `webhook_endpoint_signing_secret`
+preference on the payment method.
 
+Before going to production, you'll need to [register the webhook endpoint with
+Stripe](https://stripe.com/docs/webhooks/go-live), and make sure to subscribe
+to the events listed in [the `SolidusStripe::Webhook::Event::CORE`
+constant](https://github.com/solidusio/solidus_stripe/blob/master/lib/solidus_stripe/webhook/event.rb).
 
-Using Stripe Payment Intents API
---------------------------------
+On development, you can
+[test webhooks by using Stripe CLI](https://stripe.com/docs/webhooks/test).
 
-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.
+## Usage
 
-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.
+### Showing reusable sources in the checkout
 
-Please refer to Stripe official
-[documentation](https://stripe.com/docs/payments/payment-intents)
-for further instructions on how to make this work properly.
+When saving stripe payment methods for future usage the checkout requires
+a partial for each supported payment method type.
 
-The following configuration will use both Payment Intents and the
-payment request button API on the store payment page:
+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`).
 
-```ruby
-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
-```
+As an example, in order to show a wallet source connected to a
+[SEPA Debit payment method](https://stripe.com/docs/api/payment_methods/object#payment_method_object-sepa_debit)
+the following partial should be added:
 
-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](https://stripe.com/docs/stripe-js/elements/payment-request-button).
-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`:
+`app/views/checkouts/existing_payment/stripe/_sepa_debit.html.erb`
 
-```ruby
-<%= render 'stripe_payment_request_button', cart_checkout_payment_method: Spree::PaymentMethod::StripeCreditCard.first %>
+```erb
+<% sepa_debit = stripe_payment_method.sepa_debit %>
+🏦 <%= sepa_debit.bank_code %> / <%= sepa_debit.branch_code %><br>
+IBAN: **** **** **** **** **** <%= sepa_debit.last4 %>
 ```
 
-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:
-
-```js
-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.');
-  }
-}
-```
+### Showing reusable sources in the admin interface
 
-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](https://stripe.com/docs/js/appendix/style)
-object):
-
-```js
-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',
-    }
-  }
-};
-```
+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 style your element containers directly by using CSS rules like this:
+`app/views/spree/admin/payments/source_forms/existing_payment/stripe/`
 
-```css
-  .StripeElement {
-    border: 1px solid transparent;
-  }
+### Custom webhooks
 
-  .StripeElement--focus {
-    box-shadow: 0 1px 3px 0 #cfd7df;
-  }
+You can also use [Stripe webhooks](https://stripe.com/docs/webhooks) to trigger
+custom actions in your application.
 
-  .StripeElement--invalid {
-    border-color: #fa755a;
-  }
+First, you need to register the event you want to listen to, both [in
+Stripe](https://stripe.com/docs/webhooks/go-live) and in your application:
 
-  .StripeElement--webkit-autofill {
-    background-color: #fefde5 !important;
-  }
+```ruby
+# config/initializers/solidus_stripe.rb
+SolidusStripe.configure do |config|
+  config.webhook_events = %i[charge.succeeded]
+end
 ```
 
-### Customizing individual input fields
+That will register a new `:"stripe.charge.succeeded"` event in the [Solidus
+bus](https://guides.solidus.io/customization/subscribing-to-events). The
+Solidus event will be published whenever a matching incoming webhook event is
+received. You can subscribe to it as regular:
 
-If you want to customize individual input fields, you can override these methods
+```ruby
+# app/subscribers/update_account_balance_subscriber.rb
+class UpdateAccountBalanceSubscriber
+  include Omnes::Subscriber
 
-* `SolidusStripe.Elements.prototype.cardNumberElementOptions`
-* `SolidusStripe.Elements.prototype.cardExpiryElementOptions`
-* `SolidusStripe.Elements.prototype.cardCvcElementOptions`
+  handle :"stripe.charge.succeeded", with: :call
 
-and return a valid [options object](https://stripe.com/docs/js/elements_object/create_element?type=cardNumber) for the corresponding field type. For example, this code sets a custom placeholder and enables the credit card icon for the card number field
+  def call(event)
+    # ...
+  end
+end
 
-```js
-SolidusStripe.Elements.prototype.cardNumberElementOptions = function () {
-  return {
-    style: this.baseStyle(),
-    showIcon: true,
-    placeholder: "I'm a custom placeholder!"
-  }
-}
+# config/initializers/solidus_stripe.rb
+# ...
+Rails.application.config.to_prepare do
+  UpdateAccountBalanceSubscriber.new.subscribe_to(Spree::Bus)
+end
 ```
 
-### Passing options to the Stripe Elements instance
+The passed event object is a thin wrapper around the [Stripe
+event](https://www.rubydoc.info/gems/stripe/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](https://github.com/nebulab/omnes#adapters), which is recommended as
+otherwise the response to Stripe will be delayed until subscribers are done.
 
-By overriding the `SolidusStripe.Payment.prototype.elementsBaseOptions` method and returning a [valid options object](https://stripe.com/docs/js/elements_object/create), you can pass custom options to the Stripe Elements instance.
+You can also configure the signature verification tolerance in seconds (it
+defaults to the [same value as Stripe
+default](https://stripe.com/docs/webhooks/signatures#replay-attacks)):
 
-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:
-
-```js
-SolidusStripe.Payment.prototype.elementsBaseOptions = function () {
-  return {
-    locale: 'de',
-    fonts: [
-      {
-        cssSrc: 'https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,600'
-      }
-    ]
-  };
-};
+```ruby
+# config/initializers/solidus_stripe.rb
+SolidusStripe.configure do |config|
+  config.webhook_signature_tolerance = 150
+end
 ```
 
-## Migrating from solidus_gateway
+## Implementation
+
+### 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.
 
-If you were previously using `solidus_gateway` gem you might want to
-check out our [Wiki page](https://github.com/solidusio/solidus_stripe/wiki/Migrating-from-solidus_gateway)
-that describes how to handle this migration.
+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                  | checkout              |
+| requires_confirmation       | checkout              |
+| requires_capture            | pending               |
+| succeeded                   | completed             |
+
+Reference:
+
+- https://stripe.com/docs/payments/intents?intent=payment
+- https://github.com/solidusio/solidus/blob/master/core/lib/spree/core/state_machines/payment.rb
 
 ## Development
 
+Retrieve your API Key and Publishable Key from your [Stripe testing dashboard](https://stripe.com/docs/testing). 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](#webhooks) to learn how to configure Stripe webhooks.
+
 ### Testing the extension
 
 First bundle your dependencies, then run `bin/rake`. `bin/rake` will default to building the dummy
@@ -277,10 +212,17 @@ 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:
+Simply add this require statement to your `spec/spec_helper.rb`:
+
+```ruby
+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:
 
 ```ruby
-require '<%= file_name %>/factories'
+SolidusDevSupport::TestingSupport::Factories.load_for(SolidusStripe::Engine)
 ```
 
 ### Running the sandbox
@@ -299,21 +241,11 @@ $ bin/rails server
 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:
-
-```shell
-bin/rake changelog
-git add CHANGELOG.md
-git commit -m "Update the changelog"
-```
-
 ### Releasing new versions
 
 Please refer to the dedicated [page](https://github.com/solidusio/solidus/wiki/How-to-release-extensions) 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
+Copyright (c) 2021 Solidus Team, released under the New BSD License.

data/Rakefile

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
-require 'solidus_dev_support/rake_tasks'
-SolidusDevSupport::RakeTasks.install
+require 'bundler/gem_tasks'
 
-task default: 'extension:specs'
+task :default do
+  require 'bundler'
+  Bundler.with_unbundled_env do
+    sh 'bin/rspec'
+  end
+end

data/app/assets/javascripts/spree/backend/solidus_stripe.js

@@ -0,0 +1,2 @@
+// Placeholder manifest file.
+// the installer will append this file to the app vendored assets here: vendor/assets/javascripts/spree/backend/all.js'

data/app/assets/stylesheets/spree/backend/solidus_stripe.css

@@ -0,0 +1,4 @@
+/*
+Placeholder manifest file.
+the installer will append this file to the app vendored assets here: 'vendor/assets/stylesheets/spree/backend/all.css'
+*/

data/app/controllers/solidus_stripe/intents_controller.rb

@@ -1,66 +1,50 @@
 # frozen_string_literal: true
 
-module SolidusStripe
-  class IntentsController < Spree::BaseController
-    include Spree::Core::ControllerHelpers::Order
+require 'stripe'
 
-    def create_intent
-      @intent = create_payment_intent
-      generate_payment_response
-    end
+class SolidusStripe::IntentsController < Spree::BaseController
+  include Spree::Core::ControllerHelpers::Order
 
-    def create_payment
-      create_payment_service = SolidusStripe::CreateIntentsPaymentService.new(
-        params[:stripe_payment_intent_id],
-        stripe,
-        self
-      )
+  before_action :load_payment_method
 
-      if create_payment_service.call
-        render json: { success: true }
-      else
-        render json: { error: "Could not create payment" }, status: 500
-      end
+  def after_confirmation
+    unless params[:payment_intent]
+      return head :unprocessable_entity
     end
 
-    private
-
-    def stripe
-      @stripe ||= Spree::PaymentMethod::StripeCreditCard.find(params[:spree_payment_method_id])
+    unless current_order.confirm?
+      redirect_to main_app.checkout_state_path(current_order.state)
+      return
     end
 
-    def generate_payment_response
-      response = @intent.params
-      # Note that if your API version is before 2019-02-11, 'requires_action'
-      # appears as 'requires_source_action'.
-      if %w[requires_source_action requires_action].include?(response['status']) && response['next_action']['type'] == 'use_stripe_sdk'
-        render json: {
-          requires_action: true,
-          stripe_payment_intent_client_secret: response['client_secret']
-        }
-      elsif response['status'] == 'requires_capture'
-        render json: {
-          success: true,
-          requires_capture: true,
-          stripe_payment_intent_id: response['id']
-        }
-      else
-        render json: { error: response['error']['message'] }, status: 500
-      end
-    end
+    intent = SolidusStripe::PaymentIntent.find_by!(
+      payment_method: @payment_method,
+      order: current_order,
+      stripe_intent_id: params[:payment_intent],
+    )
+
+    if intent.process_payment
+      flash.notice = t('spree.order_processed_successfully')
 
-    def create_payment_intent
-      stripe.create_intent(
-        (current_order.total * 100).to_i,
-        params[:stripe_payment_method_id],
-        description: "Solidus Order ID: #{current_order.number} (pending)",
-        currency: current_order.currency,
-        confirmation_method: 'automatic',
-        capture_method: 'manual',
-        confirm: true,
-        setup_future_usage: 'off_session',
-        metadata: { order_id: current_order.id }
+      flash['order_completed'] = true
+
+      redirect_to(
+        spree_current_user ?
+          main_app.order_path(current_order) :
+          main_app.token_order_path(current_order, current_order.guest_token)
       )
+    else
+      flash[:error] = params[:error_message] || t('spree.payment_processing_failed')
+      redirect_to(main_app.checkout_state_path(:payment))
     end
   end
+
+  private
+
+  def load_payment_method
+    @payment_method = current_order(create_order_if_necessary: true)
+      .available_payment_methods
+      .merge(SolidusStripe::PaymentMethod.with_slug(params[:slug]))
+      .first!
+  end
 end

data/app/controllers/solidus_stripe/webhooks_controller.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "solidus_stripe/webhook/event"
+require "stripe"
+
+module SolidusStripe
+  class WebhooksController < Spree::BaseController
+    SIGNATURE_HEADER = "HTTP_STRIPE_SIGNATURE"
+
+    skip_before_action :verify_authenticity_token, only: :create
+
+    respond_to :json
+
+    def create
+      event = Webhook::Event.from_request(payload: request.body.read, signature_header: signature_header,
+        slug: params[:slug])
+      return head(:bad_request) unless event
+
+      Spree::Bus.publish(event) && head(:ok)
+    end
+
+    private
+
+    def signature_header
+      request.headers[SIGNATURE_HEADER]
+    end
+  end
+end

data/app/models/concerns/solidus_stripe/log_entries.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module SolidusStripe::LogEntries
+  extend ActiveSupport::Concern
+  extend self
+
+  # Builds an ActiveMerchant::Billing::Response
+  #
+  # @option [true,false] :success
+  # @option [String] :message
+  # @option [String] :response_code
+  # @option [#to_json] :data
+  #
+  # @return [return type] return description
+  def build_payment_log(success:, message:, response_code: nil, data: nil)
+    ActiveMerchant::Billing::Response.new(
+      success,
+      message,
+      { 'data' => data.to_json },
+      { authorization: response_code },
+    )
+  end
+
+  def payment_log(payment, **options)
+    payment.log_entries.create!(details: YAML.safe_dump(
+      build_payment_log(**options),
+      permitted_classes: Spree::LogEntry.permitted_classes,
+      aliases: Spree::Config.log_entry_allow_aliases,
+    ))
+  end
+end

data/app/models/solidus_stripe/customer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SolidusStripe
+  class Customer < ApplicationRecord
+    belongs_to :payment_method
+
+    # Source is supposed to be a user or an order and needs to respond to #email
+    belongs_to :source, polymorphic: true
+
+    def self.retrieve_or_create_stripe_customer_id(payment_method:, order:)
+      instance = find_or_initialize_by(payment_method: payment_method, source: order.user || order)
+
+      instance.stripe_id ||
+        instance.create_stripe_customer.tap { instance.update!(stripe_id: _1.id) }.id
+    end
+
+    def create_stripe_customer
+      payment_method.gateway.request { Stripe::Customer.create(email: source.email) }
+    end
+  end
+end