VibeFox Yoco 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 da loja: rand sul-africano (ZAR). A Yoco aceita somente ZAR. Em qualquer outra moeda, o método de pagamento fica oculto na finalização de compra. O total do pedido deve ser de pelo menos R2,00.
Conta na Yoco: uma conta na Yoco com pagamentos online. Você precisa das chaves secretas dela, que estão no Yoco Business Portal em Selling Online > Payment Gateway. Só as chaves secretas são digitadas. O webhook é registrado pelo plugin, e o segredo de assinatura é preenchido para você.
Site público: a Yoco envia webhooks para o seu site, por isso ele precisa estar acessível pela internet. A URL do webhook deve aceitar um POST sem redirecionamentos.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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_yoco_pay para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Yoco > Manage.
4. Digite a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Cole a chave secreta de teste (sk_test_...) e, quando estiver pronto, a chave secreta de produção (sk_live_...). Salve as configurações. O webhook é registrado para cada modo que tiver uma chave.
6. Ative Enable/Disable. Faça um pagamento de teste com um cartão de teste da Yoco enquanto Test mode estiver ativo e, depois, desmarque Test mode para receber pagamentos reais.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Yoco. Acima dos campos, a página avisa quando a moeda da loja não é ZAR (nesse caso a Yoco não é oferecida na finalização de compra) e quando o modo atual não tem chave secreta. Na lista de métodos de pagamento, a Yoco aparece como pendente de configuração até que o modo atual tenha uma chave secreta. Ao salvar, o plugin verifica as chaves e os segredos dos webhooks e registra os webhooks. Mensagens sobre isso aparecem no topo da página.
Geral
Enable/Disable: Enable Yoco 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. Padrão: Card or Instant EFT (Yoco).
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: You will be redirected to the secure Yoco page to pay by card or Instant EFT.
Chaves de API
Copie as chaves secretas no Yoco Business Portal, em Selling Online > Payment Gateway. A Yoco tem uma única API para os dois modos: é a chave que define se um pagamento é de teste ou real. O modo de teste usa somente a chave de teste; o modo de produção usa somente a chave de produção.
Test mode: Use the test secret key (no real payments). Nenhum dinheiro real é cobrado; pague com cartões de teste da Yoco. Padrão: on. Desmarque para receber pagamentos reais.
Test secret key: a chave secreta do modo de teste. Começa com sk_test_.
Live secret key: a chave secreta do modo de produção. Começa com sk_live_.
Uma chave que não começa com o prefixo esperado não é salva: a página mostra um erro e mantém o valor anterior. Se a Yoco informar, durante o registro do webhook, que uma chave pertence ao outro modo, a página avisa você.
Webhooks
A Yoco confirma pagamentos e reembolsos na URL do webhook exibida nesta seção. Ela tem este formato: https://your-site/wc-api/yoco_pay_webhook/. Você não precisa criar o webhook no portal da Yoco. Ao salvar as configurações, o plugin registra a URL na Yoco para cada modo que tenha uma chave secreta, mas não tenha um segredo de webhook, e armazena o segredo de assinatura no campo desse modo. Ele registra a URL de novo quando a chave secreta desse modo ou a URL do webhook muda. Quando a URL muda, o registro antigo é removido.
Para cada modo, a seção mostra o estado do webhook:
O plugin trata estes eventos:
Webhooks sem assinatura válida são recusados. Se o seu site usa prefixo de idioma nas URLs, mantenha a URL exatamente como as configurações a mostram, pois o webhook precisa chegar à loja sem redirecionamento.
Test webhook secret: preenchido automaticamente quando o webhook é registrado. Cole um segredo (whsec_...) somente se você mesmo tiver registrado a URL do webhook.
Live webhook secret: preenchido automaticamente quando o webhook é registrado. Limpe o campo e salve para registrar o webhook de novo.
Um segredo de webhook deve ter a forma whsec_ seguida de texto em base64. Qualquer outro valor não é salvo, e o anterior é mantido.
Avançado
Debug log: Log Yoco requests and webhooks grava requisições e webhooks em WooCommerce > Status > Logs, origem wcp_yoco_pay. Erros e avisos, como requisições falhas à Yoco e webhooks recusados, são sempre registrados. Chaves, segredos de webhook e e-mails são mascarados. Padrão: off.
Delete data: Delete the settings and logs of this plugin when it is deleted. Desativar o plugin nunca apaga nada. Os dados dos pedidos (IDs do checkout e do pagamento na Yoco) são sempre mantidos, porque são necessários para os reembolsos. Padrão: off.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, Card or Instant EFT (Yoco)) e faz o pedido. No modo de teste, a finalização de compra mostra Test mode — use a Yoco test card; no real money is charged. O plugin cria um checkout da Yoco pelo total do pedido em centavos e envia o cliente à página de pagamento da Yoco, onde ele paga com cartão ou Instant EFT.
Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que a Yoco confirma: o plugin consulta o checkout na Yoco quando o cliente volta e de novo quando o webhook assinado chega. Se a Yoco ainda não tiver confirmado o pagamento, a página de pedido recebido mostra We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again.
Se o cliente cancelar na página da Yoco, o pedido continua sem pagamento e ele chega à página Pay for order com a mensagem The Yoco payment was cancelled. Your order is saved — you can pay again below or choose another payment method. Se o pagamento falhar, a mensagem é The Yoco payment was not successful. Please try again or choose another payment method. e uma nota é adicionada ao pedido.
O cliente pode pagar de novo um pedido não pago pela página Pay for order. Antes de uma nova tentativa, o plugin verifica a anterior na Yoco. Se ela já foi paga, o pedido é concluído sem mostrar uma nova página de pagamento. Se ainda estiver aberta pelo mesmo valor e tiver sido criada há menos de 30 minutos, o cliente recebe de novo a mesma página da Yoco.
Se a Yoco não conseguir iniciar o pagamento, o cliente vê Yoco could not start the payment. Please try again in a moment or choose another payment method. e o motivo é adicionado às notas do pedido. Um pedido abaixo de R2,00 recebe Yoco requires an order total of at least R2.00.
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. Ele é compatível com o WooCommerce High-Performance Order Storage (HPOS).
Os pagamentos são cobrados imediatamente na página da Yoco. O plugin não tem cartões salvos, assinaturas ou pagamentos recorrentes, nem formulário de cartão no site, nem autorização e captura separadas, e não funciona em moedas diferentes de ZAR.
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado à Yoco e ainda não pagou, cancelou na página da Yoco ou a Yoco ainda não confirmou o pagamento.
Processing or Completed: o pagamento foi confirmado. O WooCommerce define Em andamento, ou Concluído para pedidos com apenas produtos digitais para download. A nota do pedido mostra o valor, os IDs do pagamento e do checkout na Yoco, o modo e como o pagamento foi confirmado (retorno do cliente, webhook ou verificação antes de uma nova tentativa de pagamento). O ID da transação é o ID do pagamento na Yoco.
On hold: a Yoco informou um valor ou uma moeda diferentes do total do pedido, por exemplo porque o pedido foi editado depois que o pagamento começou. A nota explica isso, e o cliente que volta da Yoco vê We received your payment and are reviewing it. We will contact you if anything else is needed. Confira o pagamento antes do envio.
Cancelled or Refunded: um pagamento que chega para um pedido assim não altera o pedido. Uma nota pede que você reembolse o pagamento no portal da Yoco ou restaure o pedido manualmente. O cliente que volta da Yoco vê Your payment was received after the order had been cancelled. Please contact us — do not pay again.
Se chegar um segundo pagamento para um pedido que já está pago, o pedido não é alterado de novo. Uma nota pede que você o reembolse no portal da Yoco.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique no botão Refund via com o título do seu método de pagamento (por padrão, Card or Instant EFT (Yoco)). São aceitos reembolsos totais e parciais. O reembolso é enviado no modo em que o pagamento foi feito (teste ou produção), então a chave secreta desse modo precisa estar configurada. Um reembolso repetido após uma resposta perdida não é pago duas vezes.
Um reembolso bem-sucedido é adicionado às notas do pedido com o ID do reembolso na Yoco. Se a Yoco recusar o reembolso, o WooCommerce mostra Yoco refused the refund: com o motivo, e nenhum reembolso é registrado. Se a Yoco informar que o reembolso está pendente, o WooCommerce mostra que ele ainda está pendente e não registra nada. Não repita: ele será adicionado ao pedido quando a Yoco confirmar por webhook.
Os reembolsos feitos no portal da Yoco chegam pelo webhook refund.succeeded e são registrados automaticamente como reembolsos do WooCommerce, sem devolver itens ao estoque. Um reembolso maior que o valor ainda disponível para reembolso não é registrado, e uma nota pede que você verifique o pedido. Um reembolso que falha adiciona uma nota dizendo que o dinheiro não foi devolvido ao cliente.
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 > Yoco. 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 de novo, 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 na vibefox.net.
Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta na vibefox.net.
Sem uma chave ativa, a Yoco não é mostrada aos clientes na finalização de compra. Se um pagamento for iniciado assim mesmo, o cliente vê This payment method is not available. Please choose another one. Os gerentes da loja conectados continuam vendo 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. 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 exigem renovação. O status é verificado de novo automaticamente em segundo plano.
Solução de problemas
A Yoco não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se o modo atual tem uma chave secreta: Test secret key no modo de teste, Live secret key no modo de produção. A moeda da loja ou do pedido deve ser ZAR, e o total do pedido deve ser de pelo menos R2,00. A página de configurações mostra um aviso quando a chave está faltando ou a moeda não é ZAR.
O pagamento foi feito, mas o pedido continua em Pending payment: o webhook não está funcionando. Abra a seção Webhooks das configurações e verifique o estado do modo que você usa. Se ele não estiver registrado, ou estiver registrado para outra URL, salve as configurações. Se o registro falhar, a página mostra o motivo. Se você digitou o segredo, confira se ele pertence ao webhook desta URL e deste modo. O pedido também é confirmado quando o cliente volta para a loja após pagar e quando tenta pagar de novo.
Não foi possível registrar o webhook: os pagamentos continuam sendo confirmados quando os clientes voltam para a loja. Corrija o motivo mostrado na mensagem, por exemplo: o site precisa estar acessível pela internet por HTTPS, e salve novamente. Você também pode registrar a URL você mesmo e colar o segredo de assinatura.
Os webhooks são recusados: os webhooks recusados são gravados no log, origem wcp_yoco_pay. webhook secret not configured significa que nenhum segredo de webhook está definido. invalid signature significa que o segredo pertence a outro registro ou modo. timestamp outside the tolerance significa que o relógio do servidor está errado: as assinaturas são aceitas dentro de 5 minutos do horário do servidor. checkout not completed yet — retry e could not confirm the checkout with Yoco — retry são temporários; a Yoco envia o webhook de novo.
The secret key must start with sk_test_ / sk_live_ error on save: uma chave foi colada no campo errado. A chave de teste começa com sk_test_, e a de produção, com sk_live_. O valor anterior foi mantido.
O cliente vê um erro ao fazer o pedido: leia as notas do pedido ou WooCommerce > Status > Logs, origem wcp_yoco_pay. Yoco is not available at the moment. Please choose another payment method. significa que o modo atual não tem chave secreta.
Ao cliente é informado que um pagamento precisa ser analisado: uma tentativa anterior foi paga com outro valor, ou depois que o pedido foi cancelado. Leia a nota do pedido e conclua o pedido ou reembolse o pagamento no portal da Yoco.
O reembolso falha com uma mensagem sobre o modo: o pagamento foi feito em modo de teste ou de produção, e a chave secreta desse modo não está definida. Digite-a e tente de novo.
O reembolso falha com No answer from Yoco: nada foi registrado no WooCommerce. Se a Yoco processou o reembolso, repita o mesmo reembolso: ele não será reembolsado duas vezes.
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 na 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 estiver acessível, 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, os registros de webhooks na Yoco e os logs, incluindo os arquivos de log rotacionados, são removidos somente se Delete data estiver ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Yoco é uma marca de seu respectivo proprietário. Este plugin não é afiliado à Yoco nem endossado por ela.