Plugin de integração TOTVS Pagamento Instantâneo

O sistema disponibiliza o plugin de nome "TOTVS Pagamento instantâneo", onde o usuário terá a possibilidade de gerenciar o pagamento feito pela modalidade PIX.

Sendo assim, quando o Plugin estiver ativo e as configurações realizadas corretamente, ao finalizar um pedido utilizando o Tipo de Cobrança configurado para o Pagamento instantâneo, já será gerado em tela um QRCode que permitirá o usuário realizar o pagamento.

Após o pagamento, a aplicação vai consultar o plugin e exibir em tela que o Pagamento por PIX foi realizado, gerando o pedido com status Finalizado.

Configuração do Plugin

Na tela de Plugins de integração acessado em Configuração > Integração, o sistema disponibiliza um card de nome "TOTVS Pagamento Instantâneo" para ativar o recurso, como mostra a imagem a seguir:

Ao clicar no botão "Configurar", é aberto a Tela de configurações do TOTVS Pagamento instantâneo. Informe cada campo conforme a configuração detalhada a seguir:

Após essa configuração, o Plugin já está passível de utilização na Aplicação.

Configuração de envio de e-mail para contexto "Plugin TOTVS Pagamento Instantâneo"

É importante que o usuário realize a configuração de e-mail para envio do QRCode, assim o cliente do Pedido poderá receber as informações do processo de pagamento por PIX por e-mail disparado pelo próprio Totvs CRM SFA através da conta de e-mail configurada na ferramenta.

Nos tópicos a seguir, é detalhar como será o comportamento para cada modelo.

Estas configurações são acessadas somente por usuários administradores e deve estar localizada em: Configuração > Email > Configuração de envio.

Contexto

Campo que permite selecionar o contexto “Plugin TOTVS Pagamento instantâneo”. Este contexto permitirá que seja configurado um envio de e-mail que tem relação com o processo de pagamento com pix.

O contexto “Plugin TOTVS Pagamento instantâneo ” somente será apresentado quando a configuração do plugin TOTVS Pagamento Instantâneo também estiver ativo (pluginintegracao.idnativo = 1)

Condição para envio 

Campo que permite selecionar o registro chamado “Envio de QR Code PIX - sob demanda”. O propósito desta configuração é enviar o link de pagamento gerado pela TOTVS Pagamento instantâneo conforme a solicitação do usuário responsável pelo pedido. Ou seja, é necessário que o usuário acione o botão de enviar na tela de QR Code para que essa configuração seja executada. E com isso a aplicação encaminha um e-mail ao(s) destinatário(s) conforme as configurações informadas.

Arquivo do relatório

Campo que permita anexar um modelo de relatório nos e-mails enviados. Podendo ser o espelho do pedido, ou um resumo do pedido entre outras possibilidades de relatório no formato PRPT.

Enviar para (Contexto)

Campo que permite definir quem receberá o e-mail:

• Cliente
• Profissional logado
• Profissional selecionado no cabeçalho
• Profissional supervisor do selecionado no cabeçalho

É possível também selecionar o campo check-box de "Exibir tela de confirmação/edição de e-mail" com label de "Permitir editar e-mails de contexto na tela de confirmação de e-mail".

• Caso o parâmetro estiver marcado, os e-mails selecionados no contexto não poderão ser editados na tela de confirmação de envio.
• Caso o parâmetro estiver desmarcado, os e-mails selecionados no contexto serão pré-preenchidos como sugestão, e podem ser editados na tela de confirmação de envio.
• Deverá ser persistida em campo configuracaoenvio.idneditaemail, byte default 0, que deverá ser criado pelo tools, opção 3.

Assunto 

Será adicionado este campo que deve permitir configurar um assunto padrão de envio nos e-mails que tratam deste processo de pagamento com cartão de crédito. Também será possível adicionar uma TAG dentro deste assunto, que irá fazer com que a aplicação troque a TAG do assunto pelo número do pedido referente ao processo de pagamento de cartão de crédito. Desta forma, o cliente quando receber o e-mail, já irá conseguir ver através do assunto qual a numeração que se trata.

CONFIGURAÇÃO DO CORPO DO E-MAIL 

Neste campo é possível configurar um corpo do e-mail personalizado para este tipo de situação. Onde o usuário cria um template de e-mail para que fique alinhado com o cliente e dar mais credibilidade ao processo. A seguir um protótipo de como ficará essa parte da configuração:

• Corpo 

Neste campo é exibido as tags: 

