Plugin de integração TOTVS Pagamento Instantâneo

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

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

Ao clicar no botão "Configurar", é aberto a tela de configurações, contendo os as informações:

• Título "TOTVS Pagamento Instantâneo"
• Grupo de elementos "Configurações do TPI"
  • Tenant URL: campo de texto, para receber a URL em que a API do TOTVS Pagamento Instantâneo (TPI) estará sendo servida (Ex: https://produtosfa.rac.staging.totvs.app)
  • Usuário: campo de texto, para receber o usuário da autenticação básica do TPI
  • Senha: campo de texto, com máscara de password, para receber a senha da autenticação básica do TPI
  • Client ID: campo de texto, para receber o identificador do sistema solicitante da requisição
  • Cliente secret: campo de texto, com máscara de password, para receber o a senha do sistema solicitante da requisição
  • Carteira: campo de texto, para receber o código da carteira digital. Para o pix, terá o identificador "pix"
  • Business Unid ID: campo de texto, para receber o identificador da unidade de negócio geradora de transações de pagamento
  • POS ID: campo de texto, para receber o identificador do ponto de venda cadastrado
• Grupo de elementos "Configurações do SFA"
  • Tipos de Cobrança: Campo pesquisa multipla escolha, buscando todos os tipos de cobrança ativos. Esse campo receberá os tipos de cobrança que, ao selecionados no cabeçalho do pedido, dispararão a requisição da transação de pagamento.
  • Timeout ao gerar transação: Campo numérico para determinar a quantidade de segundos que o sistema aguardará o retorno da criação da transação
  • Timeout consulta pagamento: Campo numérico para determinar quantos segundos o sistema irá aguardar para a consulta de pagamento.

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

Neste momento, o cliente pode receber as informações do processo de pagamento por Cartão de crédito e 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, iremos 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

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", pelo campo "Tipos de cobrança", 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 irá realizar 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 exibirá 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.

Assim quando ativo, o usuário finalizado o pedido: 

E automaticamente já é 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, Opção de Cancelar o pagamento, Enviar via email e Finalizar o pagamento:

Quando o pagamento é realizado no tempo determinado, é exibido em tela a mensagem de aprovação:

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

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

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.

Ao clicar no botão enviar, o sistema deverá trazer 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 dar 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.

ou

• • • Se a flag "Não permitir editar e-mails de contexto na tela de confirmação de envio" estiver marcada, o ícone de "X para excluir e-mail" não é exibido para e-mails que vieram do cadastro da configuração de envio.
      • Caso contrário, o sistema exibe o ícone de "X para excluir e-mail" em todos os e-mails da tela

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.

Caso o servidor responda que o pagamento está aprovado, o sistema irá exibir 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.

Caso o servidor responda que o pagamento está expirado ou cancelado, o sistema irá exibir 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 deverá notificar o usuário.

O sistema também disponibiliza o botão "Cancelar", que, ao clicado, exibe  ade 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, disparar uma requisição de cancelamento do QR Code para o servidor do TPI.

Caso a resposta seja bem sucedida, o sistema deverá 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 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 pode ser cancelado no servidor do {nome do plugin}. Tente novamente mais tarde ou entre em contato com o suporte técnico"

O sistema exibirá o botão "Finalizar", que, ao clicado, deverá notificar 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).

4. Acompanhamento / Operações de pagamento após a finalização do pedido

Após a finalização do pedido, o sistema disponibilizará í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 exibirá 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 serã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, deverá exibir 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, exibirá 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"

5. 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 deverá realizar a criação do pagamento. Ao invés, deverá informar 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 passará 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 que 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 deve consultar 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""

6. 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.