VibeFox Niubiz for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e posteriores (testado na versão 4.1.0.3).

PHP: 8.0 ou superior.

Moeda: o sol peruano (PEN) ou o dólar americano (USD) precisam estar habilitados em System > Localisation > Currencies. O método de pagamento só é oferecido quando o cliente paga em uma dessas moedas. Para outras moedas, ele fica oculto na finalização de compra.

Conta Niubiz: a Niubiz emite um ID de comerciante (código de comercio), um usuário de API e uma senha de API para cada ambiente. As credenciais de sandbox são fornecidas pela equipe de integrações da Niubiz, e as de produção, depois que a Niubiz certifica 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

O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3 wcp_niubiz_payment-oc3-(version).ocmod.zip e o pacote do OpenCart 4 wcp_niubiz_payment.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No painel de administração, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_niubiz_payment-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, por isso Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você também pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Acesse Extensions > Extensions e escolha o tipo Payments. Localize VibeFox Niubiz Payment e clique em Install (o botão verde +). Seu usuário administrador precisa do direito de modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão com o lápis) para abrir a página de configurações. Cole sua chave de licença VibeFox em License key, no bloco de licença no topo da página, e clique em Activate (veja License key).

4. Mantenha Sandbox mode ativado e informe o ID de comerciante, o usuário de API e a senha de API do sandbox (veja Configuration).

5. Ative Enable/Disable, clique em Save e faça alguns pagamentos de teste com os cartões de teste da Niubiz.

6. Depois que a Niubiz certificar sua integração, informe as credenciais de produção e desative Sandbox mode.

OpenCart 4

1. No painel de administração, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_niubiz_payment.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão do nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Acesse Extensions > Extensions e escolha o tipo Payments. Localize VibeFox Niubiz Payment, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).

4. Informe a chave de licença e as credenciais da Niubiz e faça os pagamentos de teste como nas etapas 3 a 6 para o OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões.

Uma instalação nova começa com o método de pagamento desativado e o modo sandbox ativado.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Payments > VibeFox Niubiz Payment > Edit. As seções aparecem na lista à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, a página avisa se nenhuma moeda PEN ou USD estiver habilitada na loja, ou se as credenciais do modo atual estiverem 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 quando o cliente paga em PEN ou USD. Enquanto o modo sandbox estiver ativado, a página mostra Sandbox mode is on: payments go to the Niubiz sandbox and no real charges are made. Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, um valor incorreto não é gravado: a página mostra um erro acima das configurações, o campo volta ao valor anterior e os demais campos são salvos. Isso vale para um Title vazio ou com mais de 128 caracteres, um ID de comerciante que não contenha apenas dígitos, um URL de logotipo que não comece com https://, um Sort Order que não seja um número inteiro e um Total que não seja um número igual ou maior que 0.

Niubiz

Enable/Disable: ativa ou desativa os pagamentos pela Niubiz. Padrão: off.

Title: o nome do método de pagamento que o cliente vê na finalização de compra. Ele também é o nome do método de pagamento salvo no pedido. Padrão: Credit or debit card (Niubiz). Obrigatório, até 128 caracteres.

Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay securely with Visa, Mastercard, American Express or Diners Club in the Niubiz payment form.

Sort Order: a posição da Niubiz entre os métodos de pagamento na finalização de compra. Deixe em branco ou informe um número inteiro.

Geo Zone: oferece a Niubiz apenas para endereços de pagamento na zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones. No OpenCart 4, quando a loja não pede endereço de pagamento, é usado o endereço de entrega.

Total: o total da finalização de compra, na moeda padrão da loja, que um pedido precisa atingir antes de a Niubiz ser oferecida. Deixe em branco para oferecer a Niubiz em qualquer valor.

Credenciais da Niubiz

A Niubiz fornece um ID de comerciante, um usuário de API e uma senha de API para o sandbox (QA) e, após a certificação, para a produção. Um pagamento já iniciado é sempre autorizado com as credenciais do próprio modo.

Sandbox mode: usa o sandbox da Niubiz, sem cobranças reais. Ele troca tanto os endpoints da API quanto o conjunto de credenciais abaixo. Padrão: on. Desative-o para receber pagamentos reais com as credenciais de produção. Enquanto estiver ativado, os clientes veem SANDBOX MODE: use Niubiz test cards — no real charges are made. na etapa Confirm Order e na página de pagamento.

Sandbox merchant ID: o código do comerciante (código de comercio) da sua conta sandbox, somente dígitos. Os espaços são removidos.

Sandbox API user: o usuário de API do sandbox, normalmente um endereço de e-mail.

Sandbox API password: a senha de API do sandbox.

Production merchant ID: o código do comerciante da sua conta de produção (afiliada), somente dígitos.

Production API user: o usuário de API de produção.

Production API password: a senha de API de produção.

As senhas salvas nunca são exibidas novamente nem enviadas ao navegador. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo. Para remover uma senha salva, marque Clear the saved password on save abaixo do campo e clique em Save.

Formulário de pagamento

Logo URL: endereço opcional do seu logotipo, exibido no formulário de pagamento da Niubiz. Precisa ser um endereço https://. Deixe em branco para mostrar o nome da loja.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). O pedido recebe um status somente depois que a Niubiz responde à autorização. Cada campo abaixo lista os status de pedido do seu OpenCart.

Order Status After Payment: a Niubiz aprovou o pagamento e o número da compra, o valor e a moeda conferem com o pedido. Padrão: Processing.

On Hold Status: a Niubiz aprovou um pagamento que não confere com o pedido, ou não deu uma resposta definitiva, então o cartão pode ter sido cobrado. Padrão: Pending, porque o OpenCart não tem o status On hold. Você pode criar um status próprio em System > Localisation > Order Statuses e selecioná-lo aqui.

Avançado

Debug log: grava as requisições à API da Niubiz e as etapas do pagamento no arquivo niubiz_p_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web e, ao atingir 5 MB, é movido para niubiz_p_debug.old.log.php. Erros e avisos são sempre registrados, mesmo com esta opção desativada. Senhas, tokens e dados de cartão ou de clientes nunca são registrados. Padrão: off.

Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.

Delete data on uninstall: quando ativada, desinstalar a extensão remove as configurações do gateway e o log. Os dados de pagamento da Niubiz dos pedidos (números de compra, IDs de transação) são sempre mantidos. Padrão: off.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. As senhas de API não são exportadas.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. As senhas de API salvas são mantidas.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Credit or debit card (Niubiz)). Na etapa Confirm Order, o cliente vê sua descrição e a nota You will complete the payment in the secure Niubiz payment form. O OpenCart cria o pedido nessa etapa, ainda sem status. No OpenCart 4, o cliente escolhe o método de pagamento com o botão Choose do bloco de método de pagamento, na janela Payment method options, e clica em Confirm Order na parte inferior da página de finalização de compra. Quando o cliente clica em Confirm Order, a extensão solicita à Niubiz um token de acesso e uma sessão de pagamento para o total do pedido, na moeda do pedido, e abre a página Niubiz payment da sua loja. Se a sessão não puder ser criada, o cliente permanece na etapa Confirm Order com uma breve mensagem, por exemplo We could not connect to Niubiz. Please try again in a few minutes.

Na página de pagamento, o formulário de pagamento da Niubiz abre automaticamente. A página diz Complete the payment in the secure Niubiz payment form — your card details are entered on Niubiz, not on this site. Ela também tem um botão Pay com o total do pedido, para abrir o formulário novamente, e um link Choose another payment method para voltar à finalização de compra. É necessário JavaScript. Se o formulário da Niubiz não puder ser carregado, a página mostra The Niubiz payment form could not be loaded. Please reload the page or try again later.

O cliente informa o cartão no formulário da Niubiz. A Niubiz devolve à sua loja um token de uso único, e a extensão 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 imediatamente. O pedido só é marcado como pago depois que a Niubiz confirma e a resposta confere com o pedido. Depois disso, o pedido recebe seu status da forma padrão do OpenCart, com os e-mails de pedido habituais e a atualização do estoque, e o cliente vê a página de sucesso do pedido do OpenCart.

Cartão recusado: o pedido permanece sem status e uma nota é adicionada a ele. O cliente volta à página de pagamento com Your payment was declined: e o motivo informado pela Niubiz, e pode tentar novamente com o mesmo cartão ou com outro. O formulário não reabre sobre a mensagem; o cliente clica em Pay.

Sem resposta da Niubiz: se a Niubiz não der uma resposta definitiva (tempo esgotado, erro do servidor, resposta ilegível), o pedido recebe o On Hold Status e a página de sucesso mostra We could not confirm your payment with Niubiz. Please do not pay again — the store will verify the payment and contact you. Se a Niubiz aprovou um pagamento que não confere com o pedido, a página de sucesso mostra Your payment was received and is being reviewed by the store. We will contact you if anything else is needed.

