Introdução

Este documento destina-se a especificar o processo de integração entre um terminal de pagamento Cielo (“POS”) e um sistema de checkout, de forma a se poder cumprir exigências legais de alguns estados brasileiros.

Por “checkout” entende-se um conjunto de hardware e software responsável por gerir o processo de venda de bens ou serviços em um estabelecimento através de um sistema de Automação Comercial, incluindo os processos de registro fiscal exigidos pelo governo (por exemplo, impressão de comprovante em uma impressora fiscal ou geração de Nota Fiscal Eletrônica).

Esta especificação define uma forma de trabalho diferenciada para o POS Cielo denominada “Modo Integrado”, de forma a cumprir as seguintes premissas:

• O POS recebe o valor do checkout para efetuar a transação de pagamento, seja com cartão ou via Pix.
• O POS não imprime o comprovante, devolvendo suas informações para que o checkout efetue os processos ficais.

Os capítulos a seguir descrevem de forma detalhada como o Modo Integrado funciona e quais são as informações trocadas entre os dois sistemas.

Alternativamente, sistemas de checkout que têm implementado o processo de troca de arquivos definido para o antigo “Gerenciador Padrão TEF Discado” podem utilizar uma aplicação MS/Windows distribuída pela Cielo conforme descrito no Capítulo 4, dispensando a implementação especificada neste documento.

Alternativamente, sistemas de checkout que têm implementado o processo de troca de arquivos definido para o antigo “Gerenciador Padrão TEF Discado” podem utilizar uma aplicação MS/Windows distribuída pela Cielo conforme descrito no Capítulo 4, dispensando a implementação especificada neste documento.

Referências

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format (2017)
• ISO/IEC 21778: Information technology - The JSON data interchange syntax (2017)
• TEF_DIAL: Guia Técnico da Solução TEF Discado - Versão 2.5 - março/2010 (ou versão superior)

Formatos usados neste documento

Este documento menciona diversos dados em funções e tabelas, sendo que estes dados, por suas características, devem respeitar diferentes regras de codificação.

A representação de um formato segue a seguinte regra: “[Caractere de Formato][..][Tamanho]”

[Caractere de Formato] = Letra maiúscula que define o formato.

[..] = Opcional, indica que o dado é de tamanho variável, podendo ter de zero a [Tamanho] bytes. [Tamanho] = De um a quatro dígitos numéricos representando a quantidade de bytes utilizada pela informação, ou “var” para indicar tamanho indefinido.

Exemplos:

• O código A256 indica uma informação de 256 bytes codificada de acordo com o formato “A”.
• O código N..99 indica uma informação de tamanho variável (de 0 a 99 bytes) codificada de acordo com o formato “N”.
• O código A..var indica uma informação de tamanho variável codificada de acordo com o formato “A”.

A tabela seguir detalha os formatos adotados neste documento:

Visão Geral

Escopo

A solução definida neste documento se aplica a estabelecimentos com poucos checkouts. Paraestabelecimentos com muitos checkouts (um grande supermercado, por exemplo) recomenda-se o uso de soluções TEF com pinpads.

São premissas desta solução:

• Um POS Cielo é configurado para operar em Modo Integrado com um único checkout, de forma exclusiva.
• É possível configurar mais de um POS Cielo para operar com um determinado checkout.

O diagrama a seguir ilustra o exemplo de um estabelecimento com dois checkouts e três POS Cielo, sendo que os POS #1 e #2 operam com o checkout A, enquanto o POS #3 opera com o checkout B.

Fluxo simplificado

O diagrama a seguir ilustra, de forma simplificada, o fluxo de comunicação entre o POS e o checkout.

O Modo Integrado pressupõe que o POS e o checkout estejam em uma mesma rede local, sendo que o POS usa conexão via Wi-Fi.

A operação de pagamento segue o seguinte fluxo:

1. O checkout inicia um processo de pagamento via cartão (1), aguardando a conexão de um terminal POS da CIELO via Wi-Fi (TCP/IP).
2. O lojista usa um POS da CIELO e inicia o pagamento via menu ou cartão (2), da mesma forma como é operado um POS autônomo. Este POS deve estar previamente configurado para comunicar com o checkout em questão (ver seção 2.3).
3. Ao chegar na tela de captura do valor, o POS se conecta ao checkout (3) para receber essa informação que não poderá ser editada.
4. Ao concluir a operação, o POS não imprime o comprovante e devolve os dados para o checkout (4), indicando sucesso ou fracasso, fornecendo também as informações para os procedimentos fiscais (ECF ou sistema de Nota Fiscal Eletrônica).
5. O checkout efetua os procedimentos fiscais, imprimindo comprovante na ECF (5), por exemplo.
6. Ao final, o checkout devolve uma confirmação para o POS (6), indicando se tudo correu bem ou se houve algum problema nos procedimentos fiscais ou outro erro fatal que implique na anulação da transação.

Alterações no POS

No “Modo Integrado”, o POS efetua todas as operações não financeiras da mesma forma que o POS convencional (inicialização, consultas, pré-autorização, reimpressão, relatórios, etc). Somente as transações financeiras (de pagamento) são afetadas neste modo.

O cadastro do POS na Cielo indica se ele opera em “Modo Integrado” ou de forma “convencional” (autônomo), sendo que isso não pode ser modificado manualmente no equipamento.

A aplicação do POS Cielo conta com as seguintes modificações quando opera em “Modo Integrado”:

A aplicação do POS Cielo conta com as seguintes modificações quando opera em “Modo Integrado”:

• Permite a configuração do endereço IP e porta da máquina onde está instalado o checkout.
• No momento da transação (seja com cartão, Pix, ou outro produto de pagamento da Cielo), o terminal efetua uma conexão via socket TCP com o checkout para receber o valor da transação, que não poderá ser alterado pelo operador.
• Ao final da transação, o terminal efetua uma nova conexão via socket TCP com o checkout para enviar o resultado da transação e outras informações, como a imagem do comprovante, número lógico, código de autorização, NSU, etc. Em seguida, na mesma conexão socket TCP, o terminal POS fica aguardando a confirmação do checkout para, em caso de erro, poder desfazer a transação efetuada.

Comunicação

Este capítulo apresenta em detalhes como é feita a comunicação entre o POS e o checkout.

Fluxo detalhado

O fluxo a seguir ilustra os processos envolvidos na comunicação entre as partes:

1. Ao finalizar o registro dos produtos sendo vendidos, o operador seleciona a opção “Pagamento em Cartão” no checkout. Neste momento, o checkout abre uma tela indicando “Aguardando POS Cielo…” e entra em modo de espera por uma conexão socket TCP/IP (“listen”).
2. O operador inicia uma transação de pagamento no POS. Ao invés de solicitar o valor, o POS efetua uma conexão socket TCP com o checkout (“connect”).
3. O POS envia ao checkout uma mensagem de “início de sessão” e este devolve algumas informações úteis, como o valor a ser pago.
4. O POS poderá desconectar o socket TCP para liberar recursos (“closesocket”). O checkout apresenta uma mensagem de “Aguardando autorização…” e volta a ficar em modo “listen”, aguardando nova conexão socket TCP.
5. O POS se conecta à Cielo para efetuar a autorização financeira.
6. Independentemente do resultado da autorização (sucesso ou falha), o POS efetua uma nova conexão socket TCP com o checkout (“connect”), se necessário, e envia o resultado da autorização em uma mensagem de “fim de sessão”.
7. Se a transação financeira for aprovada, o checkout efetua os procedimentos fiscais exigidos pelo governo e devolve uma resposta ao POS indicando se estes foram bem-sucedidos.
8. O POS desconecta o socket TCP para liberar recursos (“closesocket”). Se a transação foi aprovada na Cielo, mas o checkout indicou falha nos procedimentos fiscais, o POS marca

Observações:

