Getnet DocsGetnet Docs

Initialize the TPV

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

Initialization is the mandatory first step in the integration lifecycle. You must successfully initialize the TPV before performing any financial operation (such as payments or refunds) or querying transaction data.

During initialization, the library connects to the Get Smart SDK Payment Service to:

  1. Verify Configuration: Ensures the terminal is correctly configured in the Getnet host.
  2. Security Checks: Validates keys and security protocols.
  3. Update Parameters: Downloads the latest configuration (e.g., active features, currency, merchant details) from the host.

Performing Initialization

To initialize the device, use the InitializationRepository.

The core method is initTpv(). This is a suspend function that returns a RepositoryResult containing the TpvInfo object upon success.

Implementation

Call initTpv() within a coroutine scope. Note how we access merchant data via the virtualTerminalList.

suspend fun initializeDevice() {
    // 1. Call the initialization method
    val result = initializationRepository.initTpv()

    // 2. Handle the result
    when (result) {
        is RepositoryResult.Success -> {
            // Initialization successful
            val tpvInfo: TpvInfo = result.data

            // Accessing Configuration Flags
            val isPreauthEnabled = tpvInfo.config.showPreauthorizations
            val isQrEnabled = tpvInfo.config.showQrPayment

            // Accessing Merchant Data (FUC, Terminal, Name)
            // These are stored in the virtual terminal list
            val terminalData = tpvInfo.virtualTerminalList?.firstOrNull()

            println("Initialized Merchant: ${terminalData?.merchantName}")
            println("Terminal ID: ${terminalData?.terminal}")
            println("Currency Code: ${terminalData?.currency}")

            // You can now proceed to payment screens
        }
        is RepositoryResult.ConnectionError -> {
            // Handle network/service failure
            showError("Connection failed. Check internet or Smart SDK Service.")
        }
        is RepositoryResult.ProtocolError -> {
            // Handle logical errors (e.g., TPV_NOT_INITIALIZED or MAPPING errors)
            showError("Protocol Error: ${result.type}")
        }
        is RepositoryResult.Cancelled -> {
            // Handle cancellation (unlikely for initialization, but possible)
        }
    }
}

Understanding TpvInfo

When initialization succeeds, you receive a TpvInfo object. This data class contains crucial details about the terminal’s identity and capabilities.

Key Properties

The object is structured into three main parts:

  • deviceInfo: Specific hardware/terminal data.
  • config (TpvConfig): Operational flags and feature settings.
    • showPreauthorizations: (Boolean) If Pre-authorizations are enabled.
    • noOriginal: (Boolean) If “Refunds without Original” are allowed.
    • showQrPayment: (Boolean) If QR payments (Alipay/WeChat) are enabled.
    • showPlazox: (Boolean) If Plazox (deferred payments) is enabled.
    • isOffline: (Boolean) If the TPV is currently running in offline mode.
  • virtualTerminalList: A list of TpvVirtualTerminal objects containing the financial identity.
    • merchantName: The commercial name of the merchant.
    • fuc: The Merchant ID.
    • terminal: The Terminal Number.
    • currency: The currency code configured (e.g., 978 for EUR).
    • csb / csbType: Banking codes.

Managing Terminal Information

The InitializationRepository provides additional methods to retrieve or update the stored terminal information without triggering a full host synchronization.

Retrieving Cached Info

If you need to access the terminal configuration later in your app (e.g., to display the Merchant Name in a header) without making a network call, use getTpvInfoRepositoryResult().

suspend fun getCachedConfig() {
    val result = initializationRepository.getTpvInfoRepositoryResult()

    if (result is RepositoryResult.Success) {
        val cachedInfo = result.data
        // Use cached data...
    }
}

Saving Terminal Information

In advanced scenarios where you need to manually update the local terminal information context, you can use saveTerminalInformation().

suspend fun updateLocalConfig(newInfo: TpvInfo) {
    initializationRepository.saveTerminalInformation(newInfo)
}

Next Steps

Once the TPV is successfully initialized, you are ready to process transactions: