Braintree

Payment Instruments

Aurora has support for Braintree's platform and provides example implementation for the following payment instruments.

• Debit/Credit Cards via Hosted Fields (PCI compliant card payments with full UI control)
• PayPal
• PayPal PayLater
• Google Pay
• Apple Pay

Aurora also provides example implementations of utilising Braintree's platform as a checkout replacement with the following instrument types available on the basket.

• PayPal
• PayPal PayLater
• Google Pay
• Apple Pay

Note that Braintree supports multiple more payment instruments such as Samsung Pay, Venmo or Local payment methods which Aurora does not provide example implementations of, however, due to the nature of Braintree's agnostic backend services these payment instruments can be implemented without needing Aurora to change.

The Aurora Demo templates utilise Braintree's Hosted Fields and individual Payment Instrument implementations which gives the merchant full control over the UI and UX. Drop-in UI is not provided within the Aurora Demo templates, however, it can be implemented on the front-end templates using the Aurora Demo implementation as inspiration.

Braintree Transaction Processing

Some Braintree transactions will initially enter a PENDING state, notably payment, release and refund transactions. Pending transactions will be resolved at a future date and are dependent on Braintree's batch settlement process.

Refunds made against a transaction that is currently PENDING will initially enter a state ON_HOLD. The system will process the refund request once the PENDING payment has been settled by Braintree.

Setup

Aurora Service Deployment

The Braintree Integration uses the Aurora Microservice (MS) framework, and as such must be deployed in advance of its full activation on your store.

Doing this requires a one-off development to configure your server(s) to provide the service, after which, you can then configure the integration at your own leisure.

If you have not yet had (or do not know if you have had) the Braintree MS set up and configured for your store, then please contact your agency for more details regarding how to get this done.

Initial Requirements

To make use of the Braintree payment gateway integration you must have ready the following details

• Braintree merchant ID
• Braintree merchant account ID - this will use the default gateway account if left blank*
• Braintree API public key
• Braintree API private key

* Please see the notes on Braintree's Merchant Account ID

Aurora Store Configuration

Once the Braintree MS is deployed, you will be able to configure it in the Aurora Admin UI, setting it ready to take payments for your store(s).

Enable the Braintree MS Service

Store > Settings > Feeds > Microservice > Proxy Braintree

This 'visibility behaviour' is enforced entirely within the Aurora front-end templates and so is the default behaviour offered by the Aurora Demo Example front-end templates, but may not be how your own front-end templates are configured.

This presents itself as the $config.microservice_proxybraintree_live configuration in the templates allowing you to show and hide easily.

Enable on the Checkout

Store > Settings > Payment Providers

This 'visibility behaviour' is enforced entirely within the Aurora front-end templates and so is the default behaviour offered by the Aurora Demo Example front-end templates, but may not be how your own front-end templates are configured.

This presents itself as the $accepted_payment_types["proxy-braintree"] configuration in the templates if enabled.

Microservice Configuration

Store > Plugins > Braintree Configure

Merchant Account IDs

A quick note on Braintree Merchant account IDs within the plugin settings. You may leave these blank and Braintree will use the default merchant account. However, we have noted that there is an issue at the time of writing with Braintree where this doesn't happen for PayPal PayLater. If you intend to take payment using PayPal PayLater, please ensure you have set the Merchant Account ID for every chargeable currency.

Template Integration

Checkout

To integrate Braintree on the checkout, there are a few front-end template changes to make. Below are the templates and assets used within the Aurora Demo templates, which can be used as a reference to implement this within your store(s) front-end templates.

Assets and Templates

These templates are developed for the payment instruments defined at the top of this article. Further payment instruments such as Samsung Pay, Venmo etc will require additional front-end template development utilising the Braintree documentation guides.

Please note that these are all provided with a view to having them working within Aurora Demo. As such, if you have customised your templates and their supporting JavaScript files away from the standard Aurora Demo implementations, you may need to use these files for 'inspiration' only.

Aurora Braintree JavaScript Library

The library is provided as an example implementation for the payment instruments defined at the top of this article. If this meets the requirements of your store(s) and front-end templates you may use it directly, otherwise you are free to copy this or roll your own implementation as you see fit.