• Quem efetua a conexão e a desconexão do socket TCP/IP é sempre o POS, sendo que o checkout assume um comportamento passivo a esse respeito.
• O processo pode ser cancelado no checkout a qualquer momento pelo operador. Neste caso, o checkout fecha o socket e deixa de aguardar conexões vindas dos POS.
• Caso o checkout receba uma mensagem inconsistente do POS, ele fecha o socket e volta a esperar por uma nova conexão do POS (ver detalhamento na seção 3.4).
• O tempo máximo de espera para conexão socket (“connect”) é de 5 (cinco) segundos. O POS deve tentar a conexão até 6 (seis) vezes, totalizando 30 (trinta) segundos.
• O tempo máximo de espera pela resposta de início de sessão é de 3 (três) segundos.
• O tempo máximo de espera pela resposta de finalização de sessão é de 60 (sessenta) segundos.

Formato das mensagens

As mensagens trocadas entre o POS e checkout utilizam o formato JSON. Além disso, para evitar fragmentação por conta da rede TCP/IP, as mensagens devem ser encabeçadas por dois bytes que indicam o tamanho.

Ao receber uma mensagem via socket, o receptor deve conferir os bytes de tamanho e, se estes indicarem uma quantidade de bytes maior do que foi recebido, isso indica que houve fragmentação. Neste caso, deve-se buscar mais bytes na camada TCP/IP até que a mensagem esteja completa.

O tempo máximo de espera por um fragmento de mensagem é de 1 (um) segundo.

Corpo da mensagem (JSON):

{
  "msg_id": "CmdInitSession",
  "pos_id": "91746241",
  "seq_pos": "00018725"
}

Bytes trafegados

00 49 7B 93 6D 73 67 5F 69 64 94 3A 20 93 43 6D 64 49 6E 69 74 53 65 73 73 69 6F 6E 94 2C 20 93 70 6F 73 5F 69 64 94 3A 20 93 39 31 37 34 36 32 34 31 94 2C 20 93 73 65 71 5F 70 6F 73 94 3A 20 93 30 30 30 31 38 37 32 35 94 7D

Comandos e Respostas

Esta seção define o formato das mensagens trocadas entre o POS e o checkout.

Observações

• A coluna “Presença” das tabelas desta seção indica se um campo deve ou não existir, usando a seguinte codificação:
• M: Campo é mandatório, deve ocasionar erro se não for recebido.
• O: Campo é opcional, a condição pela qual existe está informada na coluna “Descrição”.
• MO: Campo é mandatório dentro de um objeto, mas o objeto é opcional.

Início de sessão

Este comando é enviado pelo POS ao checkout para iniciar um processo de pagamento. Neste momento, o operador já deve ter selecionado a opção de “pagamento com cartão” no checkout, que fica em estado de espera para iniciar a sessão.

Na resposta a este comando, o checkout devolve o valor que será usado na transação, sendo que ele não poderá ser editado pelo operador do POS.

Comando

Observações

• Para reforçar a integridade da comunicação entre o POS e o checkout, o POS gera um número sequencial (seq_pos) que deve ser devolvido pelo checkout na resposta.
• O checkout deve esperar por este comando por tempo indeterminado. O sistema deve, entretanto, disponibilizar uma forma para que o operador possa cancelar o processo enquanto o checkout aguarda o início da sessão (mais detalhes na seção 3.4).

Observações:

• Ao receber a resposta, o POS deve conferir pos_id e seq_pos e, caso estejam diferentes, a operação deve ser finalizada com erro.
• O checkout devolve o resultado da última sessão efetuada pelo POS. Isso serve para garantir que o POS acerte suas pendências caso ele não tenha recebido a RspEndSession da transação anterior.
• O POS deve esperar a resposta do checkout por 3 (três) segundos. Se a resposta não for recebida neste tempo, o POS aborta o processo com erro de “TEMPO ESGOTADO”.

Exemplo:

O POS envia um comando para iniciar uma sessão.

