Devolver un pago

Esta guía explica cómo iniciar una transacción de devolución desde tu aplicación Android a la aplicación Get Smart.

Una transacción de devolución revierte total o parcialmente un pago anterior. Para procesar una devolución, debes proporcionar el número de pedido de la transacción original junto con el importe de la devolución.

Requisitos

Antes de comenzar, asegúrate de tener:

• La aplicación Get Smart instalada en el dispositivo
• El número de pedido de la transacción original (valor ORDER de la respuesta del pago original)
• El importe a devolver (puede ser parcial o total)
• Conocimientos básicos de la Arquitectura

Proceso de transacción de devolución

Esta sección te guía a través del proceso de inicio de una transacción de devolución con la integración Get Smart App2App.

Paso 1: Crear el Intent de devolución

En primer lugar, instancia un nuevo Intent con el nombre de acción específico requerido por la aplicación Get Smart:

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

Paso 2: Añadir parámetros requeridos

Pasa los detalles de la devolución a la aplicación Get Smart utilizando 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: El parámetro original_order es obligatorio para las devoluciones. Esto vincula la devolución a la transacción de pago original. Utiliza el valor exacto de ORDER devuelto en la respuesta del pago original.

Paso 3: Añadir parámetros opcionales

También puedes incluir parámetros opcionales para realizar un seguimiento de la devolución:

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

Paso 4: Lanzar la transacción

Ejecuta el intent utilizando 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();
}

El siguiente fragmento de código demuestra el flujo completo para iniciar una devolución:

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 ...
    }
}

La siguiente tabla enumera los campos mínimos que debes enviar:

Tipos de devolución

Devolución Total - Para devolver el importe íntegro de la transacción original, establezca el importe de la devolución igual al importe del pago original.

Devolución Parcial - Para devolver solo una parte de la transacción original, establezca el importe de la devolución en un valor inferior al del pago original.

Qué sucede a continuación

Una vez lanzado el Intent, la aplicación Get Smart toma el control, muestra la interfaz de devolución, procesa la devolución, gestiona la impresión de boletas y devuelve el control a tu aplicación a través de onActivityResult.

Gestión de errores

Falta el Pedido Original - Si no proporcionas el parámetro original_order, la devolución fallará. La aplicación Get Smart lo necesita para vincular la devolución al pago original.

Pedido Original Inválido - Si el original_order no coincide con ninguna transacción existente, la devolución será denegada. Asegúrate de utilizar exactamente el valor de ORDER de la respuesta del pago original.

Aplicación no Encontrada - Si la aplicación Get Smart no está instalada, Android lanza una excepción ActivityNotFoundException. Captura siempre esta excepción e informa al usuario.

Nombre de Parámetro Incorrecto - El parámetro debe ser original_order (con guion bajo), no originalOrder ni original-order. Los extras de los Intent de Android distinguen entre mayúsculas y minúsculas y utilizan el nombre exacto de la clave.

Transacción no Encontrada - Si la transacción original es demasiado antigua o no figura en el sistema Get Smart, la devolución puede fallar. Comprueba las políticas de tu procesador de pagos sobre los plazos de devolución.

Buenas prácticas

Al procesar devoluciones, sigue estas buenas prácticas:

• Almacena los Números de Pedido Originales - Guarda el valor ORDER de cada respuesta de pago para futuras operaciones de devolución.
• Valida el Importe de la Devolución - Asegúrate de que el importe de la devolución no supere el importe del pago original.
• Realiza un Seguimiento de las Devoluciones - Mantén un registro de qué pedidos se han devuelto y por qué importe.
• Gestiona Devoluciones Parciales - Si tu lógica de negocio permite múltiples devoluciones parciales, realiza un seguimiento del importe acumulado devuelto.
• Confirmación del Usuario - Considera solicitar la confirmación del usuario antes de procesar una devolución.
• Pista de Auditoría - Registra todos los intentos de devolución con marcas de tiempo y resultados.

Próximos pasos

Ahora que ya sabes cómo procesar transacciones de devolución:

• Aprende a gestionar el resultado de la devolución en Gestionar Resultados de la Transacción
• Aprende a crear un pago en Crear un pago