VibeFox Barion for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões anteriores do PHP.
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. As credenciais de teste e de produção são diferentes.
Moeda: a moeda do carrinho 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, então o site precisa estar acessível pela internet, sem firewall ou autenticação básica na frente.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.
Instalação
1. No back office, vá em 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 Barion Gateway na lista de módulos e clique em Configure.
3. Informe a sua chave de licença VibeFox em License key, no bloco de licença no topo da página Configure, e clique em Activate (veja Chave de licença).
4. Informe a POSKey de teste e o e-mail da carteira de teste, deixe Test Mode ligado, ative Enable/Disable e clique em Save. Faça um pedido de teste.
5. Quando tudo estiver funcionando, informe as credenciais de produção e desligue o Test Mode.
A URL de callback é enviada à Barion automaticamente com cada pagamento. Não é preciso configurar nada no portal da Barion.
Ao ser instalado, o módulo cria dois status de pedido, Awaiting Barion payment e Barion payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Barion Gateway > 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 o modo atual não tem POSKey ou e-mail do beneficiário (o método de pagamento fica então 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 ligado, ela mostra O modo de teste está ativo: os pagamentos vão para o sandbox da Barion (api.test.barion.com), nenhum valor real é cobrado.
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.
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, a sua loja. O modo de teste usa somente as credenciais de teste; o modo de produção, somente as de produção.
Test Mode: usa as credenciais de teste informadas abaixo e o sandbox da Barion (api.test.barion.com). Nenhum valor real é cobrado. Padrão: ligado. Desligue para receber pagamentos reais. Enquanto estiver ligado, os clientes veem Modo de teste: nenhum pagamento real é efetuado. abaixo do método de pagamento.
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.
As POSKeys salvas nunca são exibidas novamente. O campo fica vazio e mostra Salva — deixe em branco para mantê-la. Informe um novo valor somente se quiser alterá-la.
Clear saved POSKeys: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Callback URL: o endereço que a Barion chama após cada pagamento, por exemplo https://your-shop/module/wcp_barion_gateway/callback com URLs amigáveis, possivelmente com um código de idioma como /en/. Ele é enviado à Barion com cada pagamento, então não há nada a configurar. Ele só precisa estar acessível pela internet.
Pedidos
Order Status After Payment: o status do pedido definido após um pagamento bem-sucedido e verificado.
Pagamentos que a Barion ainda está processando aguardam em Awaiting Barion payment. Divergências de valor ou moeda sempre vão para Barion payment on hold.
Avançado
Logging: grava as requisições e os callbacks da Barion em logs/barion_p_debug.log.php, na pasta do módulo. 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 ligado, desinstalar o módulo remove as configurações do módulo e o log. Os pedidos, os seus dados de pagamento da Barion e os status de 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 Barion) e vê a nota Você será redirecionado para a página de pagamento segura da Barion. Após a confirmação, o módulo inicia um pagamento Barion pelo total do carrinho, na moeda do carrinho, e envia o cliente à página de pagamento da Barion. Os produtos, o frete, a embalagem para presente e o imposto são listados no pagamento, que aparece como Cart com o número do carrinho; o e-mail do cliente é passado como sugestão, e o idioma da página acompanha o idioma do carrinho quando a Barion o suporta. Nesse ponto, ainda não existe nenhum pedido.
Após 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ó: o módulo pede à Barion o status do pagamento com a POSKey do modo em que ele foi iniciado. O pedido só é marcado como pago depois que a Barion confirma, e somente se o valor e a moeda coincidirem com o carrinho. O link de retorno contém a chave segura do carrinho, e somente os pagamentos iniciados para esse carrinho são verificados.
Se o pagamento foi bem-sucedido, o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Seu pagamento com a Barion foi recebido. Se o pagamento ainda está em andamento na Barion, o pedido é criado em Awaiting Barion payment e a página mostra Seu pagamento está sendo confirmado pela Barion. Você receberá um e-mail assim que ele for confirmado. Se esse pagamento for depois cancelado, expirar ou falhar na Barion, a página mostra Seu pagamento na Barion não foi concluído. Entre em contato conosco sobre este pedido. Se a Barion não puder ser acessada quando o cliente voltar, uma página Confirmação do pagamento mostra o mesmo texto de «sendo confirmado» e um botão Check again; o callback cria o pedido assim que a Barion confirma o pagamento.
Se o pagamento não foi concluído (cancelado, expirado ou falhou), nenhum pedido é criado, o carrinho é mantido e o cliente volta à finalização de compra com O pagamento não foi concluído. Tente novamente. O cliente pode tentar de novo. Cada tentativa é registrada, então um pagamento tardio de uma tentativa anterior ainda cria o pedido, e uma tentativa anterior que expira não cancela um pedido de uma tentativa mais recente.
Se o pagamento não puder ser iniciado, o cliente permanece na finalização de compra com uma mensagem curta: Não foi possível iniciar o pagamento na Barion. Tente novamente ou escolha outro método de pagamento., A Barion não aceita pagamentos em a moeda do carrinho, ou A Barion não pode processar um pedido com valor total zero. Os detalhes são gravados no log quando o Logging está ligado.
O callback funciona com a loja em modo de manutenção e não é bloqueado pela restrição de países da sua loja.
O módulo aceita somente pagamentos imediatos. Não tem pagamentos com reserva ou captura posterior, assinaturas ou pagamentos recorrentes, cartões salvos, Barion Pixel nem dados adicionais de 3-D Secure; a Barion cuida do 3-D Secure na página de pagamento dela.
Pedidos e reembolsos
Status do pedido
No order yet: o cliente foi enviado à Barion e não pagou, ou a Barion ainda não confirmou o pagamento. Existe apenas o carrinho.
Awaiting Barion payment: a Barion informa que o pagamento ainda está em andamento. Uma nota mostra o PaymentId da Barion, o valor e, em modo de teste, (test mode). O pedido passa para «Pagamento aceito» quando a Barion confirma o pagamento.
Payment accepted or Delivered: a Barion confirmou o pagamento. O status segue Order Status After Payment. O pagamento é registrado com o ID da transação da Barion, e uma nota mostra o valor, o PaymentId e a transação.
Barion payment on hold: a Barion informou um valor ou moeda diferente do total do pedido, por exemplo porque o carrinho foi alterado depois que o pagamento foi iniciado. A nota mostra os dois valores. Verifique o pagamento no portal da Barion e, em seguida, atenda o pedido ou reembolse o pagamento no portal da Barion.
Canceled: a última tentativa de pagamento de um pedido aguardando foi cancelada ou expirou na Barion.
Payment error: a última tentativa de pagamento de um pedido aguardando falhou.
Refunded: o pagamento foi totalmente reembolsado pelo módulo.
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 pago, uma nota pede que você o verifique no portal da Barion e o reembolse se for duplicado. As notas são mensagens privadas na página do pedido.
Bloco de pagamento da Barion
A página do pedido mostra um bloco Barion payment com o PaymentId, a transação da Barion, o status do pagamento, o valor pago e reembolsado, um selo Test mode para pagamentos de teste e o histórico de reembolsos.
Reembolsos
No bloco Barion payment, informe o valor (o valor ainda não reembolsado vem preenchido), opcionalmente um motivo, e clique em Refund via Barion. Confirme a pergunta Reembolsar este valor pela Barion? Esta ação não pode ser desfeita. São suportados reembolsos totais e parciais. Você precisa ter permissão para editar pedidos. O motivo é enviado à Barion como comentário. Reembolsos em HUF devem ser valores inteiros. O reembolso é enviado no modo (teste ou produção) em que o pagamento foi feito, então a POSKey desse modo precisa estar preenchida. Se a Barion não aceitar ou não confirmar o reembolso, o bloco 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 coloca o pedido em Refunded. Um reembolso parcial não altera o status.
Os reembolsos estão disponíveis quando a Barion confirmou o pagamento e o pedido foi pago por ela. Um pagamento com divergência de valor ou moeda não pode ser reembolsado pelo PrestaShop; reembolse-o no portal da Barion. O módulo não cria notas de crédito, e os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Barion.
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 Barion Gateway é o primeiro bloco em Modules > Module Manager > VibeFox Barion Gateway > Configure, 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: presta-payment-barion e o link Manage licenses and domains in your account, que abre a sua conta na vibefox.net. Apenas 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 Key not found, This key belongs to another product, Domain limit reached ou License expired on 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 puder ser acessado, o módulo continua funcionando com o último status conhecido.
Uma chave funciona em um único domínio: o domínio da loja principal, inclusive em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta da vibefox.net.
Sem uma chave ativa, a Barion 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. A vitrine do PrestaShop não sabe que você está conectado ao back office, então o método de pagamento também fica oculto para você: 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: pagamentos já iniciados continuam sendo confirmados e os reembolsos funcionam.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser informada, 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 Barion não aparece na finalização de compra: verifique se a licença está ativa, se o Enable/Disable está ligado, se o modo atual tem POSKey e e-mail do beneficiário (a página de configurações mostra um aviso quando um deles falta) e se a moeda do carrinho é HUF, EUR, USD ou CZK. Em Payment > Preferences, verifique se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente.
O pagamento foi feito, mas nenhum pedido foi criado: o pedido é criado quando a Barion chama a URL de callback ou quando o cliente volta à sua loja. Certifique-se de que o site está acessível pela internet (sem firewall ou autenticação básica na frente da URL de callback). Verifique se a POSKey do modo em que o pagamento foi feito está correta, pois o módulo a usa para pedir à Barion o status do pagamento. Ative o Logging para ver o callback.
O callback responde Busy, retry: o pedido estava sendo processado pelo retorno do cliente no mesmo momento, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A Barion chama novamente. Ative o Logging para ver o motivo.
O callback responde API error: a loja não conseguiu ler o status do pagamento na Barion, ou a POSKey do modo em que o pagamento foi feito não está definida. Verifique essa 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ê «Falha na verificação do pagamento»: o link de retorno não corresponde ao carrinho, por exemplo porque foi aberto em outra sessão do navegador ou foi editado. O status do pagamento continua sendo confirmado pelo callback.
O cliente vê um erro ao escolher a Barion: ative o Logging e veja o campo Log na página do módulo. Uma POSKey ou e-mail do beneficiário incorreto gera Não foi possível iniciar o pagamento na Barion.
O pedido está em Barion payment on hold: leia a nota de divergência no pedido, verifique o pagamento no portal da Barion e, em seguida, atenda 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.
O reembolso diz que a POSKey da Barion para o modo deste pedido não está configurada: o pagamento foi feito em modo de teste ou de produção, e a POSKey desse modo está vazia. Informe-a e tente novamente.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Barion Gateway 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 log são removidos. Se estiver desligado, todas as configurações são mantidas para uma reinstalação posterior. Os dados de pagamento da Barion dos pedidos e os status de pedido Awaiting Barion payment e Barion payment on hold são sempre mantidos, para que pedidos pagos antes ainda possam ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Barion é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Barion.