Hosted Fields

Setup and Integration

braintree.setup

Configure your integration using braintree.setup() with "custom" as your integration type:

JavaScript

braintree.setup(CLIENT_AUTHORIZATION, 'custom', options);

Parameters

Argument Type Description

CLIENT AUTHORIZATION String Either a tokenization key or a client token

options

Object

Key	Type	Description
id	String	The reference to the DOM id of your `form` element.
hostedFields	Object	See Hosted Fields options
paypal	Object	Optional - see PayPal options

Learn more about the global setup options and callbacks such as onPaymentMethodReceived, onReady, and onError

Basic integration

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:

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" />
    </form>
<script src="https://js.braintreegateway.com/js/braintree-3.111.0.min.js"></script>
    <script>
    braintree.setup("CLIENT_AUTHORIZATION", "custom", {
      id: "my-sample-form",
      hostedFields: {
        number: {
          selector: "#card-number"
        },
        cvv: {
          selector: "#cvv"
        },
        expirationDate: {
          selector: "#expiration-date"
        }
      }
    });
  </script>
</body>
</html>

When braintree.setup is executed, it will take over the submit event of #my-sample-form. When a submit is attempted, Braintree.js will securely collect the payment information and attempt to tokenize the credit card.

By default, the form will be submitted with a hidden payment_method_nonce input. However, if you have specified an onPaymentMethodReceived callback, a paymentMethod object containing the nonce will be returned and the form will not be submitted.

For more information about Braintree.js, visit the Setup Guide.

PayPal

If you have PayPal configured, include the PayPal configuration object inside the custom configuration object. Learn more about specific PayPal settings on the PayPal client guide:

JavaScript

braintree.setup('CLIENT_AUTHORIZATION', 'custom', {
  id: 'my-sample-form',
  hostedFields: {
    // ...
  },
  paypal: {
    // ...
  }
});

Customization

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

Handling errors withonError

As with onPaymentMethodReceived, the general usage of the onError callback is documented in the Setup method options reference.

Validation errors

When client-side validation fails in Hosted Fields, onError will fire with a VALIDATION type. This error payload will also present information about which fields were invalid.

Key Type Description

type String VALIDATION

message String 'Some payment method input fields are invalid.'
'User did not enter a payment method' (if all fields are empty)

details