VibeFox Barion for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0).

PHP: 8.0 ou posterior.

Loja Barion: você precisa do POSKey (chave secreta) da sua loja e do endereço de e-mail da carteira Barion que recebe os pagamentos. Ambos estão no portal da Barion: secure.barion.com para o modo real, secure.test.barion.com para o modo de teste, em My stores e na sua loja. As credenciais de teste e as reais são diferentes.

Moeda: a moeda do pedido deve 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, por isso o site precisa estar acessível pela internet, sem firewall ou autenticação básica na frente. O modo de manutenção não bloqueia o callback: 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 (startup action).

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.

Instalação

O download é um único arquivo zip com os pacotes das duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3, wcp_barion_gateway-oc3-(version).ocmod.zip, e o pacote do OpenCart 4, wcp_barion_gateway.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, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_barion_gateway-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, então 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. Vá em Extensions > Extensions, escolha o tipo Payments, encontre VibeFox Barion Gateway 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 de 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 a seção Chave de licença).

4. Informe o POSKey de teste e o e-mail da carteira de teste, mantenha Test Mode ativado, ative Enable/Disable e clique em Save. Faça um pedido de teste.

5. Quando tudo estiver funcionando, informe as credenciais reais e desative Test Mode.

OpenCart 4

1. No painel de administração, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_barion_gateway.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir 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. Vá em Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Barion Gateway, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).

4. Informe a chave de licença e as credenciais da Barion e teste o pagamento como nas etapas 3 a 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só a URL de callback é diferente (veja Callback URL).

A URL de callback é enviada automaticamente à Barion em cada pagamento. Nada precisa ser configurado no portal da Barion. Uma instalação nova começa com o método de pagamento desativado e o modo de teste ativado.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox Barion Gateway > Edit. As seções ficam listadas à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, a página avisa quando o modo atual não tem POSKey ou e-mail do beneficiário (nesse caso, o método de pagamento fica oculto na finalização de compra) e quando a moeda padrão da sua loja não é suportada pela Barion, com a lista das moedas suportadas. Enquanto o modo de teste estiver ativado, ela mostra Test mode is on: payments go to the Barion sandbox (api.test.barion.com), no real money is charged. Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title deve ter de 1 a 128 caracteres, Sort Order deve ser um número inteiro e Total um número igual ou maior que 0. Se algum campo tiver erro, nada é salvo e a página indica o campo.

Barion

Enable/Disable: Enable Barion Payment 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: Barion. 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 Barion — card, Barion Wallet, Apple Pay or Google Pay.

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

Geo Zone: oferece a Barion somente 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.

Total: o valor total da compra, na moeda padrão da loja, que um pedido deve atingir para que a Barion seja oferecida. Deixe vazio para oferecer a Barion para qualquer valor.

Credenciais da loja na Barion

Obtenha seu POSKey e o e-mail da carteira no portal da Barion: secure.barion.com (real) ou secure.test.barion.com (teste), My stores, sua loja (os portais estão vinculados nesta seção). O modo de teste usa apenas as credenciais de teste, e o modo real usa apenas as reais.

Test Mode: usa as credenciais de teste informadas abaixo e a sandbox da Barion (api.test.barion.com). Nenhum dinheiro real é cobrado. Padrão: ativado. Desative para receber pagamentos reais. Enquanto estiver ativado, os clientes veem Test mode: no real payment is taken. na etapa Confirm Order.

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 endereço de 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 real da Barion (secure.barion.com, My stores).

Live Payee Email: o endereço de e-mail da sua carteira da Barion, que recebe os pagamentos.

Os POSKey salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo. Para remover um POSKey salvo, marque Clear the saved POSKey on save abaixo do campo e clique em Save.

Callback URL: o endereço que a Barion chama após cada pagamento. No OpenCart 3 ele tem a forma https://your-store/index.php?route=extension/payment/wcp_barion_gateway/callback; no OpenCart 4, https://your-store/index.php?route=extension/wcp_barion_gateway/payment/wcp_barion_gateway.callback. Ele é montado a partir do endereço público da sua instalação do OpenCart. É enviado à Barion em cada pagamento, então não há nada a configurar. Ele só precisa ser acessível pela internet.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). Ele recebe um status somente depois que a Barion informa o pagamento (pelo callback ou pelo retorno do cliente; o estado é sempre consultado na Barion). Cada campo abaixo lista os status de pedido do seu OpenCart.

