Transaction Lifecycle

A payment transaction in the Get Mini Android SDK is executed through a coordinated sequence of operations between your Android application, the integrated mPOS library, the external Get Mini PIN pad, and the payment authorization host. Understanding this lifecycle is essential for correct session management, user feedback, and safe handling of exceptional situations.

This document describes the transaction flow as implemented by the Get Mini Android SDK, based on direct method calls and synchronous response objects.

Understanding Transaction Stages

Each card-present transaction progresses through four logical stages. These stages reflect the actual responsibilities defined in the Get Mini Android SDK and the PIN pad protocol.

At every stage, failures may occur that require explicit handling by the host application.

Stage 1: Initialization and PIN pad Connection

Before any payment operation can be performed, the application must ensure that:

• The execution environment (integration, certification, or production) is configured via RedCLSConfigurationLibrary.setiEntorno().
• The application license has been initialized via RedCLSConfigurationLibrary.setAppLicense().
• A successful login has been performed (with credentials via RedCLSMerchantConfigurationManager.login() or transparent login via autoLogin()/loginWithoutUser()).
• A valid terminal (RedCLSTerminalData) has been selected from the login response.

Once these prerequisites are satisfied, the application must establish a connection with the PIN pad using the RedCLSPinPadManager. The PIN pad can be connected via Bluetooth, USB, or Wi‑Fi, depending on the RedCLSConfigurationPinPadData configuration.

The connection process involves:

1. Instantiating RedCLSPinPadManager with a delegate implementing RedCLSPinPadInterface, the PIN pad configuration, and terminal data.
2. Calling connectWithPinPad() to establish the physical connection.
3. Waiting for the conexionPinPadRealizada() callback to confirm successful connection.

After the physical connection is established, the PIN pad must be explicitly initialized by calling inicializarPinpad(). During this process, the SDK:

• Verifies that the PIN pad is authorized for the selected terminal.
• Synchronizes configuration and parameters.
• Transparently performs key loading or software updates if required (telecarga).

The initialization returns a RedCLSInitPinPadResponse object containing status, terminal information, and key loading details.

Initialization typically occurs once per application session. Subsequent transactions may reuse the existing connection and initialization state unless the connection is lost or the PIN pad is reset.

Stage 2: Card Reading and Customer Interaction

Once the transaction parameters (amount, invoice reference, and optional flags) are constructed in a RedCLSOperativeWithCardData object, the application invokes the payment operation:

RedCLSOperativeWithCardResponse response =
    pinPadManager.operativaConTarjeta(operativeData);

At this point, the PIN pad enters an interactive state and requests customer input. Depending on the card and transaction context, this may involve:

• Contactless: tapping a card or mobile device on the PIN pad’s NFC reader.
• Chip (EMV): inserting the card into the reader and, if required, entering the PIN on the secure keypad.
• Magnetic stripe: swiping the card through the reader.

All card data capture, PIN entry, and cryptographic processing are performed exclusively on the PIN pad. The Android application never has access to raw card data.

During this stage, the application may receive callbacks through the RedCLSPinPadInterface for:

• DCC (Dynamic Currency Conversion): The seleccionMonedaPagoDCC() callback allows the customer to choose the transaction currency.
• Installment payment: The seleccionDeferPayment() callback allows the customer to select installment options.

The application should guide the customer through clear UI instructions and wait for the PIN pad to complete the capture process or report an error or cancellation.

Stage 3: Authorization Processing

After successful card capture, the Get Mini Android SDK transmits the encrypted transaction data to the authorization host using the P.U.P protocol.

While authorization is in progress:

• The transaction must be considered in flight.
• The application must not interrupt the process.
• The PIN pad remains locked for the current operation.

Authorization time depends on network conditions and host response times. The SDK performs this operation synchronously and returns a definitive result once the host has approved or declined the transaction.

Critical: All network operations must be executed on a background thread, never on the Android UI thread.

Stage 4: Finalization and Result Handling

When the authorization response is received, the SDK finalizes the operation and returns a RedCLSOperativeWithCardResponse object containing:

• status: Integer code indicating success (0) or error.
• Response: String containing the server’s XML response (if successful).
• msgKO: Error description (if failed).
• stackTraceKO: Exception trace (if failed).
• transactionData: A RedCLSTransactionData object with parsed transaction details including:
  • Card number (masked), expiration, cardholder name
  • Transaction amount, currency, order number
  • Authorization code and response code
  • Transaction identifier (RTS)
  • EMV-specific data (if applicable)
  • Receipt printing flags and literals
  • DCC data (if applicable)

The application must:

1. Check the status field to determine if the operation succeeded.
2. For approved transactions, extract the transactionData for receipt printing and record-keeping.
3. For declined transactions, display the appropriate error message from msgKO or responseCode.

After finalization, the application may either:

• Keep the PIN pad connection open to process additional transactions (recommended for consecutive operations), or
• Explicitly close the connection by calling cerrarConexiones() to release PIN pad resources.

At this stage, the transaction lifecycle is complete.

Transaction State Communication

The Get Mini Android SDK communicates transaction progress and results through synchronous method calls that return structured response objects.

Each operation returns:

• A status code indicating success or failure.
• A result or error description.
• Detailed transaction data when applicable (via RedCLSTransactionData).

If an error occurs at any stage, the lifecycle terminates immediately and control returns to the application. Common failure scenarios include:

• PIN pad connection loss during interaction (pinPadNoEncontrado() callback).
• Customer cancellation during PIN entry.
• Network errors during authorization.
• Invalid terminal or configuration states.

Applications should interpret error codes (defined in RedCLSErrorCodes) carefully and provide appropriate user feedback or retry options when safe to do so.

Connection Management Best Practices

• Single session, multiple transactions: If processing multiple consecutive payments, keep the PIN pad connection and initialization active between transactions to improve performance.
• Connection state tracking: Maintain state to determine whether connection and initialization are required before each operation.
• Proper cleanup: Always call cerrarConexiones() when exiting the payment flow or when the application is backgrounded.

SDK Version Notes

This lifecycle description applies to:

• Get Mini Android SDK 2.5.x – Current reference implementation

Earlier versions follow the same conceptual flow but may differ in method signatures and supported features.

Related Resources

• Security and Device Binding – Terminal association, transparent login, and key management
• Quickstart: Your First Sale – End-to-end example covering login, PIN pad initialization, and payment execution