VibeFox Niubiz for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.
Moeda: soles peruanos (PEN) ou dólares americanos (USD). O método de pagamento só é oferecido para carrinhos em uma dessas moedas. Para as demais moedas, ele fica oculto na finalização de compra.
Conta na Niubiz: a Niubiz emite um merchant ID (código de comercio), um API user e uma API password para cada ambiente. As credenciais de sandbox são fornecidas pela equipe de integrações da Niubiz; as de produção, depois que a Niubiz certificar a sua integração. Não é preciso configurar nenhum webhook: a Niubiz responde à autorização imediatamente.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.
Instalação
1. No back office, acesse Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.
2. Quando o envio terminar, clique em Configure ou, depois, encontre VibeFox Niubiz Payment na lista de módulos e clique em Configure.
3. Insira a sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Mantenha Sandbox mode ativado e insira o merchant ID, o API user e a API password da sandbox (veja Configuração).
5. Ative Enable/Disable, clique em Save e faça alguns pagamentos de teste com os cartões de teste da Niubiz.
6. Quando a Niubiz certificar a sua integração, insira as credenciais de produção e desative Sandbox mode.
Ao instalar, o módulo cria o status de pedido Niubiz payment on hold. O PrestaShop vincula um novo módulo de pagamento a todas as moedas, a todos os grupos de clientes e aos países ativos naquele momento. Você pode alterar isso em Payment > Preferences. Confira ali se PEN ou USD está permitido para o módulo.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Niubiz Payment > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa quando não há nenhuma moeda PEN ou USD ativa na loja, ou quando as credenciais do modo atual estão incompletas (nos dois casos, o método de pagamento fica oculto na finalização de compra). Se a moeda padrão da loja não for PEN nem USD, a página informa que a Niubiz só é oferecida para carrinhos em PEN ou USD. Enquanto o modo sandbox estiver ativado, a página mostra O modo sandbox está ativado: os pagamentos vão para a sandbox da Niubiz e nenhuma cobrança real é feita.
Niubiz
Enable/Disable: Enable Niubiz payments liga ou desliga o método de pagamento. Padrão: desligado.
Title: o nome do método de pagamento que os clientes veem na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Credit or debit card (Niubiz). Obrigatório: um título vazio não é salvo e o anterior é mantido.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely with Visa, Mastercard, American Express or Diners Club in the Niubiz payment form.
Credenciais da Niubiz
A Niubiz fornece um merchant ID, um API user e uma API password para a sandbox e, após a certificação, para a produção. A documentação para desenvolvedores está em desarrolladores.niubiz.com.pe.
Sandbox mode: usa o ambiente de sandbox (QA) da Niubiz, sem cobranças reais. Ele troca tanto os endpoints da API quanto o conjunto de credenciais abaixo. Padrão: ligado. Desligue para pagamentos reais. Enquanto estiver ligado, os clientes veem MODO SANDBOX: use os cartões de teste da Niubiz — nenhuma cobrança real é feita. abaixo do método de pagamento e na página de pagamento.
Sandbox merchant ID: o código de comerciante da sua conta de sandbox, somente dígitos. Os espaços são removidos. Se o valor tiver outros caracteres, a página mostra um erro e mantém o valor anterior. Os demais campos são salvos.
Sandbox API user: o API user da sandbox.
Sandbox API password: a API password da sandbox.
Production merchant ID: o código de comerciante da sua conta de produção (afiliada), somente dígitos, com a mesma verificação.
Production API user: o API user de produção.
Production API password: a API password de produção.
As senhas salvas nunca são exibidas novamente. O campo fica vazio e mostra Salva — deixe vazio para mantê-la. Digite um novo valor somente se quiser alterá-la.
Clear saved passwords: marque uma senha e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Formulário de pagamento
Logo URL: endereço HTTPS opcional do seu logotipo, exibido no formulário de pagamento da Niubiz, de cerca de 187 × 40 px. Sem ele, é exibido o nome da loja. Um endereço que não seja um https:// válido é recusado com um erro e o valor anterior é mantido.
Avançado
Debug log: registra as chamadas à API da Niubiz em logs/niubiz_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados, mesmo quando esta opção está desligada. Credenciais, tokens, dados do cartão e do cliente nunca são registrados. Padrão: desligado.
Log: mostra o tamanho e as últimas entradas do registro. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: quando ligado, desinstalar o módulo remove as suas configurações e o registro. Os dados de pagamento salvos para os pedidos (tentativas na Niubiz, notas do pedido) e o status do pedido são sempre mantidos. Padrão: desligado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Credit or debit card (Niubiz)) e confirma o pedido. O módulo solicita à Niubiz um token de acesso e uma sessão de pagamento para o total do carrinho na moeda do carrinho, e abre a página de pagamento Niubiz payment da sua loja. Nesse ponto, ainda não existe nenhum pedido.
Na página de pagamento, o formulário de pagamento da Niubiz abre automaticamente. A página diz Conclua o pagamento no formulário seguro de pagamento da Niubiz — os dados do seu cartão são digitados na Niubiz, não neste site. Ela também tem um botão Pay com o total do carrinho para abrir o formulário novamente e um link Choose another payment method. É necessário JavaScript. Se o formulário da Niubiz não puder ser carregado, a página mostra Não foi possível carregar o formulário de pagamento da Niubiz. Recarregue a página ou tente mais tarde.
O cliente digita o cartão no formulário da Niubiz. A Niubiz devolve à sua loja um token de uso único, e o módulo o autoriza no servidor com o valor, a moeda e o número da compra da sessão, no ambiente em que a sessão foi criada. O pagamento é cobrado na hora. O pedido só é marcado como pago quando a Niubiz aprova o pagamento e a resposta confere com o carrinho. Depois disso, o pedido é criado e o cliente vê a página padrão de confirmação do pedido.
Cartão recusado: nenhum pedido é criado. O cliente volta à página de pagamento com Seu pagamento foi recusado: e o motivo da Niubiz, e pode tentar de novo com o mesmo cartão ou com outro. O formulário não é reaberto sobre a mensagem; o cliente clica em Pay.
Sem resposta da Niubiz: se a Niubiz não der uma resposta definitiva (tempo esgotado, erro no servidor, resposta ilegível), o pedido é criado em Niubiz payment on hold e a página de confirmação mostra Não foi possível confirmar o seu pagamento na Niubiz. Por favor, não pague novamente — a loja vai verificar o pagamento e entrará em contato com você. Se a Niubiz aprovou um pagamento que não confere com o carrinho, a página mostra Seu pagamento foi recebido e está sendo analisado pela loja. Entraremos em contato se for necessário mais alguma coisa.
Solicitação recusada: se a própria Niubiz recusar a solicitação (por exemplo, credenciais inválidas ou um número de compra duplicado), nenhum pedido é criado e o cliente vê A Niubiz não conseguiu processar o pagamento e o seu cartão não foi cobrado. O motivo é gravado no registro.
Carrinho alterado: se o total do carrinho mudar depois que o formulário foi aberto (por exemplo, em outra aba do navegador), o pagamento não é autorizado e o cliente vê O seu carrinho mudou desde que o formulário de pagamento foi aberto, por isso o seu cartão não foi cobrado. Confira o total e pague novamente.
Sessão expirada: uma sessão de pagamento da Niubiz dura até 20 minutos. Quando ela já foi usada, tem menos de 5 minutos restantes, pertence a outro modo ou a outro merchant ID, ou o total do carrinho mudou, a página de pagamento cria uma nova sessão.
Cada tentativa de pagamento recebe um novo número de compra: o ID do carrinho seguido de um número de tentativa de três dígitos (até 12 caracteres), porque a Niubiz exige um número de compra único para cada autorização.
O módulo aceita somente pagamentos únicos com cartão. Não há reembolsos nem cancelamentos pelo PrestaShop, nem cartões salvos, assinaturas ou pagamentos recorrentes, nem escolha de parcelamento (cuotas), nem pagamentos com PagoEfectivo, Yape ou outras carteiras e pagamentos QR. Pedidos colocados em espera porque a resposta foi perdida não são reconferidos automaticamente.
Pedidos
Status do pedido
No order yet: o cliente está na página de pagamento e não pagou, ou o cartão foi recusado ou a solicitação foi rejeitada. Só existe o carrinho. Recusas e rejeições são registradas no log do módulo.
Payment accepted: a Niubiz aprovou o pagamento e a resposta conferiu com o carrinho. O pagamento é registrado com o ID da transação da Niubiz, e uma nota mostra o ambiente, o ID da transação, o código de autorização, o número da compra e a bandeira do cartão com o número mascarado.
Niubiz payment on hold, approved but not matching: a Niubiz aprovou um pagamento cujo número da compra, valor ou moeda difere do carrinho, ou cuja resposta não contém o valor ou a moeda. O pedido não é marcado como pago. Se a aprovação estiver na moeda do carrinho, o valor aprovado é registrado como um pagamento com o seu ID de transação. A nota lista as diferenças. Confira a transação no console da Niubiz.
Niubiz payment on hold, no definitive answer: a Niubiz não respondeu com clareza, então o cartão pode ter sido cobrado. Nenhum pagamento é registrado. A nota informa o número da compra. Procure-o no console da Niubiz: se a transação estiver aprovada e correta, mude o pedido para Payment accepted; se não estiver, cancele-o.
Se um segundo pagamento receber resposta para um carrinho que já tem pedido, nenhum segundo pedido é criado. Uma nota no pedido informa o número da compra, o ID da transação e o valor, para que você possa conferir no console da Niubiz e estornar ou anular, se necessário.
Bloco de pagamento da Niubiz
A página do pedido mostra um bloco Niubiz payment com o número da compra, o ambiente (sandbox ou produção), o ID da transação, o código de autorização, o cartão e as notas do pedido. Para um pedido em Niubiz payment on hold, o bloco lembra você de conferir o número da compra no console da Niubiz. O bloco é somente leitura.
Reembolsos
Reembolsos e cancelamentos não estão disponíveis pelo PrestaShop. Estorne ou anule a transação no console da Niubiz e atualize o pedido manualmente. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Niubiz.
Chave de licença
O módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Niubiz Payment é o primeiro bloco de Modules > Module Manager > VibeFox Niubiz Payment > Configure, acima das configurações. Insira a chave em License key e clique em Activate. Depois disso, o bloco mostra a chave mascarada, o status (por exemplo, a data até a qual a licença está ativa e o seu domínio) e os botões Check now para verificar o status novamente, Change key para inserir outra chave e Remove key para remover a chave desta loja. Abaixo aparecem a linha Product: presta-payment-niubiz e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente funcionários com a permissão Configure para o módulo podem alterar a chave. Os textos do bloco seguem o idioma do back office (inglês e russo estão incluídos).
Se a chave não for aceita, o bloco informa o motivo, por exemplo Chave não encontrada, Esta chave pertence a outro produto, Limite de domínios atingido ou Licença expirou em seguido de uma data. Depois que o endereço da loja mudar, ou depois que você liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não estiver acessível, o módulo continua funcionando com o último status conhecido.
Uma chave funciona em um único domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, a Niubiz não é exibida aos clientes na finalização de compra. Se mesmo assim um pagamento for iniciado, o cliente vê Este método de pagamento não está disponível. Escolha outro. A vitrine do PrestaShop não sabe que você está logado no back office, então o método de pagamento também fica oculto para você: pode configurar o módulo antes de comprar uma chave, mas não testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia durante os primeiros 14 dias após a chave ser inserida e, depois, uma vez por semana. Não é necessário nenhum cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A Niubiz não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, se o merchant ID, o API user e a API password do modo atual estão preenchidos (os campos de sandbox no modo sandbox, os de produção nos demais casos) e se a moeda do carrinho é PEN ou USD. A página de configurações mostra um aviso quando as credenciais ou as moedas estão incorretas. Em Payment > Preferences, confira se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente.
O pagamento foi aprovado, mas nenhum pedido foi criado: a Niubiz não tem webhook para este formulário de pagamento, então o pedido só é criado pela resposta à autorização. Se o cliente não concluiu o formulário, não há pedido. Caso contrário, veja o campo Log na página do módulo e procure o número da compra no console da Niubiz. Se a Niubiz respondeu, mas o pedido não pôde ser criado (por exemplo, porque o módulo estava desligado), o cliente vê Seu pagamento foi recebido, mas o pedido não pôde ser concluído automaticamente. Entre em contato conosco — não pague novamente., e o módulo tenta criar o pedido de novo quando o cliente abrir a página de pagamento outra vez.
O cliente vê «Não foi possível conectar à Niubiz»: não foi possível obter o token de acesso. Verifique o API user e a API password do modo atual e se o seu servidor consegue acessar a API da Niubiz. Ative o Debug log para ver os detalhes.
O cliente vê «Não foi possível iniciar o pagamento na Niubiz»: a Niubiz não criou a sessão de pagamento. Verifique o merchant ID do modo atual e o registro.
O cliente vê «Esta tentativa de pagamento já foi processada»: o mesmo formulário foi enviado duas vezes. O cliente inicia o pagamento novamente na página de pagamento; o cartão não é cobrado duas vezes.
O cliente vê «Este pedido já está sendo pago»: outra solicitação está autorizando o mesmo carrinho neste momento. O cliente aguarda um instante e verifica o e-mail antes de tentar de novo.
O registro mostra que a Niubiz informou uma autorização duplicada: a Niubiz já conhece este número de compra. Confira no console da Niubiz; o cliente pode tentar novamente com um novo número de compra.
Pedido em Niubiz payment on hold: leia as notas no bloco Niubiz payment. A Niubiz não deu uma resposta definitiva ou aprovou um pagamento que não confere com o carrinho. Procure o número da compra no console da Niubiz e mude o pedido para Payment accepted ou cancele-o.
Erro ao salvar as configurações: o merchant ID deve conter somente dígitos, e a URL do logotipo deve ser um endereço https:// válido. O valor anterior é mantido.
Para desenvolvedores: se a Niubiz pedir o envio de campos antifraude específicos do comerciante (MDD), outro módulo pode adicioná-los com o hook actionNiubizPMerchantDefineData. Os dados do titular enviados com a sessão de pagamento podem ser alterados com o hook actionNiubizPCardholderData.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Niubiz Payment e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete data on uninstall estiver ligado, as configurações do módulo e o registro são removidos. Se estiver desligado, todas as configurações são mantidas para uma reinstalação futura. As tentativas de pagamento na Niubiz (números de compra, ambiente, IDs de transação) e o status de pedido Niubiz payment on hold são sempre mantidos como histórico de pagamentos. Os pedidos existentes mantêm as suas notas de pagamento e os IDs de transação.
A Niubiz é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Niubiz.