Hosted Fields

Setup and Integrationanchor

braintree.setupanchor

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

  1. JavaScript
braintree.setup(CLIENT_AUTHORIZATION, 'custom', options);
Parametersanchor
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 integrationanchor

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" />
    </form>
<script src="https://js.braintreegateway.com/js/braintree-2.32.1.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.

PayPalanchor

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:

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

Customizationanchor

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

Handling errors with onErroranchor

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

Validation errorsanchor

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 Object

An object containing specific details of the error, if the fields are not all empty.

Key Type Description
invalidFieldKeys Array A collection of field key strings, such as number, cvv, postalCode, and expirationDate, which indicates the field(s) containing invalid user input.
isEmpty Boolean false
isValid Boolean false

See also


Next Page: Styling →