The library itself exposes a vast array of configuration options. Each payment instrument has its own configuration section which allows enabling, disabling and overriding certain aspects of the implementation.

The example configuration is below, this enables all payment instruments defined in this article to provide configuration for the checkout.

let amountTotal = {$payment_total_chargeable};
let currency = '{$currency_iso_chargeable}';

{literal}
$(document).ready(function () {
  try {
    window.BraintreePayments.initPaymentMethods({
      amountTotal: amountTotal,
      currency: currency,
      container: $('#payment_methods_fieldset'),
      form: $('#checkout_form'),
      checkoutButton: $('.checkout_placeyourorder_container').first(),
      nonceField: $('#braintree-payment-nonce'),
      deviceDataField: $('#braintree-device-data'),
      addressOverrideField: $('#braintree-address-override'),
      genericErrorMessage: 'There was a problem processing your payment, please check your card details and try again',
      methodsContainer: $('#proxy-braintree-payment-method-container'),
      methods: {
        hostedFields: {
          enabled: true,
          trigger: $('#proxy-braintree-hosted-fields'),
          container: $('#braintree-hosted-fields'),
          vaultedCardsContainer: $('#braintree-stored-cards-container'),
          vaultedCardHtmlTemplate: $('#braintree-stored-card-template'),
          vaultedCardContainerSelector: '.braintree-vaulted-card',
          vaultedCardTriggerSelector: '.braintree-vaulted-card-trigger',
          vaultedCardRemoveTriggerSelector: '.braintree-vaulted-card-remove',
          vaultCardCheckboxContainer: $('#braintree-save-card'),
          hostedFieldSelector: '.braintree-hosted-field',
          styles: {
            'input': {
              'font-size': '11px',
              'transition': 'color 0.1s',
            },
            // Style the text of an invalid input
            'input.invalid': {
              'color': '#E53A40'
            },
          }
        },
        paypal: {
          enabled: true,
          payLaterEnabled: true,
          trigger: $('#proxy-braintree-paypal'),
          container: $('#braintree-paypal-container'),
          buttonSelector: '#paypal-button',
          payLaterButtonSelector: '#paypal-paylater-button',
          sdkOptions: {
            currency: currency,
          },
          createPaymentOptions: {
            currency: currency,
            enableShippingResolver: () => {
              let selectedShipment = $("input:radio[name='shiptowhere']:checked").val();
              return !['store', 'collect_plus'].includes(selectedShipment);
            }
          },
          buttonConfig: {
            style: {
              color: 'black'
            }
          }
        },
        googlepay: {
          enabled: true,
          trigger: $('#proxy-braintree-googlepay'),
          container: $('#braintree-googlepay-container')
        },
        applepay: {
          enabled: true,
          button: $('#braintree-applepay-button'),
          trigger: $('#proxy-braintree-applepay'),
          container: $('#braintree-applepay-container'),
        }
      }
    });
  } catch (err) {
    BraintreePayments.showError(err);
  }

  $.frontend.events.on('braintree.error', (_, err) => {
    err = (typeof err === 'object' && err !== null) ? err.errorMessage || '' : err;
    let errorMessage = err || BraintreePayments.config.genericErrorMessage;
    $.frontend.alert(errorMessage, 'Payment Error');
  });
});
{/literal}

A lot of the configuration is wiring the HTML to the JS library so it's able to render and interact with the page. Other options proxy through the Braintree or payment instruments SDK providing the ability to change styles, provide callbacks and or alter functionality.

Basket

To integrate Braintree into the basket, there are a few front-end template changes to make. Below are the templates and assets used within Aurora Demo which can be used as a reference to implement this within your store(s) front-end templates.

A key difference to the checkout integration is that the payment instrument becomes a checkout replacement, e.g. PayPal will be responsible for capturing the address information along with the payment.

Assets and Templates

These templates are developed for the payment instruments defined at the top of this article. Further payment instruments such as Samsung Pay, Venmo etc will require additional front-end template development utilising the Braintree documentation guides.

Please note that these are all provided with a view to having them working within the Aurora Demo. As such, if you have customised your templates and their supporting JavaScript files away from the standard Aurora Demo implementations, you may need to use these files for 'inspiration' only.