Order Status After Payment: o status definido após um pagamento bem-sucedido e verificado. Padrão: Processando.

Awaiting Barion Payment Status: o cliente terminou na página da Barion, mas a Barion ainda está processando o pagamento. Padrão: Pendente.

Barion Payment On Hold Status: o pagamento foi aprovado, mas o valor ou a moeda diferem do pedido. Uma nota explica o motivo; verifique o pagamento manualmente. Padrão: Pendente, porque o OpenCart não tem o status Em espera. Você pode criar o seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

Payment Failed Status: um pedido aguardando pagamento cujo pagamento na Barion falhou. Padrão: Falhou.

Payment Canceled Status: um pedido aguardando pagamento cujo pagamento na Barion foi cancelado ou expirou. Padrão: Cancelado.

Refunded Status: definido depois que o pagamento é totalmente reembolsado pela página do pedido. Padrão: Reembolsado.

Avançado

Logging: grava as requisições e os callbacks da Barion no arquivo barion_p_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web. Chaves secretas e e-mails das carteiras não são registrados. Padrão: desligado. Enquanto estiver desligado, nada é gravado, nem mesmo erros.

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

Delete Data on Uninstall: quando ativado, desinstalar a extensão remove as configurações do gateway e o log. Os pedidos e os dados de pagamento da Barion deles são sempre mantidos. Padrão: desligado.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. Os POSKey não são exportados.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. Os POSKey salvos são mantidos.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Barion). Na etapa Confirm Order, o cliente vê a sua descrição e a nota You will be redirected to the secure Barion payment page. O OpenCart cria o pedido nessa etapa, ainda sem status. Quando o cliente clica em Confirm Order, a extensão inicia um pagamento na Barion pelo total do pedido, na moeda do pedido, e envia o cliente à página de pagamento da Barion. Os produtos, o frete, outras taxas do pedido e os impostos aparecem no pagamento; o número do pedido do OpenCart é passado como número do pedido, o e-mail do cliente é passado como referência, e o idioma da página segue o idioma do cliente quando a Barion o suporta (húngaro, alemão, francês, espanhol, tcheco, eslovaco, esloveno, grego; caso contrário, inglês). No OpenCart 4, o cliente escolhe o método de pagamento com o botão Choose do bloco do 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.

Depois de pagar, o cliente volta à sua loja, e a Barion também chama a URL de callback. Nenhuma das duas requisições marca algo como pago por si só: a extensão consulta na Barion o estado do pagamento com o POSKey do modo em que o pagamento foi iniciado. O pedido só é marcado como pago quando a Barion confirma, e somente se o valor e a moeda coincidirem com o pedido. O link de retorno contém um token aleatório da tentativa de pagamento, e somente os pagamentos iniciados para aquele pedido são verificados. Em seguida, o pedido recebe seu status da forma padrão do OpenCart, com os e-mails habituais do pedido e a atualização de estoque. No OpenCart 4, o navegador não envia a sessão da loja quando a Barion devolve o cliente, por isso a extensão primeiro mostra uma página curta que reabre o mesmo endereço de retorno a partir da sua loja: o cliente mantém o carrinho e o login.

Se o pagamento foi bem-sucedido, o cliente vê a página de sucesso do pedido do OpenCart. Se o pagamento ainda estiver em andamento na Barion, o pedido recebe o status Awaiting Barion Payment Status e a página de sucesso mostra Your payment is being confirmed by Barion. You will receive an e-mail as soon as it is confirmed. Se a Barion não puder ser acessada quando o cliente retorna, ou se o pagamento foi feito mas ainda não foi aplicado, uma página Payment confirmation mostra o mesmo texto e um botão Check again; o callback define o status do pedido assim que a Barion confirma o pagamento.

