Hosted Fields

Setup and Integration

braintree.hostedFields.createAnchorIcon

Set up the SDK and create a client. If you use other payment method types, such as PayPal, then you can re-use the same client.

Pass the client to braintree.hostedFields.create within the options object:

  1. Callback
  2. Promise
braintree.client.create({
  authorization: 'CLIENT_AUTHORIZATION'
}, function (clientErr, clientInstance) {
  if (clientErr) {
    // Handle error in client creation
    return;
  }

  var options = {
    client: clientInstance,
    styles: {
      /* ... */
    },
    fields: {
      /* ... */
    }
  };

  braintree.hostedFields.create(options, function (hostedFieldsErr, hostedFieldsInstance) {
    if (hostedFieldsErr) {
      // Handle error in Hosted Fields creation
      return;
    }

    // Use the Hosted Fields instance here to tokenize a card
  });
});

See the braintree.hostedFields.create reference for details.

Basic integrationAnchorIcon

To start using Hosted Fields, you need to create a basic HTML checkout form. You will need to define <div> containers in place of the <input> elements that would normally comprise your credit card input fields (card number, expiration date, and CVV).

Note

Depending on your AVS settings you may also want to include a postal/ZIP code field for later use in server-side Transaction calls.

Here's a sample form that uses Hosted Fields:

  1. HTML
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Checkout</title>
  </head>
  <body>
    <form action="/" id="my-sample-form" method="post">
      <label for="card-number">Card Number</label>
      <div id="card-number"></div>

      <label for="cvv">CVV</label>
      <div id="cvv"></div>

      <label for="expiration-date">Expiration Date</label>
      <div id="expiration-date"></div>

      <input type="submit" value="Pay" disabled />
    </form>
<script src="https://js.braintreegateway.com/web/3.111.0/js/client.min.js"></script>
<script src="https://js.braintreegateway.com/web/3.111.0/js/hosted-fields.min.js"></script>
    <script>
      var form = document.querySelector('#my-sample-form');
      var submit = document.querySelector('input[type="submit"]');

      braintree.client.create({
        authorization: 'CLIENT_AUTHORIZATION'
      }, function (clientErr, clientInstance) {
        if (clientErr) {
          console.error(clientErr);
          return;
        }

        // This example shows Hosted Fields, but you can also use this
        // client instance to create additional components here, such as
        // PayPal or Data Collector.

        braintree.hostedFields.create({
          client: clientInstance,
          styles: {
            'input': {
              'font-size': '14px'
            },
            'input.invalid': {
              'color': 'red'
            },
            'input.valid': {
              'color': 'green'
            }
          },
          fields: {
            number: {
              container: '#card-number',
              placeholder: '4111 1111 1111 1111'
            },
            cvv: {
              container: '#cvv',
              placeholder: '123'
            },
            expirationDate: {
              container: '#expiration-date',
              placeholder: '10/2022'
            }
          }
        }, function (hostedFieldsErr, hostedFieldsInstance) {
          if (hostedFieldsErr) {
            console.error(hostedFieldsErr);
            return;
          }

          submit.removeAttribute('disabled');

          form.addEventListener('submit', function (event) {
            event.preventDefault();

            hostedFieldsInstance.tokenize(function (tokenizeErr, payload) {
              if (tokenizeErr) {
                console.error(tokenizeErr);
                return;
              }

              // If this was a real integration, this is where you would
              // send the nonce to your server.
              console.log('Got a nonce: ' + payload.nonce);
            });
          }, false);
        });
      });
    </script>
  </body>
</html>

In this example, when the customer submits the form, Hosted Fields will securely collect and attempt to tokenize the card details. If tokenization succeeds, your callback will receive a nonce. Send this nonce to your server, which you can use to make a transaction. If you want to store this card in your Vault, Braintree strongly recommends verifying the card while vaulting.

If tokenization fails, you will receive a BraintreeError with pertinent details. For a detailed example of handling tokenization errors with Hosted Fields, see our client reference.

CustomizationAnchorIcon

You can find all the Hosted Fields configuration options in the JavaScript reference.