Integrate TEF.

Your in-person operation
powered by IOPAY

A well-defined two-tiered integration

TEF in-person capture takes place locally between Your Applicationthe Zoop component and the PINPad The payment transaction, however, remains integrated into IOPAY. This preserves a single layer for account, transaction management, terminal activation, events and webhooks

Who does what in integration

The separation below prevents the use of the Zoop component for local capture from being confused with an exchange of the main integration of the operation

SDK Embedded or Desktop Server

There are two documented ways to implement the local layer Both preserve the same IOPAY architecture for account, activation and events

From the empty project to the first payment in five steps

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 integrated directly into PDV

In this approach, the capture component is within Your Application The plugin converses locally with PINPad while the operation remains linked to IOPAY infrastructure

Initiation after activation

After that marketplace, seller and accessKey if they have been recovered and persisted, use those values in runtime to restart the SDK They must not be manually typed by the operator

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

val desktopPlugin = DesktopPlugin(
    Zoop.constructorParameters()
)

Zoop.plug(desktopPlugin)

State of integration

The token is born in the SDK and the link is completed in IOPAY

Activation associates the device with the correct account This step must occur before the first transaction and must be tested also after you restart your application

Consult the transaction key before charging

The Zoop transaction key needs to be in the PINPad for card payments to be executed If you are absent, tap IOPAY to coordinate the correction with the equipment supplier

Example of card charge

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)

Treat also the flow intermediate messages to show the operator instructions such as approaching, inserting or reading the card Local feedback allows PDV to keep track of what's happening at the terminal

What persists of the result

Alternative via local WebSocket

Zoop Desktop Server runs as a local service and exposes a WebSocket to Your Application Your scope continues to be TEF capture Accreditation, account, webhooks and transactional flow remain on IOPAY platforms

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>"
}

Your Application continues receiving events from IOPAY.

Adding TEF does not change the asynchronous integration agreement: Your Application continues to receive webhooks from IOPAY for each event and transaction according to the contracted integration SDK/Server Local Return complements the PDV experience; it does not eliminate the IOPAY event layer

Recommended correlation model

Exercise faults before approval

Don't just validate the approval scenario The pilot must consider communication failures, expired token, interruption during capture, restart application and cancellations

Activation data must remain outside the interface and logs

marketplace, seller and accessKey are part of the technical startup of the device Your Application must protect and use them automatically after activation

Checklist before releasing the pilot

Official documentation for implementation

Use the guides below as a technical reference for the version of the component installed in the project Parameters, compatibility, versions and protocols may evolve; always validate official documentation during implementation