Solicitação recusada: se a Niubiz recusar a própria solicitação (por exemplo, credenciais inválidas ou um número de compra duplicado), o pedido permanece sem status, uma nota é adicionada e o cliente vê Niubiz could not process the payment and your card was not charged. Se a API da Niubiz não puder ser acessada naquele momento, o cliente vê We could not connect to Niubiz and your card was not charged. Please try again in a few minutes.

Pedido alterado: se o total do pedido já não corresponder à sessão quando o formulário for enviado, o pagamento não é autorizado e o cliente vê Your order total has changed since the payment form was opened, so your card was not charged. Please check the total and pay again.

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 ID de comerciante, ou o total do pedido mudou, a página de pagamento cria uma nova sessão.

Cada tentativa de pagamento recebe um novo número de compra: o número do pedido seguido de um número de tentativa de três dígitos, porque a Niubiz exige um número de compra único para cada autorização. O OpenCart 3 cria um novo pedido toda vez que a etapa Confirm Order é exibida. O OpenCart 4 mantém um só pedido para a finalização de compra e o atualiza; por isso, depois de um cartão recusado, o cliente paga o mesmo pedido com um novo número de compra. Um carrinho já pago não é cobrado de novo: o cliente é levado à página de sucesso do pedido pago.

O OpenCart 4 mantém o pedido na finalização de compra até que a página de sucesso seja exibida. Se esse pedido for fechado sem pagamento nesse meio-tempo (por exemplo, se você o cancelou), o cliente é enviado de volta à finalização de compra com Your previous order was cancelled or its payment failed. Please confirm the order again., e o próximo Confirm Order paga um novo pedido. Se esse pedido já tiver um status e o carrinho tiver agora outros produtos ou quantidades, a mensagem é Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again. No OpenCart 4, as mensagens que enviam o cliente de volta à finalização de compra, como The Niubiz payment could not be found. Please confirm your order again., são exibidas acima da página de finalização de compra.

A página de pagamento, a resposta do formulário da Niubiz e o retorno à loja também funcionam enquanto a loja está em modo de manutenção: o OpenCart 3 deixa passar as requisições das extensões de pagamento, e no OpenCart 4 a extensão adiciona para elas uma ação de inicialização.

A extensão aceita somente pagamentos pontuais com cartão. Não há reembolsos ou cancelamentos a partir do OpenCart, nem cartões salvos, assinaturas ou pagamentos recorrentes, nem seleção de parcelamento (cuotas), nem PagoEfectivo, Yape ou outras carteiras e pagamentos por QR. Pedidos colocados em espera porque a resposta se perdeu não são verificados novamente de forma automática.

Pedidos

Status do pedido

Sem status (pedido ausente): o cliente está na página de pagamento e não pagou, ou o cartão foi recusado, ou a solicitação foi negada. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders. Recusas e negativas são adicionadas às notas do pedido.

No OpenCart 4, um pedido não pago da finalização de compra pode receber o status Voided, que o OpenCart 4 define quando o cliente volta à etapa Confirm Order. A extensão trata esse pedido como um pedido sem status, e um pagamento posterior ainda o confirma.

Order Status After Payment (padrão Processing): a Niubiz aprovou o pagamento e a resposta conferiu com o pedido. 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.

On Hold Status (padrão Pending), aprovado mas não conferente: a Niubiz aprovou um pagamento cujo número de compra, valor ou moeda difere do pedido, ou cuja resposta não contém o valor ou a moeda. O pedido não é marcado como pago. A nota lista as diferenças. Verifique a transação no console da Niubiz.

On Hold Status (padrão Pending), sem resposta definitiva: a Niubiz não respondeu de forma clara, então o cartão pode ter sido cobrado. A nota informa o número da compra. Procure-o no console da Niubiz: se a transação estiver aprovada e correta, defina o pedido como pago; se não, cancele-o.

Se um segundo pagamento for respondido para um carrinho que já está pago, nenhum segundo status é definido. Uma nota no pedido pago informa o número da compra, o ID da transação e o valor, para que você possa conferir no console da Niubiz e reembolsar ou anular, se necessário.

As notas são entradas do History do pedido que o cliente não vê.

Aba VibeFox Niubiz Payment

Em Sales > Orders, abra um pedido pago com a Niubiz. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Niubiz Payment mostra o número da compra, o ambiente (sandbox ou produção), a Niubiz answer, o ID da transação, o código de autorização, o cartão, o valor (e o valor aprovado pela Niubiz), os problemas encontrados, o número de tentativas e as Niubiz notes do pedido. Para um pedido no status de espera, a aba lembra você de conferir o número da compra no console da Niubiz. A aba é somente leitura e é exibida aos usuários que têm acesso à extensão.

Reembolsos

