Guia de Migração: SDK TEF para SDK Único

Este guia orienta integradores que utilizam o SDK TEF (componente DTEFMobile, classe MobileSDK, documentado no DevCenter anterior) na migração para o SDK Único. A partir desta consolidação, este DevCenter passa a concentrar toda a documentação de integração de pagamentos.

Por que migrar?

O SDK TEF foi descontinuado e não receberá novas funcionalidades — a evolução acontece no SDK Único, que mantém a comunicação com o autorizador Linx TEF (DTEF Server) e adiciona:

• Interface única para múltiplas adquirentes: a mesma integração atende Linx TEF, Stone, Cielo, Getnet, Rede, PagSeguro, Sicoob, SiTef, Vero e outras.
• Distribuição via repositório Maven: sem cópia manual de AARs no projeto.
• Bibliotecas de fabricante resolvidas por flavor: as dependências proprietárias de cada terminal (Sunmi, Gertec, Ingenico, Transire, etc.) são embarcadas pelo SDK — o App não precisa mais declarar PPComp, gedi-payment, bcapos e afins.
• Interface de usuário embarcada opcional: o fluxo de captura dirigido por callbacks (UICallback) passa a ser opcional; por padrão o SDK Único exibe as próprias telas da jornada de pagamento.

Visão geral das diferenças

Aspecto	SDK TEF (DTEFMobile)	SDK Único
Distribuição	AARs locais (dtefmobile, log-manager, linxpay-sdk)	Repositório Maven SDK_UNICO
Dependências de fabricante	Declaradas pelo App, por modelo de terminal	Resolvidas pelo SDK via flavors ou artefatos standalone
Classe principal	MobileSDK (pacote com.linx.dtefmobile.sdk)	Paykit (pacote com.linx.paykit.core)
Ativação do terminal	Auth + Auth.AuthCredential (CNPJ + token)	paykit.activate(ActivationParameters) (CNPJ + token)
Montagem da transação	TransactionBuilder + TransactionType/ParameterType	Métodos dedicados (credit, debit, voucher, pix, fleet, ...) com objetos de parâmetros tipados
Interação com o usuário	Obrigatória via UICallback (App desenha toda a UI)	Telas embarcadas por padrão; UI própria via PaykitUiCallback (edição padrão ou Edição Reduced)
Confirmação da transação	confirmTransaction/undoTransaction + finalizeTransaction manuais	autoConfirm = true (padrão) ou confirmPendingTransaction/undoPendingTransaction com finalizePayment
Resultado	TransactionResult (getResultCode() == 0)	PaymentResult (status == APPROVED; PENDING quando autoConfirm = false)
Impressão	SmartPrintService + PrintLayoutBuilder	paykit.print(bitmap), printLastReceipt, printReceipt
Linguagem dos exemplos	Java	Kotlin (interoperável com Java)

Pré-requisitos

1. Credenciamento: para utilizar o SDK Único é necessário ser credenciado como Automação Comercial/Integrador e possuir um PaykitId. Veja Cadastre-se.
2. Acesso ao repositório Maven: solicite o Personal Access Token do feed SDK_UNICO durante o processo de integração.
3. Terminal compatível: confira a página de Dispositivos Homologados.

Passo 1 - Substituir as dependências

Remova do projeto os módulos locais e bibliotecas do SDK TEF:

// REMOVER - SDK TEF
implementation project(path: 'dtefmobile')
implementation project(path: 'log-manager')
implementation project(path: 'linxpay-sdk')
implementation 'org.slf4j:slf4j-api:1.7.28'
implementation 'com.github.tony19:logback-android:2.0.0'

Remova também as dependências proprietárias por fabricante que o SDK TEF exigia para SmartPOS (por exemplo PPCompp2, PayLib-release, bcapos, dm-apos, gedi-payment, libhcl-gpos780). No SDK Único elas são embarcadas pela flavor da adquirente/terminal.

Em seguida, configure o repositório SDK_UNICO, as flavors e as dependências do SDK Único conforme Primeiros Passos:

