Repository files navigation

⛔️ This extension is archived. ⛔️

It has been renamed and moved tosolidus_braintree.

If you were using this project, you can follow theinstructions to upgrade to the new extension.

solidus_paypal_braintree is an extension that adds support for usingBraintree as a payment source in yourSolidus store. It supports Apple Pay, PayPal, and credit card transactions.

🚧 This extension is currently only compatible with the legacysolidus_frontend 🚧

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:

bundlebundleexec rails g solidus_paypal_braintree:install

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, goingtoAccount -> My User and clickingView Authorizations in theAPI Keys,Tokenization Keys, Encryption Keys section.

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

# config/initializers/spree.rbRails.application.config.to_preparedoSpree::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 toouse_data_collector:true# Fingerprint the user's browser when using Paypal})end

Other optional preferences are discussed below.

2. Visit/admin/payment_methods/new

3. Setprovider to SolidusPaypalBraintree::Gateway

4. Click "Save"

5. Choosebraintree_credentials from thePreference Source select

6. ClickUpdate to save

Alternatively, create a payment method from the Rails console with:

SolidusPaypalBraintree::Gateway.new(name:"Braintree",preference_source:"braintree_credentials").save

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. Before proceeding to checkout, ensure you've created a Braintree configuration for your store:

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. ClickSave changes to save

Or from the console:

Spree::Store.all.eachdo |store|store.create_braintree_configuration(credit_card:true,paypal:true,apple_pay:true,venmo:true)end

4. If your site uses an unmodifiedsolidus_frontend, it should now be ready to take payments. See below for more information on configuring Paypal and ApplePay.

5. Typical Solidus sites will have customized frontend code, and may require some additional work. Uselib/views/frontend/spree/checkout/payment/_paypal_braintree.html.erb andapp/assets/javascripts/solidus_paypal_braintree/checkout.js as models.

You'll need the following:

• A device running iOS 10+.
• An Apple Pay sandbox account. You can check out Apple'sdocumentation 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 arelots 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 atest card in its Wallet

The following is a relatively bare-bones implementation to enable Apple Pay on the frontend:

<% if current_store.braintree_configuration.apple_pay? %><scriptsrc="https://js.braintreegateway.com/web/3.84.0/js/apple-pay.min.js"></script><buttonid="apple-pay-button"class="apple-pay-button"></button><script>varapplePayButtonElement=document.getElementById('apple-pay-button');varapplePayOptions={paymentMethodId:<%=id%>,      storeName: "<%=current_store.name%>",      orderEmail: "<%=current_order.email%>",      amount: "<%=current_order.total%>",      shippingContact:{emailAddress:'<%= current_order.email %>',givenName:'<%= address.firstname %>',familyName:'<%= 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 %>'}};varbutton=newSolidusPaypalBraintree.createApplePayButton(applePayButtonElement,applePayOptions);button.initialize();</script><% end %>

Braintree has someexcellent documentation on what you'll need to do to get Apple Pay up and running.

For additional information check outApple's documentation andBraintree's documentation.

There are two ways for users to use Venmo for payments:

1. Braintree's native Venmo integration, which supports vaulting of payment sources.See more.
2. Through the PayPal buttons when using checkout flow, therefore doesn't support vaulting.See more.

To add Venmo for PayPal,see here

• Only available as a financing option on the checkout page; Venmo currently does not support shipping callbacks so it cannot be on the cart page.
• Currently available to US merchants and buyers and there are also other prequisites.
  • https://developer.paypal.com/docs/business/checkout/pay-with-venmo/#eligibility
  • https://developer.paypal.com/braintree/articles/guides/payment-methods/venmo#availability

1. Enable Venmo in yourBraintree account
2. Enable Venmo in yourstore's Braintree configuration.
3. Ensure your Braintree API credentials are in the Braintree payment method.
4. Set your Braintree payment method's preference ofpreferred_venmo_new_tab_support tofalse if your store cannot handle Venmo returning a user to a new tab after payment. This may be because your website is a single-page applicaiton (SPA). On mobile, the user may be returned to the same store tab if their browser supports it, otherwise a new tab will be created (unless you have this preference asfalse).

