solidus_paypal_braintree 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 56c8047e148da21f23e2c7764b03fbfa7091c9ca
+  data.tar.gz: 4fd0ea732eecabaa4781fdd5bba6e8ae16a22bb8
+SHA512:
+  metadata.gz: 4346d0ca96f967828853a548addef236066b9c87b738326da3b72b05570ac37a2e57787d1d7b517d90a33dd0bb7f79f2f45a9399ab996bc50ab027bef559bcc8
+  data.tar.gz: 844c939eb60eae893152b9cd3131307eb0e1edf79e6d097955bc325a77c7a5fc0368a4042f0f3d957a8ace3616843004bd2bb37ccff93e80cb966b8b99b57430

data/LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) 2016 Stembolt
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+    * Neither the name Spree nor the names of its contributors may be used to
+      endorse or promote products derived from this software without specific
+      prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,196 @@
+SolidusPaypalBraintree
+======================
+
+[![Build Status](https://travis-ci.org/solidusio/solidus_paypal_braintree.svg?branch=master)](https://travis-ci.org/solidusio/solidus_paypal_braintree)
+
+`solidus_paypal_braintree` is an extension that adds support for using [Braintree](https://www.braintreepayments.com) as a payment source in your [Solidus](https://solidus.io/) store. It supports Apple Pay, PayPal, and credit card transactions.
+
+Installation
+------------
+
+Add solidus_paypal_braintree to your Gemfile:
+
+```ruby
+gem 'solidus_paypal_braintree', github: 'solidusio/solidus_paypal_braintree', branch: :master
+```
+
+Bundle your dependencies and run the installation generator:
+
+```shell
+bundle
+bundle exec rails g solidus_paypal_braintree:install
+```
+
+## Basic Setup
+
+### Retrieve Braintree account details
+You'll need the following account details:
+- `Merchant ID`
+- `Public key`
+- `Private key`
+
+These values can be obtained by logging in to your Braintree account, going
+to `Account -> My User` and clicking `View Authorizations` in the **API Keys,
+Tokenization Keys, Encryption Keys** section.
+
+### Create a new payment method
+Payment methods can accept preferences either directly entered in admin, or from a static source in code. For most projects we recommend using a static source, so that sensitive account credentials are not stored in the database.
+
+1. Set static preferences in an initializer
+```ruby
+# config/initializers/spree.rb
+Spree::Config.configure do |config|
+  config.static_model_preferences.add(
+    SolidusPaypalBraintree::Gateway,
+    'braintree_credentials', {
+      environment: Rails.env.production? ? 'production' : 'sandbox',
+      merchant_id: ENV['BRAINTREE_MERCHANT_ID'],
+      public_key: ENV['BRAINTREE_PUBLIC_KEY'],
+      private_key: ENV['BRAINTREE_PRIVATE_KEY']
+    }
+  )
+end
+```
+Other optional preferences are discussed below.
+2. Visit `/admin/payment_methods/new`
+3. Set `provider` to SolidusPaypalBraintree::Gateway
+4. Click "Save"
+5. Choose `braintree_credentials` from the `Preference Source` select
+6. Click `Update` to save
+
+Alternatively, create a payment method from the Rails console with:
+```ruby
+SolidusPaypalBraintree::Gateway.new(
+  name: "Braintree",
+  preference_source: "braintree_credentials"
+).save
+```
+
+### Configure payment types
+Your payment method can accept payments in three ways: through Paypal, through ApplePay, or with credit card details entered directly by the customer. By default all are disabled for all your site's stores.
+1. Visit /solidus_paypal_braintree/configurations/list
+2. Check the payment types you'd like to accept. If your site has multiple stores, there'll be a set of checkboxes for each.
+3. Click `Save changes` to save
+
+Or from the console:
+```ruby
+Spree::Store.all.each do |store|
+  store.create_braintree_configuration(
+    credit_card: true,
+    paypal: true,
+    apple_pay: true
+  )
+end
+```
+
+3. If your site uses an unmodified `solidus_frontend`, it should now be ready to take credit card payments (if you've enabled that payment type). Paypal and ApplePay require some further configuration, discussed below.
+
+Apple Pay
+---------
+
+### Setup
+Braintree has some [excellent documentation](https://developers.braintreepayments.com/guides/apple-pay/configuration/javascript/v3) on what you'll need to do to get Apple Pay up and running.
+
+In order to make everything a little simpler, this extension includes some client-side code to get you started. Specifically, it provides some wrappers to help with the initialization of an Apple Pay session. The following is a relatively bare-bones implementation:
+```javascript
+var applePayButton = document.getElementById('your-apple-pay-button');
+window.SolidusPaypalBraintree.fetchToken(function(clientToken) {
+  window.SolidusPaypalBraintree.initialize(clientToken, function(braintreeClient) {
+    window.SolidusPaypalBraintree.setupApplePay(braintreeClient, "YOUR-MERCHANT-ID", funtion(applePayInstance) {
+      applePayButton.addEventListener('click', function() { beginApplePayCheckout(applePayInstance) });
+    }
+  }
+}
+
+beginApplePayCheckout = function(applePayInstance) {
+  window.SolidusPaypalBraintree.initializeApplePaySession({
+    applePayInstance: applePayInstance,
+    storeName: 'Your Store Name',
+    currentUserEmail: Spree.current_email,
+    paymentMethodId: Spree.braintreePaymentMethodId,
+  }, (session) => {
+    // Add in your logic for onshippingcontactselected and onshippingmethodselected.
+  }
+};
+```
+
+For additional information checkout the [Apple's documentation](https://developer.apple.com/reference/applepayjs/) and [Braintree's documentation](https://developers.braintreepayments.com/guides/apple-pay/client-side/javascript/v3).
+
+### Development
+Developing with Apple Pay has a few gotchas. First and foremost, you'll need to ensure you have access to a device running iOS 10+. (I've heard there's also been progress on adding support to the Simulator.)
+
+Next, you'll need an Apple Pay sandbox account. You can check out Apple's [documentation](https://developer.apple.com/support/apple-pay-sandbox/) for additional help in performing this step.
+
+Finally, Apple Pay requires the site to be served via HTTPS. I recommend setting up a proxy server to help solve this. There are [lots of guides](https://www.google.ca/search?q=nginx+reverse+proxy+ssl+localhost) on how this can be achieved.
+
+PayPal
+------
+
+A default checkout view is provided that will display PayPal as a payment option.
+It will only be displayed if the `SolidusPaypalBraintree::Gateway` payment
+method is configured to display on the frontend and PayPal is enabled in the
+store's configuration.
+
+The checkout view
+[initializes the PayPal button](/lib/views/frontend/spree/checkout/payment/_paypal_braintree.html.erb)
+using the
+[vault flow](https://developers.braintreepayments.com/guides/paypal/overview/javascript/v3),
+which allows the source to be reused.
+
+If you are creating your own checkout view or would like to customize the
+[options that get passed to tokenize](https://braintree.github.io/braintree-web/3.6.3/PayPal.html#tokenize)
+, you can initialize your own using the `PaypalButton` JS object:
+
+```javascript
+var button = new PaypalButton(document.querySelector("#your-button-id"));
+
+button.initialize({
+  // your configuration options here
+});
+```
+
+After successful tokenization, a callback function is invoked that submits the
+transaction via AJAX and advances the order to confirm. It is possible to provide
+your own callback function to customize the behaviour after tokenize as follows:
+
+```javascript
+var button = new PaypalButton(document.querySelector("#your-button-id"));
+
+button.setTokenizeCallback(your-callback);
+```
+
+## Optional configuration
+
+### Accepting multiple currencies
+The payment method also provides an optional preference `merchant_currency_map`.
+This preference allows users to provide different Merchant Account Ids for
+different currencies. If you only plan to accept payment in one currency, the
+defaut Merchant Account Id will be used and you can omit this option.
+An example of setting this preference can be found
+[here](https://github.com/solidusio/solidus_paypal_braintree/blob/master/spec/spec_helper.rb#L70-L72).
+
+### Default store configuration
+The migrations for this gem will add a default configuration to all stores that
+has each payment type disabled. It also adds a `before_create` callback to
+`Spree::Store` that builds a default configuration. You can customize the
+default configuration that gets created by overriding the private
+`build_default_configuration` method on `Spree::Store`.
+
+Testing
+-------
+
+First bundle your dependencies, then run `rake`. `rake` will default to building the dummy app if it does not exist, then it will run specs, and [Rubocop](https://github.com/bbatsov/rubocop) static code analysis. The dummy app can be regenerated by using `rake test_app`.
+
+```shell
+bundle
+bundle exec rake
+```
+
+When testing your applications integration with this extension you may use it's factories.
+Simply add this require statement to your spec_helper:
+
+```ruby
+require 'solidus_paypal_braintree/factories'
+```
+
+Copyright (c) 2016 Stembolt, released under the New BSD License

data/Rakefile

@@ -0,0 +1,30 @@
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+begin
+  require 'spree/testing_support/extension_rake'
+  require 'rubocop/rake_task'
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new(:spec)
+
+  RuboCop::RakeTask.new
+
+  task default: %i(first_run rubocop spec)
+rescue LoadError
+  # no rspec available
+end
+
+task :first_run do
+  if Dir['spec/dummy'].empty?
+    Rake::Task[:test_app].invoke
+    Dir.chdir('../../')
+  end
+end
+
+desc 'Generates a dummy app for testing'
+task :test_app do
+  ENV['LIB_NAME'] = 'solidus_paypal_braintree'
+  Rake::Task['extension:test_app'].invoke
+end

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

@@ -0,0 +1,66 @@
+//= require spree/braintree_hosted_form.js
+
+$(function() {
+  var $paymentForm = $("#new_payment"),
+      $hostedFields = $("[data-braintree-hosted-fields]"),
+      hostedFieldsInstance = null;
+
+  function onError (err) {
+    var msg = err.name + ": " + err.message;
+    show_flash("error", msg);
+  }
+
+  function showForm(id) {
+    $("#card_form" + id).show();
+  }
+
+  function hideForm(id) {
+    $("#card_form" + id).hide();
+  }
+
+  function initFields($container, id) {
+    function setHostedFieldsInstance(instance) {
+      hostedFieldsInstance = instance;
+      return instance;
+    }
+
+    if (hostedFieldsInstance === null) {
+      braintreeForm = new BraintreeHostedForm($paymentForm, $container, id);
+      braintreeForm.initializeHostedFields().
+        then(setHostedFieldsInstance).
+        then(braintreeForm.addFormHook(onError)).
+        fail(onError);
+    }
+  }
+
+  // exit early if we're not looking at the New Payment form, or if no
+  // SolidusPaypalBraintree payment methods have been configured.
+  if (!$paymentForm.length || !$hostedFields.length) { return; }
+
+  $.when(
+    $.getScript("https://js.braintreegateway.com/web/3.9.0/js/client.min.js"),
+    $.getScript("https://js.braintreegateway.com/web/3.9.0/js/hosted-fields.min.js")
+  ).done(function() {
+    $hostedFields.each(function() {
+      var $this = $(this),
+          $radios = $("[name=card]", $this),
+          id = $this.data("payment-method-id");
+
+      // If we have previous cards, init fields on change of radio button
+      if ($radios.length) {
+        $radios.on("change", function() {
+          if ($(this).val() == 'new') {
+            showForm(id);
+            initFields($this, id);
+          } else {
+            hideForm(id);
+          }
+        });
+      } else {
+        // If we don't have previous cards, init fields immediately
+        initFields($this, id);
+        showForm(id);
+      }
+    });
+  });
+});

data/app/assets/javascripts/spree/braintree_hosted_form.js

@@ -0,0 +1,98 @@
+function BraintreeHostedForm($paymentForm, $hostedFields, paymentMethodId) {
+  this.paymentForm = $paymentForm;
+  this.hostedFields = $hostedFields;
+  this.paymentMethodId = paymentMethodId;
+}
+
+BraintreeHostedForm.prototype.initializeHostedFields = function() {
+  return this.getToken().
+    then(this.createClient.bind(this)).
+    then(this.createHostedFields());
+};
+
+BraintreeHostedForm.prototype.promisify = function (fn, args, self) {
+  var d = $.Deferred();
+
+  fn.apply(self || this, (args || []).concat(function (err, data) {
+    if (err) d.reject(err);
+    d.resolve(data);
+  }));
+
+  return d.promise();
+};
+
+BraintreeHostedForm.prototype.getToken = function () {
+  var opts = {
+    url: "/solidus_paypal_braintree/client_token",
+    method: "POST",
+    data: {
+      payment_method_id: this.paymentMethodId
+    },
+  };
+
+  function onSuccess(data) {
+    return data.client_token;
+  }
+
+  return Spree.ajax(opts).then(onSuccess);
+};
+
+BraintreeHostedForm.prototype.createClient = function (token) {
+  var opts = { authorization: token };
+  return this.promisify(braintree.client.create, [opts]);
+};
+
+BraintreeHostedForm.prototype.createHostedFields = function () {
+  var self = this;
+  var id = this.paymentMethodId;
+
+  return function(client) {
+    var opts = {
+      client: client,
+
+      fields: {
+        number: {
+          selector: "#card_number" + id
+        },
+
+        cvv: {
+          selector: "#card_code" + id
+        },
+
+        expirationDate: {
+          selector: "#card_expiry" + id
+        }
+      }
+    };
+
+    return self.promisify(braintree.hostedFields.create, [opts]);
+  };
+};
+
+BraintreeHostedForm.prototype.addFormHook = function (errorCallback) {
+  var self = this;
+  var shouldSubmit = false;
+
+  function submit(payload) {
+    shouldSubmit = true;
+
+    $("#payment_method_nonce", self.hostedFields).val(payload.nonce);
+    self.paymentForm.submit();
+  }
+
+  return function(hostedFields) {
+    self.paymentForm.on("submit", function(e) {
+      if (self.hostedFields.is(":visible") && !shouldSubmit) {
+        e.preventDefault();
+
+        hostedFields.tokenize(function(err, payload) {
+          if (err) {
+            errorCallback(err);
+          } else {
+            submit(payload);
+          }
+        });
+      }
+    });
+  };
+};

data/app/assets/javascripts/spree/checkout/braintree.js

@@ -0,0 +1,60 @@
+//= require spree/braintree_hosted_form
+
+$(function() {
+  /* This provides a default error handler for Braintree. Since we prevent
+   * submission if tokenization fails, we need to manually re-enable the
+   * submit button. */
+  function braintreeError (err) {
+    SolidusPaypalBraintree.braintreeErrorHandle(err);
+    enableSubmit();
+  }
+
+  function enableSubmit() {
+    /* If we're using jquery-ujs on the frontend, it will automatically disable
+     * the submit button, but do so in a setTimeout here:
+     * https://github.com/rails/jquery-rails/blob/master/vendor/assets/javascripts/jquery_ujs.js#L517
+     * The only way we can re-enable it is by delaying longer than that timeout
+     * or stopping propagation so their submit handler doesn't run. */
+    if ($.rails) {
+      setTimeout(function () {
+        $.rails.enableFormElement($submitButton);
+        $submitButton.attr("disabled", false).removeClass("disabled").addClass("primary");
+      }, 100);
+    } else {
+      $submitButton.attr("disabled", false).removeClass("disabled").addClass("primary");
+    }
+  }
+
+  function disableSubmit() {
+    $submitButton.attr("disabled", true).removeClass("primary").addClass("disabled");
+  }
+
+  var $paymentForm = $("#checkout_form_payment");
+  var $hostedFields = $("[data-braintree-hosted-fields]");
+  var $submitButton = $("input[type='submit']", $paymentForm);
+  var $checkoutForm = $("#checkout_form_payment");
+
+  // If we're not using hosted fields, the form doesn't need to wait.
+  if ($hostedFields.length > 0) {
+    disableSubmit();
+  }
+
+  $checkoutForm.submit(disableSubmit);
+
+  $.when(
+    $.getScript("https://js.braintreegateway.com/web/3.9.0/js/client.min.js"),
+    $.getScript("https://js.braintreegateway.com/web/3.9.0/js/hosted-fields.min.js")
+  ).done(function() {
+    var fieldPromises = $hostedFields.map(function() {
+      var $this = $(this);
+      var id = $this.data("id");
+
+      var braintreeForm = new BraintreeHostedForm($paymentForm, $this, id);
+      return braintreeForm.initializeHostedFields().
+        then(braintreeForm.addFormHook(braintreeError)).
+        fail(braintreeError);
+    });
+
+    $.when.apply($, fieldPromises).done(enableSubmit);
+  });
+});