val sdkPayServicesVersion = "VERSAO_ATUAL"

implementation("SDKPayServices:core:$sdkPayServicesVersion")
implementation("SDKPayServices:config:$sdkPayServicesVersion")
implementation("SDKPayServices:common:$sdkPayServicesVersion")

Para quem migra do SDK TEF e continua transacionando com o autorizador Linx, as flavors equivalentes são linxtef (geral), linxtefadyen, linxtefgpos760 e linxtefgpos720. Se o projeto não puder adotar flavors, utilize os artefatos standalone (core-linxtef, linxtef, ...) descritos em Primeiros Passos.

Ambientes legados

Integrações do SDK TEF em projetos antigos (AGP 3.3.x, Gradle 4.10.3, Java 8, Android 7.1) podem migrar para a Edição Reduced, variante headless do SDK Único com artefatos *-reduced compatíveis com esse toolchain — o modelo de UI por callbacks é o mais próximo do UICallback do SDK TEF.

Passo 2 - Revisar o AndroidManifest

As permissões exigidas são praticamente as mesmas do SDK TEF. Confira a lista completa em Primeiros Passos — destaque para READ_PHONE_STATE, que passa a ser necessária.

Passo 3 - Migrar a instanciação do SDK

No SDK TEF, o App instanciava MobileSDK(activity, uiCallback) e a classe Auth para a ativação. No SDK Único, tudo parte de uma única instância de Paykit, criada via PaykitFactory:

val paykit = PaykitFactory().build(
    Parameters(this, "Nome da Aplicação", PaykitId("SEU_PAYKIT_ID"))
)

Atenção

Crie a instância uma única vez na inicialização do aplicativo (ex.: onCreate) e reutilize-a em todas as operações. A instanciação não deve ser refeita a cada ativação ou transação.

Passo 4 - Migrar a ativação do terminal

A ativação continua sendo feita uma única vez por terminal (ou quando ele é realocado para outra loja), com CNPJ da loja e token de ativação.

Antes (SDK TEF):

Auth auth = new Auth(application, this); // this = UICallback
Auth.Credential credential = Auth.AuthCredential.getCredential(
    Environment.SANDBOX,
    "11111111111111",           // CNPJ
    "baF64aaR5a4dez91a86e72f8"  // token de ativação
);
auth.authenticate(credential, new Auth.Callback() { /* ... */ });

Depois (SDK Único):

val activationParams = ActivationParameters(
    storeCnpj = "11111111111111",
    tef = TefActivationParameters(
        production = false,             // Environment.SANDBOX -> false
        token = "baF64aaR5a4dez91a86e72f8"
    )
)

paykit.activate(activationParams, object : Callback<ActivationResult> {
    override fun execute(result: ActivationResult?) {
        if (result?.success == true) { /* terminal ativado */ }
    }
})

Correspondências:

SDK TEF	SDK Único
Environment.PRODUCTION / Environment.SANDBOX	TefActivationParameters.production = true/false
CNPJ em getCredential(...)	ActivationParameters.storeCnpj
Token de ativação em getCredential(...)	TefActivationParameters.token
Auth.CustomCredential (host próprio)	Tratado no processo de integração com a equipe Linx
Dados do estabelecimento no retorno	ActivationResult (success, message, rawData com número de série)

Passo 5 - Migrar as transações

No SDK TEF toda transação passa por TransactionBuilder + executeTransaction. No SDK Único cada modalidade tem um método dedicado com objeto de parâmetros próprio — consulte a seção Transações deste DevCenter para cada uma.