By default your default Venmo business account will be used. If you want to use a non-default profile, overridetheSolidusPaypalBraintree::Gateway#venmo_business_profile_id method with its id.

Test the following scenarios:

• Ensure the Venmo checkout button opens a modal with a QR code and is closeable.
• Do a full transaction
• Ensure that you can also save the payment source in the user wallet.
• Ensure the saved Venmo wallet payment source loads in the partial correctly.
• Ensure the saved Venmo payment source can be reused for another order.
• Test doing transactions on the admin
• Testing voiding and refunding Venmo transactions

You'll need the Venmo app in order to fully test the integration. However, if you are outside of the US, this is not an option. You can fake the tokenization by:

• Altering thevenmo_button.js file to call thehandleVenmoSuccess function instead of tokenizing; or
• Manually doing its steps:
  1. Update the #venmo_payment_method_nonce hidden input value to "fake-venmo-account-nonce".
  2. Remove the disabled attributes from the venmo-fields inputs.
  3. If you have hosted fields on the page (credit_card enabled in Braintree configuration), remove it's submit button listener:$('#checkout_form_payment').off('submit');

More information

In yourstore's Braintree configuration, you can customize the Venmo checkout button's color and width.

Note, other images such as Venmo's full logo and shortened "V" logo are included in the assets.

Ensure that you followVenmo's guidelines when making other style changes, otherwise failing to comply can lead to an interruption of your Venmo service.

A default checkout view is provided that will display PayPal as a payment option.It will only be displayed if theSolidusPaypalBraintree::Gateway paymentmethod is configured to display on the frontend and PayPal is enabled in thestore's configuration.

You can find button configuration options in/solidus_paypal_braintree/configurations/list if you want to change the color,shape, layout, and a few other options. For more information check outPayPal's documentation.

Keep in mind that:

• paypal_button_tagline does not work when thepaypal_button_layout is set tovertical, and will be ignored; and
• paypal_button_layout ofhorizontal limits financing options/buttons to 2, where asvertical is 4.Other available financing options after the limit will not be rendered in the PayPal's iframe DOM.

The checkout viewinitializes the PayPal buttonusing theVault flow,which allows the source to be reused. Please note that PayPal messaging is disabled with vault flow. If you want, you can useCheckout with PayPalinstead, which doesn't allow you to reuse sources but allows your customers to pay with their PayPalbalance and with PayPal financing options (see setup instructions). More information about otherfinancing options below.

If you are creating your own checkout view or would like to customize theoptions that get passed to tokenize, you can initialize your own using theCreatePaypalButton JS object:

varpaypalOptions={// your configuration options here}varbutton=newSolidusPaypalBraintree.createPaypalButton(document.querySelector("#your-button-id"),paypalOptions);button.initialize();

A PayPal button can also be included on the cart view to enable express checkouts:

render"spree/shared/paypal_cart_button"

When using 'checkout'paypal flow and not 'vault'. Your customers can have different finance options such as

• paylater
• Venmo

Venmo is currently available to US merchants and buyers. There are also otherprequisites.

By default, the extension and Braintree will try to render a Venmo button to buyers when prequisites are met and you have enabled it in your Braintree account).

Set the SolidusPaypalBraintreePaymentMethodenable_venmo_funding preference to:

• enabled, available as a PayPal funding option (if other prequisites are met); or
• disabled (default).

Note, Venmo is currently only available as a financing option on the checkout page; Venmo currently does not support shipping callbacks so it cannot be on the cart page.

As Venmo is only available in the US, you may want to mock your location for testing

PayPal offers anon-site messaging component to notify the customer that there are financing options available. This component is included in both the cart and checkout partials, but is disabled by default. To enable this option, you'll need to use thecheckout flow, and set thepaypal button messaging option totrue in your Braintree configuration.

You can also include this view partial to implement this messaging component anywhere - for instance, on the product page:

