VibeFox Ozow 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.

Moeda: rand sul-africano (ZAR). O método de pagamento só é exibido para carrinhos em ZAR. A Ozow cobra em centavos inteiros, então a moeda deve usar 2 casas decimais.

Conta na Ozow: uma conta de comerciante Ozow com o Site Code e a Private Key do seu site na Ozow, obtidos no painel do comerciante Ozow. A API Key é opcional, mas recomendada. A Ozow usa o mesmo Site Code e as mesmas chaves para pagamentos de teste e reais.

Site acessível: a sua loja precisa estar acessível pela Internet, sem proteção por senha e sem firewall bloqueando a Ozow, para que as notificações da Ozow cheguem. A notificação é aceita mesmo quando a loja está em modo de manutenção.

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 Ozow Pay na lista de módulos e clique em Configure.

3. Cole 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. Insira o Site Code e a Private Key, e de preferência a API Key, obtidos no painel do comerciante Ozow.

5. Ative Enable/Disable e clique em Save. Faça um pagamento de teste com Test mode ativado e depois desative o modo de teste para aceitar pagamentos reais.

Ao ser instalado, o módulo cria dois status de pedido: Awaiting Ozow payment e Ozow 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; ali, ZAR precisa estar permitido para o módulo. Um país habilitado depois também precisa ser marcado para o módulo nesse mesmo local.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Ozow Pay > Configure. Cada seção com um botão Save salva a página inteira. Acima dos campos, a página avisa quando o Site Code ou a Private Key está faltando (a Ozow fica então oculta na finalização de compra), quando a moeda padrão da loja não é ZAR, quando a moeda tem mais de 2 casas decimais (defina 2 em International > Localization > Currencies), e exibe Test mode is on: no real payments are accepted. Do not ship orders paid in test mode. enquanto o modo de teste estiver ativado.

Ozow

Enable/Disable: Enable Ozow payments liga ou desliga o método de pagamento. Padrão: off.

Title: o nome do método de pagamento que o cliente vê na finalização de compra. Também é o nome do método de pagamento gravado no pedido. Padrão: Instant EFT (Ozow).

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay instantly and securely from your South African bank account. You will be redirected to Ozow to choose your bank and approve the payment. No modo de teste, a linha TEST MODE: no money will be charged. é acrescentada abaixo (somente quando a descrição não estiver vazia).

Credenciais da Ozow

Copie o Site Code, a Private Key e a API Key do painel do comerciante Ozow (Merchant details / Sites). A seção traz um link para a documentação de integração da Ozow em hub.ozow.com.

Site Code: o Site Code do site da Ozow que recebe os pagamentos. Respostas de outro Site Code são rejeitadas.

Private Key: assina cada solicitação de pagamento e verifica cada resposta da Ozow. Mantenha-a em sigilo. Sem ela, o método de pagamento fica oculto e nenhuma resposta da Ozow é aceita.

API Key (recommended): opcional. Com uma API Key, cada pagamento aprovado também é confirmado pela API GetTransaction da Ozow antes que o pedido seja marcado como pago. A API precisa informar que o pagamento está concluído, para este carrinho, com o mesmo valor, moeda e Site Code.

As chaves salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente para alterá-lo.

Clear saved secrets: marque Private Key ou API Key e salve para remover uma chave salva. Um campo vazio mantém o valor salvo.

Test mode: a Ozow usa o mesmo Site Code e as mesmas chaves para os testes: os pagamentos são criados com IsTest=true e nenhum dinheiro é movimentado. Pedidos pagos em modo de teste recebem uma mensagem no pedido; não os envie. Desative o modo de teste para aceitar pagamentos reais. Um pagamento de teste nunca paga um pedido em modo real. Padrão: on.

Notificações de pagamento

As URLs de notificação, sucesso, cancelamento e erro são enviadas à Ozow em cada pagamento, então nada precisa ser configurado no painel da Ozow, a menos que o seu site na Ozow esteja configurado com URLs fixas. A seção mostra as quatro URLs: Notification URL, Success URL, Cancel URL e Error URL. São links do módulo da sua loja (controladores notify e return). Se o seu site na Ozow usar URLs fixas, copie-as exatamente como as configurações as mostram.

