Referência: PaykitUiCallback

Na edição Reduced (Headless) não existem telas internas. Sempre que o fluxo de pagamento precisa exibir uma informação ou coletar um dado, o SDK invoca um método da interface PaykitUiCallback que o aplicativo registrou.

O aplicativo é responsável por:

1. Exibir a informação ou solicitação na própria interface; e
2. Nos métodos que coletam dados, devolver a resposta chamando o lambda operationResult recebido.

Pacote: com.linx.paykit.common.ui

Grupos de métodos

Grupo	Métodos	Resposta
Informativos	onShowMessage, onShowAlert, onShowError, onShowProcessing, onShowInsertCard, onShowRemoveCard, onShowPassword, onShowQrCode	Apenas exibir
Interativos	onShowConfirmation, onShowInput, onShowMenu	Chamar operationResult
Estado de cancelamento	setCanceledStatus, showCanceledStatus, isCanceled	Armazenar/retornar flag

Atenção

Em todo método interativo, o aplicativo deve chamar operationResult exatamente uma vez (com sucesso ou cancelamento). Se não chamar, o fluxo TEF fica suspenso aguardando a resposta. Se o callback não estiver registrado, o SDK responde "cancelado" a cada solicitação e o fluxo interativo entra em repetição.

Métodos informativos

Recebem o conteúdo a ser exibido e não exigem resposta.

Método	Quando é chamado	Ação do aplicativo
onShowAlert(message)	Alerta simples.	Exibir o alerta.
onShowMessage(message)	Mensagem informativa / instrução / atualização de status.	Exibir e atualizar a mensagem corrente.
onShowError(message)	Mensagem de erro.	Exibir como erro (o SDK aguarda ~2s após a chamada).
onShowProcessing(message)	Operação em andamento (ex.: "Processando, aguarde...").	Exibir indicador de progresso.
onShowInsertCard(message)	Instrução para inserir/aproximar/passar o cartão.	Exibir de forma proeminente.
onShowRemoveCard(message)	Instrução para retirar o cartão.	Exibir a instrução.
onShowPassword()	Coleta de senha (PIN) no pinpad.	Exibir indicativo "digite a senha" (a digitação é capturada pelo pinpad).
onShowQrCode(message, qrCode, timeout)	Exibição de QR Code (Pix/QR).	Renderizar qrCode como QR Code pelo tempo de timeout (segundos).

Métodos interativos

Exigem que o aplicativo chame operationResult com o resultado da interação.

onShowConfirmation

fun onShowConfirmation(message: String, operationResult: (ConfirmationOperationResult) -> Unit)

Solicita uma confirmação Sim/Não (ex.: "OPERACAO CANCELADA?", "Imprimir via do cliente?").

override fun onShowConfirmation(
    message: String,
    operationResult: (ConfirmationOperationResult) -> Unit
) {
    mostrarDialogoSimNao(
        message,
        onSim = { operationResult(ConfirmationOperationResult.Yes) },
        onNao = { operationResult(ConfirmationOperationResult.No) }
    )
}

ConfirmationOperationResult:

Valor	Significado
Yes	Operador confirmou.
No	Operador negou / cancelou a etapa.

onShowInput

fun onShowInput(parameters: InputParameters, operationResult: (InputOperationResult) -> Unit)

Solicita a entrada de um dado (ex.: número do cartão na anulação digitada, validade, CVV, valor). O objeto InputParameters descreve o campo:

Campo	Tipo	Descrição
label	String	Rótulo do campo (ex.: "NUMERO DO CARTAO").
mask	String?	Máscara de formatação, quando houver.
defaultValue	String?	Valor inicial sugerido.
minLength	Int?	Tamanho mínimo do dado.
maxLength	Int?	Tamanho máximo do dado.
minValue	BigDecimal?	Valor mínimo (para campos numéricos/monetários).
maxValue	BigDecimal?	Valor máximo (para campos numéricos/monetários).
dataType	InputDataType?	Tipo do dado solicitado.
amountDecimals	Int?	Casas decimais (campos de valor).

InputDataType: AMOUNT, AMOUNT_DECIMALS, TEXT, NUMBER, CARD_NUMBER, CARD_DATE, CARD_SECURITY_CODE, DATE. Utilize-o para escolher o teclado/máscara e validar com minLength/maxLength.

override fun onShowInput(
    parameters: InputParameters,
    operationResult: (InputOperationResult) -> Unit
) {
    coletarTexto(
        label = parameters.label,
        tipo = parameters.dataType,
        onConfirmar = { texto -> operationResult(InputOperationResult.Success(texto)) },
        onCancelar = { operationResult(InputOperationResult.Canceled) }
    )
}

