Skip to main content

BraintreePlugin

BraintreePlugin​

@vendure/payments-pluginbraintree.plugin.ts

This plugin enables payments to be processed by Braintree, a popular payment provider.

Requirements​

  1. You will need to create a Braintree sandbox account as outlined in https://developers.braintreepayments.com/start/overview.
  2. Then install braintree and @types/braintree from npm. This plugin was written with v3.x of the Braintree lib. 
    yarn add @vendure/payments-plugin braintree
    yarn add -D @types/braintree
    or 
    npm install @vendure/payments-plugin braintree
    npm install -D @types/braintree

Setup​

  1. Add the plugin to your VendureConfig plugins array: 
    import { BraintreePlugin } from '@vendure/payments-plugin/package/braintree';
    import { Environment } from 'braintree';

    // ...

    plugins: [
      BraintreePlugin.init({
        environment: Environment.Sandbox,
        // This allows saving customer payment
        // methods with Braintree (see "vaulting"
        // section below for details)
        storeCustomersInBraintree: true,
      }),
    ]
  2. Create a new PaymentMethod in the Admin UI, and select "Braintree payments" as the handler.
  3. Fill in the Merchant ID, Public Key & Private Key from your Braintree sandbox account.

Storefront usage​

The plugin is designed to work with the Braintree drop-in UI. This is a library provided by Braintree which will handle the payment UI for you. You can install it in your storefront project with:

yarn add braintree-web-drop-in
# or
npm install braintree-web-drop-in

The high-level workflow is:

  1. Generate a "client token" on the server by executing the generateBraintreeClientToken mutation which is exposed by this plugin.
  2. Use this client token to instantiate the Braintree Dropin UI.
  3. Listen for the "paymentMethodRequestable" event which emitted by the Dropin.
  4. Use the Dropin's requestPaymentMethod() method to get the required payment metadata.
  5. Pass that metadata to the addPaymentToOrder mutation. The metadata should be an object of type { nonce: string; }

Here is an example of how your storefront code will look. Note that this example is attempting to be framework-agnostic, so you'll need to adapt it to fit to your framework of choice.

// The Braintree Dropin instance
let dropin: import('braintree-web-drop-in').Dropin;

// Used to show/hide a "submit" button, which would be bound to the
// `submitPayment()` method below.
let showSubmitButton = false;

// Used to display a "processing..." spinner
let processing = false;

//
// This method would be invoked when the payment screen is mounted/created.
//
async function renderDropin(order: Order, clientToken: string) {
  // Lazy load braintree dropin because it has a reference
  // to `window` which breaks SSR
  dropin = await import('braintree-web-drop-in').then((module) =>
    module.default.create({
      authorization: clientToken,
      // This assumes a div in your view with the corresponding ID
      container: '#dropin-container',
      card: {
        cardholderName: {
            required: true,
        },
        overrides: {},
      },
      // Additional config is passed here depending on
      // which payment methods you have enabled in your
      // Braintree account.
      paypal: {
        flow: 'checkout',
        amount: order.totalWithTax / 100,
        currency: 'GBP',
      },
    }),
  );

  // If you are using the `storeCustomersInBraintree` option, then the
  // customer might already have a stored payment method selected as
  // soon as the dropin script loads. In this case, show the submit
  // button immediately.
  if (dropin.isPaymentMethodRequestable()) {
    showSubmitButton = true;
  }

  dropin.on('paymentMethodRequestable', (payload) => {
    if (payload.type === 'CreditCard') {
      showSubmitButton = true;
    }
    if (payload.type === 'PayPalAccount') {
      this.submitPayment();
    }
  });

  dropin.on('noPaymentMethodRequestable', () => {
    // Display an error
  });
}

async function generateClientToken() {
  const { generateBraintreeClientToken } = await graphQlClient.query(gql`
    query GenerateBraintreeClientToken {
      generateBraintreeClientToken
    }
  `);
  return generateBraintreeClientToken;
}

async submitPayment() {
  if (!dropin.isPaymentMethodRequestable()) {
    return;
  }
  showSubmitButton = false;
  processing = true;

  const paymentResult = await dropin.requestPaymentMethod();

  const { addPaymentToOrder } = await graphQlClient.query(gql`
    mutation AddPayment($input: PaymentInput!) {
      addPaymentToOrder(input: $input) {
        ... on Order {
          id
          payments {
            id
            amount
            errorMessage
            method
            state
            transactionId
            createdAt
          }
        }
        ... on ErrorResult {
          errorCode
          message
        }
      }
    }`, {
      input: {
        method: 'braintree', // The code of you Braintree PaymentMethod
        metadata: paymentResult,
      },
    },
  );

  switch (addPaymentToOrder?.__typename) {
      case 'Order':
          // Adding payment succeeded!
          break;
      case 'OrderStateTransitionError':
      case 'OrderPaymentStateError':
      case 'PaymentDeclinedError':
      case 'PaymentFailedError':
        // Display an error to the customer
        dropin.clearSelectedPaymentMethod();
  }
}

Storing payment details (vaulting)​

Braintree has a vault feature which allows the secure storage of customer's payment information. Using the vault allows you to offer a faster checkout for repeat customers without needing to worry about how to securely store payment details.

To enable this feature, set the storeCustomersInBraintree option to true.

BraintreePlugin.init({
  environment: Environment.Sandbox,
  storeCustomersInBraintree: true,
}),

Since v1.8, it is possible to override vaulting on a per-payment basis by passing includeCustomerId: false to the generateBraintreeClientToken mutation:

const { generateBraintreeClientToken } = await graphQlClient.query(gql`
  query GenerateBraintreeClientToken($includeCustomerId: Boolean) {
    generateBraintreeClientToken(includeCustomerId: $includeCustomerId)
  }
`, { includeCustomerId: false });

as well as in the metadata of the addPaymentToOrder mutation:

const { addPaymentToOrder } = await graphQlClient.query(gql`
  mutation AddPayment($input: PaymentInput!) {
    addPaymentToOrder(input: $input) {
      ...Order
      ...ErrorResult
    }
  }`, {
    input: {
      method: 'braintree',
      metadata: {
        ...paymentResult,
        includeCustomerId: false,
      },
    }
  );
Signature
class BraintreePlugin {
    static options: BraintreePluginOptions = {};
    init(options: BraintreePluginOptions) => Type<BraintreePlugin>;
}

options​

property
BraintreePluginOptions

init​

method
(options: BraintreePluginOptions) => Type<BraintreePlugin>

BraintreePluginOptions​

@vendure/payments-plugintypes.ts

Options for the Braintree plugin.

Signature
interface BraintreePluginOptions {
    environment?: Environment;
    storeCustomersInBraintree?: boolean;
    extractMetadata?: (transaction: Transaction) => PaymentMetadata;
}

environment​

property
Environment
default:
Environment.Sandbox

The Braintree environment being targeted, e.g. sandbox or production.

storeCustomersInBraintree​

property
boolean
default:
false

If set to true, a Customer object will be created in Braintree, which allows the secure storage ("vaulting") of previously-used payment methods. This is done by adding a custom field to the Customer entity to store the Braintree customer ID, so switching this on will require a database migration / synchronization.

Since v1.8, it is possible to override vaulting on a per-payment basis by passing includeCustomerId: false to the generateBraintreeClientToken mutation.

extractMetadata​

property
v1.7.0
(transaction: Transaction) => PaymentMetadata

Allows you to configure exactly what information from the Braintree Transaction object (which is returned by the transaction.sale() method of the SDK) should be persisted to the resulting Payment entity metadata.

By default, the built-in extraction function will return a metadata object that looks like this:

Example

const metadata = {
  "status": "settling",
  "currencyIsoCode": "GBP",
  "merchantAccountId": "my_account_id",
  "cvvCheck": "Not Applicable",
  "avsPostCodeCheck": "Not Applicable",
  "avsStreetAddressCheck": "Not Applicable",
  "processorAuthorizationCode": null,
  "processorResponseText": "Approved",
  // for Paypal payments
  "paymentMethod": "paypal_account",
  "paypalData": {
    "payerEmail": "michael-buyer@paypalsandbox.com",
    "paymentId": "PAYID-MLCXYNI74301746XK8807043",
    "authorizationId": "3BU93594D85624939",
    "payerStatus": "VERIFIED",
    "sellerProtectionStatus": "ELIGIBLE",
    "transactionFeeAmount": "0.54"
  },
  // for credit card payments
  "paymentMethod": "credit_card",
  "cardData": {
    "cardType": "MasterCard",
    "last4": "5454",
    "expirationDate": "02/2023"
  }
  // publicly-available metadata that will be
  // readable from the Shop API
  "public": {
    "cardData": {
      "cardType": "MasterCard",
      "last4": "5454",
      "expirationDate": "02/2023"
    },
    "paypalData": {
      "authorizationId": "3BU93594D85624939",
    }
  }
}