Checkout UIs/
Hosted Fields/
Setup and Integration

Setup and Integration

Use Hosted Fields to build secure, customizable card input fields for your checkout form, so you can collect and tokenize card details without your server directly handling raw card data.

PrerequisitesAnchorIcon

Before you create Hosted Fields, complete the following:

  • Set up the SDK and create a client using a CLIENT-AUTHORIZATION.
  • Define <div> container elements in your checkout form for each card input field you plan to use, such as card number, expiration date, and CVV.

braintree.hostedFields.createAnchorIcon

If you use other payment method types, such as PayPal, you can reuse the same client. Pass the client to braintree.hostedFields.create within the options object:

  1. Async/Await
async function createHostedFields() {
  try {
    const clientInstance = await braintree.client.create({
      authorization: 'CLIENT-AUTHORIZATION'
    });
    const hostedFieldsInstance = await braintree.hostedFields.create({
      client: clientInstance,
      styles: {
        /* ... */
      },
      fields: {
        /* ... */
      }
    });
    // Use the Hosted Fields instance here to tokenize a card
  } catch (err) {
    // Handle error in client or Hosted Fields creation
  }
}

If setup succeeds, hostedFieldsInstance is ready to use for tokenizing card details.

See the braintree.hostedFields.create reference for details.

Build a basic integrationAnchorIcon

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

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.147.0/js/client.min.js"></script>
    <script src="https://js.braintreegateway.com/web/3.147.0/js/hosted-fields.min.js"></script>

    <script>
      var form = document.querySelector('#my-sample-form');
      var submit = document.querySelector('input[type="submit"]');

      try {
        const clientInstance = await braintree.client.create({
          authorization: 'CLIENT-AUTHORIZATION'
        });
        // This example shows Hosted Fields, but you can also use this
        // client instance to create additional components here, such as
        // PayPal or Data Collector.

        const hostedFieldsInstance = await 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'
            }
          }
        });

        submit.removeAttribute('disabled');

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

          const payload = await hostedFieldsInstance.tokenize();

          // 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);
      } catch (hostedFieldsErr) {
        console.error(hostedFieldsErr);
        return;
      }
    </script>
  </body>
</html>

In this example, when the customer submits the form, Hosted Fields securely collects and attempts to tokenize the card details. If tokenization succeeds, your callback receives 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 receive a BraintreeError with pertinent details. For a detailed example of handling tokenization errors with Hosted Fields, see the HostedFields.tokenize reference.

Customize Hosted FieldsAnchorIcon

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