Aurora Braintree JavaScript Library

The checkout replacement library utilised on the basket page is the exact same as the checkout library, we provide it with a slightly varied configuration.

The example configuration is below, this enables all payment instruments defined in this article to provide configuration for the basket.

let amountTotal = {$paymentCostChargeable};
let currency = '{$currency_iso_chargeable}';
let userReference = '{$userReference}';

{literal}
$(document).ready(function () {
  try {
    window.BraintreePayments.initPaymentMethods({
      isCheckoutReplacement: true,
      amountTotal: amountTotal,
      currency: currency,
      userReference: userReference,
      container: $('#basket-braintree-payments'),
      form: $('#basket-braintree-payments'),
      nonceField: $('#braintree-payment-nonce'),
      deviceDataField: $('#braintree-device-data'),
      billingAddressField: $('#braintree-billing-address'),
      shippingAddressField: $('#braintree-shipping-address'),
      shippingOptionDetailsField: $('#braintree-shipping-details'),
      shipToWhereField: $('#braintree-shiptowhere'),
      deliveryOptionField: $('#braintree-delivery-option'),
      storeIdField: $('#braintree-store-id'),
      emailField: $('#braintree-email'),
      genericErrorMessage: 'There was a problem processing your payment, please check your card details and try again',
      methodsContainer: $('#proxy-braintree-payment-method-container'),
      methods: {
        paypal: {
          enabled: true,
          payLaterEnabled: true,
          container: $('#braintree-paypal-container'),
          buttonSelector: '#paypal-button',
          payLaterButtonSelector: '#paypal-paylater-button',
          shippingAddressEditable: true,
          sdkOptions: {
            currency: currency,
          },
          createPaymentOptions: {
            currency: currency,
          },
          buttonConfig: {
            style: {
              color: 'black'
            }
          }
        },
        googlepay: {
          enabled: true,
          container: $('#braintree-googlepay-container'),
        },
        applepay: {
          enabled: true,
          button: $('#braintree-applepay-button'),
          container: $('#braintree-applepay-container'),
        }
      }
    });
  } catch (err) {
    BraintreePayments.showError(err);
  }

  $.frontend.events.on('braintree.error', (_, err) => {
    err = (typeof err === 'object' && err !== null) ? err.errorMessage || '' : err;
    let errorMessage = err || BraintreePayments.config.genericErrorMessage;
    $.frontend.alert(errorMessage, 'Payment Error');
  });
});
{/literal}

Card Payments

To integrate card payments using the AuroraBraintree JavaScript Library you will need to configure the options below when calling initPaymentMethods

PayPal Payments

To integrate PayPal payments using the AuroraBraintree JavaScript Library you will need to configure the options below when calling initPaymentMethods

Note: To integrate PayPal's billing address you will need to request access to the customers billing address from PayPal.

After doing this the JS library will handle the address automatically on the basket page. The checkout page will require the configuring of the addressOverrideField value which you can see an example of in the Aurora Demo templates.

Apple Pay Payments

To integrate Apple Pay payments using the AuroraBraintree JavaScript Library you will need to configure the options below when calling initPaymentMethods

Google Pay Payments

To integrate Google Pay payments using the AuroraBraintree JavaScript Library you will need to configure the options below when calling initPaymentMethods

Fraud Protection

Braintree has two levels of fraud protection that are managed entirely from the Braintree Dashboard. Your store is only required to send device data to Braintree when handling transactions to allow these services to work.

If you're using the Aurora Demo templates and JavaScript Library then the configuration required is:

Payment Vaulting (Saved Cards)

You can securely provide saved cards functionality on your store checkout utilising Braintree's Vault.

To do this, enable vaulting in the Braintree plugin settings, if you're using the example JS library this will utilise this setting to render the applicable elements. You will however need to configure the library to understand how to render saved cards. An example of this is visible in the Aurora Demo templates. The relevant configuration values are:

Note: The example JS library restricts saved cards to only hosted field (card) payments. While it is possible to utilise the Braintree Vault for other payment methods they are not applicable to most stores, e.g. Apple Pay and Google Pay is only possible for recurring payments while PayPal requires a billing agreement to be put in place.

ThreeDS

