VibeFox Barion for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. Sem o WooCommerce, o plugin mostra um aviso na área administrativa e o método de pagamento não é carregado.
PHP: 8.0 ou superior.
Loja Barion: você precisa da POSKey (chave secreta) da sua loja e do e-mail da carteira Barion que recebe os pagamentos. Ambos estão no portal da Barion: secure.barion.com para produção e secure.test.barion.com para teste, em My stores e na sua loja. Teste e produção têm credenciais diferentes.
Moeda: a moeda da loja precisa ser HUF, EUR, USD ou CZK. Para outras moedas, o método de pagamento fica oculto na finalização de compra.
Loja acessível: a Barion chama a sua loja após cada pagamento, então o site precisa estar acessível pela internet, sem modo de manutenção, firewall ou autenticação básica na frente de /wc-api/.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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_barion_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Barion > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira a POSKey de teste e o e-mail da carteira de teste, mantenha Test Mode ativado e ative Enable/Disable. Faça um pedido de teste.
6. Quando tudo estiver funcionando, insira as credenciais de produção e desmarque Test Mode.
A URL de callback é enviada à Barion automaticamente em cada pagamento. Nada precisa ser configurado no portal da Barion.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Barion. Se a moeda da loja não for compatível, a página informa isso em vermelho na seção Barion shop credentials e lista as moedas compatíveis; o método de pagamento fica oculto na finalização de compra.
Geral
Enable/Disable: Enable Barion Payment 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: Barion.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely with Barion — card, Barion Wallet, Apple Pay or Google Pay.
Credenciais da loja Barion
Obtenha a sua POSKey e o e-mail da carteira no portal da Barion: secure.barion.com (produção) ou secure.test.barion.com (teste), My stores, sua loja. Esta seção também mostra a URL de callback, por exemplo https://your-site/wc-api/barion_payment_callback/. Ela é enviada à Barion em cada pagamento; só precisa estar acessível pela internet.
Test Mode: Enable Barion test/sandbox mode. O modo de teste usa as credenciais de teste abaixo e o sandbox da Barion (api.test.barion.com); nenhum dinheiro real é cobrado. Padrão: ativado. Desmarque para receber pagamentos reais.
Test POSKey: a chave secreta (POSKey) da sua loja no sistema de teste da Barion (secure.test.barion.com, My stores).
Test Payee Email: o e-mail da sua carteira de teste da Barion, que recebe os pagamentos de teste.
Live POSKey: a chave secreta (POSKey) da sua loja no sistema de produção da Barion (secure.barion.com, My stores).
Live Payee Email: o e-mail da sua carteira Barion, que recebe os pagamentos.
Pedidos
Order Status After Payment: o status do pedido definido após um pagamento bem-sucedido e verificado.
Avançado
Logging: Enable debug logging. Os logs são salvos em WooCommerce > Status > Logs, origem wcp_barion_gateway. As chaves secretas nunca são registradas. Padrão: desativado.
Delete Data on Uninstall: Remove the plugin settings when the plugin is deleted. Pedidos e os dados de pagamento Barion deles são sempre mantidos. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, Barion) e faz o pedido. O plugin inicia um pagamento Barion pelo total do pedido, na moeda do pedido, e envia o cliente à página de pagamento da Barion. Os itens do pedido, o frete, as taxas e o imposto são listados no pagamento, o e-mail de faturamento do cliente é enviado como referência, e o idioma da página acompanha o idioma da loja quando a Barion oferece suporte a ele.
Depois de pagar, o cliente volta à sua loja. A Barion também chama a URL de callback. Nenhuma dessas requisições marca o pedido como pago por si só: o plugin consulta a Barion sobre o status do pagamento com a sua POSKey, e o pedido só é marcado como pago depois que a Barion confirma e o valor e a moeda coincidem com o pedido. O link de retorno contém a chave do pedido, e somente os pagamentos iniciados para esse pedido são verificados.
Se o pagamento foi concluído ou ainda está em andamento na Barion, o cliente chega à página de pedido recebido. Caso contrário, o cliente volta à finalização de compra e vê Payment was not completed. Please try again. O cliente pode tentar novamente; cada tentativa é registrada, então um pagamento tardio de uma tentativa anterior ainda conclui o pedido.
Se o pagamento não puder ser iniciado, o cliente vê The Barion payment could not be started. Please try again or choose another payment method. Gerentes da loja logados também veem o motivo técnico. Os detalhes vão para o log.
O método de pagamento funciona na finalização de compra clássica e no bloco de Finalização de compra. É compatível com o armazenamento de pedidos de alto desempenho do WooCommerce (HPOS).
O plugin aceita somente pagamentos imediatos. Não tem pagamentos com reserva ou captura posterior, não tem WooCommerce Subscriptions ou pagamentos recorrentes, não salva cartões, não tem o Barion Pixel e não envia dados extras de 3-D Secure; a Barion cuida do 3-D Secure na página de pagamento dela.
Pedidos e reembolsos
Status do pedido
Pending payment: o pagamento Barion foi iniciado e a Barion ainda não o confirmou. A nota do pedido mostra o PaymentId da Barion, o valor e, no modo de teste, (test mode).
Processing or Completed: a Barion confirmou o pagamento. O status segue Order Status After Payment. A nota do pedido mostra o valor, o PaymentId e a transação. O ID da transação é o ID de transação da Barion.
On hold: a Barion informou um valor ou uma moeda diferente do total do pedido, por exemplo porque o pedido foi editado depois que o pagamento foi iniciado. Verifique o pagamento no portal da Barion e conclua ou reembolse o pedido manualmente.
Cancelled: a tentativa de pagamento mais recente foi cancelada ou expirou na Barion.
Failed: a tentativa de pagamento mais recente falhou.
Um pedido pago ou reembolsado nunca é alterado por um callback posterior. Se outro pagamento for bem-sucedido para um pedido já pago, uma nota pede que você verifique no portal da Barion e reembolse se for uma duplicata.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Barion. São compatíveis reembolsos totais e parciais. O motivo do reembolso é enviado à Barion como comentário. Reembolsos em HUF devem ser valores inteiros. O reembolso é enviado no modo (teste ou produção) em que o pedido foi pago, então a POSKey desse modo precisa estar definida. Se a Barion não aceitar ou não confirmar o reembolso, o WooCommerce mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido, com a transação e o status da Barion.
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 > Barion. 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 em vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, a Barion não é mostrada 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. 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: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente em segundo plano, automaticamente.
Solução de problemas
A Barion não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se o modo atual tem POSKey e e-mail do beneficiário, e se a moeda da loja é HUF, EUR, USD ou CZK.
O pagamento foi feito, mas o pedido continua com o status Pending payment: o pedido é concluído quando a Barion chama a URL de callback ou quando o cliente volta à sua loja. Verifique se o site está acessível pela internet (sem modo de manutenção, firewall ou autenticação básica na frente de /wc-api/). Confirme que a POSKey do modo em que o pedido foi pago está correta, porque o plugin consulta a Barion sobre o status do pagamento com ela. Ative Logging para ver o callback.
O callback responde Busy, retry: o pedido estava sendo processado pelo retorno do cliente no mesmo momento. A Barion chama de novo.
O callback responde API error: a loja não conseguiu ler o status do pagamento na Barion. Verifique a POSKey do modo em que o pedido foi pago.
Um pedido está On hold com uma nota de divergência: o valor ou a moeda informados pela Barion são diferentes do total do pedido. Verifique o pagamento no portal da Barion e conclua ou reembolse manualmente.
Por que não consigo reembolsar 10.50 HUF: a Barion processa HUF sem casas decimais. Informe um valor inteiro.
O reembolso diz que a POSKey do modo deste pedido não está configurada: o pedido foi pago no modo de teste ou de produção, e a POSKey desse modo está vazia. Insira-a e tente novamente.
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 em 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.
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 de licença deste plugin são sempre removidos. As configurações do gateway são removidas somente se Delete Data on Uninstall estava ativado. Caso contrário, permanecem para uma eventual reinstalação. Pedidos e os dados de pagamento Barion deles são sempre mantidos. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Barion é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Barion.