VibeFox Ozow for WooCommerce — Ajuda

Requisitos

WordPress: 6.2 ou superior.

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

PHP: 8.0 ou superior.

Moeda: rand sul-africano (ZAR). O método de pagamento fica oculto para outras moedas. A Ozow cobra centavos inteiros, por isso o WooCommerce deve usar 2 casas decimais.

Conta Ozow: uma conta de comerciante Ozow com o Site Code e a Private Key do seu site 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: o seu site precisa estar acessível pela Internet, sem modo de manutenção, sem proteção por senha e sem firewall bloqueando a Ozow, para que as notificações da Ozow cheguem.

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

Instalação

1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_ozow_pay para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > Ozow > 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 o Site Code e a Private Key e, de preferência, a API Key, obtidos no painel do comerciante Ozow.

6. Ative o Enable/Disable. Faça um pagamento de teste com o Test mode ativado e depois desative o modo de teste para receber pagamentos reais.

Configuração

Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Ozow. Acima dos campos, a página avisa quando o Site Code ou a Private Key está ausente (a Ozow fica oculta no checkout), quando a moeda da loja não é ZAR e quando o WooCommerce usa mais de 2 casas decimais, e mostra Test mode is on: no real payments are accepted. Do not ship orders paid in test mode. enquanto o modo de teste estiver ativado. Na lista de métodos de pagamento, a Ozow aparece como precisando de configuração até que o Site Code e a Private Key sejam preenchidos.

Geral

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

Title: o nome do método de pagamento que o cliente vê no checkout. Padrão: Instant EFT (Ozow).

Description: o texto exibido abaixo do método de pagamento no checkout. 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. é adicionada abaixo dele.

Credenciais 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 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 foi concluído, para este pedido, com o mesmo valor, a mesma moeda e o mesmo Site Code.

Test mode: Enable Ozow 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 nota no pedido; não os envie. Desative o modo de teste para receber pagamentos reais. Um pagamento de teste nunca paga um pedido no modo real. Padrão: ativado.

Notificações de pagamento

As URLs de notificação, de sucesso, de cancelamento e de erro são enviadas à Ozow em todo pagamento, então não é preciso configurar nada no painel da Ozow, a menos que o seu site na Ozow esteja configurado com URLs fixas. A seção mostra a URL de notificação. Ela tem este formato: https://your-site/wc-api/ozow_pay/?ozow_notify=1. Se o seu site na Ozow usar URLs fixas, copie-a exatamente como as configurações a mostram.

Avançado

Debug log: Log payment requests and Ozow responses grava os detalhes em WooCommerce > Status > Logs, origem wcp_ozow_pay. Erros e avisos são sempre registrados. Chaves, hashes e dados de clientes nunca são registrados. Padrão: desativado.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Ozow data saved on orders is kept). Padrão: desativado.

Checkout

O cliente escolhe o método de pagamento (por padrão Instant EFT (Ozow)) e faz o pedido. O plugin envia o cliente para a página de pagamento hospedada pela Ozow com uma solicitação assinada do total do pedido em ZAR. A referência no extrato bancário é Order seguida do número do pedido (até 20 letras latinas, algarismos, espaços e hífens). O nome do cliente é passado à Ozow. 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. Os dois trazem a mesma resposta assinada e são processados da mesma forma, então o pedido é atualizado mesmo quando um deles se perde. 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 trazer a chave deste pedido, e o valor e a moeda precisam coincidir com o pedido. Com uma API Key, o pagamento também é conferido pela API GetTransaction.

Após um pagamento aprovado, o cliente chega à página de pedido recebido. Se a Ozow ainda não tiver confirmado 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 o cliente cancelar na página da Ozow ou o pagamento falhar, o pedido passa para Falhou e o cliente volta à página Pay for order com 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. O cliente pode pagar o mesmo pedido novamente.

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 (somente para pedidos em ZAR). É compatível com o WooCommerce High-Performance Order Storage (HPOS).