Avançado

Debug log: registra as solicitações de pagamento e as respostas da Ozow em logs/ozow_p_debug.log.php, na pasta do módulo (não acessível pela web). Erros e avisos são sempre registrados. Chaves, hashes, tokens e dados de clientes nunca são registrados. Padrão: off.

Log: mostra o tamanho atual e o final do log, com um botão Clear log.

Delete data on uninstall: remove as configurações e os logs deste módulo quando ele é desinstalado (os dados da Ozow salvos nos pedidos são mantidos). Padrão: off.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Instant EFT (Ozow)) e confirma o pedido. O módulo envia o cliente à página de pagamento hospedada pela Ozow com uma solicitação assinada do total do carrinho em ZAR. A referência no extrato bancário é Cart e o número do carrinho (até 20 letras latinas, dígitos, espaços e traços). O nome do cliente é passado à Ozow. Nesse momento ainda não existe nenhum pedido. Na página da Ozow, o cliente escolhe um banco sul-africano e aprova o pagamento no aplicativo do banco.

Em seguida, a Ozow notifica a loja e devolve o cliente. As duas comunicações trazem a mesma resposta assinada e são processadas da mesma forma, então o pedido é criado mesmo que uma delas se perca. O pedido só é marcado como pago depois que a Ozow confirma: o hash precisa ser verificado com a sua Private Key, o Site Code precisa ser o seu, a resposta precisa pertencer a esta tentativa de pagamento do carrinho, e o valor e a moeda precisam coincidir com o carrinho. Com uma API Key, o pagamento também é verificado pela API GetTransaction.

Depois de um pagamento bem-sucedido, o cliente vê a página padrão de confirmação do pedido. Se a Ozow ou o banco ainda estiver analisando o pagamento, a página diz We are waiting for Ozow to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Se o pedido estiver em espera, diz Your Ozow payment was received and is being reviewed by the store. We will contact you if anything is needed. Se um pagamento analisado falhar depois ou o pedido não pago for cancelado, diz Your Ozow payment was not completed. Please contact us about this order. Se a Ozow ainda não tiver confirmado o pagamento quando o cliente voltar, uma página mostra o texto de espera com os botões Check again e Back to checkout.

Se o cliente cancelar na página da Ozow ou o pagamento falhar, nenhum pedido é criado. O cliente volta à finalização de compra com o mesmo carrinho e vê The Ozow payment was cancelled. You can try again or choose another payment method. ou The Ozow payment was not completed. You can try again or choose another payment method.

Se o carrinho não estiver em ZAR, o cliente vê Ozow accepts payments in South African rand (ZAR) only. Please choose another payment method.

O módulo aceita somente pagamentos únicos em ZAR. Não há reembolsos pelo PrestaShop, nem assinaturas, nem contas bancárias salvas ou tokenização, nem envio de links de pagamento pelo back office.

Pedidos e reembolsos

Status do pedido

Ainda sem pedido: o cliente foi enviado à Ozow e não pagou, cancelou, ou a Ozow ainda não confirmou o pagamento. Só existe o carrinho.

Payment accepted: o pagamento foi confirmado. A mensagem do pedido mostra o valor e o ID da transação Ozow, e se o pagamento foi confirmado pela API GetTransaction. O ID da transação do pagamento do pedido é o TransactionId da Ozow. Um pagamento de teste recebe a mensagem TEST MODE — no money was received, do not ship this order.

Awaiting Ozow payment: a Ozow ou o banco está analisando o pagamento. O pedido é atualizado quando a Ozow envia o status final.

Ozow payment on hold: a mensagem do pedido informa o motivo: o valor ou a moeda pagos são diferentes do carrinho; chegou um pagamento para um pedido que já havia sido cancelado; ou, com uma API Key, a API GetTransaction ainda não conseguiu confirmar o pagamento ou o contradiz. Verifique o pagamento no seu painel da Ozow e altere o status do pedido. Se a API não tiver conseguido responder, a próxima notificação da Ozow conclui o pedido.