Most if not all stores will utilise 3DS. If you're utilising the example JS library you do not need to do anything to have 3DS run for the payment instruments that support it, (card and Google Pay).

If you wish to override this behaviour then you would have to change the configuration value for the methods option threeDS.

In the MS plugin settings, there are two important options regarding 3DS.

Require 3D Secure

This option simply informs Braintree that 3DS was required for this transaction, if it did not happen then we don't want the transaction to proceed. This will result in an error if for whatever reason the customer circumvented the 3DS on the storefront. See Requiring 3D Secure for further details.

Require Liability Shift on 3DSecure Transactions

Before a transaction is created with Braintree we fetch the 3DS information. This allows us to check if the liability shift was possible and decide if we want to continue with the transaction.

For information on what Liability Shift is and why you may want to utilise this setting check out the 3DS Braintree docs.

Error Handling

The example JS library will emit a braintree.error event with an error object or string. You can see in the code examples how this is handled in the Aurora Demo templates and you are free to use this event to handle the error how you see fit.

In the case of an unexpected error, the configuration option genericErrorMessage allows you to pass a fallback message which will come into your error handler.

Site Text

User error messages from the Aurora payment service that can be changed and translated using the Aurora Site Text system.

The "part" of the site text is generally dynamic from Braintree as we proxy those errors back into Aurora from the plugin. This allows you to be very specific about the error messages to prevent the need of creating generic errors, for example, "your transaction failed", instead you could use "Your account had insufficient funds, please try another card" as you know it won't get used for another error type.

Site Text is managed in the admin inside Content > Site Text and you will be able to filter your cached messages by braintree .

It's recommended you thoroughly test all error cases in order to create your translations ready for go-live.

Testing

Testing certain scenarios is done with various methods, card numbers, transaction amounts, billing addresses etc. Below is a few quick links.

Transaction Amounts
Valid Cards
Error Cards
Fraud Cards
AVS

Google Pay

Google Pay can be tested using their test card suite. Signing up to the Test Card Google Group replaces all your accounts cards with test cards and test data.

Apple Pay

Testing Apple Pay requires an Apple device with TouchID or FaceID, this could be a newer Mac, iPhone, iPad etc.

On this device, you will need to sign in to the Apple Account used for sandbox testing.

Once signed in Safari will use this account to provide test cards.

See more in the Apple Pay docs

PayPal

Linking a PayPal Sandbox account within the Braintree Control Panel allows usage of PayPal's testing processes

Backend Payments

Braintree is an optional payment method within the admin interface of your store. When completing an order through the admin you will have the option to pay via Braintree which will provide a hosted fields implementation to capture payment. This follows all the MS plugin settings except for 3DS which is not applicable when the customer is not present.

Known Limitations

Basket Payment Shipping Options

When checking out on the basket page using PayPal, Apple Pay or Google Pay with the example JS library, the only shipping method shown will be the one currently in place.

The customer can select and alter the shipping method on the basket page and this will reflect when next opening the payment instruments sheet but they will only have the single option in the sheet to select.

We must stress this is not due to the inability to do this but more the effort to implement. If you would like to provide this ability to your customers you should look at the documentation of each provider and implement the callbacks required. You may also want to override the default shippingOptionsResolver implementation with your own using the example JS library as inspiration.

PayPal
Having provided multiple shipping methods to the PayPal SDK then using the configuration methods.paypal.buttonConfig you can supply callbacks to implement shipping method changes.

Apple Pay
The Apple Pay implementation is not currently extendable to provide this functionality. In this case after providing multiple shipping methods via the shipping option resolver you would require overwriting the session.onshippingmethodselected which you can see in the example JS library and Apple Pay docs.

Google Pay
The Google Pay implementation is not currently extendable to provide this functionality. In this case after providing multiple shipping methods via the shipping option resolver you would require overwriting the new google.payments.api.PaymentsClient call to implement the paymentDataCallbacks as described in the Google Pay docs.

Basket Components and Third Party Delivery Store Service Support

Aurora supports a number of third party delivery store services, which integrate with services such as Doddle and DPD.

The Braintree basket payment buttons do not currently work with all services.

The following store delivery options are supported with Braintree basket payment buttons:

• Aurora customer store locations
• Collect+