POS ➡️

{
    "msg_id": "CmdInitSession",
    "pos_id": "91746241",
    "seq_pos": "00018725"
}

O checkout aceita a conexão e informa o valor de R$ 125,80:

AC ➡️

{
    "msg_id": "RspInitSession",
    "pos_id": "91746241",
    "seq_pos": "00018725",
    "status": 0,
    "seq_ac": "00000098",
    "transaction": {
        "amount": "12580"
    },
    "last_endsession": {
        "seq_pos": "00018724",
        "seq_ac": "00000097",
        "status": 0
    }
}

Finalização de sessão

Este comando é enviado pelo POS ao checkout para indicar a conclusão do processo de pagamento, seja este bem ou malsucedido.

Em caso de sucesso, o POS envia uma série de informações referentes à transação efetuada, bem como imagens dos comprovantes que podem ser impressos pelo checkout.

Comando

Os códigos do produto (matriz e secundário) identificam o tipo de transação efetuada (por exemplo: cartão de crédito à vista, parcelado, cartão de débito, Pix, voucher, etc.) e não estão aqui especificados por serem dinâmicos e configuráveis nas tabelas do POS Cielo. Estas informações devem ser fornecidas pela Cielo em um documento à parte.

Observações:

• O checkout deve esperar por este comando por tempo indeterminado. O sistema deve, entretanto, disponibilizar uma forma para que o operador possa cancelar o processo enquanto o checkout aguarda a finalização da sessão (mais detalhes na seção 3.4).

Resposta

Observações:

• O checkout deve guardar os dados dessa resposta para envio numa próxima sessão que for estabelecida com o mesmo POS (ver RspInitSession).
• Ao receber a resposta, o POS deve conferir pos_id e seq_pos e, caso estejam diferentes, a mensagem deve ser ignorada. Se a transação foi aprovada, deve-se mantê-la pendente de confirmação até a próxima sessão, momento em que o checkout informa o que aconteceu de fato com a finalização da sessão.
• O POS deve esperar a resposta do checkout por 60 (sessenta) segundos. Se a resposta não for recebida neste tempo, o POS aborta o processo com erro de “TEMPO ESGOTADO”. Se a transação foi aprovada, deve-se mantê-la pendente de confirmação até a próxima sessão, momento em que o checkout informa o que aconteceu de fato com a finalização da sessão.
• Se a transação foi aprovada e o checkout responde com status diferente de 0 (zero), o POS deverá desfazer a transação.
• O POS sempre devolve as imagens dos comprovantes da transação. Cabe ao checkout imprimir ou não, de acordo com os desejos do lojista e do cliente.

Exemplo

O POS envia um comando para finalizar a sessão, indicando sucesso na transação de pagamento.

POS ➡️

{
    "msg_id": "CmdEndSession",
    "pos_id": "91746241",
    "seq_pos": "00018725",
    "seq_ac": "00000098",
    "status": 0,
    "pos_sn": "987264BY3463-23",
    "transaction": {
        "amount": "12580",
        "prod_pri": 1003,
        "prod_sec": 14,
        "nsu": "987654",
        "aut": "901782",
        "installments": 3,
        "timestamp": "2023-11-29T15:02:18",
        "receipt_gen": [
            " CIELO",
            "29/11/2023 23:14:56",
            "",
            "LOJAS DA CHINA",
            "RUA 25 DE MARCO, 123",
            "SAO PAULO - SP",
            "EC:000237236782351 POS:91746241",
            "",
            "VALOR: 125,80",
            "",
            "************6254 ONL-C",
            "DOC:987654 AUT:901782",
            "",
            " AUTORIZADA COM SENHA",
            " 446353-6254",
            "A0000000031010-6FA837C30903A7D6",
            " CREDITO VISA"
        ],
        "receipt_cli": [
            " CIELO – VIA CLIENTE",
            "29/11/2023 23:14:56",
            "",
            "LOJAS DA CHINA",
            "RUA 25 DE MARCO, 123",
            "SAO PAULO - SP",
            "EC:000237236782351 POS:91746241",
            "",
            "VALOR: 125,80",
            "",
            "************6254 CREDITO VISA",
            "DOC:987654 AUT:901782"
        ],
        "receipt_cli_sm": [
            "CIELO 29/11/2023 23:14:56",
            "POS:91746241 ETB:000237236782351",
            "VLR: 125,80 CREDITO VISA ***6254",
            "DOC:987654 AUT:901782"
        ],
        "receipt_mch": [
            " CIELO – VIA LOJA",
            "29/11/2023 23:14:56",
            "",
            "LOJAS DA CHINA",
            "RUA 25 DE MARCO, 123",
            "SAO PAULO - SP",
            "EC:000237236782351 POS:91746241",
            "",
            "VALOR: 125,80",
            "",
            "************6254 ONL-C",
            "DOC:987654 AUT:901782",
            "",
            " AUTORIZADA COM SENHA",
            " 446353-6254",
            "A0000000031010-6FA837C30903A7D6",
            " CREDITO VISA"
        ]
    }
}

