Estornar um Pagamento

Este guia explica como iniciar uma transação de estorno (devolução) a partir de sua aplicação Android para a aplicação Get Smart.

Uma transação de estorno reverte total ou parcialmente um pagamento anterior. Para processar um estorno, você deve fornecer o número do pedido da transação original junto com o valor do estorno.

Requisitos

Antes de começar, certifique-se de que você possui:

• A aplicação Get Smart instalada no dispositivo
• O número do pedido da transação original (valor ORDER da resposta do pagamento original)
• O valor a ser estornado (pode ser parcial ou total)
• Compreensão básica da Arquitetura

Processo de Transação de Estorno

Esta seção orienta você no processo de iniciar uma transação de estorno com a integração Get Smart App2App.

Passo 1: Criar o Intent de Estorno

Primeiro, instancie um novo Intent com o nome da ação específica exigida pela aplicação Get Smart:

Intent intent = new Intent("es.android.redsys.mPOS.movil.tpvAndroid_PAYMENT_REQUEST");5

Passo 2: Adicionar Parâmetros Obrigatórios

Passe os detalhes do estorno para a aplicação Get Smart usando intent.putExtra():

// Set the refund amount
double refundAmount = 25.99;
intent.putExtra("amount", refundAmount);

// Set the transaction type to Refund (1 = Sale, 2 = Refund)
intent.putExtra("type", 2);

// IMPORTANT: Provide the original transaction's order number
String originalOrder = "ORD-2024-12345";
intent.putExtra("original_order", originalOrder);

Crítico: O parâmetro original_order é obrigatório para estornos. Isso vincula o estorno à transação de pagamento original. Use o valor exato de ORDER retornado na resposta do pagamento original.

Passo 3: Adicionar Parâmetros Opcionais

Você também pode incluir parâmetros opcionais para rastrear o estorno:

// Add a refund invoice number
String refundInvoice = "REF-2024-001";
intent.putExtra("invoice", refundInvoice);

Passo 4: Lançar a Transação

Execute o intent usando startActivityForResult:

// Define a unique request code to identify this call later
static final int REQUEST_CODE_REFUND = 1002;

try {
    startActivityForResult(intent, REQUEST_CODE_REFUND);
} catch (ActivityNotFoundException e) {
    // Handle the error: The Get Smart app is not installed
    new AlertDialog.Builder(this)
        .setTitle("Payment App Not Found")
        .setMessage("Please ensure the Get Smart application is installed and updated.")
        .setPositiveButton("OK", null)
        .show();
}

O snippet de código a seguir demonstra o fluxo completo para iniciar um estorno:

public class RefundActivity extends AppCompatActivity {
    private static final int REQUEST_CODE_REFUND = 1002;

    public void processRefund(double amount, String originalOrderNumber, String refundInvoice) {
        // 1. Create the Intent
        Intent intent = new Intent("es.android.redsys.mPOS.movil.tpvAndroid_PAYMENT_REQUEST");

        // 2. Add required parameters
        intent.putExtra("amount", amount);
        intent.putExtra("type", 2); // 2 = Refund
        intent.putExtra("original_order", originalOrderNumber); // REQUIRED for refunds

        // 3. Add optional parameters
        if (refundInvoice != null) {
            intent.putExtra("invoice", refundInvoice);
        }

        // 4. Launch with error handling
        try {
            startActivityForResult(intent, REQUEST_CODE_REFUND);
        } catch (ActivityNotFoundException e) {
            // Alert the user if the app is missing
            new AlertDialog.Builder(this)
                .setTitle("Payment Application Not Found")
                .setMessage("You must install and update the Get Smart application.")
                .setPositiveButton("OK", null)
                .show();
        }
    }

    // Handle the result (see Handle Transaction Results guide)
    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        // ... result handling code ...
    }
}

A tabela abaixo lista os campos mínimos que você precisa enviar:

Tipos de Estorno

Estorno Total - Para estornar todo o valor da transação original, defina o valor do estorno igual ao valor do pagamento original.

Estorno Parcial - Para estornar apenas parte da transação original, defina o valor do estorno para um valor inferior ao do pagamento original.

O que acontece a seguir

Após lançar o Intent, a aplicação Get Smart assume o controle, exibe a interface de estorno, processa o estorno com o gateway de pagamento, lida com a impressão de comprovantes e devolve o controle à sua aplicação via onActivityResult.

Tratamento de Erros

Pedido Original Ausente - Se você não fornecer o parâmetro original_order, o estorno falhará. A aplicação Get Smart precisa disso para vincular o estorno ao pagamento original.

Pedido Original Inválido - Se o original_order não corresponder a nenhuma transação existente, o estorno será negado. Certifique-se de usar o valor exato de ORDER da resposta do pagamento original.

Aplicação não Encontrada - Se a aplicação Get Smart não estiver instalada, o Android lançará uma ActivityNotFoundException. Sempre capture esta exceção e informe o usuário.

Nome de Parâmetro Incorreto - O parâmetro deve ser original_order (com sublinhado), não originalOrder ou original-order. Os extras de Intent do Android diferenciam maiúsculas de minúsculas e usam o nome exato da chave.

Transação não Encontrada - Se a transação original for muito antiga ou não estiver no sistema Get Smart, o estorno pode falhar. Verifique as políticas do seu processador de pagamentos sobre limites de tempo para estornos.

Melhores Práticas

Ao processar estornos, siga estas melhores práticas:

• Armazene Números de Pedidos Originais - Salve o valor ORDER de cada resposta de pagamento para futuras operações de estorno.
• Valide o Valor do Estorno - Certifique-se de que o valor do estorno não exceda o valor do pagamento original.
• Rastreie Estornos - Mantenha registros de quais pedidos foram estornados e em qual valor.
• Lide com Estornos Parciais - Se sua lógica de negócio permitir múltiplos estornos parciais, rastreie o valor estornado cumulativo.
• Confirmação do Usuário - Considere solicitar a confirmação do usuário antes de processar um estorno.
• Trilha de Auditoria - Registre todas as tentativas de estorno com carimbos de data/hora e desfechos.

Próximos Passos

Agora que você entende como processar transações de estorno:

• Saiba como tratar o resultado do estorno em Tratar Resultados da Transação
• Saiba como criar um pagamento de etapa única em Criar um Pagamento de Etapa Única
• Revise todos os parâmetros de requisição em Referência de Parâmetros de Requisição