O attestation é uma verificação de segurança que garante que o SDK está sendo executado em um dispositivo seguro e confiável.

Como funciona?

O attestation ocorre automaticamente antes de cada transação. Se a verificação falhar, o pagamento é interrompido.

pay()  →  Attestation  →  ✅ Aprovado  →  Transação inicia
                       →  ❌ Reprovado →  Pagamento interrompido (onError)

⚠️

Aviso

O erro de attestation pode ocorrer já no momento da criação do terminal. Nesse fluxo, não temos informações suficientes para identificar a causa exata do problema.

É possível reconhecer que se trata de um erro de attestation por meio do código retornado. No entanto, isso apenas indica a categoria do erro — não o motivo específico. Ou seja, saber que é um erro de attestation é diferente de saber o que causou esse erro, e neste ponto não temos visibilidade sobre essa causa.

Além disso, em alguns cenários, pode não haver detalhes adicionais disponíveis para consulta. Portanto, o integrador não deve assumir que todo erro de attestation virá acompanhado de informações completas para diagnóstico.

O que é verificado

Validações manuais do dispositivo

Antes de iniciar transações, verifique se o dispositivo atende aos requisitos do Play Integrity. Use o checklist abaixo para identificar e corrigir problemas preventivamente.

Checklist de verificação

Execute estas verificações no dispositivo para garantir que ele passará no attestation:

⚠️

Dispositivos que não passam nas verificações 5, 6 ou 7 não conseguirão realizar transações com o SDK Tap to Pay, pois falham na verificação de integridade do dispositivo (DeviceIntegrity_NotMet ou DeviceIntegrity_NotStrong).

Níveis de integridade do Play Integrity

O Google Play Integrity classifica dispositivos em três níveis. O SDK Tap to Pay exige no mínimo o nível MEETS_DEVICE_INTEGRITY:

Validação programática

Adicione uma verificação antes de chamar pay() para orientar o usuário caso o dispositivo não atenda aos requisitos básicos:

import android.os.Build
import com.google.android.gms.common.GoogleApiAvailability
import com.google.android.gms.common.ConnectionResult

fun checkDeviceReadiness(context: Context): List<String> {
    val issues = mutableListOf<String>()

    // Verificar versão do Android (mínimo API 23)
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.M) {
        issues.add("Android 6.0 (API 23) ou superior é necessário. Versão atual: ${Build.VERSION.RELEASE}")
    }

    // Verificar Google Play Services
    val googleApiAvailability = GoogleApiAvailability.getInstance()
    val resultCode = googleApiAvailability.isGooglePlayServicesAvailable(context)
    if (resultCode != ConnectionResult.SUCCESS) {
        if (googleApiAvailability.isUserResolvableError(resultCode)) {
            issues.add("Google Play Services precisa ser atualizado.")
        } else {
            issues.add("Google Play Services não está disponível neste dispositivo.")
        }
    }

    // Verificar conectividade
    val connectivityManager = context.getSystemService(Context.CONNECTIVITY_SERVICE) as android.net.ConnectivityManager
    val activeNetwork = connectivityManager.activeNetwork
    if (activeNetwork == null) {
        issues.add("Sem conexão com a internet. O attestation requer acesso à rede.")
    }

    return issues
}

// Uso antes de chamar pay()
val issues = checkDeviceReadiness(context)
if (issues.isNotEmpty()) {
    issues.forEach { issue ->
        Log.w("PreAttestation", "⚠️ $issue")
    }
    // Exibir mensagem ao usuário com os problemas encontrados
} else {
    Log.d("PreAttestation", "✅ Dispositivo pronto para attestation")
    // Prosseguir com TapOnPhone.pay(...)
}

💡

Essa verificação programática cobre apenas os pré-requisitos básicos. Verificações mais profundas — como bootloader, root e integridade da ROM — são realizadas diretamente pela Google Play Integrity API durante o attestation automático do SDK.

Configuração das credenciais de Attestation

Para receber informações detalhadas sobre falhas de segurança, configure as credenciais de attestation no parâmetro attestation da classe Credentials durante o setConfig:

val credentials = Credentials(
    clientId = "seu_client_id",
    clientSecret = "seu_client_secret",
    marketplace = "seu_marketplace",
    seller = "seu_seller",
    accessKey = "seu_access_key",

    // Credenciais de attestation (opcionais)
    attestation = Attestation(
        clientId = "seu_client_id_attestation",
        clientSecret = "seu_client_secret_attestation"
    )
)

TapOnPhone.setConfig(
    ConfigParameters(
        context = context,
        credentials = credentials,
        sdkConfig = sdkConfig
    )
)

💡

O campo attestation é completamente opcional. Sem ele, o SDK funciona normalmente, mas não fornece detalhes específicos sobre erros de attestation. Preencha apenas se quiser receber informações detalhadas sobre falhas de segurança do dispositivo.

🔑

As credenciais de attestation são diferentes das credenciais principais do SDK. Elas são recebidas durante o onboarding e são específicas para a Cliente Role. Consulte a seção Onboarding para mais detalhes sobre os tipos de credenciais.

API de Status de Attestation

A API de Status de Attestation por Instance ID fornece informações sobre as verificações realizadas contra um identificador de instância específico, permitindo identificar e gerenciar rapidamente problemas de attestation.

⏱️

Os dados de attestation ficam disponíveis por apenas 1 hora após a consulta.

Quando o Attestation falha

Quando o attestation falha, o SDK executa automaticamente os seguintes passos:

① Identifica o erro  →  ② Consulta a API  →  ③ Retorna detalhes no onError
   DEVICE_STATE_FAILURE     de attestation        attestationStatus + integrityErrorCode

Tratamento no código

O callback onError recebe os detalhes da falha de attestation:

TapOnPhone.pay(
    request = PaymentRequest(
        amount = 10000,  // R$ 100,00
        paymentType = PaymentType.CREDIT,
        installments = 2,
        referenceId = UUID.randomUUID().toString(),
        metadata = """
            {
                "clientId": "1234",
                "name": "John Doe"
            }
        """
    ),
    onSuccess = { result ->
        println("Pagamento Aprovado! Id: ${result.transactionId}")
    },
    onError = { error ->
        when (error.type) {
            ErrorResponse.ErrorType.Payment -> {
                val paymentError = error.error as? PaymentErrorResponse
                paymentError?.let {
                    println("Pagamento negado - id: ${it.transactionId}")
                    println("Mensagem: ${it.message}")
                    println("Código: ${it.code}")
                    println("Descrição: ${it.description}")

                    // Informações de attestation (se disponíveis)
                    it.attestationStatus?.forEach { attestation ->
                        Log.d("status", attestation.status)
                        Log.d("timestamp", attestation.timestampUtc)
                        attestation.outcomes.forEach { outcome ->
                            Log.d(
                                "outcome",
                                "moniker[${outcome.moniker}] " +
                                "code[${outcome.statusCode}] " +
                                "reason[${outcome.reason}]"
                            )
                        }
                    }

                    // Código de erro da Google Play Integrity API
                    it.integrityErrorCode?.let { integrityError ->
                        Log.e("Payment", "Code: ${integrityError.code}")
                        Log.e("Payment", "Description: ${integrityError.description}")
                    }
                }
            }
            else -> {
                // Tratar outros tipos de erro
            }
        }
    },
    onEvent = { event ->
        Log.d("Payment", "Evento: ${event.name}")
    }
)

Tabela de erros de Attestation

Códigos retornados no campo attestationStatus.outcomes:

Integrity Error Codes

A Google Play Integrity API retorna códigos de erro quando não é possível verificar a integridade do dispositivo ou da aplicação. O SDK captura esses erros e os disponibiliza através do campo integrityErrorCode nos objetos SessionErrorResponse e PaymentErrorResponse.

Códigos de erro

Como tratar

Trate esses erros exibindo mensagens apropriadas ao usuário. Os cenários mais comuns:

📘

Para erros internos ou desconhecidos (como -100), oriente o usuário a tentar novamente mais tarde. Se o problema persistir, colete os logs do SDK e entre em contato com o suporte Zoop.

Onde o campo attestationStatus aparece

O campo attestationStatus existe apenas nos objetos públicos abaixo:

• SessionErrorResponse — usado em ErrorResponse.Session quando a falha ocorre no contexto de sessão (OperationType.session).
• PaymentErrorResponse — usado em ErrorResponse.Payment quando a falha ocorre no pagamento (OperationType.pay).

Outras variantes de ErrorResponse (ex.: Pix, SMS, Default) usam outros tipos em erros. O que esta página chama de status remoto de attestation restringe-se às linhas Sim da tabela. Nas linhas Não, TapOnPhoneError em Initialize e Terminal mantém mensagem, códigos, kernel e demais metadados; apenas não há enriquecimento com o array retornado pela API {instanceId}/attestation-status.

Falha antes de existir instância no backend

Se a criação do terminal falhar antes de haver instanceId (instância ainda não criada ou ID indisponível), o SDK não consegue montar a chamada de status de attestation. O erro exposto nesses casos segue como TapOnPhoneError (Initialize ou Terminal), sem attestationStatus. Isso se alinha à regra de que o instanceId só fica disponível após inicialização bem-sucedida do terminal ver Inicialização .

SessionErrorResponse

data class SessionErrorResponse(
    override val message: String? = "session error",
    val code: Int?,
    val attestationStatus: Array<AttestationStatus>?,
    val kernel: KernelError?,
    val integrityErrorCode: IntegrityErrorCode?,
) : ErrorBase(message) {
    data class KernelError(
        val code: Int,
        val name: String,
        val description: String,
    )
}

PaymentErrorResponse

Trecho ilustrativo — a classe pública inclui também identificação da transação, fonte do erro, integridade e outros campos; o campo relevante para attestation remota é attestationStatus.

data class PaymentErrorResponse(
    val transactionId: String?,
    val referenceId: String?,
    override val message: String? = "payment error",
    val code: Int?,
    val source: String?,
    val description: String?,
    val errorSource: String?,
    val operationType: String?,
    val kernel: KernelError?,
    val attestationStatus: Array<AttestationStatus>,
) : ErrorBase(message) {
    data class KernelError(
        val code: Int,
        val name: String,
        val description: String,
    )
}

Array vazio

O SDK pode preencher attestationStatus com um array vazio quando o enriquecimento não se aplica ou quando a consulta à API de attestation não é concluída com sucesso internamente. O integrador deve tratar a presença do campo como informativa, não como garantia de que uma análise remota foi obtida.