Exemplo de implementação do coletarTexto com AlertDialog:

private fun coletarTexto(
    label: String,
    tipo: InputDataType?,
    onConfirmar: (String) -> Unit,
    onCancelar: () -> Unit
) = activity.runOnUiThread {
    val input = EditText(activity).apply {
        hint = label
        inputType = when (tipo) {
            InputDataType.NUMBER, InputDataType.CARD_NUMBER,
            InputDataType.CARD_SECURITY_CODE -> InputType.TYPE_CLASS_NUMBER
            InputDataType.AMOUNT, InputDataType.AMOUNT_DECIMALS ->
                InputType.TYPE_CLASS_NUMBER or InputType.TYPE_NUMBER_FLAG_DECIMAL
            else -> InputType.TYPE_CLASS_TEXT
        }
    }
    AlertDialog.Builder(activity)
        .setTitle(label)
        .setView(input)
        .setCancelable(false)
        .setPositiveButton("Confirmar") { _, _ -> onConfirmar(input.text.toString()) }
        .setNegativeButton("Cancelar") { _, _ -> onCancelar() }
        .show()
}

InputOperationResult:

Valor	Significado
Success(text)	Valor digitado pelo operador.
Canceled	Operador cancelou a entrada (aborta a etapa).
Ignore	Pular este campo (tratado como string vazia).

onShowMenu

fun onShowMenu(label: String, items: Array<String>, timeout: Int?, operationResult: (MenuOperationResult) -> Unit)

Solicita a seleção de uma opção (ex.: escolher agenda, tipo de financiamento). timeout em segundos (null = sem tempo limite).

override fun onShowMenu(
    label: String,
    items: Array<String>,
    timeout: Int?,
    operationResult: (MenuOperationResult) -> Unit
) {
    mostrarMenu(
        label, items,
        onEscolher = { indice -> operationResult(MenuOperationResult.Success(indice)) },
        onCancelar = { operationResult(MenuOperationResult.Canceled) }
    )
}

Exemplo de implementação do mostrarMenu com AlertDialog:

private fun mostrarMenu(
    label: String,
    items: Array<String>,
    onEscolher: (Int) -> Unit,
    onCancelar: () -> Unit
) = activity.runOnUiThread {
    AlertDialog.Builder(activity)
        .setTitle(label)
        .setCancelable(false)
        .setItems(items) { _, indice -> onEscolher(indice) }
        .setNegativeButton("Cancelar") { _, _ -> onCancelar() }
        .show()
}

Quando timeout for informado, agende a resposta padrão (ex.: MenuOperationResult.Canceled ou a opção default do seu fluxo) para o caso de o operador não escolher dentro do prazo — e garanta que operationResult seja chamado uma única vez.

MenuOperationResult:

Valor	Significado
Success(index)	Índice (base 0) da opção escolhida em items.
Canceled	Seleção cancelada.

Nota

O SDK resolve casos triviais antes de chamar o aplicativo: menu vazio é cancelado e menu com uma única opção é selecionado automaticamente. O aplicativo recebe a chamada quando há duas ou mais opções. Existe ainda uma sobrecarga deprecada de onShowMenu sem timeout; implemente-a (a interface exige) delegando para a versão atual.

Estado de cancelamento

Membro	Direção	Descrição
isCanceled	Leitura	Propriedade-espelho do status de cancelamento, mantida pelo aplicativo.
setCanceledStatus(canceled)	SDK → app	O SDK define o status (ex.: limpa para false ao iniciar/encerrar a jornada). O app deve gravar.
showCanceledStatus()	SDK → app	O SDK lê se o app solicitou cancelamento.

@Volatile private var canceled = false
override val isCanceled: Boolean get() = canceled
override fun setCanceledStatus(canceled: Boolean) { this.canceled = canceled }
override fun showCanceledStatus(): Boolean = canceled

Nota

Na edição Reduced, implemente os três membros (a interface exige), mas para abortar uma etapa interativa em andamento responda ConfirmationOperationResult.No / InputOperationResult.Canceled / MenuOperationResult.Canceled na própria solicitação.

Threading

Atenção

• Os métodos do PaykitUiCallback são invocados em thread de segundo plano do SDK (não a thread principal/UI). Faça a exibição na thread principal (runOnUiThread / Handler(Looper.getMainLooper())).
• O lambda operationResult pode ser chamado de qualquer thread — chame-o quando o operador concluir a interação.
• Chame operationResult uma única vez por solicitação; chamadas extras são ignoradas pelo SDK.
• Não bloqueie a thread do callback aguardando o operador — colete o dado de forma assíncrona e responda via operationResult.