Erro de pagamento: um pagamento que estava em análise foi cancelado, abandonado ou falhou. Uma resposta bem-sucedida posterior da Ozow para ele ainda marca o pedido como pago.

Um pedido já pago nunca é revertido, e um pedido cancelado ou reembolsado nunca é reaberto. Se chegar um segundo pagamento para um pedido já pago, uma mensagem pede que você reembolse o duplicado no seu painel da Ozow. Se um pedido estiver em espera por outro motivo, por exemplo definido por você, um pagamento posterior apenas acrescenta uma mensagem, e você define o pedido como Payment accepted manualmente.

Bloco de pagamento da Ozow

A página do pedido mostra um bloco Ozow payment com a referência e a tentativa da transação, o ID da transação Ozow, o status, o valor solicitado, o valor informado pela Ozow, a mensagem da Ozow e a marca TEST MODE nos pagamentos de teste.

Reembolsos

Reembolsos pelo PrestaShop não são suportados. Reembolse o pagamento no seu painel de comerciante Ozow e, em seguida, registre o reembolso no PrestaShop manualmente.

Chave de licença

O módulo funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença License — VibeFox Ozow Pay é o primeiro bloco de Modules > Module Manager > VibeFox Ozow Pay > 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-payment-ozow e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente funcionários com a permissão Configure do 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 domínio: o domínio da loja principal, também em uma configuração multiloja. 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 Ozow 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.

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 inserida e, depois, uma vez por semana. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.

Solução de problemas

A Ozow não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, se o Site Code e a Private Key estão preenchidos e se a moeda do carrinho é ZAR. Em Payment > Preferences, verifique se o módulo está permitido para ZAR, para o país do cliente e para o grupo do cliente. A página de configurações mostra um aviso quando algo está faltando.

O pagamento foi aprovado, mas nenhum pedido foi criado: a notificação da Ozow não chegou à loja e o cliente não voltou. Verifique se a sua loja está acessível pela Internet (sem proteção por senha e sem firewall bloqueando a Ozow). Se o seu site na Ozow estiver configurado com URLs fixas, verifique se elas são exatamente as exibidas em Payment notifications. Ative o Debug log e leia o log na página Configure.

A notificação responde Invalid hash: a Private Key nas configurações não pertence ao site da Ozow que enviou a resposta. Copie-a novamente do painel do comerciante Ozow. Nada é alterado.

A notificação responde Unknown site: a resposta veio de outro site da Ozow. Verifique o Site Code.

A notificação responde Order mismatch ou Order not found: a resposta não pertence a um pagamento iniciado nesta loja. Nada é alterado.

A notificação responde Gateway not configured: o Site Code ou a Private Key está faltando. Preencha-os; a Ozow pode tentar novamente.

A notificação responde Payment not confirmed yet: a resposta ainda não pôde ser aplicada. Com uma API Key, a API GetTransaction não conseguiu confirmar o pagamento (o pedido fica em espera e a próxima notificação o conclui; se continuar em espera, verifique a API Key e o pagamento no seu painel da Ozow). Esta também é a resposta quando o retorno do cliente estava sendo processado para o mesmo carrinho no mesmo momento, ou quando o pedido não pôde ser criado; consulte o log.

Um pagamento de teste não pagou o pedido: o módulo está em modo real. Pagamentos de teste nunca pagam um pedido em modo real; a mensagem do pedido ou o log informa isso.

O pedido está em Ozow payment on hold após o pagamento: leia a mensagem do pedido e verifique o pagamento no seu painel da Ozow; depois, defina o pedido como Payment accepted ou reembolse o pagamento na Ozow.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Ozow Pay 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 ativado, as configurações do módulo e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os registros de pagamentos da Ozow e os status de pedido Awaiting Ozow payment e Ozow payment on hold são sempre mantidos, para que notificações atrasadas de pedidos antigos continuem sendo reconhecidas após uma reinstalação. Os pedidos existentes mantêm suas mensagens de pagamento e IDs de transação.

A Ozow é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Ozow.