• "NÚMERO DO PEDIDO” - Se  o usuário incluir essa tag no corpo, ao enviar o e-mail será substituído pelo número do pedido em questão.
• “IMAGEM QR CODE” - Se o usuário incluir essa tag no corpo, ao enviar o e-mail será substituído pela imagem do QR Code gerada pela TPI (pedidopagamento.imagem)
• "PIX COPIA E COLA" - Se o usuário incluir essa tag no corpo, ao enviar o e-mail será substituído pelo código do QR Code gerado pela TPI. (pedidopagamento.codigotransacao)

Pagamento instantâneo por PIX no Pedido de Venda

Após a configuração realizada nos pontos acima, o Pedido de venda já estará pronto para realizar o processo gerando essa forma de pagamento em QRCode.

Assim, ao confeccionar um pedido de venda no SFA, contanto que o campo "Tipo de cobrança" do cabeçalho do pedido esteja vinculado com o plugin de integração "TOTVS Pagamento Instantâneo", o sistema irá disparar a seguinte lógica de funcionamento;

Ao finalizar um pedido, contato que não haja aprovações pendentes para o pedido, o sistema realiza a solicitação do QR code para pagamento junto à TOTVS Pagamento Instantâneo, respeitando o tempo do campo "Timeout ao gerar transação".
Quando a requisição for bem sucedida, o sistema exibe em tela o QR Code (pedidopagamento.imagem), juntamente com o código do "PIX copia e cola"(pedidopagamento.codigopagamento), armazenando a informação vinculado ao pedido de venda (processorTransactionId) (pedidopagamento.tokentransacao).

Caberá ao usuário vendedor compartilhar a informação para pagamento.

Por exemplo, ao finalizar o pedido normalmente:  

Logo em seguida é exibido em tela o tempo de requisição do Plugin TOTVSPagamento Instantâneo para gerar o QRCode do pagamento:

Assim que o pagamento é gerado, é exibido em tela a as opções de leitura do QRCode, Cancelar o pagamento, Enviar via email e Finalizar o pagamento:

Quando o pagamento é realizado no tempo dentro do tempo determinado nas configurações, é exibido em tela a mensagem de "Pagamento aprovado":

O mesmo processo é realizado no Android, e ocorre da seguinte forma: 

Além disso, se a configuração de envio de e-mail de contexto "Plugin TOTVS Pagamento Instantâneo" estiver ativa, o sistema exibirá botão "Enviar" com ícone de envelope, para enviar o QR Code por e-mail ao cliente.

ou

Ao clicar no botão enviar, o sistema exibe os e-mails trazidos pelo contexto da configuração de e-mail, respeitando o que foi definido na flag "Não permitir editar e-mails de contexto na tela de confirmação de envio", porém também da a possibilidade de o usuário adicionar novos e-mails para receber o QR Code.

Dessa forma, ainda que o e-mail do cadastro não esteja correto, o usuário tem a oportunidade de colocar o e-mail correto para recebimento do QR Code. Nestes casos que o envio do QR Code é realizado por e-mail, o sistema seguirá realizando a consulta de pagamento de 10 em 10 segundos no servidor, até que obtenha um resultado diferente de PENDENTE do servidor de pagamentos da TPI.

E assim como no exemplo anterior, o servidor responde que o pagamento está aprovado, o sistema exibe a mensagem de "Pagamento aprovado. Pedido finalizado com sucesso."  Dessa forma, o pedido será finalizado e o status de pagamento (pedidopagamento.idtiposituacaopagamento, onde sgltiposituacaopagamento="APR") será atualizado para APROVADO.

Mensagens de alerta ao gerar o Pagamento

Nos casos de alguma inconscistencia no processo, é sempre alertado ao usuário em tela sobre o procedimento, por exemplo:

Caso a geração do QR Code não seja bem sucedida, por qualquer que seja o motivo, o sistema exibe a mensagem: 

Caso o servidor responda que o pagamento está expirado ou cancelado, o sistema irá exibe a mensagem de "Pagamento expirado/cancelado. Finalize o pedido novamente para gerar um novo pagamento". Dessa forma, o pedido não será finalizado, e o status de pagamento é atualizado para o código de retorno (cancelado (sgl CAN)/expirado (sgl EXP)).

O sistema respeita o tempo máximo de consulta de status de pagamento, segundo o parâmetro "Timeout consulta pagamento". Quando o tempo de requisição de pagamento ultrapassar o tempo definido no campo de timeout, o usuário será notificado: "Pedido finalizado com sucesso! Entretanto, o pagamento precisa ser aprovado para que o pedido seja devidamente encaminhado para faturamento". Dessa forma, o pedido é finalizado e o status de pagamento permanecerá como PENDENTE.

