Consultando Transações Anteriores

Em alguns cenários, o seu aplicativo pode não receber o resultado final da transação do aplicativo Tap on Phone. Isso pode acontecer se o seu aplicativo falhar (crash), se o sistema Android o encerrar enquanto estiver em execução em segundo plano ou se o usuário forçar o fechamento do aplicativo. Você também pode precisar recuperar detalhes de transações anteriores para preencher um histórico de transações ou uma tela de detalhes.

Para gerenciar esses casos, você pode consultar o status de uma transação específica enviando um Broadcast do Android contendo o ID único da transação.

Pré-requisitos

Antes de poder consultar uma transação anterior, certifique-se de que você tem:

O userId, userToken e merchantId associados à sessão.
O sdkTransactionId (UUID) da transação que você deseja verificar. O aplicativo Tap on Phone transmite (broadcasts) este ID logo no início do processo de pagamento. (Consulte Processar uma Transação de Compra para aprender como capturar este ID).

Se você estiver tentando recuperar o status imediatamente após uma tentativa de pagamento, aguarde pelo menos 5 segundos (idealmente 10 segundos) antes de enviar a solicitação de status. Isso dá ao backend do Tap on Phone tempo suficiente para concluir o processamento da transação.

Passo 1: Registrar um Broadcast Receiver

Quando você consulta o status da transação, o aplicativo Tap on Phone responde de forma assíncrona por meio de um broadcast. Você deve registrar um BroadcastReceiver para capturar esta resposta.

Por padrão, o aplicativo Tap on Phone responde usando a action com.dejamobile.cbp.sps.TRANSACTION_STATUS_BROADCAST_RESPONSE.

val statusResponseAction = "com.dejamobile.cbp.sps.TRANSACTION_STATUS_BROADCAST_RESPONSE"

val receiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        // Extract the receipt or failure details
        val receipt = intent?.getStringExtra("Receipt")
        val failure = intent?.getStringExtra("Failure")

        if (receipt != null) {
            println("Got transaction receipt: $receipt")
            // Parse the receipt data to determine the final status (APPROVED/DECLINED)
        } else if (failure != null) {
            println("Transaction status failure: $failure")
            // Handle the failure
        }

        // Unregister the receiver once handled
        context?.unregisterReceiver(this)
    }
}

// Register the receiver
val filter \= IntentFilter(statusResponseAction)
registerReceiver(receiver, filter)

Embora o broadcast de resposta use as strings Receipt e Failure para agrupar o resultado, o intent também carrega os mesmos campos de dados detalhados que a resposta do intent de pagamento padrão (como status, amount, pan, etc.). Consulte Gerenciar Resultados de Transações para obter detalhes sobre como analisar esses campos.

Passo 2: Enviar o Broadcast de Solicitação de Status

Assim que o seu receiver estiver escutando, construa e envie o intent de broadcast. Você deve direcionar à classe TransactionStatusBroadcastReceiver e passar as credenciais de sessão obrigatórias junto com o TransactionId.

private fun queryTransactionStatus(transactionUUID: String) {
    val intent = Intent().apply {
        action = "com.dejamobile.cbp.sps.TRANSACTION_STATUS_BROADCAST"
        component = ComponentName(
            "com.dejamobile.cbp.sps.app",
            "com.dejamobile.cbp.sps.app.broadcast.TransactionStatusBroadcastReceiver"
        )
        addFlags(Intent.FLAG_INCLUDE_STOPPED_PACKAGES)

        // Session Identifiers
        putExtra("userId", userId)
        putExtra("merchantId", merchantId)
        putExtra("userToken", userToken)

        // The UUID of the transaction to query
        putExtra("TransactionId", transactionUUID)

        // Optional: Specify your custom response action if you don't want to use the default
        // putExtra("ResponseAction", "your.custom.action.name")
    }

    // Send the broadcast
    sendBroadcast(intent)
}

Passo 3: Gerenciar Erros e Novas Tentativas

Se o seu broadcast receiver capturar uma resposta que contenha uma string Failure (ou se a resposta indicar que a transação não existe), não presuma imediatamente que a transação falhou permanentemente.

Problemas de rede ou problemas internos do dispositivo podem ocasionalmente fazer com que a recuperação do status falhe. Siga esta lógica de novas tentativas (retry):

Primeira Falha: Se o broadcast retornar um erro, aguarde alguns segundos e tente reenviar o broadcast mais uma vez.
Segunda Falha: Se um erro ainda for retornado após a segunda tentativa, você pode considerar com segurança a transação como negada ou anulada.