render"spree/shared/paypal_messaging, options: {total: @product.price, placement: "product", currency: 'USD'}"

While we provide the messaging component on the payment buttons for cart and checkout, you're expected to move these to where they make the most sense for your frontend. PayPal recommends keeping the messaging directly below wherever the order or product total is located.

If your store requires thephone number into user addressesyou'll need to configure PayPal to return the phone back when it returns theaddress used by the user:

1. Log into your PayPal account
2. Hover over the user in the Navbar to get the dropdown
3. Click on Account Settings
4. In the left panel under Products & Services, click Website Payments
5. Click Update for Website Preferences
6. Set Contact Telephone toOn (Required Field) orOn (Optional Field)

Using the optionOff will not make the address valid and will raise avalidation error.

For fraud prevention, PayPal recommends using a data collector to collect deviceinformation, which we've included by default. You're able to turn off the PayPaldata collector on the payment method preferences if you desire. If you usestatic preferences, adduse_data_collector: false to your initializer.

The payment method also provides an optional preferencemerchant_currency_map.This preference allows users to provide different Merchant Account Ids fordifferent currencies. If you only plan to accept payment in one currency, thedefaut Merchant Account Id will be used and you can omit this option.An example of setting this preference can be foundhere.

In addition to this, you can also specify different PayPal accounts for eachcurrency by using thepaypal_payee_email_map preference. If you only wantto use one PayPal account for all currencies, then you can ignore this option.You can find an example of setting this preferencehere.

The migrations for this gem will add a default configuration to all stores thathas each payment type disabled. It also adds abefore_create callback toSpree::Store that builds a default configuration. You can customize thedefault configuration that gets created by overriding the privatebuild_default_configuration method onSpree::Store.

You can style the Braintree credit card fields by using thecredit_card_fields_style preference on the payment method. Thecredit_card_fields_style will be passed to thestyle key when initializing the credit card fields. You can find more information about styling hosted fields can be foundhere.

You can also use theplaceholder_text preference on the payment method to set the placeholder text you'd like to use for each of the hosted fields. You'll pass the field name in as the key, and the placeholder text you'd like to use as the value. For example:

{number:"Enter card number",cvv:"Enter CVV",expirationDate:"mm/yy"}

This gem supports3D Secure 2,which satisfies theStrong Customer Authentication (SCA)requirements introduced by PSD2.

3D Secure can be enabled from Solidus Admin -> Braintree (left-side menu) ->tick3D Secure checkbox.

Once enabled, you can use the following card numbers to test 3DS 2 on yourclient side in sandbox:https://developers.braintreepayments.com/guides/3d-secure/migration/javascript/v3#client-side-sandbox-testing.

To run the specs it is required to set the Braintree test account data in these environment variables:BRAINTREE_PUBLIC_KEY,BRAINTREE_PRIVATE_KEY,BRAINTREE_MERCHANT_ID andBRAINTREE_PAYPAL_PAYEE_EMAIL

First bundle your dependencies, then runrake.rake will default to building the dummy app if it does not exist, then it will run specs, andRubocop static code analysis. The dummy app can be regenerated by usingrake test_app.

bundlebundleexec 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'

PayPal looks at the buyer's IP geolocation to determine what funding sources should be available to them. Because for example, Venmo is currently only available to US buyers. Because of this, you may want to pretend that you are from US so you can check if Venmo is correctly integrated for these customers. To do this, set the payment method's preference offorce_buyer_country to "US". See more information about preferences above.

This preference has no effect on production.

To run this extension in a sandboxed Solidus application, you can runbin/sandbox. The path forthe sandbox app is./sandbox andbin/rails will forward any Rails commands tosandbox/bin/rails.

Here's an example:

$ bin/rails server=> Booting Puma=> Rails 7.0.4 application starting in development* Listening on tcp://127.0.0.1:3000Use Ctrl-C to stop

Please refer to the dedicatedpage on Solidus wiki.

Copyright (c) 2016-2020 Stembolt and others contributors, released under the New BSD License