Se o pagamento não foi concluído (cancelado, expirado ou com falha), o pedido fica sem status, o carrinho é mantido e o cliente volta à finalização de compra com a mensagem Payment was not completed. Please try again. Se o link de retorno não corresponder ao pedido, a mensagem é Payment verification failed. No OpenCart 4, essas mensagens são exibidas acima da página de finalização de compra. No OpenCart 3, cada nova tentativa cria um novo pedido no OpenCart. O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza, por isso a nova tentativa é um novo pagamento na Barion do mesmo pedido. A Barion não pode cancelar um pagamento já iniciado; por isso, antes de um novo pagamento, a extensão verifica na Barion os pagamentos abertos anteriores do carrinho: se algum deles estiver pago ou ainda em processamento, o pedido correspondente é confirmado e o cliente vai para a página de sucesso sem pagar de novo. Se outro pedido do mesmo carrinho (os mesmos produtos na mesma visita) já estiver pago, o cliente também vai para a página de sucesso, sem novo pagamento; uma nova compra depois de uma concluída é um carrinho novo. Um pagamento tardio de uma tentativa anterior do mesmo pedido ainda o confirma, e uma tentativa anterior que expira não cancela o pedido. Se o cliente pagar dois pedidos de um mesmo carrinho (duas abas), o segundo pagamento não confirma o seu pedido: o pedido pago recebe uma nota informando que um segundo pagamento para o mesmo carrinho foi recebido, para que você possa reembolsá-lo no portal da Barion.

No OpenCart 4, o pedido permanece na finalização de compra até que a página de sucesso seja exibida. Se esse pedido tiver sido fechado sem pagamento nesse meio-tempo (por exemplo, se o pagamento pendente foi cancelado na Barion ou se você cancelou o pedido), o próximo Confirm Order envia o cliente de volta à finalização de compra com a mensagem Payment was not completed. Please try again., e a finalização de compra então cria um novo pedido do carrinho. Se o pedido já tiver um status e o carrinho tiver mudado desde então (outros produtos ou quantidades), o pedido sai da finalização de compra e o carrinho alterado recebe um novo pedido e o seu próprio pagamento.

Se o pagamento não puder ser iniciado, o cliente permanece na etapa Confirm Order com uma mensagem curta acima do botão: The Barion payment could not be started. Please try again or choose another payment method., Barion does not support payments in a moeda do pedido, Barion payment is not available at the moment. Please choose another payment method. ou Barion cannot process an order with a zero total. Os detalhes são gravados no log quando Logging está ativado.

A extensão aceita somente pagamentos imediatos. Não há pagamentos com reserva ou captura posterior, assinaturas ou pagamentos recorrentes, cartões salvos, Barion Pixel nem dados extras de 3-D Secure; a Barion cuida do 3-D Secure na sua própria página de pagamento.

Pedidos e reembolsos

Status dos pedidos

Sem status (pedido ausente): o cliente foi enviado à Barion e não pagou, o pagamento não foi concluído ou a Barion ainda não confirmou o pagamento. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders.

Awaiting Barion Payment Status (padrão Pending): a Barion informa que o pagamento ainda está em andamento. Uma nota mostra o PaymentId da Barion, o valor e, no modo de teste, (test mode). O pedido passa ao status de pago quando a Barion confirma o pagamento.

Order Status After Payment (padrão Processing): a Barion confirmou o pagamento. Uma nota mostra o valor, o PaymentId e a transação da Barion.

Barion Payment On Hold Status (padrão Pending): a Barion informou um valor ou uma moeda diferentes do total do pedido. A nota mostra os dois valores. Verifique o pagamento no portal da Barion e, depois, conclua o pedido ou reembolse o pagamento no portal da Barion.

Payment Canceled Status (padrão Canceled): a última tentativa de pagamento de um pedido aguardando foi cancelada ou expirou na Barion.

Payment Failed Status (padrão Failed): a última tentativa de pagamento de um pedido aguardando falhou.

Refunded Status (padrão Refunded): o pagamento foi totalmente reembolsado pela extensão.

Se um pagamento do pedido ainda for bem-sucedido depois que o pedido foi cancelado ou falhou, o pedido passa a pago. 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ê o verifique no portal da Barion e o reembolse caso seja uma duplicidade. As notas são entradas do History do pedido que o cliente não vê.

Aba VibeFox Barion Gateway

Em Sales > Orders, abra um pedido pago com a Barion. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Barion Gateway mostra o PaymentId com o rótulo Test mode para pagamentos de teste, a Transaction da Barion, o Status do pagamento, os valores Paid / refunded, o formulário de reembolso, o histórico de reembolsos e as Barion notes do pedido. A aba é mostrada aos usuários que têm acesso à extensão.

Reembolsos

