Pular para o conteúdo principal

Configuração

Pré-requisitos​

  • Terminal POS com o serviço BTG Pay (com.btg.pay.service) instalado
  • Android Studio com suporte a minSdk 30 (Android 11)
  • compileSdk 35 ou superior no build.gradle do app
  • Java 17 configurado no projeto (sourceCompatibility e targetCompatibility)

Adicionar o AAR ao projeto​

O arquivo btg-pay-client.aar deve ser colocado no diretório libs/ do módulo do app. Se o diretório não existir, ele deve ser criado manualmente.

app/
├── libs/
│   └── btg-pay-client.aar
├── src/
└── build.gradle.kts

Em seguida, declarar as dependências no build.gradle.kts:

// build.gradle.kts do módulo app
dependencies {
    implementation(files("libs/btg-pay-client.aar"))
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1")
}

A dependência de kotlinx-coroutines-android é necessária porque as operações assíncronas do SDK — como impressão e consulta de status — utilizam coroutines.

Após essa configuração, sincronizar o projeto no Android Studio. O BtgPayClient e as demais interfaces do SDK estarão disponíveis para importação.

Conectar ao serviço​

Toda operação do SDK exige uma conexão ativa com o serviço BTG Pay. A conexão é estabelecida chamando connect com um ConnectionListener.

import btgpay.client.BtgPayClient

class MinhaActivity : AppCompatActivity() {

    private val client by lazy { BtgPayClient(applicationContext) }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        client.connect(object : BtgPayClient.ConnectionListener {
            override fun onConnected() {
                // Client pronto para uso.
            }
            override fun onDisconnected() {
                Log.w(TAG, "Serviço desconectado — aguardando reconexão automática")
            }
            override fun onBindFailed() {
                Log.e(TAG, "Serviço BTG Pay não está instalado no terminal")
            }
            override fun onInitFailed(reason: String) {
                Log.e(TAG, "Falha na inicialização: $reason")
            }
        })
    }

    override fun onDestroy() {
        client.disconnect()
        super.onDestroy()
    }
}

A desconexão é feita com disconnect(), que cancela qualquer operação em andamento antes de desvincular o serviço.

Quando o processo do serviço morre, o Android mantém o binding e tenta reconectar automaticamente — o onConnected será chamado novamente quando o serviço voltar. Se connect for chamado com o client já conectado, o onConnected é invocado imediatamente. Se chamado durante uma conexão em andamento, o novo listener substitui o anterior e a conexão é reaproveitada.

Próximos passos​

Com a conexão ativa, o terminal está pronto para operar. O próximo passo depende do cenário: