Refund a Payment

This guide explains how to initiate a refund (devolución) transaction from your Android application to the Get Smart application.

A refund transaction reverses or partially reverses a previous payment. To process a refund, you must provide the original transaction’s order number along with the refund amount.

Requirements

Before you begin, ensure you have:

• The Get Smart application installed on the device
• The original transaction’s order number (ORDER value from the original payment response)
• The amount to refund (can be partial or full)
• Basic understanding of the Architecture

Refund Transaction Process

This section guides you through the process of initiating a refund transaction with the Get Smart App2App integration.

Step 1: Create the Refund Intent

First, instantiate a new Intent with the specific action name required by the Get Smart application:

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

Step 2: Add Required Parameters

Pass the refund details to the Get Smart application using 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);

Critical: The original_order parameter is required for refunds. This links the refund to the original payment transaction. Use the exact ORDER value returned in the original payment response.

Step 3: Add Optional Parameters

You can also include optional parameters to track the refund:

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

Step 4: Launch the Transaction

Execute the intent using 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();
}

The following code snippet demonstrates the complete flow for initiating a refund:

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

The table below lists the minimum fields you need to send:

Refund Types

Full Refund - To refund the entire original transaction amount, set the refund amount equal to the original payment amount.

Partial Refund - To refund only part of the original transaction, set the refund amount to less than the original payment amount.

What Happens Next

After you launch the Intent, the Get Smart application takes control, displays the refund interface, processes the refund, handles receipt printing, and returns control to your application via onActivityResult.

Error Handling

Missing Original Order - If you don’t provide the original_order parameter, the refund will fail. The Get Smart application needs this to link the refund to the original payment.

Invalid Original Order - If the original_order doesn’t match any existing transaction, the refund will be denied. Ensure you’re using the exact ORDER value from the original payment response.

Application Not Found - If the Get Smart application is not installed, Android throws an ActivityNotFoundException. Always catch this exception and inform the user.

Wrong Parameter Name - The parameter must be original_order (with underscore), not originalOrder or original-order. Android Intent extras are case-sensitive and use the exact key name.

Transaction Not Found - If the original transaction is too old or not in the Get Smart system, the refund may fail. Check your payment processor’s policies on refund time limits.

Best Practices

When processing refunds, follow these best practices:

• Store Original Order Numbers - Save the ORDER value from each payment response for future refund operations
• Validate Refund Amount - Ensure the refund amount doesn’t exceed the original payment amount
• Track Refunds - Maintain records of which orders have been refunded and by how much
• Handle Partial Refunds - If your business logic allows multiple partial refunds, track the cumulative refunded amount
• User Confirmation - Consider asking for user confirmation before processing a refund
• Audit Trail - Log all refund attempts with timestamps and outcomes

Next Steps

Now that you understand how to process refund transactions:

• Learn how to handle the refund result in Handle Transaction Results
• Learn how to create a single-step payment in Create a Single-Step Payment
• Review all request parameters in Request Parameters Reference