VibeFox Niubiz for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 6.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

Moeda da loja: soles peruanos (PEN) ou dólares americanos (USD). Para outras moedas, o método de pagamento fica oculto na finalização de compra.

Conta 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 vêm da equipe de integração da Niubiz, e as de produção depois que a Niubiz certificar a sua integração. Nenhum webhook precisa ser configurado: 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 WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_niubiz_payment para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > Niubiz > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Mantenha Sandbox mode ativado e insira o merchant ID, o API user e a API password do sandbox (veja Configuração).

6. Ative Enable/Disable e faça alguns pagamentos de teste com os cartões de teste da Niubiz.

7. Depois que a Niubiz certificar a sua integração, insira as credenciais de produção e desmarque Sandbox mode.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Niubiz. Acima dos campos, a página avisa quando a moeda da loja não é PEN nem USD, 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), e mostra O modo sandbox está ativo: os pagamentos vão para o sandbox da Niubiz e nenhuma cobrança real é feita. enquanto o modo sandbox estiver ativo. Na lista de métodos de pagamento, a Niubiz aparece como precisando de configuração até que o modo atual tenha credenciais completas.

Geral

Enable/Disable: Enable Niubiz payments ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o nome do método de pagamento que o cliente vê na finalização de compra. Padrão: Credit or debit card (Niubiz).

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 Niubiz

A Niubiz fornece um merchant ID, um API user e uma API password para o sandbox e, após a certificação, para a produção. A documentação para desenvolvedores está em desarrolladores.niubiz.com.pe.

Sandbox mode: Use the Niubiz sandbox (QA) environment — no real charges. Troca tanto os endpoints da API quanto o conjunto de credenciais abaixo. Padrão: ativado. Desmarque para receber pagamentos reais.

Sandbox merchant ID: o código de comerciante da sua conta sandbox, somente dígitos. Espaços são removidos. Se o valor tiver outros caracteres, a página de configurações mostra um erro e mantém o valor anterior.

Sandbox API user: o API user do sandbox.

Sandbox API password: a API password do sandbox.

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

Production API user: o API user de produção.

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

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 começa com https:// é recusado e o valor anterior é mantido.

Avançado

Debug log: Log API calls grava as requisições da Niubiz em WooCommerce > Status > Logs, origem wcp_niubiz_payment. Erros são sempre registrados. Credenciais, tokens e dados de cartão ou do cliente nunca são registrados. Padrão: desativado.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted. Desativar o plugin nunca apaga nada. Os dados de pagamento salvos nos pedidos são mantidos. Padrão: desativado.

As configurações da versão 1.0, que tinha um único conjunto de credenciais, são transferidas automaticamente: para os campos do sandbox se o modo de teste estava ativo, caso contrário para os campos de produção.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Credit or debit card (Niubiz)) e faz o pedido. O plugin solicita à Niubiz um token de acesso e uma sessão de pagamento para o total do pedido e envia o cliente para a página de pagamento do pedido da sua loja. No modo sandbox, a finalização de compra e a página de pagamento mostram MODO SANDBOX: use os cartões de teste da Niubiz. Nenhuma cobrança real é feita.

Na página de pagamento, o formulário de pagamento da Niubiz é aberto automaticamente. A página também tem um botão Pay com o total do pedido para reabrir o formulário, um botão Cancel order 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 novamente 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 plugin o autoriza no servidor com o valor, a moeda e o número de compra próprios do pedido. O pagamento é cobrado imediatamente. O pedido só é marcado como pago quando a Niubiz aprova o pagamento e a resposta confere com o pedido. Depois disso, o cliente vê a página de pedido recebido.

Cartão recusado: o cliente volta à página de pagamento com Seu pagamento foi recusado: e o motivo da Niubiz, e pode tentar novamente com o mesmo cartão ou 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 no servidor ou resposta ilegível), o cliente vê a página de pedido recebido com Não conseguimos confirmar seu pagamento com a Niubiz. Por favor, não pague novamente — a loja verificará o pagamento e entrará em contato com você.

Sessão expirada: a sessão de pagamento dura até 20 minutos. Quando ela é usada ou está prestes a expirar, ou quando o total do pedido ou o modo são alterados, a página de pagamento cria uma nova sessão.

Cada tentativa de pagamento recebe um novo número de compra: o ID do pedido 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. Um cliente pode pagar novamente um pedido não pago ou com falha pela página Pay for order.

O método de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. É compatível com o WooCommerce High-Performance Order Storage (HPOS).

O plugin aceita somente pagamentos únicos com cartão. Não há reembolsos nem cancelamentos pelo WooCommerce, 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 foi perdida não são reconferidos automaticamente.

Pedidos

Status do pedido