O plugin aceita somente pagamentos únicos em ZAR. Não há reembolsos pelo WooCommerce, assinaturas, contas bancárias salvas ou tokenização, nem envio de links de pagamento pelo administrador.

Pedidos

Status do pedido

Pending payment: o cliente foi enviado à Ozow e ainda não pagou, ou a Ozow ainda não confirmou o pagamento.

Processing: o pagamento foi confirmado. Este é o status padrão do WooCommerce após o pagamento; pedidos com apenas produtos virtuais para download passam para Concluído. A nota do pedido mostra o valor e o ID da transação na Ozow, e se o pagamento foi confirmado pela API GetTransaction. O ID da transação do pedido é o TransactionId da Ozow. Um pagamento de teste recebe a nota TEST MODE — no money was received, do not ship this order.

On hold: a nota do pedido explica o motivo. A Ozow ou o banco está analisando o pagamento (o pedido é atualizado quando a Ozow envia o status final); o valor ou a moeda pagos diferem do pedido; 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. Confira o pagamento no seu painel da Ozow e altere o status do pedido. Se a API não conseguiu responder, a próxima notificação da Ozow conclui o pedido.

Failed: o cliente cancelou o pagamento, o pagamento foi abandonado ou a Ozow informou um erro. O cliente pode pagar novamente pelo pedido.

Um pedido já pago nunca volta atrás, e um pedido cancelado ou reembolsado nunca é reaberto. Se chegar um segundo pagamento para um pedido já pago, uma nota pede que você reembolse a duplicata no seu painel da Ozow. Se um pedido estiver em espera por outro motivo, por exemplo definido por você, um pagamento posterior apenas adiciona uma nota e você mesmo define o pedido como Processing.

Reembolsos

Reembolsos pelo WooCommerce não são suportados. Reembolse o pagamento no painel do comerciante Ozow e registre o reembolso manualmente no 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 > Ozow. 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 Ozow não é exibida aos clientes no checkout. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. Os gerentes da loja conectados ainda veem o método de pagamento, marcado com (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. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados.

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

Solução de problemas

A Ozow não aparece no checkout: verifique se a licença está ativa, se o Enable/Disable está ativado, se o Site Code e a Private Key estão preenchidos e se a moeda da loja ou do pedido é ZAR. A página de configurações mostra um aviso quando algo está faltando.

O pagamento foi feito, mas o pedido continua em Pending payment: a notificação da Ozow não chegou à loja e o cliente não voltou. Verifique se o seu site está acessível pela Internet (sem modo de manutenção, proteção por senha ou firewall bloqueando a Ozow). Se o seu site na Ozow usar URLs fixas, confirme que a URL de notificação é exatamente a exibida nas configurações. Ative o Debug log e consulte WooCommerce > Status > Logs, origem wcp_ozow_pay.

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

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

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

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

A notificação responde Order busy: outra resposta da Ozow para o mesmo pedido estava sendo processada naquele mesmo momento. A resposta não é aplicada; a próxima notificação ou o retorno do cliente a aplicará.

A notificação responde Payment not confirmed yet: 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 concluirá. Se continuar em espera, verifique a API Key e o pagamento no seu painel da Ozow.

O cliente vê Ozow accepts payments in South African rand (ZAR) only: o pedido está em outra moeda. A Ozow não pode ser usada para ele.

Um pagamento de teste não pagou o pedido: o gateway está no modo real. Pagamentos de teste nunca pagam um pedido no modo real; uma nota no pedido informa isso.

O pedido está On hold após o pagamento: leia a nota do pedido e confira o pagamento no seu painel da Ozow; depois, defina o pedido como Processing ou reembolse o pagamento na Ozow.

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, as demais opções do plugin e os seus logs só são removidos se Delete data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação posterior. Os pedidos existentes mantêm as suas notas de pagamento e IDs de transação.

Ozow é uma marca registrada de seu respectivo titular. Este plugin não é afiliado à Ozow nem endossado por ela.