Reembolsos e cancelamentos não estão disponíveis no OpenCart. Reembolse ou anule a transação no console da Niubiz e atualize o status do pedido manualmente. Devoluções de produtos em Sales > Returns não devolvem dinheiro pela Niubiz.

Chave de licença

A extensão funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Niubiz Payment é o primeiro bloco em Extensions > Extensions > Payments > VibeFox Niubiz Payment > Edit, acima das configurações. Cole 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: opencart-payment-niubiz e o link Manage licenses and domains in your account, que abre sua conta em vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel administrativo (inglês e russo estão incluídos).

Se a chave não for aceita, o bloco informa o motivo, por exemplo Key not found, This key belongs to another product, Domain limit reached ou License expired on seguido de uma data. Depois de alterar o endereço da loja ou de liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um único domínio: o endereço da loja informado na configuração do OpenCart. 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 um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. Um usuário administrador conectado ao painel no mesmo navegador ainda vê o método de pagamento na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa visualização não está disponível: a loja não vê o login no painel administrativo, então, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois de abrir a página Edit uma vez, um lembrete aparece no Dashboard do administrador. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática quando você abre o Dashboard ou a página Edit do administrador: uma vez por dia durante os primeiros 14 dias após a chave ser informada e, depois, uma vez por semana. Não é necessário cron job. Desinstalar a extensão 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 ID de comerciante, o usuário de API e a senha de API do modo atual estão preenchidos (campos de sandbox no modo sandbox, campos de produção nos demais casos) e se o cliente paga em PEN ou USD. A página de configurações mostra um aviso quando as credenciais ou as moedas estão incorretas. Verifique também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.

O pagamento foi feito, mas o pedido continua sem status: a Niubiz não tem webhook para este formulário de pagamento, então o pedido só recebe o status a partir da resposta à autorização. Se o cliente não concluiu o formulário, nada foi pago. Caso contrário, veja o campo Log na página da extensão e procure o número da compra no console da Niubiz. Se a Niubiz respondeu, mas não foi possível definir o status, o cliente vê Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again., e a extensão tenta definir o status novamente quando o cliente abre a página de pagamento ou confirma o carrinho outra vez.

O cliente vê We could not connect to Niubiz: não foi possível obter o token de acesso. Verifique o usuário de API e a senha de API do modo atual e se o seu servidor consegue acessar a API da Niubiz. Ative Debug log para ver os detalhes.

O cliente vê We could not start the Niubiz payment: a Niubiz não criou a sessão de pagamento. Verifique o ID de comerciante do modo atual e o log.

O cliente vê This payment attempt was already processed: 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ê This order is already being paid: outra requisição está autorizando o mesmo carrinho neste momento. O cliente aguarda um instante e confere o e-mail antes de tentar de novo.

Uma nota informa que a Niubiz reportou 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.

O pedido está no status de espera: leia as notas na aba VibeFox Niubiz Payment. A Niubiz não deu uma resposta definitiva ou aprovou um pagamento que não confere com o pedido. Procure o número da compra no console da Niubiz e defina o pedido como pago ou cancele-o.

Erro ao salvar as configurações: o ID de comerciante deve conter somente dígitos, o URL do logotipo deve ser um endereço https:// válido e o título não pode estar vazio nem ter mais de 128 caracteres. O valor anterior é mantido.

Para desenvolvedores: se a Niubiz exigir o envio de campos antifraude específicos do comerciante (MDD), outra extensão pode adicioná-los com o evento do OpenCart niubiz_p_merchant_define_data. Os dados do titular do cartão enviados com a sessão de pagamento podem ser alterados com o evento niubiz_p_cardholder_data.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Niubiz Payment. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as próprias configurações da extensão: Enable/Disable, Sort Order, Geo Zone, Total e os status de pedido da seção Orders, que voltam aos padrões em uma reinstalação. O evento do OpenCart da extensão também é removido (no OpenCart 4, seus eventos e sua ação de inicialização, que deixa passar no modo de manutenção a página de pagamento, a resposta do formulário da Niubiz e o retorno). Se Delete data on uninstall estiver ativado, as demais configurações do gateway (título, descrição, modo sandbox, credenciais, logotipo, registros) e o log são removidos. Se estiver desativado, elas são mantidas para uma reinstalação futura. As tentativas de pagamento da Niubiz (números de compra, ambiente, IDs de transação) são sempre mantidas como histórico de pagamentos. Os pedidos existentes mantêm suas notas de pagamento.

No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Niubiz Payment na lista de extensões instaladas e, depois, em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

A Niubiz é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pela Niubiz.