Aguardando pagamento: o cliente foi enviado à página de pagamento e ainda não pagou.

Em processamento: a Niubiz aprovou o pagamento e a resposta conferiu com o pedido. Pedidos apenas com produtos virtuais para download passam para Concluído, como de costume no WooCommerce. A nota do pedido mostra o ambiente, o ID da transação, o código de autorização, o número de compra e a bandeira do cartão com o número mascarado. O ID da transação do pedido é o ID da transação da Niubiz.

Falhou: o cartão foi recusado. A nota do pedido mostra o motivo da Niubiz, o código de ação e o número de compra. O cliente pode pagar novamente.

Em espera, aprovado mas não confere: 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. Confira a transação no console da Niubiz. O cliente vê Seu pagamento foi recebido e está sendo analisado pela loja.

Em espera, 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 de compra. Procure-o no console da Niubiz: se a transação estiver aprovada e correta, mude o pedido para Em processamento; caso contrário, cancele-o.

Cancelado: o cliente clicou em Cancel order na página de pagamento, ou o pedido foi cancelado por você ou pelo tempo limite de reserva de estoque do WooCommerce.

Quando a Niubiz recusa a própria requisição (por exemplo um número de compra duplicado, HTTP 406 ou credenciais inválidas), o status do pedido não muda. Uma nota informa que o cartão não foi cobrado, e o cliente pode tentar novamente com um novo número de compra.

Reembolsos

Reembolsos e cancelamentos não estão disponíveis pelo WooCommerce. Reembolse ou anule a transação no console da Niubiz e atualize o pedido manualmente, por exemplo com um reembolso manual do WooCommerce.

Chave de licença

O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Niubiz. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa, e o seu domínio. Use Check now para verificar o status novamente, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta no vibefox.net.

Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga de domínio. Libere a vaga na sua conta no 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ê Este método de pagamento não está disponível. Escolha outro. Os gerentes da loja logados ainda veem o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados: os pagamentos já iniciados no formulário da Niubiz continuam sendo autorizados.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática em segundo plano.

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á ativado, se o merchant ID, o API user e a API password do modo atual estão preenchidos (campos do sandbox no modo sandbox, campos de produção caso contrário) e se a moeda é PEN ou USD. Na página Pay for order, vale a moeda do pedido. A página de configurações mostra um aviso quando as credenciais ou a moeda estão incorretas.

O pagamento foi feito, mas o pedido continua Aguardando pagamento: a Niubiz não tem webhook para este formulário de pagamento, então o pedido só é atualizado pela resposta à autorização. Se o pedido estiver Em espera com uma nota, procure o número de compra no console da Niubiz. Se continuar Aguardando pagamento, o cliente não concluiu o formulário; verifique WooCommerce > Status > Logs, origem wcp_niubiz_payment.

O cliente vê Não foi possível conectar à Niubiz: o token de acesso não pôde ser obtido. 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 pela Niubiz: a Niubiz não criou a sessão de pagamento. Verifique o merchant ID do modo atual e o log.

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ê Sua sessão de pagamento expirou e seu cartão não foi cobrado: a página de pagamento ficou aberta por tempo demais. O cliente tenta novamente na mesma página.

Nota do pedido: a Niubiz informou uma autorização duplicada: a Niubiz já conhece este número de compra. Confira-o no console da Niubiz; o cliente pode tentar novamente com um novo número de compra.

O pedido está Em espera com uma nota da Niubiz: leia a nota. A Niubiz não deu uma resposta definitiva, ou aprovou um pagamento que não confere com o pedido. Procure o número de compra no console da Niubiz e mude o pedido para Em processamento ou cancele-o.

Erro ao salvar as configurações: um merchant ID deve conter somente dígitos, e a URL do logotipo deve ser um endereço https:// válido. O valor anterior é mantido.

O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta no vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Para desenvolvedores: se a Niubiz pedir o envio de campos antifraude específicos do comerciante (MDD), adicione-os com o filtro niubiz_p_merchant_define_data. As chaves são MDD seguido de um número, e os valores podem ter até 100 caracteres. Outros filtros: niubiz_p_cardholder_data (dados do titular enviados com a sessão de pagamento), niubiz_p_purchase_number (número de compra de uma tentativa, de 1 a 12 letras ou dígitos, único por tentativa) e niubiz_p_icon (ícone do método de pagamento).

Desinstalação

Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin são sempre removidos. As configurações do gateway e os logs são removidos somente se Delete data on uninstall estiver ativado. Os dados da Niubiz salvos nos pedidos (ID da transação, número de compra, cartão mascarado) fazem parte do histórico de pagamentos e são sempre mantidos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

A Niubiz é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Niubiz.