braintree-ui

Allow your projects to take payments in as few lines of code possible.

Credit cards, PayPal, Apple Pay, Google Pay and Venmo, supported only.

Testing Credit Cards | PayPal | Apple Pay | Google Pay | Venmo

Usage

This component requires no dependencies, use the <braintree-ui/> HTML custom element where you wish to display. Ensure to import the script somewhere on your page.

Consume the payload event, which gets emitted when a valid payment method is chosen and completed by the user.

<braintree-ui token="{{ CLIENT_TOKEN }}" data-amount="0.01"></braintree-ui>
<script src="https://uicomponent.live.payments.maginfrastructure.com/payments.js"></script>
<script>
el = document.querySelector('braintree-ui')
function makePayment (nonce) {
   fetch('https://example.com/checkout')
     .then(response => response.json())
     .then(result => {
       // Pass the result through to the component.
       // Expected format:
       // {
       //  success: Boolean,
       //  verification: {
       //    status: String("processor_declined|processor_declined"),
       //    gatewayRejectionReason: String
       //  }
       // }
       el.dispatchEvent(new CustomEvent('complete', { detail: result }))
       if (result.success) {
         alert('Payment successful')
       } else {
         el.dataset.error = 'There was an error'
       }
     })
}

el.addEventListener('payload', function(event) {
   console.log(event.detail)
   // { nonce: "tokencc_bh_kz4r7k_7c2fsp_4qyf6q_wb5vmy_6y8", ... }
   makePayment(event.detail.nonce)
})

</script>

Debugging

To view debugging in DevTools Console, enable the debug key on LocalStorage.

localStorage.debug = "braintree-ui:*"

Sandbox Example

Example cards
Card NumberCard TypeResponse
4111111111111111VISAValid
4000111111111115VISAProcessor Declined
4000000000001000 (Jan, 2 years from now)VISA3D Secure no challenge
4000000000001091 (Jan, 2 years from now)VISA3D Secure challenge success
4000000000001109 (Jan, 2 years from now)VISA3D Secure challenge failure

More information, see Braintree Card Testing

this example is using a sandbox account

Loading Demo, Please Wait

Demo Actions

API Options

Properties and events that can be used to interface with this Web Component.

Properties

PropertyAttributeTypeDefaultDescription
amountdata-amountstring""Defines transaction amount as attribute to pass to braintree.

Required for 3D Secure, and Google Payment
buttonRemoveddata-button-removedbooleanfalseButton Removed

Enable the button responsible for tokenise, enabled by default can be
set to false to allow for custom tokenise integration.
buttonTextdata-button-textstring"Pay Now"Button Text

The label for the button text when not in spinner state

Default option:
- Pay Now
configdata-config{ token: null; }{"token":null}Object that contains the Braintree Client tokenization key token that authorizes this client to tokenize payment information.

As an integrator of this component, This object is returned from the paymentGateway/client-config payments api endpoint when using the corresponding merchantId.
configurableboolean
currencyCodedata-currency-codestring"GBP"ISO4217 Currency code the given amount is defined using.

Required for Google Payment
defaultPaymentMethoddata-default-payment-methodstring""
enabledPaymentMethodsdata-enabled-payment-methodsstring[]Payment methods to display
Defaults options: ["hosted-fields", "paypal"]

Example:
<braintree-ui data-enabled-payment-methods="[\"hosted-fields\"]"></braintree-ui>
N.B. The given property must be an valid JSON array string. Double quotes are mandatory in JSON.

Available Options:
- hosted-fields
- paypal
- google-payment
- apple-pay - When enabled will only show on supported devices/browsers. macOS with TouchID (or via iOS device), iOS with TouchID/FaceID.

Note: Apple Pay requires Domain Registration
enumerableboolean
errorMessagedata-error-messagestring""Display a Braintree related error message, ideal for server side errors when attempting transactions.
googleMerchantIddata-google-merchant-idstring""Google Pay Merchant ID

Required for Google Pay production mode
isLoggedIndata-is-logged-inbooleanfalseBoolean value to let the component know if the user is currently logged in, defaults to false.
isThreeDSecureChallengeRequestedEnableddata-enable-three-d-secure-challenge-requestedanyToggle to force 3D Secure authentication.
* Note: if you don't need to force additional 3DS authentication or you are not sure, don't set it. In that case it would not force 3DS authentication.
If it will be set to "true/false" will be included in the 3DS verification process
isThreeDSecureEnableddata-enable-three-d-securebooleanfalseToggle to Activate or disable 3D Secure. Allows shift of fraud liability to card issuer.

Note: You'll need to use a Client Token instead of a Tokenization Key for token
prefillCardNumberdata-prefill-card-numberstring""Prefill Hosted Field Card Number

Primarily used in Automation tests.
prefillCvvdata-prefill-cvvstring""Prefill Hosted Field CVV

Primarily used in Automation tests.
prefillExpiryDatedata-prefill-expiry-datestring""Prefill Hosted Field Expiry Date

Primarily used in Automation tests.
themeLabelModedata-theme-label-modestring"outside"Label display mode

Available options:
- outside
- edge
tokentokenstring""A Braintree Client tokenization key that authorizes this client to tokenize payment information.

This tokenization key can be shipped with application without the need to generate a new key for each session.

Learn more about tokenization keys

Note: If you're using 3D Secure you'll need to generate a JWT Signed Client Token, learn more about client tokens.

Events

EventDescription
completeDispatch this event to the component when you've successfully completed a transaction or when the transaction has failed from your server.
errorHandle the human readable display of a Server Side error, and allow the user to change payment method. List of all Braintree errors.
payloadDispatched when the payment is payment method has been provided
tokenize
userErrorHandle the human readable display of a 3d Secure status codes, and allow the user to change payment method. List of all 3d Secure status codes.

CSS Custom Properties

PropertyDescription
--braintree-ui-border-radiusBorder radius of Payment Methods (default: 0.4rem)
--braintree-ui-color-primaryPrimary color for Titles, and Labels (default: #032f61)
--braintree-ui-gap-spacingControls the gap between block elements (default: 1rem)