Caso a resposta não seja bem sucedida, por qualquer motivo o sistema notificado o usuário.

Botão Cancelar

Como visto no exemplo anterior, o sistema também disponibiliza o botão "Cancelar", que, ao clicado, exibe uma mensagem de confirmação para o usuário: "A ação irá cancelar o QR Code, que não poderá mais ser pago. Deseja prosseguir?" Sim/não.

Se sim, é disparado uma requisição de cancelamento do QR Code para o servidor do TPI.

Caso a resposta seja bem sucedida, o sistema irá notificar o usuário: "Pagamento cancelado com sucesso. Finalize o pedido novamente para gerar um novo pagamento". Dessa forma, o pedido não será finalizado, e o status de pagamento deverá ser atualizado para cancelado(sgl CAN).

Caso a resposta não seja bem sucedida, o sistema deverá notificar o usuário: "Pagamento não pode ser cancelado. Tente novamente mais tarde ou entre em contato com o suporte técnico"

Botão Finalizar

Como visto no exemplo anterior, o sistema também disponibiliza o botão "Finalizar", que, ao clicado, notifica o usuário: "Pedido finalizado com ressalva! O pedido precisa ter seu pagamento aprovado para ser encaminhado para faturamento. Você será notificado automaticamente das atualizações, porém pode consultar instantaneamente o status do pagamento pela tela de pagamentos do pedido". Dessa forma, o pedido será finalizado e o status de pagamento permanecerá como PENDENTE (sgl PEND).

Acompanhamento das Operações de pagamento após a finalização do pedido (parte da documentação que ainda não foi refatorada)

Após a finalização do pedido, o sistema disponibiliza ícone de "Status de pagamento" na listagem de pedidos, e também no "Roda teto" do pedido, exibindo o status do último registro de pagamento vinculado ao pedido.

Os status possíveis são:

PENDENTE: com ícone de "alerta amarelo", o status representa o pagamento gerado mas com pagamento ainda pendente de aprovação

APROVADO: com ícone de "check verde", o status representa o pagamento já validado no servidor como aprovado.

CANCELADO: com ícone "X vermelho", o status representa o pagamento que foi cancelado pelo operador.

EXPIRADO: com ícone de "ampulheta", o status representa o pagamento que não foi pago a tempo, e teve seu registro expirado pelo servidor de pagamento.

REEMBOLSADO: com ícone de "dinheiro amarelo", o status representa o pagamento que tinha sido aprovado, mas foi reembolsado ao pagador.

Ao clicar no ícone de "status de pagamento" relacionado a um pedido, o sistema exibe tela conforme o protótipo a seguir:

No Android, a consulta dos registros será online, para garantir que os dados sempre estejam atualizados. Caso não seja possível realizar a conexão online, o sistema deverá mostrar a data de atualização como a data da ultima sincronização.

Os campos disponíveis são:

• Identificador transação: identificador do token que será o mesmo identificador exibido na plataforma da TOTVS Pagamento Instantâneo.

Ao clicar sobre o conteúdo, o sistema deverá copiar o identificador para a área de transferência do dispositivo, e disparar uma mensagem toast: "Copiado para área de transferência"

• Status pagamento: além do ícone, exibe o nome do status de pagamento conforme possibilidades supracitadas.
• Data criação: Data de criação da transação no servidor de pagamento.
• Data última atualização: Data referente à última observação do pagamento
• Histórico do pagamento: Ícone que, ao clicado, exibe tela conforme o protótipo a seguir, exibindo o conteúdo textual da tabela de observações de pagamento, para acompanhamento do histórico.

• Exibir QR Code: Ícone que, ao clicado, consultará no banco para retornar a imagem e conteúdo do QR code para pagamento. Nessa tela, as opções de "Cancelar" e "Cobrar depois" não serão exibidas, somente a função "Enviar e-mail". O timer de consulta de pagamento também não será disparado.

Caso a resposta não seja bem sucedida, por qualquer motivo o sistema deverá notificar o usuário: "Pagamento não pôde ser criado no servidor do {nome do plugin}, cuja resposta foi: ${resposta da requisição}. ". Caso não houver mensagem de retorno, o sistema deverá exibir: "Pagamento não pôde ser criado no servidor do {nome do plugin}. Tente novamente mais tarde ou entre em contato com o suporte técnico"

• Consultar pagamento: Ícone que, ao clicado, fará uma requisição ao servidor do TPI para retornar o status atual do pagamento.