Operação no SDK TEF	SDK Único
TransactionBuilder.credit() + executeTransaction	paykit.credit(creditParameters)
TransactionBuilder.debit() + executeTransaction	paykit.debit(debitParameters)
TransactionBuilder.voucher() + executeTransaction	paykit.voucher(voucherParameters)
QR Code / PIX (JSON_INTEGRACAO_QR)	paykit.pix(paymentParameters), paykit.wallet e paykit.qrCode
Frota (LISTA_PRODUTOS_ABASTECIMENTO)	paykit.fleet(fleetParameters) com TefFleetUnifiedBuilder
TransactionBuilder.cancel()	paykit.cancel(cancelParameter)
Pré-autorização	paykit.preAuthorize / capturePreAuthorization / cancelPreAuthorization
Reimpressão	paykit.printLastReceipt(receiptType)
Consulta de transação	paykit.getTransaction / getLastTransaction
Menu administrativo	paykit.executeAdminOperation(AdminOperation.SHOW_MENU)

Exemplos: QR Code/PIX e Frota

Dois casos em que a migração muda mais a forma de parametrizar. No QR Code, o SDK TEF recebia um JSON de integração via withParameter(ParameterType.JSON_INTEGRACAO_QR, json) (carteiras, pagador, expiração). No SDK Único, a transação usa parâmetros tipados:

val paymentParams = PaymentParameters(
    amount = BigDecimal("10.00"),
    externalId = "ORDER_123456"
)

paykit.pix(paymentParams, object : Callback<PaymentResult> {
    override fun execute(result: PaymentResult) { /* tratar resultado */ }
})

Na Frota, os dados de abastecimento iam no JSON ParameterType.LISTA_PRODUTOS_ABASTECIMENTO (placa, matrícula, hodômetro, produtos). No SDK Único, use FleetParameters — e, para o fluxo unificado de frotas TEF, o TefFleetUnifiedBuilder descrito em Frota:

val fleetParams = FleetParameters(
    amount = BigDecimal("200.00"),
    vehiclePlate = "ABC1234",
    driverId = "12345678901",
    odometer = 1000
)

paykit.fleet(fleetParams, object : Callback<PaymentResult> {
    override fun execute(result: PaymentResult) { /* tratar resultado */ }
})

Pré-autorização, reimpressão e as demais operações têm mapeamento direto na tabela acima, com exemplo completo na página de cada transação.

Parâmetros de entrada

Os with*() do TransactionBuilder e os ParameterType de entrada viram campos tipados nos objetos de parâmetros:

SDK TEF	SDK Único
withAmount(20.00) / VALOR_TRANSACAO (valor x100)	amount = BigDecimal("20.00") (valor decimal)
withInstallment(n) / NUMERO_PARCELAS	installments = n
withCpf(...) / CPF_CLIENTE	cpf = "..."
withBillOfSale(...) / CUPOM_FISCAL	billOfSale = "..."
withDateOfSale / withHourOfSale	dateTimeOfSale = Date(...)
withFinancialType(FinancialType...)	creditType = CreditTransactionType... (ver tabela abaixo)
withParameter(ParameterType, ...)	Campos dedicados dos *Parameters (externalId, items, postCreditDays, ...)
TRATAR_DESFAZIMENTO	autoConfirm
NOME_APLICACAO	Parameters(context, "Nome da Aplicação", paykitId) na construção do Paykit

Atenção

No SDK TEF o valor era informado em centavos ("100" = R$ 1,00). No SDK Único o valor é um BigDecimal decimal (BigDecimal("1.00") = R$ 1,00).

Modalidades de financiamento

FinancialType (SDK TEF)	CreditTransactionType (SDK Único)
ONE_INSTALMENT (à vista)	AT_SIGHT
MERCHANT (parcelado lojista)	STORE_INSTALMENTS
ISSUER (parcelado administradora)	ADMIN_INSTALMENTS ou ISSUER_INSTALMENTS
CDC	BANK_INSTALMENTS / FINANCING (consultar provedor)
PRE_DATED (pré-datado)	postCreditDays nos parâmetros de crédito
WITH_INSTALMENT_CASH / WITHOUT_INSTALMENT_CASH	Consultar modalidades do provedor (suporte Banrisul/Vero)

Confirmação e desfazimento

No SDK TEF, após cada transação autorizada era obrigatório chamar confirmTransaction ou undoTransaction, e finalizeTransaction ao fim do ciclo. No SDK Único:

