SolidusPaypalBraintree
solidus_paypal_braintree
is an extension that adds support for using Braintree as a payment source in your Solidus store. It supports Apple Pay, PayPal, and credit card transactions.
Installation
Add solidus_paypal_braintree to your Gemfile:
gem 'solidus_paypal_braintree', github: 'solidusio/solidus_paypal_braintree', branch: :master
Bundle your dependencies and run the installation generator:
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.
- Set static preferences in an initializer
# 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'],
paypal_flow: 'vault', # 'checkout' is accepted too
}
)
end
Other optional preferences are discussed below.
-
Visit
/admin/payment_methods/new
-
Set
provider
to SolidusPaypalBraintree::Gateway -
Click "Save"
-
Choose
braintree_credentials
from thePreference Source
select -
Click
Update
to save
Alternatively, create a payment method from the Rails console with:
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.
-
Visit /solidus_paypal_braintree/configurations/list
-
Check the payment types you'd like to accept. If your site has multiple stores, there'll be a set of checkboxes for each.
-
Click
Save changes
to save
Or from the console:
Spree::Store.all.each do |store|
store.create_braintree_configuration(
credit_card: true,
paypal: true,
apple_pay: true
)
end
-
If your site uses an unmodified
solidus_frontend
, it should now be ready to take payments. See below for more information on configuring Paypal and ApplePay. -
Typical Solidus sites will have customized frontend code, and may require some additional work. Use
lib/views/frontend/spree/checkout/payment/_paypal_braintree.html.erb
andapp/assets/javascripts/solidus_paypal_braintree/checkout.js
as models.
Apple Pay
Developing with Apple Pay
You'll need the following:
- A device running iOS 10+.
- An Apple Pay sandbox account. You can check out Apple's documentation for additional help in performing this step.
- A site served via HTTPS. To set this up for development we recommend setting up a reverse proxy server. There are lots of guides on how this can be achieved.
- A Braintree sandbox account with Apple Pay enabled (
Settings>Processing
) and configured (Settings>Processing>Options
) with your Apple Merchant ID and the HTTPS domain for your site. - A sandbox user logged in to your device, with a test card in its Wallet
Enabling Apple Pay for custom frontends
The following is a relatively bare-bones implementation to enable Apple Pay on the frontend:
<% if current_store.braintree_configuration.apple_pay? %>
<script src="https://js.braintreegateway.com/web/3.22.1/js/apple-pay.min.js"></script>
<button id="apple-pay-button" class="apple-pay-button"></button>
<script>
var applePayButtonElement = document.getElementById('apple-pay-button');
var applePayOptions = {
paymentMethodId: <%= id %>,
storeName: "<%= current_store.name %>",
orderEmail: "<%= current_order.email %>",
amount: "<%= current_order.total %>",
shippingContact: {
emailAddress: '<%= current_order.email %>',
familyName: '<%= address.firstname %>',
givenName: '<%= address.lastname %>',
phoneNumber: '<%= address.phone %>',
addressLines: ['<%= address.address1 %>','<%= address.address2 %>'],
locality: '<%= address.city %>',
administrativeArea: '<%= address.state.name %>',
postalCode: '<%= address.zipcode %>',
country: '<%= address.country.name %>',
countryCode: '<%= address.country.iso %>'
}
};
var button = new SolidusPaypalBraintree.createApplePayButton(applePayButtonElement, applePayOptions);
button.initialize();
</script>
<% end %>
Further Apple Pay information
Braintree has some excellent documentation on what you'll need to do to get Apple Pay up and running.
For additional information check out Apple's documentation and Braintree's documentation.
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 using the Vault flow, which allows the source to be reused. If you want, you can use Checkout with PayPal instead, which doesn't allow you to reuse sources but allows your customers to pay with their PayPal balance (see setup instructions).
If you are creating your own checkout view or would like to customize the
options that get passed to tokenize
, you can initialize your own using the PaypalButton
JS object:
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:
var button = new PaypalButton(document.querySelector("#your-button-id"));
button.setTokenizeCallback(your-callback);
Express checkout from the cart
A PayPal button can also be included on the cart view to enable express checkouts:
render "spree/shared/paypal_cart_button"
PayPal configuration
If your store requires the phone number into user addresses you'll need to configure PayPal to return the phone back when it returns the address used by the user:
- Log into your PayPal account
- Go to Profile -> My Selling Tools -> Website preferences
- Set Contact Telephone to
On (Required Field)
orOn (Optional Field)
Using the option Off
will not make the address valid and will raise a
validation error.
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.
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 static code analysis. The dummy app can be regenerated by using rake test_app
.
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:
require 'solidus_paypal_braintree/factories'
Copyright (c) 2016 Stembolt, released under the New BSD License