O checkout recebe os dados da transação, efetua os procedimentos fiscais e retorna indicação de sucesso para o POS.

AC ➡️

{
    "msg_id": "RspEndSession",
    "pos_id": "91746241",
    "seq_pos": "00018725",
    "seq_ac": "00000098",
    "status": 0
}

Fluxo de comunicação no checkout

Esta sessão detalha como o checkout deve tratar a comunicação TCP/IP com o POS, contemplando eventuais situações de erro.

O checkout adota as seguintes premissas para trocar mensagens com o POS:

• Caso o checkout receba uma mensagem inconsistente do POS (formato JSON inválido, mensagem incompleta, campos faltando, campo seq_ac inválido), ele deve fechar o socket e voltar a aguardar uma mensagem do POS.
• Caso o checkout receba uma mensagem incompleta do POS (verificado através dos dois bytes de tamanho no início), ele deverá aguardar os fragmentos restantes da mensagem por no máximo 1 (um) segundo cada um. Se esse tempo se esgotar, a mensagem recebida é considerada inconsistente e, portanto, descartada.
• O checkout deve permitir o cancelamento da operação pelo usuário. Se isso acontecer, o checkout deve fechar os sockets TCP/IP e voltar à tela de escolha da forma de pagamento.
• Se a operação ocorreu normalmente (do ponto de vista do protocolo de comunicação), seja um InitSession ou EndSession, o checkout devolve a mensagem de resposta ao POS e não fecha o socket. A responsabilidade de fechar o socket de comunicação é do POS.
  • Depois de enviar a resposta do EndSession, o checkout deve esperar o POS desconectar o socket. Se isso não acontecer em até 10 (dez) segundos, então o checkout deverá fechar o socket para encerrar o processo.
• O POS poderá, opcionalmente, desconectar o socket entre o InitSession e o EndSession. Se o checkout detectar uma desconexão enquanto aguarda uma mensagem do POS, ele deve voltar a aguardar a conexão do POS sem gerar nenhum tipo de erro.

O fluxograma a seguir detalha o processo de comunicação a ser efetuado pelo checkout imediatamente após o operador solicitar pagamento usando a Cielo:

Situações de exceção

Esta sessão ilustra o comportamento esperado dos sistemas POS e checkout em situações de exceção.

Transação negada

O diagrama a seguir mostra a situação em que a transação financeira não é aprovada na rede Cielo.

A Cielo nega a transação (1). O POS envia um comando para finalizar a sessão, indicando que a transação foi negada (2) com a mensagem “SALDO INSUFICIENTE”.

Exemplo de Fluxo

1. A Cielo nega a transação.

2. O POS envia um comando para finalizar a sessão, indicando que a transação foi negada com a mensagem “SALDO INSUFICIENTE”:

POS ➡️