• Com autoConfirm = true (padrão), a confirmação é enviada automaticamente e o ciclo é gerenciado pelo SDK.
• Com autoConfirm = false, a transação retorna com status == PENDING e o App deve chamar paykit.confirmPendingTransaction(pendingTransactionParameters) ou paykit.undoPendingTransaction(pendingTransactionParameters) — equivalentes diretos de confirmTransaction/undoTransaction.
• O papel do finalizeTransaction passa a ser o parâmetro finalizePayment (padrão true) dos PendingTransactionParameters: em ciclos com múltiplos pagamentos, informe finalizePayment = false nas confirmações/desfazimentos intermediários e true na última operação do ciclo.

Passo 6 - Migrar o tratamento do resultado

Antes (SDK TEF): TransactionCallback.onResult(TransactionResult), sucesso somente quando getResultCode() == 0.

Depois (SDK Único): Callback<PaymentResult>, sucesso quando status == TransactionStatus.APPROVED.

TransactionResult (SDK TEF)	PaymentResult (SDK Único)
getResultCode() == 0	status == TransactionStatus.APPROVED (ou PENDING quando autoConfirm = false — transação aprovada aguardando confirmPendingTransaction)
getResultCode() != 0 / getErrorMessage()	status (DECLINED, ERROR, CANCELLED, ...) e message
getNsu() / getAuthorizerNsu() / getAuthorizerNsuAdicional()	nsuInfo
getAuthorizationCode(), getBrand(), getCardNumber(), ...	transactionInfo
getTransactionAmount()	amount (BigDecimal)
getReceipt() / getCustomerSalesReceipt() / getStoreSalesReceipt()	transactionInfo.storeReceipt / transactionInfo.customerReceipt; reimpressão via printLastReceipt/printReceipt
getFinancialType() / getOperationType()	paymentType e transactionType
getParameter(ParameterType)	rawData (Map<String, String>)
getInstallment()	transactionInfo
MobileSDK.getInfo() (Info)	paykit.retrieveSdkInfo() (Map<String, String>)

Passo 7 - Migrar a interface de usuário

Esta é a maior mudança conceitual da migração.

No SDK TEF, o App era obrigado a implementar UICallback (onShowMessage, onInput, onShowMenu, onMaskInput, onShowQRCode, getCanceledStatus, ...) e desenhar toda a jornada de captura dirigida pelo SDK.

No SDK Único, há dois caminhos:

1. Edição padrão (recomendada): o SDK exibe as próprias telas da jornada de pagamento (leitura de cartão, senha, QR Code, mensagens). O App apenas chama o método da transação e trata o resultado no Callback. Toda a implementação de UICallback pode ser removida. A edição padrão também aceita UI própria: registre um PaykitUiCallback com useInternalScreens = false.
2. Edição Reduced (headless): para quem precisa de UI própria em ambiente legado que não comporta o módulo de UI do SDK (sem Jetpack Compose), a Edição Reduced expõe a mesma interface PaykitUiCallback, equivalente funcional do UICallback.

Correspondência dos principais callbacks para quem optar por UI própria (edição padrão com useInternalScreens = false ou Edição Reduced):

UICallback (SDK TEF)	PaykitUiCallback (SDK Único)
onShowMessage / onShowError / onShowAlert	Callbacks de mensagem da jornada
onInput / onMaskInput (com InputModel)	Callbacks de captura de dados
onShowMenu (com MenuItem/MenuResult)	Callbacks de seleção
onShowQRCode	Callback de exibição de QR Code
getCanceledStatus / setCanceled	Fluxo de cancelamento da jornada

Consulte a assinatura completa em PaykitUiCallback.

Passo 8 - Migrar a impressão

No SDK TEF a impressão usava SmartPrintService (singleton) com layouts montados via PrintLayoutBuilder (38/44/48 colunas, QR Code, código de barras, imagens).

No SDK Único a impressão faz parte da interface Paykit:

SDK TEF	SDK Único
MobileSDK.getInfo().isPrintSupported()	Consulte Dispositivos Homologados; o retorno de print indica NO_PRINTER_DETECTED
PrintLayoutBuilder (texto, alinhamento, QR Code, barcode)	Renderize o layout como Bitmap e use paykit.print(bitmap)
SmartPrintService.print(printLayout, callback)	paykit.print(bitmap, Callback<PrintResult>)
Reimpressão do último comprovante	paykit.printLastReceipt(receiptType)
Impressão de comprovante específico	paykit.printReceipt(printReceiptParameters)
PrinterCallback.onSuccess/onError(code, message)	PrintResult (success, status, message)
Impressão automática do comprovante	autoPrintReceipt / printMerchantReceipt nos parâmetros da transação

Nota

Não há equivalente direto do PrintLayoutBuilder no SDK Único: o comprovante TEF é impresso automaticamente (autoPrintReceipt) ou reimpresso via printLastReceipt; conteúdo customizado (cupons, vias diferenciadas) deve ser gerado como Bitmap pelo App.

Recursos sem equivalente direto

• setCurrentTransactionInfo (códigos 25, 456, 1336): as informações da rede autorizadora e do link de pagamento QR estão disponíveis em PaymentResult.rawData/transactionInfo.
• SUPORTA_CALLBACK_IDENTIFICADA / InputModel.getValueId(): aplicável apenas à Edição Reduced; consulte a equipe Linx durante a integração.
• Split de pagamento (DADOS_SPLIT) e parâmetros Calcard: consulte a equipe Linx sobre disponibilidade no SDK Único para o seu cenário.
• Tela de suporte (requisito de homologação do DTEFMobile 2.3.1+): recomenda-se manter uma tela equivalente exibindo o retorno de paykit.retrieveSdkInfo().
• Deep Link: o SDK Único adiciona um modo de integração por Deep Link, sem equivalente no SDK TEF, útil para integrações de baixo acoplamento.

Dispositivos homologados

A lista de terminais suportados pelo SDK Único — incluindo os equipamentos Transire (linha Zire, séries E e K, e impressora ZTO) portados na ação Transire Day — está centralizada em Dispositivos Homologados. Observe que a homologação de um terminal no SDK TEF não implica homologação automática no SDK Único; consulte sempre a tabela atualizada.

Passo 9 - Homologar com a equipe Linx

Concluída a migração, valide o aplicativo em um dispositivo homologado, exercitando as modalidades de pagamento utilizadas (incluindo confirmação/desfazimento e comprovantes), e agende a homologação com a equipe Linx — assim como no SDK TEF, a homologação é requisito para operar em produção.

Checklist de migração

1. Obter PaykitId (credenciamento) e token do feed Maven SDK_UNICO.
2. Remover AARs do SDK TEF (dtefmobile, log-manager, linxpay-sdk, slf4j/logback) e as BCs/bibliotecas proprietárias de fabricante (PPComp, gedi-payment, bcapos, etc.).
3. Adicionar repositório SDK_UNICO, flavors (ou artefatos standalone) e dependências SDKPayServices:*.
4. Revisar permissões do AndroidManifest.xml.
5. Criar a instância única do Paykit via PaykitFactory().build(...) na inicialização do App.
6. Substituir Auth/authenticate por paykit.activate(...).
7. Substituir TransactionBuilder/executeTransaction pelos métodos dedicados do Paykit, convertendo valores para BigDecimal.
8. Substituir confirmTransaction/undoTransaction/finalizeTransaction por autoConfirm (ou confirmPendingTransaction/undoPendingTransaction com finalizePayment na última operação do ciclo).
9. Adaptar o tratamento de resultado para PaymentResult/TransactionStatus (incluindo PENDING quando autoConfirm = false).
10. Remover a implementação de UICallback (edição padrão) ou migrá-la para PaykitUiCallback (useInternalScreens = false ou Edição Reduced).
11. Migrar a impressão para paykit.print/printLastReceipt/printReceipt.
12. Validar em dispositivo homologado e realizar a homologação com a equipe Linx (Passo 9).