Caso o servidor responda que o pagamento está aprovado, o sistema irá exibir mensagem toast de "Pagamento aprovado" Dessa forma, o status do pagamento será atualizado para APROVADO.

Caso o servidor responda que o pagamento está expirado, o sistema irá exibir mensagem toast de "Pagamento expirado" Dessa forma, o status do pagamento será atualizado para EXPIRADO.

Caso o servidor responda que o pagamento está cancelado, o sistema irá exibir mensagem toast de "Pagamento cancelado" Dessa forma, o status do pagamento será atualizado para CANCELADO.

Caso o servidor responda que o pagamento está reembolsado, o sistema irá exibir mensagem toast de "Pagamento reembolsado" Dessa forma, o status do pagamento será atualizado para REEMBOLSADO.

Caso o servidor responda que o pagamento está pendente, o sistema irá exibir a mensagem toast de "Pagamento pendente"

Caso a resposta não seja bem sucedida, por qualquer motivo, o sistema deverá notificar o usuário: "Pagamento não pôde ser consultado no servidor do {nome do plugin}, cuja resposta foi: ${resposta da requisição}.". Caso não houver mensagem de retorno, o sistema deverá exibir: "Pagamento não pôde ser consultado no servidor do {nome do plugin}. Tente novamente mais tarde ou entre em contato com o suporte técnico"

• Cancelar pagamento: Ícone que, ao clicado, deverá exibir mensagem de confirmação para o usuário: "A ação irá cancelar o QR Code, que não poderá mais ser pago. Deseja prosseguir?" Sim/não. Se sim, fará uma requisição ao servidor do TPI para cancelar o pagamento

Caso a resposta seja bem sucedida, o sistema deverá exibir mensagem toast: "Pagamento cancelado". Dessa forma, o status de pagamento deverá ser atualizado para CANCELADO.

Caso a resposta não seja bem sucedida, o sistema deverá notificar o usuário: "Pagamento não pode ser cancelado no servidor do {nome do plugin}, cuja resposta foi: ${resposta da requisição}. ". Caso não houver mensagem de retorno, o sistema deverá exibir: "Pagamento não pôde ser criado no servidor do {nome do plugin}. Tente novamente mais tarde ou entre em contato com o suporte técnico"

Haverá botão "Novo pagamento" que deverá ser exibido sempre que não houver a presença de nenhum pagamento com status APROVADO ou PENDENTE, para pedidos de origem Web/Android, sem numeropedidoerp, de status PENDENTE.

Esse botão, quando clicado, fará a criação de nova transação junto à TPI, e exibir o conteúdo do QR code, em tela semelhante ao resultado do ícone "Exibir QR code"

Fluxo de pagamento quando há aprovações de pedidos

Ao finalizar um pedido com tipos de cobrança vinculados com o plugin de integração TPI, em que o mesmo seja encaminhado para aprovação, qualquer que seja, o sistema não realiza a criação do pagamento. Ao invés, informa o usuário com a seguinte mensagem: "A geração do pagamento do pedido deverá ser gerada após a aprovação do pedido, para que seja devidamente encaminhado para faturamento."

Nesse cenário, o pedido passa pelo fluxo de aprovação padrão, onde os usuários determinarão a situação das aprovações do pedido entre os seguintes status:

PENDENTE
APROVADO
REPROVADO
CONTESTADO
CANCELADO

Um pedido é declarado totalmente aprovado quando apenas possui aprovações vinculadas nos status de APROVADO ou CANCELADO.

Além dos filtros definidos no ponto 3, o botão "Novo pagamento" na tela de "Pagamento do pedido" somente deve ser exibido para pedidos com as situações acima, ou não contendo aprovações vinculadas. 

Isso para permitir que, após aprovado, o usuário tenha a opção de clicar no botão "Novo pagamento" para gerar um QR Code, compartilhar ao seu cliente, e posteriormente consultar pagamento pelo ícone "Consultar pagamento".

Na notificação que é gerada pela aplicação quando o pedido é aprovado, o sistema consulta se o plugin "TOTVS Pagamento instantâneo" está ativo e o pedido está vinculado com um dos tipos de cobrança configurados no plugin. Se positivo, o sistema deverá adicionar a mensagem "Será necessário gerar um pagamento para o pedido X através da tela de "Pagamentos do pedido""

Persistência e integração de dados de pagamento

A presente documentação apenas define que os tokens de pagamento serão armazenados em banco de dados do SFA, vinculados com os pedidos de venda.

A integração de dados de pagamento com o ERP deverá ocorrer sob demanda, de maneira configurável ou customizada, mediante identificação dos campos de destino pelo cliente que utiliza o plugin de integração.