PagHiper fora do próprio aplicativo: loja virtual, Agenda PRO, Gestão de Cobranças e API
A PagHiper não é usada só dentro do próprio aplicativo dela. Outros aplicativos do sistema leem a mesma integração e se comportam de um jeito específico quando o meio de pagamento é a PagHiper. Boa parte das queixas de "o pedido não entrou" e "parou do nada" nasce aí, e não no aplicativo da PagHiper.
ONDE MAIS A PAGHIPER APARECE
Aqui cobrimos quatro lugares: a loja virtual (e-commerce), a Agenda PRO, o catálogo de meios de pagamento da Gestão de Cobranças e o retorno do pedido da loja virtual pela API. Não é uma lista fechada — a PagHiper também aparece nos cadastros do financeiro (forma de pagamento com banco PagHiper, geração de boleto e Pix). Se o lugar que você procura não estiver aqui, vale confirmar com o suporte antes de descartar.
NA LOJA VIRTUAL A OPÇÃO NÃO APARECE COM O NOME PAGHIPER
Quando o meio de pagamento da loja virtual é a PagHiper (ou a Iugu), o sistema trata aquela forma de um jeito diferente ao montar a lista do checkout: em vez de mostrar o nome da integração, ele desdobra a opção conforme os recursos habilitados naquela integração, apresentando "Boleto bancário" e/ou "Cartão de crédito", com os ícones genéricos.
Duas consequências práticas:
Você pode achar que "a PagHiper não aparece no meu checkout" quando ela está lá — aparece como Boleto bancário, não com o nome do parceiro.
Se a loja tiver mais de um meio de pagamento desse tipo ativo ao mesmo tempo (PagHiper e Iugu, por exemplo), só o primeiro da ordem recebe esse desdobramento. O outro segue com o nome próprio.
Na hora de pagar, a loja envia o pedido para o ERP, que aciona a PagHiper e devolve o resultado da transação para a loja. Sobre a tela que o comprador vê — se ele conclui tudo dentro da loja ou é levado para outro site — vale conferir no próprio checkout.
POR QUE A PAGHIPER DESATIVA SOZINHA NA LOJA VIRTUAL
Este é o ponto que mais gera chamado, e a causa quase nunca é a PagHiper.
Toda vez que a loja virtual lê o meio de pagamento — ao listar, ao abrir, ao editar e ao processar o pagamento — o sistema confere se aquela integração da PagHiper é mesmo visível para a loja em que você está. A conferência é feita em cadeia: a integração aponta para uma forma de pagamento, a forma de pagamento aponta para uma conta bancária, e essa conta bancária precisa estar vinculada à loja atual. Se qualquer elo dessa cadeia não fechar, o sistema conclui que não existe integração para aquela loja.
E aí vem o comportamento que assusta: ele não mostra aviso nenhum. Ele devolve o meio de pagamento como desativado e, se já havia um vínculo gravado com a integração, desfaz esse vínculo e grava a desativação. Do lado do cliente, a PagHiper "sumiu sozinha" ou "desativou do nada", e a opção de boleto some do checkout.
Duas situações produzem exatamente isso. A primeira é integrar a PagHiper e nunca ter vinculado a conta bancária daquela forma de pagamento à loja — a integração fica configurada e a loja continua sem enxergar. A segunda é o vínculo existir e ser desfeito depois, por exemplo quando alguém mexe nas lojas da conta bancária. Nesse caso funcionava e parou, sem que ninguém tenha tocado na PagHiper.
O conserto é conceitual e é do ERP: garantir que a conta bancária usada pela forma de pagamento da PagHiper esteja vinculada à loja onde a loja virtual roda. Como se cadastra conta bancária, como se cadastra forma de pagamento e como funciona o vínculo por loja estão no conteúdo do ERP e no conteúdo geral de Integrações.
Vale lembrar o pré-requisito geral das integrações de pagamento: antes de a integração funcionar precisa existir uma forma de pagamento apontando para ela, e uma forma de pagamento já vinculada a outro banco não pode ser reaproveitada para a PagHiper.
NA AGENDA PRO
A PagHiper também é uma das integrações reconhecidas como meio de pagamento das formas de pagamento da Agenda PRO, e a conferência lá é a mesma da loja virtual: a integração precisa fechar a cadeia até a conta bancária vinculada à loja atual. Se não fechar, a Agenda PRO desfaz o vínculo e desativa o meio de pagamento do mesmo jeito silencioso.
As telas e o restante do funcionamento da Agenda PRO têm conteúdo próprio.
NA GESTÃO DE COBRANÇAS
A PagHiper faz parte do catálogo de meios de pagamento da Gestão de Cobranças. No sistema ela é descrita assim: "Conecte a PagHiper via API para emitir cobranças, consultar pagamentos e automatizar o retorno das transações". Ela é classificada como integração por API e traz um atalho para a tela de configuração da PagHiper.
No catálogo, a PagHiper aparece marcada como ativa quando já existe uma forma de pagamento apontando para ela; sem essa forma de pagamento, ela aparece como disponível para conectar.
Um detalhe que evita mal-entendido: a PagHiper está no catálogo, mas não é a opção marcada como recomendada — o selo de recomendada é da Conta Integrada. Estar sem o selo não significa estar indisponível nem com defeito.
Como a régua de cobrança funciona é assunto do conteúdo da Gestão de Cobranças. Aqui fica só o registro de que a PagHiper está no catálogo dela.
NO RETORNO DO PEDIDO DA LOJA VIRTUAL PELA API
Existe um endpoint específico da API para o pedido da loja virtual. Nele, além dos dados do pedido, o sistema devolve o lançamento financeiro ligado àquele pedido — se houver mais de um, é considerado o primeiro. Se a forma de pagamento desse lançamento for da PagHiper, o retorno traz junto um bloco com os dados da transação da PagHiper daquele lançamento, identificado com o nome PagHiper. Havendo mais de uma transação para o mesmo lançamento, vem a mais recente.
Atenção ao endpoint: esse bloco vem no retorno do pedido da loja virtual. A consulta comum de pedido pela API não traz esses dados de integração. Se o bloco não vier, verifique primeiro se a chamada foi para o endpoint certo; depois, se o lançamento tem mesmo transação da PagHiper — normalmente a forma de pagamento do lançamento não é da PagHiper, ou a cobrança nunca chegou a ser gerada. Autenticação e uso geral da API estão na pasta da API.
A PAGHIPER RODA DENTRO DO ERP
Diferença que vale registrar para o diagnóstico: a PagHiper é executada pelo próprio ERP. Ela não está entre as integrações bancárias que o sistema manda executar por um serviço externo. Então o roteiro de investigação é o do ERP — conta bancária, forma de pagamento, vínculo com a loja, plano — e não o roteiro das integrações bancárias externas, que tem conteúdo próprio em bancos externos e marketplaces e só serve aqui como contraste.
O QUE COSTUMA DAR ERRADO
Meio de pagamento da PagHiper desativado sozinho na loja virtual. Causa real: a conta bancária da forma de pagamento não está vinculada àquela loja. O sistema desativa em silêncio, sem mensagem. Reative depois de acertar o vínculo, não antes — sem o vínculo ele volta a desativar na próxima leitura.
Sumiu a opção de boleto no checkout da loja. Mesma causa acima, vista pelo lado do comprador. Antes de investigar, confirme que você não está procurando pelo nome "PagHiper" no checkout: ali a opção aparece como Boleto bancário.
O pedido entrou mas a cobrança não foi gerada. Causa real: a forma de pagamento daquele lançamento não está apontando para a integração. O sistema responde Forma de pagamento "<nome>" não vinculada a integração!, com o nome da forma de pagamento no meio da mensagem.
A PagHiper não aparece na lista de meios de pagamento da loja. Causa real possível: o recurso não está liberado no plano da empresa. Nesse ponto o sistema apenas remove a integração da lista, sem mensagem. A mensagem de plano — "O seu plano atual não lhe permite acessar a integração com o PagHiper. Por favor, contrate outro plano!" — aparece na hora de gerar a cobrança pela integração. Quando quem esbarra nisso é o comprador, sem usuário logado, a mensagem que aparece é outra: "Este lançamento não está disponível!".
ONDE ESTÁ O RESTO
A visão geral da PagHiper e o índice do que cada assunto responde estão no conteúdo de apresentação da PagHiper. As telas do próprio aplicativo, o cadastro da integração, o Pix e as permissões têm conteúdo próprio na mesma pasta.
O desenho comum dos canais de venda, o de-para de situações e de meios de pagamento e as travas de autorização estão na pasta de marketplaces e e-commerce. O roteiro comum de integrar um meio de pagamento e o funcionamento geral do Pix estão na pasta de meios de pagamento. O índice de integrações, o vínculo por loja e o efeito de remover uma integração estão no conteúdo geral de Integrações.