Na aba VibeFox Barion Gateway, informe o valor (é preenchido o valor ainda não reembolsado), opcionalmente um Reason (optional), e clique em Refund via Barion. Confirme a pergunta Reembolsar este valor pela Barion? Isso não pode ser desfeito. Reembolsos totais e parciais são suportados. Você precisa do direito de modificar a extensão (definido em System > Users > User Groups). O motivo é enviado à Barion como comentário. Reembolsos em HUF devem ser valores inteiros. O reembolso é enviado no modo (teste ou real) em que o pagamento foi feito, por isso o POSKey desse modo precisa estar definido. Se a Barion não aceitar ou não confirmar o reembolso, a aba mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com a transação e o status da Barion. Um reembolso total define o pedido como Refunded Status sem notificar o cliente e sem devolver produtos ao estoque, como uma mudança manual de status. Um reembolso parcial não altera o status.

Os reembolsos ficam disponíveis assim que a Barion confirma o pagamento e o pedido está pago por ela. Um pagamento com diferença de valor ou moeda não pode ser reembolsado pelo OpenCart; reembolse-o no portal da Barion. Devoluções de produtos em Sales > Returns não devolvem dinheiro pela Barion.

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 Barion Gateway é o primeiro bloco de Extensions > Extensions > Payments > VibeFox Barion Gateway > 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-barion e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify sobre a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel de administração (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 domínio: o endereço da loja 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 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. Um usuário administrador conectado ao painel de administração 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 prévia não está disponível: a loja não vê o login do administrador, 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 painel de administração. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente automaticamente quando você abre o Dashboard do painel de administração ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser informada, 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 Barion não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, se o modo atual tem um POSKey e um e-mail do beneficiário (a página de configurações mostra um aviso quando algum está faltando) e se a moeda do pedido é HUF, EUR, USD ou CZK. 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: o pedido recebe o status quando a Barion chama a URL de callback ou quando o cliente volta à sua loja. Garanta que o site esteja acessível pela internet (sem firewall ou autenticação básica na frente da URL de callback). Confira se o POSKey do modo em que o pagamento foi feito está correto, pois a extensão consulta com ele o estado do pagamento na Barion. Ative Logging para ver o callback.

O callback responde Busy, retry: o pedido estava sendo processado pelo retorno do cliente no mesmo momento, ou o status do pedido não pôde ser definido. A Barion chama novamente. Ative Logging para ver o motivo.

O callback responde API error: a loja não conseguiu ler o estado do pagamento na Barion, ou o POSKey do modo em que o pagamento foi feito não está definido. Verifique esse POSKey.

O callback responde Order not found: o PaymentId não foi iniciado por esta loja. As chamadas da Barion para outras lojas ou sistemas de teste são ignoradas.

O cliente vê Payment verification failed.: o link de retorno não corresponde ao pedido, por exemplo porque foi editado. O estado do pagamento continua sendo confirmado pelo callback.

O cliente vê um erro depois de Confirm Order: ative Logging e veja o campo Log na página da extensão. Um POSKey ou e-mail do beneficiário incorreto gera The Barion payment could not be started. This payment method is not available. Please reload the checkout page. significa que a sessão de finalização de compra não corresponde mais ao pedido, ou que o método de pagamento foi desligado nesse meio-tempo: o cliente deve recarregar a finalização de compra.

O pedido está no status de retenção: leia a nota de divergência na aba VibeFox Barion Gateway, verifique o pagamento no portal da Barion e, depois, conclua o pedido ou reembolse-o no portal da Barion.

Por que não consigo reembolsar 10.50 HUF: a Barion processa HUF sem casas decimais. Informe um valor inteiro.

Não há formulário de reembolso na aba: a aba informa o motivo: o pagamento ainda não foi confirmado, está totalmente reembolsado, seu grupo de usuários não tem o direito de modificar a extensão ou o POSKey do modo do pagamento não está configurado.

Para desenvolvedores: a extensão dispara os eventos do OpenCart wcp_barion_supported_currencies (a lista de moedas) e wcp_barion_payment_request (a requisição de pagamento e o pedido, antes de serem enviados à Barion).

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Barion Gateway. 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, os seus eventos e a sua ação de inicialização, que deixa o callback passar no modo de manutenção). Se Delete Data on Uninstall estiver ativado, as demais configurações do gateway (título, descrição, modo de teste, POSKey, e-mails dos beneficiários, log) e o log são removidos. Se estiver desativado, elas são mantidas para uma reinstalação posterior. Os registros de pagamento e de reembolso da Barion são sempre mantidos, então os pedidos pagos antes podem ser reembolsados mesmo após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento.

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

A Barion é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada à Barion nem endossada por ela.