{
  "msg_id": "CmdEndSession",
  "pos_id": "91746241",
  "seq_pos": "00018725",
  "seq_ac": "00000098",
  "status": 21,
  "pos_sn": "987264BY3463-23",
  "message": "SALDO INSUFICIENTE"
}

O checkout recebe a informação de negação e fecha a sessão com sucesso:

AC ➡️

{
    "msg_id": "RspEndSession",
    "pos_id": "91746241",
    "seq_pos": "00018725",
    "seq_ac": "00000098",
    "status": 21
}

Checkout ocupado

O diagrama a seguir mostra uma situação em que o checkout está ocupada atendendo um outro POS.

O POS envia um comando para iniciar uma sessão:

POS ➡️

{
    "msg_id": "CmdInitSession",
    "pos_id": "91746241",
    "seq_pos": "43567484"
}

O checkout não aceita a conexão, informando que está com uma sessão aberta com outro terminal.

AC ➡️

{
    "msg_id": "RspInitSession",
    "pos_id": "91746241",
    "seq_pos": "43567484",
    "status": 11
}

Não foi possível conectar o checkout

O diagrama a seguir ilustra a situação em que a transação é efetuada com sucesso na rede Cielo, maso POS não consegue a conexão socket para finalizar a sessão com o checkout. Esta situação pode ocorrer com facilidade se o operador cancelar o processo.

Se o POS não conseguir conexão socket com o checkout em 5 (cinco) segundos, ele deve desfazer a transação com a rede Cielo.

Erro no procedimento fiscal

O diagrama a seguir mostra a situação em que a transação financeira é aprovada na rede Cielo, mas o checkout não consegue efetuar os procedimentos fiscais e decide cancelar o pagamento.

A rede Cielo aprova a transação (1) e o POS envia um comando para finalizar a sessão, indicando sucesso (2).

POS ➡️

{
    "msg_id": "CmdEndSession",
    "pos_id": "91746241",
    "seq_pos": "00018725",
    "seq_ac": "00000098",
    "status": 0,
    "pos_sn": "987264BY3463-23",
    "transaction": {
        "amount": "12580",
        "prod_pri": 3,
        "prod_sec": 14,
        "nsu": "987654",
        "aut": "901782",
        "installments": 3,
        "timestamp": "2023-11-29T15:02:18",
        "receipt_gen": [
            // Conjunto de strings correspondente ao comprovante genérico
        ],
        "receipt_cli": [
            // Conjunto de strings correspondente ao comprovante do cliente
        ],
        "receipt_cli_sm": [
            // Conjunto de strings correspondente ao comprovante reduzido do cliente
        ],
        "receipt_mch": [
            // Conjunto de strings correspondente ao comprovante do lojista
        ]
    }
}

O checkout recebe os dados da transação, mas não consegue efetuar os procedimentos fiscais e retorna indicação de erro para o POS (3).

AC ➡️

{
    "msg_id": "RspEndSession",
    "pos_id": "91746241",
    "seq_pos": "00018725",
    "seq_ac": "00000098",
    "status": 12
}

O POS desfaz a transação na rede Cielo (4).

Implementação Alternativa (SIMBIOSE)

Existe um padrão antigo de mercado para comunicação entre sistemas de checkout e sistemas de pagamento usando troca de arquivos especificado pelo documento TEF_DIAL. Apesar de ser um padrão bem antigo, ele ainda é suportado por diversos sistemas de checkout do mercado brasileiro.

Para facilitar a integração com esses sistemas existentes, a Cielo fornece uma aplicação denominada “SIMBIOSE” capaz de emular essa troca de arquivos e implementar a comunicação com o POS usando o protocolo JSON especificado neste documento.

Este formato organiza a informação de forma clara e acessível, destacando a aplicação SIMBIOSE

O “SIMBIOSE” implementa o esquema especificado no documento TEF_DIAL com as seguintes diferenças:

Somente os seguintes tipos de operação estão implementados:

Os seguintes campos foram criados para implementar os diferentes tipos e vias de comprovante: