Integre TEF & PinPads

A sua operação física
potencializada com Iopay

Uma integração dividida em duas camadas bem definidas.

A captura presencial TEF acontece localmente entre Sua Aplicação, o componente Zoop e o PINPad. A operação de pagamentos, porém, continua integrada à IOPAY. Isso preserva uma única camada para conta, gestão transacional, ativação do terminal, eventos e webhooks.

Quem faz o quê na integração.

A separação abaixo evita que o uso do componente Zoop para captura local seja confundido com uma troca da integração principal da operação.

SDK Embedded ou Desktop Server.

Há duas formas documentadas de implementar a camada local. As duas preservam a mesma arquitetura IOPAY para conta, ativação e eventos.

Do projeto vazio ao primeiro pagamento em cinco passos.

implementation(
    "br.zoop.pos.plugin:zoop-pos-plugin-desktop-jvm:X.Y.Z"
)

Zoop.initialize(context)

val desktopPlugin = DesktopPlugin(
    Zoop.constructorParameters()
)

Zoop.plug(desktopPlugin)

val activationRequest =
    ZoopFoundationPlugin
        .createDashboardActivationRequestBuilder()
        .tokenCallback(/* receber e exibir o token */)
        .confirmCallback(/* persistir dados confirmados */)
        .build()

Zoop.post(activationRequest)

{
  "marketplace": "<retornado-na-ativacao>",
  "seller": "<retornado-na-ativacao>",
  "accessKey": "<retornado-na-ativacao>"
}

Zoop Desktop SDK integrado diretamente ao PDV.

Nesta abordagem, o componente de captura fica dentro de Sua Aplicação. O plugin conversa localmente com o PINPad, enquanto a operação continua vinculada à infraestrutura IOPAY.

Inicialização após a ativação

Depois que marketplace, seller e accessKey tiverem sido recuperados e persistidos, use esses valores em tempo de execução para inicializar novamente o SDK. Eles não devem ser digitados manualmente pelo operador.

Zoop.initialize(context) {
    credentials {
        marketplace = storedMarketplace
        seller = storedSeller
        accessKey = storedAccessKey
    }
}

val desktopPlugin = DesktopPlugin(
    Zoop.constructorParameters()
)

Zoop.plug(desktopPlugin)

Estado da integração

O token nasce no SDK e o vínculo é concluído na IOPAY.

A ativação associa o dispositivo à conta correta. Esse passo deve ocorrer antes da primeira transação e precisa ser testado também após reiniciar Sua Aplicação.

Consulte a chave transacional antes de cobrar.

A chave transacional Zoop precisa existir no PINPad para que pagamentos com cartão sejam executados. Se estiver ausente, acione a IOPAY para coordenar a correção com o fornecedor do equipamento.

Exemplo de cobrança por cartão

val paymentRequest = DesktopPlugin
    .createPaymentRequestBuilder()
    .amount(1000)              // R$ 10,00 - valor em centavos
    .option(Option.CREDIT)
    .installments(2)
    .referenceId("pedido-84217")
    .callback(/* tratar sucesso e falha */)
    .build()

Zoop.post(paymentRequest)

Trate também as mensagens intermediárias do fluxo para exibir ao operador instruções como aproximação, inserção ou leitura do cartão. O retorno local permite que o PDV acompanhe o que está acontecendo no terminal.

O que persistir do resultado

Alternativa via WebSocket local.

O Zoop Desktop Server roda como um serviço local e expõe um WebSocket para Sua Aplicação. Seu escopo continua sendo a captura TEF. Credenciamento, conta, webhooks e fluxo transacional permanecem nas plataformas IOPAY.

java -version

ws://localhost:1337

const socket = new WebSocket('ws://localhost:1337');

socket.onopen = () => {
    console.log('Desktop Server conectado');
};

socket.onmessage = (event) => {
    const message = JSON.parse(event.data);
    handleZoopMessage(message);
};

socket.onerror = (error) => {
    handleSocketError(error);
};

socket.onclose = () => {
    handleSocketClosed();
};

{
  "type": "activation"
}

{
  "type": "initialize",
  "marketplace": "<valor recebido na ativacao>",
  "seller": "<valor recebido na ativacao>",
  "accessKey": "<valor recebido na ativacao>"
}

Sua Aplicação continua ouvindo a IOPAY.

Adicionar TEF não muda o contrato de integração assíncrona: Sua Aplicação continua recebendo pela IOPAY os webhooks de cada evento e transação conforme a integração contratada. O retorno local do SDK/Server complementa a experiência do PDV; ele não elimina a camada de eventos IOPAY.

Modelo recomendado de correlação

Exercite falhas antes de homologar.

Não valide apenas o cenário de aprovação. O piloto deve contemplar falhas de comunicação, token expirado, interrupção durante a captura, reinicialização da aplicação e cancelamentos.

Dados de ativação devem permanecer fora da interface e dos logs.

marketplace, seller e accessKey fazem parte da inicialização técnica do dispositivo. Sua Aplicação deve protegê-los e usá-los de forma automática após a ativação.

Checklist antes de liberar o piloto.

Documentação oficial para implementação.

Use os guias abaixo como referência técnica da versão do componente instalada no projeto. Parâmetros, compatibilidade, versões e protocolos podem evoluir; valide sempre a documentação oficial durante a implementação.