Standard Client-Side Implementation

Android v5

• Current Braintree SDKs
• Android v5
• iOS v7
• JavaScript v3
• Previous Versions
• Android v4
• iOS v6
• JavaScript v2

Add the Card Fields component to your Android checkout screen to collect card number, expiration date, and CVV input with built-in formatting, validation, brand detection, and tokenization. When you finish this guide, your app renders the 3 card fields, enables your pay button once the form is valid, and returns a nonce you can send to your server to complete a transaction.

If you need more direct control over card tokenization, see Advanced client-side for Android v5.

Before you begin

Before you add Card Fields, complete the following:

• Set up the Braintree Android SDK. See Setup for the base SDK installation.
• Generate a tokenization key or client token. See Client Authorization for the available authorization types.
• Decide where Card Fields fits in your checkout screen. Card Fields renders the card number, expiration date, and CVV fields. You provide everything else, including any non-card fields, such as name or billing address, and your pay button.

Add the Card Fields dependency

In your build.gradle file, add the ui-components dependency. This requires Braintree Android SDK 5.29.0 or higher, the first release that includes ui-components. Use the latest available version.

dependencies {
    implementation("com.braintreepayments.api:ui-components:LATEST-VERSION")
}

We recommend using the latest versions of our SDKs. See the Braintree Android changelog for the current release.

Verify: Sync your project. The build completes without dependency resolution errors.

Add the Card Fields view to your layout

Add the CardFields view and your own pay button to your layout file. The pay button starts disabled until the form is valid.

<com.braintreepayments.api.uicomponents.cardfields.CardFields
    android:id="@+id/cardFields"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />

<Button
    android:id="@+id/payButton"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:text="Pay"
    android:enabled="false" />

Verify: Render the layout. You see the card number, expiration date, and CVV fields, and a disabled pay button.

Initialize Card Fields

In your fragment or activity, get a reference to the CardFields view you added to your layout. Then call initialize on that reference, passing in the tokenization key or client token. This authorizes Card Fields to communicate with Braintree on your behalf and prepares the view to accept card input.

class CheckoutFragment : Fragment() {
    private lateinit var cardFields: CardFields

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        cardFields = view.findViewById(R.id.cardFields)
        val authorization = "YOUR-TOKENIZATION-KEY"

        cardFields.initialize(authorization)
    }
}

Replace YOUR-TOKENIZATION-KEY with the tokenization key or client token you generated in Before you begin.

Verify: Run your app. Card Fields loads without throwing an authorization error.

Enable your pay button when the form is valid

Card Fields reports form validity through a listener. Use it to enable your pay button only when the customer enters a valid card number, expiration date, and CVV.

val payButton = view.findViewById<Button>(R.id.payButton)

cardFields.setOnValidationChangedListener { isFormValid ->
    payButton.isEnabled = isFormValid
}

Verify: Enter an incomplete or invalid card number. The pay button stays disabled. Enter a valid card number, expiration date, and CVV. The pay button becomes enabled.

Handle the tokenization result

Register a result callback before you call submit. Card Fields returns a nonce on success, or an error on failure.

cardFields.setCardFieldsResultCallback { result ->
    when (result) {
        is CardFieldsResult.Success -> {
            val nonce = result.nonce
            // Send the nonce to your server. See Server-Side to create the transaction.
        }
        is CardFieldsResult.Failure -> {
            val error = result.error
            // Handle the error
        }
    }
}

Verify: Trigger a test submission after completing the next step. Your callback receives either a CardFieldsResult.Success with a nonce, or a CardFieldsResult.Failure with an error.

Trigger submission from your pay button

Card Fields doesn't include a pay button. Call submit from your own button's click handler.

payButton.setOnClickListener {
    cardFields.submit()
}

Verify: Select the pay button with a valid form. The result callback from the previous step runs.

Optional: Add supplemental card data

Use setPaymentRequest to merge non-card data, such as the cardholder name or postal code, into the tokenization request. Card Fields fills in the card number, expiration date, and CVV from the form.

cardFields.setPaymentRequest(
    Card(
        cardholderName = "Firstname Lastname",
        postalCode = "12345"
    )
)

Verify: Complete a submission. The tokenization request includes the cardholder name and postal code you set, along with the card data from the form.

Test your integration

Test your integration in sandbox before you go live. See Testing and Go Live for sandbox test values and steps to confirm a successful transaction.

Next steps

• See Overview for what Card Fields is and what it replaces.
• See Advanced client-side: Android v5 for more direct control over card tokenization without Card Fields.
• See Server-side to create the transaction using the payment method nonce.