---
title: Integrating reCAPTCHA Enterprise into an Android app
description: PingOne Advanced Identity Cloud PingAM Android
component: orchsdks
page_id: orchsdks:journey:use-cases/recaptcha-enterprise/android-recaptcha-enterprise
canonical_url: https://developer.pingidentity.com/orchsdks/journey/use-cases/recaptcha-enterprise/android-recaptcha-enterprise.html
section_ids:
  importing_dependencies: Importing dependencies
  handling_the_callback_with_the_sdk: Handling the callback with the SDK
  config: Configuring the verification
  payload: Customizing the assessment payload
  custom-error: Returning custom error codes
---

# Integrating reCAPTCHA Enterprise into an Android app

[icon: circle-check, set=far]PingOne Advanced Identity Cloud [icon: circle-check, set=far]PingAM [icon: android, set=fab]Android

To add support for reCAPTCHA Enterprise to your Android apps, complete the following tasks.

## Importing dependencies

Add the following to your `build.gradle` configuration file:

```gradle
dependencies {
    implementation("com.pingidentity.sdks:recaptcha-enterprise:2.0.0")
}
```

## Handling the callback with the SDK

Use code similar to the following to handle the `ReCaptchaEnterpriseCallback` in your client-side code using the Orchestration SDKs:

Handling `ReCaptchaEnterpriseCallback` on Android

```kotlin
val node = journey.start("login")

node.callbacks.forEach { callback ->
    when (callback) {
        is ReCaptchaEnterpriseCallback -> {
            val result = callback.verify()
            result.onSuccess { token ->
                // Verification successful, proceed with the flow
                println("ReCaptcha token: $token")
            }.onFailure { error ->
                // Handle verification failure
                println("Verification failed: ${error.message}")
            }
        }
        // Handle other callbacks
    }
}

// Continue the journey
val next = node.next()
```

## Configuring the verification

You can pass a number of options into the call to `verify()` to customize its operation:

Configuring the call to `verify()` on Android

```kotlin
callback.verify {
    // Different action types
    recaptchaAction = RecaptchaAction.SIGNUP
    // or custom action
    recaptchaAction = RecaptchaAction.custom("PASSWORD_RESET")

    // Longer timeout for slower networks
    timeoutInMills = 15000L
}
```

The available properties for configuring the `verify()` call are as follows:

| Property                              | Default                 | Description                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recaptchaAction` (`RecaptchaAction`) | `RecaptchaAction.LOGIN` | The type of action you want to verify.Specify either of the built-in values:- `RecaptchaAction.LOGIN`

  For login journeys

- `RecaptchaAction.SIGNUP`

  For registration journeysOr you can specify your own action using the `custom` method:```
RecaptchaAction.custom("PASSWORD_RESET")
RecaptchaAction.custom("PAYMENT")
RecaptchaAction.custom("ADD_TO_CART")
``` |
| `timeoutInMills` (`Long`)             | `10000L`                | How long to wait, in milliseconds, for a verification to complete.Use longer timeouts for slow networks or critical operations.                                                                                                                                                                                                                                           |
| `customPayload` (`JsonObject?`)       | `null`                  | Add relevant metadata to help with risk assessment and debugging.Learn more in [Customizing the assessment payload](#payload).                                                                                                                                                                                                                                            |
| `logger` (`Logger`)                   | `Logger.WARN`           | What level of logging the module should output.Choose from the following options:- `Logger.DEBUG`

  Detailed debugging messages, for use during development.

- `Logger.WARN`

  Only logs warnings and errors.

- `Logger.INFO`

  Logs info-level messages.

- `Logger.NONE`

  Disables logging.                                                                      |

## Customizing the assessment payload

You can add additional data to customize the payload that the server sends to the Google reCAPTCHA Enterprise for assessment.

Add data to the payload to leverage additional functionality provided by reCAPTCHA Enterprise.

The JSON format the payload expects is as follows:

```json
{
  "token": string,
  "siteKey": string,
  "userAgent": string,
  "userIpAddress": string,
  "expectedAction": string,
  "hashedAccountId": string,
  "express": boolean,
  "requestedUri": string,
  "wafTokenAssessment": boolean,
  "ja3": string,
  "headers": [
    string
  ],
  "firewallPolicyEvaluation": boolean,
  "transactionData": {
    object (TransactionData)
  },
  "userInfo": {
    object (UserInfo)
  },
  "fraudPrevention": enum (FraudPrevention)
}
```

By default, the SDK or the node itself populates the following fields:

* `token`

* `siteKey`

* `userAgent`

* `userIpAddress`

* `expectedAction`

You can however also override these values if it suits your use case.

|   |                                                                                                                                                                                                                                                                             |
| - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | You can add custom payload data as part of an authentication journey that includes the [reCAPTCHA Enterprise node](https://docs.pingidentity.com/auth-node-ref/latest/recaptcha-enterprise.html). Custom data in the journey overrides any custom data added by the client. |

To learn more about the payload, refer to [Project Assessments - Event](https://cloud.google.com/recaptcha/docs/reference/rest/v1/projects.assessments#event) in the Google Developer documentation.

To add custom data for an assessment, set the `customPayload` property in the `verify` configuration block:

Customizing reCAPTCHA payload on Android

```kotlin
callback.verify {
    // Add custom payload for risk assessment
    customPayload = buildJsonObject {
        put("firewallPolicyEvaluation", true)
        put("transactionData", buildJsonObject {
            put("transactionId", "TXN-12345")
            put("paymentMethod", "CREDIT_CARD")
            put("cardBin", "123456")
            put("cardLastFour", "1234")
            put("currencyCode", "USD")
            put("value", 99.99)
        })
        put("userInfo", buildJsonObject {
            put("accountId", "user-abc123")
            put("creationMs", "1609459200000")
        })
    }
}
```

## Returning custom error codes

You can return a custom error to the node if required for your business logic:

Returning custom reCAPTCHA client errors on Android

```kotlin
val result = callback.verify {

  // Optional custom client error code
  customError = { exception ->
      "custom_client_error ${exception.message?.uppercase()}"
  }
}
```