Getnet DocsGetnet Docs

Processar um Estorno ou Cancelamento

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

Este guia explica como iniciar um estorno ou cancelar uma transação de pagamento existente usando o aplicativo Tap on Phone. Ambas as operações exigem o ID da transação original e usam uma estrutura de Intent semelhante às compras padrão.

Entendendo Estornos vs. Cancelamentos

Embora ambas as operações devolvam fundos ao cliente, elas têm diferentes casos de uso e restrições:

  • Cancelamento: Reverte uma transação. A transação deve ser válida, aprovada e não ter sido estornada ou cancelada anteriormente. O usuário logado no app deve ter acesso de administrador.
  • Estorno: Devolve fundos ao cliente após a transação ser totalmente processada. A transação deve ser válida, aprovada e não ter sido estornada ou cancelada anteriormente. O usuário logado no seu aplicativo deve ter acesso de administrador para realizar um estorno.

Pré-requisitos

Antes de processar um estorno ou cancelamento, certifique-se de que você tem:

  • Um aplicativo Tap on Phone inicializado.
  • O userId, userToken e merchantId associados à sessão atual.
  • O transactionId (do sistema Tap on Phone) do pagamento aprovado original.
  • Configurou seu backend para gerenciar solicitações de autorização de refund via Single Sign-On (SSO) (consulte Integração de Backend: Gerenciando Solicitações de SSO).

Passo 1: Registrar o Activity Result Launcher

Registre um callback de Activity Result para gerenciar o resultado do processo de estorno ou cancelamento.

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

    if (result.resultCode == Activity.RESULT_OK && data != null) {
        val status = data.getStringExtra("status") ?: "None"

        if (status == "APPROVED") {
            println("Transaction successfully modified (Refunded/Canceled).")
            // Extract receipt data for the refund/cancellation
        } else {
            val declineCause = data.getStringExtra("declineCause") ?: "Unknown"
            println("Modification declined: $declineCause")
        }
    } else if (result.resultCode == Activity.RESULT_CANCELED) {
        val errorCode = data?.getStringExtra("errorCode") ?: "None"
        val errorMessage = data?.getStringExtra("errorMessage") ?: "User Canceled"
        println("Operation failed or was canceled: $errorMessage ($errorCode)")
    }
}

Passo 2: Preparar os Metadados de SSO

Como os estornos são operações sensíveis, o backend do Tap on Phone os valida contra o seu backend usando SSO. Você deve passar o seu Client ID no campo operationMetadata para que a plataforma possa rotear a solicitação de autorização corretamente.

// Format your Client ID as a JSON string
val operationMetadata = "{\"ClientID\\":\"your-client-id-here\"}"

Passo 3: Construir e Iniciar o Intent

Crie um intent explícito direcionado à POSActivity no aplicativo Tap on Phone.

Você deve especificar o transactionType (seja REFUND ou CANCEL) e fornecer o identificador da transação que deseja modificar no campo originalTransaction.

private fun performRefundOrCancel(originalTransactionId: Int, isRefund: Boolean) {
    val intent = Intent().apply {
        setClassName(
            "com.dejamobile.cbp.sps.app",
            "com.dejamobile.cbp.sps.app.POSActivity"
        )

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

        // Specify the type: "REFUND" or "CANCEL"
        val type = if (isRefund) "REFUND" else "CANCEL"
        putExtra("transactionType", type)

        // Pass the ID of the transaction to modify
        putExtra("originalTransaction", originalTransactionId)

        // Required for SSO authorization
        putExtra("operationMetadata", operationMetadata)
    }

    // Launch the intent
    modificationResultLauncher.launch(intent)
}

Passo 4: Gerenciar o Resultado

Assim que você iniciar o intent, o aplicativo Tap on Phone assume o controle. Para um estorno, pode ser solicitado ao lojista que apresente o cartão de pagamento original.

Quando a operação for concluída, o seu callback modificationResultLauncher é executado. Inspecione o campo status para verificar se o estorno ou cancelamento foi aprovado e atualize seus registros de pedidos internos de acordo.

Próximos Passos