Pular para o conteúdo principal

API PosPinpad

Referência da interface PosPinpad (com.tupifintech.apossdk.sdk.api) — a porta de entrada do SDK.

Visão Geral​

A interface concentra todas as operações de alto nível: configuração, registro/inicialização, captura de cartão/PIN, pagamentos, PIX, estorno, pré-autorização, consultas, impressão e tela secundária.

Métodos suspend executam I/O e devem ser chamados de dentro de um CoroutineScope. Métodos @RunAsync são despachados internamente para threads próprias e retornam pelos callbacks.

Criação da instância​

companion object {
    fun create(context: Context, posPinpadCallback: PosPinpadCallback): PosPinpad
}

Inicializa o HttpClient (mTLS) e retorna a instância pronta. Sempre use este método.

val posPinpad = PosPinpad.create(context, callback)

Configuração e Inicialização​

getTerminalConfig()​

suspend fun getTerminalConfig(slug: String): TerminalConfigResponse

Busca a personalização do parceiro (identidade visual, IDs de escopo, schema de registro, botões da dashboard, documentos legais, customização de recibo). Lança TerminalConfigException em caso de falha.

authenticate()​

suspend fun authenticate(request: AuthenticationRequest): AuthenticationResponse

Autentica o terminal com credenciais (email/CNPJ + senha).

register()​

suspend fun register(fields: Map<String, String>, partnerSlug: String): RegistrationResult

Registra o terminal via campos dinâmicos do registrationSchema. A chave de cada field é o id do campo no schema. Retorna o merchantId usado na inicialização.

terminalInitialization()​

suspend fun terminalInitialization(
    request: TerminalInitializationRequest
): TerminalInitializationResponse

Inicializa o terminal: carrega tabelas EMV/AID/CAPK e configurações do adquirente. Emite também onTablesLoaded(ok).

logout()​

suspend fun logout()

isTerminalInitialized()​

fun isTerminalInitialized(): Boolean

getTablesInfo()​

fun getTablesInfo(): TablesInfo?

Lê do storage local (não chama o backend) as versões das tabelas EMV por adquirente e o timestamp da última atualização. null se nunca foram carregadas.

Pagamentos​

createPayment()​

suspend fun createPayment(
    type: TransactionType,
    amount: Long,
    paymentMethod: PaymentMethod?,
    installments: Int,
    installmentsInterest: Boolean? = false
)

Inicia o fluxo de pagamento completo (captura de cartão → PIN → processamento → resultado).

Parâmetros:

ParâmetroTipoDescrição
typeTransactionTypeTipo da transação (AUTHORIZATION, PRE_AUTHORIZE, etc.)
amountLongValor em centavos (1000 = R$ 10,00)
paymentMethodPaymentMethod?DEBIT, CREDIT, CASH (PIX usa método próprio)
installmentsIntNúmero de parcelas (1 = à vista)
installmentsInterestBoolean?Se há juros nas parcelas

Fluxo de callbacks (cartão/crédito-débito):

  1. onStartGetCard() — aguardando cartão
  2. onStartGetPinCoordinates(setPinCoordinates) — app fornece as coordenadas do PIN
  3. onPinEntry(pinMask, message, amount) — atualização da máscara
  4. onPinError(...) — senha offline incorreta (se aplicável)
  5. onCardRemovalRequested() / onCardRemoved() — remoção do cartão (chip)
  6. onTransactionCompleted(result) — resultado final

Exemplos:

// Crédito à vista — R$ 50,00
posPinpad.createPayment(
    type = TransactionType.AUTHORIZATION,
    amount = 5000L,
    paymentMethod = PaymentMethod.CREDIT,
    installments = 1
)

// Crédito parcelado — R$ 300,00 em 3x sem juros
posPinpad.createPayment(
    type = TransactionType.AUTHORIZATION,
    amount = 30000L,
    paymentMethod = PaymentMethod.CREDIT,
    installments = 3,
    installmentsInterest = false
)

// Débito — R$ 25,00
posPinpad.createPayment(
    type = TransactionType.AUTHORIZATION,
    amount = 2500L,
    paymentMethod = PaymentMethod.DEBIT,
    installments = 1
)

// Pré-autorização — R$ 100,00
posPinpad.createPayment(
    type = TransactionType.PRE_AUTHORIZE,
    amount = 10000L,
    paymentMethod = PaymentMethod.CREDIT,
    installments = 1
)

createPixPayment()​

suspend fun createPixPayment(amount: Long)

Gera um pagamento PIX (QR Code). O payload chega por onPixQrCodeGenerated(qrCode, transactionId, amount, expiresInSeconds).

cancelPayment()​

fun cancelPayment()

Cancela a operação em andamento, liberando imediatamente qualquer bloqueio aguardando coordenadas ou entrada de senha.

Captura de Cartão​

waitForCard()​

suspend fun waitForCard(
    waitContact: Boolean,
    waitMagneticStripe: Boolean,
    waitContactless: Boolean,
    timeoutSeconds: Int
): CardReadType?

Aguarda um evento de cartão por até timeoutSeconds. Retorna o tipo de leitura (CHIP, CONTACTLESS, MAGSTRIPE) ou null no timeout. Útil para melhorar a UX antes de iniciar a transação.

removeCard()​

suspend fun removeCard()

Consulta de Transações​

getTransactionSummaries()​

suspend fun getTransactionSummaries(filters: QueryFilterBuilder): TransactionSummaryResponse

API unificada (GET /transactions/summaries) para buscar transações: histórico, pré-autorizações ou transações estornáveis — o que muda é o filtro. Use QueryFilterBuilder para montar os filtros dinâmicos.

val filters = QueryFilterBuilder()
    .pagination(offset = 0, limit = 20, preloads = true)
    .add(FilterField.STATUS, FilterOperator.EQ, "approved")
    .add(FilterField.CREATED_AT, FilterOperator.GE, "2025-01-01")

val response = posPinpad.getTransactionSummaries(filters)
response.data.forEach { tx -> /* ... */ }

Veja QueryFilterBuilder e TransactionSummary.

getTransactionLimits()​

fun getTransactionLimits(
    transactionType: TransactionType,
    paymentMethod: PaymentMethod,
    installments: Int = 1
): TransactionLimits?

Consulta os limites configurados para uma operação (valor mín./máx., parcelas, valor por parcela), derivados da inicialização. Use antes de iniciar o pagamento para validar localmente. null se a combinação não existir. Apenas CREDIT/DEBIT retornam valores.

Estorno (Refund)​

startRefundFlow()​

@RunAsync
fun startRefundFlow()

Inicia o fluxo de estorno: captura o cartão, busca transações elegíveis e chama onRefundTransactionsAvailable(...). O app seleciona a transação e confirma pela função recebida no callback. O resultado chega por onRefundCompleted(result) ou onRefundError(code, message).

Pré-Autorização (busca para captura)​

startPreAuthFlow()​

@RunAsync
fun startPreAuthFlow(preAuthId: String? = null)

Inicia o fluxo de busca de pré-autorizações: captura o cartão, busca pré-autorizações elegíveis e chama onPreAuthTransactionsAvailable(...). O app seleciona e confirma a captura pela função recebida no callback.

Para criar uma pré-autorização, use createPayment(type = PRE_AUTHORIZE, ...).

Impressão​

Os métodos de impressão ficam diretamente no PosPinpad. Use os overloads com PrintAttributes (preferidos). O parâmetro notifyComplete controla a propagação de onPrintCompleted() — use false nas instruções intermediárias e true apenas na última.

fun print(text: String)                                  // texto plano (legado)
fun printText(text: String, attributes: PrintAttributes, notifyComplete: Boolean = true)
fun printColumns(texts: List<String>, attributes: List<PrintAttributes>, notifyComplete: Boolean = true)
fun printImage(source: Any, width: Int, height: Int)
fun printImage(source: Any, width: Int, height: Int, attributes: PrintAttributes, notifyComplete: Boolean = true)
fun printBitmap(bitmap: Bitmap, notifyComplete: Boolean = true)
fun printQrCode(payload: String, align: Align = Align.CENTER, sizePx: Int = 200, notifyComplete: Boolean = true)
fun feedPaper(lines: Int, notifyComplete: Boolean = true)
fun feedStep(steps: Int, notifyComplete: Boolean = true)

Exemplo:

posPinpad.printText("COMPROVANTE DE VENDA", PrintAttributes(align = Align.CENTER, typeface = Typeface.BOLD))
posPinpad.printColumns(
    listOf("Valor", "R$ 50,00"),
    listOf(PrintAttributes(weight = 1), PrintAttributes(align = Align.RIGHT, weight = 1))
)
posPinpad.printQrCode(pixPayload, sizePx = 200)
posPinpad.feedStep(1) // destaca a bobina

Veja PrintAttributes (Align/Typeface).

Tela Secundária (apenas OCTA 400)​

Em L300/L400 estes métodos são no-op. Verifique disponibilidade com hasSecondaryDisplay().

fun hasSecondaryDisplay(): Boolean
fun getSecondaryDisplayResolution(): IntArray            // [largura, altura]; default [378, 172]
fun initSecondaryDisplay()                               // → onSecondaryDisplayReady() / onSecondaryDisplayError()
fun setSecondaryDisplayPower(on: Boolean): Boolean
fun setSecondaryDisplayBrightness(percent: Int): Boolean // 0..100
fun showVideoOnSecondaryDisplay(filePath: String): Boolean
fun showOnSecondaryDisplay(source: Any)                  // resId Int, file path/"@drawable/x" String ou Bitmap
fun showMessageOnSecondaryDisplay(message: String)
fun showQrCodeOnSecondaryDisplay(bitmap: Bitmap)
fun showViewOnSecondaryDisplay(view: View)               // medida automaticamente para 378x172
fun clearSecondaryDisplay()
fun releaseSecondaryDisplay()                            // chamar no onDestroy

Dispositivo, Chaves e Diagnóstico​

fun getDeviceInfo(): DeviceInfo
fun hasDukptKey(index: Int): Boolean         // true se getDUKPT(index) e getDUKPTData(index) OK
fun hasPagSeguroKeys(): Boolean
suspend fun checkInternetConnection(): HealthCheckResult
fun cancelPendingTransactionsWorker()        // desativa temporariamente o reenvio de pendentes

Próximos Passos​

  • Callbacks — eventos e notificações
  • Modelos — estruturas de dados e códigos de erro
  • Exemplos — exemplos práticos