Gerenciar Resultados de Transações

Após o aplicativo Tap on Phone concluir o processamento de um pagamento, estorno ou cancelamento, ele devolve o controle ao seu aplicativo. Ele passa o resultado da transação através da API Activity Result do Android.

Este guia explica como analisar o código de resultado, determinar o status final da transação e extrair os dados detalhados do recibo.

Passo 1: Verificar o Activity Result Code

Quando o seu callback registrado do Activity Result é acionado, você deve primeiro inspecionar o resultCode. Este código informa se o aplicativo Tap on Phone concluiu seu processo.

• RESULT_OK: O processo de transação foi concluído com sucesso e o app Tap on Phone gerou um recibo. Nota: Isso não significa que o pagamento foi aprovado; significa apenas que o processo terminou sem um erro fatal do sistema.
• RESULT_CANCELED: O processo foi abortado antes que um recibo pudesse ser gerado. Isso acontece se o usuário cancelar manualmente a operação (por exemplo, pressionando o botão de voltar) ou se ocorrer um erro antes da transação ficar online (como uma falha na leitura do cartão ou timeout de rede).

val resultLauncher = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
    val data = result.data

    if (result.resultCode == Activity.RESULT_OK && data != null) {
        // The process finished and generated a receipt. Proceed to Step 2.
    } else if (result.resultCode == Activity.RESULT_CANCELED) {
        // The process was canceled or failed. Proceed to Step 4.
    }
}

Passo 2: Determinar o Status da Transação

Quando você recebe RESULT_OK, você deve avaliar o extra status para determinar o resultado financeiro real da transação:

• APPROVED: A transação foi bem-sucedida.

• DECLINED: A transação foi rejeitada. Verifique declineCause e declineError para obter detalhes.

// ... inside your RESULT_OK block
val status = data.getStringExtra("status") ?: "None"

if (status == "APPROVED") {
    println("The transaction was approved.")
    // Fulfill the order and save the receipt data
} else if (status == "DECLINED") {
    val declineCause = data.getStringExtra("declineCause") ?: "Unknown reason"
    println("The transaction was declined: $declineCause")
    // Prompt the user to try a different payment method
}

Passo 3: Extrair Dados do Recibo

Para cada transação concluída (RESULT_OK), os dados do intent contêm informações detalhadas sobre o pagamento. Você usa esses campos para atualizar o seu backend, imprimir recibos físicos ou enviar recibos digitais ao cliente.

Extraia os dados usando os getters de intent padrão do Android:

// Basic Identifiers
val transactionId = data.getIntExtra("transactionId", -1)
val uuid = data.getStringExtra("uuid") ?: "" // Unique receipt ID

// Financial Details
val amount = data.getLongExtra("amount", 0) // Amount in cents
val currency = data.getStringExtra("currency") ?: "" // ISO 4217 code (e.g., "EUR")
val date = data.getStringExtra("date") ?: ""

// Card & EMV Details
val scheme = data.getStringExtra("scheme") ?: "" // e.g., "Visa", "Mastercard"
val pan = data.getStringExtra("pan") ?: "" // Masked PAN (e.g., "************1234")
val aid = data.getStringExtra("aid") ?: "" // Selected EMV Application ID
val applicationLabel = data.getStringExtra("applicationLabel") ?: ""
val authCode = data.getStringExtra("authCode") ?: "" // EMV Authorization Code

A String de Recibo Formatada

Se você deseja exibir ou imprimir um recibo sem formatar manualmente cada campo, o aplicativo Tap on Phone fornece uma string pré-formatada.

Extraia o extra formatedString. Esta string contém um layout de recibo completo e pronto para impressão que inclui o nome do lojista, localização, PAN mascarado, data e códigos de autorização.

val fullReceiptString = data.getStringExtra("formatedString") ?: "No receipt available"
println(fullReceiptString)

Passo 4: Gerenciar Cancelamentos e Erros

Quando você recebe RESULT_CANCELED, você deve verificar se foi um simples cancelamento do usuário ou um erro do sistema.

Se um erro causou o cancelamento, o app Tap on Phone inclui detalhes do erro nos extras do intent. Se o intent não contiver esses extras, você pode presumir que o usuário cancelou o processo manualmente.

// ... inside your RESULT_CANCELED block
if (data != null && data.hasExtra("errorCode")) {
    val errorCode = data.getStringExtra("errorCode") ?: "Unknown"
    val errorName = data.getStringExtra("errorName") ?: "Unknown"
    val errorMessage = data.getStringExtra("errorMessage") ?: "Unknown"

    println("Transaction failed with error [$errorCode]: $errorName - $errorMessage")
    // Display the error message to the merchant
} else {
    println("The merchant canceled the transaction.")
}

Próximos Passos

• Para uma lista exaustiva de todos os campos de dados disponíveis retornados no intent, consulte a referência de Parâmetros de Resposta.
• Aprenda como consultar o status de uma transação anterior usando seu UUID em Consultando Transações Anteriores.