VibeFox Yoco 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 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 suas chaves secretas, que estão no Yoco Business Portal em Selling Online > Payment Gateway. Somente as chaves secretas são informadas. O webhook é registrado pelo módulo, e o segredo de assinatura é preenchido para você.
Site público: a Yoco envia webhooks para a sua loja, por isso ela 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 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 Yoco Pay 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. Cole a chave secreta de teste (sk_test_...) e, quando estiver pronto, a chave secreta de produção (sk_live_...). Clique em Save. O webhook é registrado para cada modo que tenha uma chave.
5. Ative Enable/Disable e clique em Save. Faça um pagamento de teste com um cartão de teste da Yoco enquanto Test mode estiver ativado e, depois, desative Test mode para receber pagamentos reais.
Ao ser instalado, o módulo cria o status de pedido Yoco payment on hold. O PrestaShop habilita um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitar isso em Payment > Preferences.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Yoco Pay 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 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, por exemplo Enter the test secret key to offer Yoco at checkout (test mode). Ao salvar, o módulo verifica as chaves e os segredos de webhook e registra os webhooks. As mensagens sobre isso aparecem no topo da página.
Yoco
Enable/Disable: Enable Yoco ativa ou desativa o método de pagamento. Padrão: desativado.
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 armazenado no pedido. 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 do Yoco Business Portal em Selling Online > Payment Gateway. A Yoco tem uma única API para os dois modos: a chave define se um pagamento é de teste ou real. O modo de teste usa somente a chave de teste; o modo de produção, somente a chave de produção.
Test mode: usa a chave secreta de teste. Nenhum dinheiro real é cobrado; pague com cartões de teste da Yoco. Padrão: ativado. Desative para receber pagamentos reais. Enquanto estiver ativado, os clientes veem Test mode — use a Yoco test card; no real money is charged. abaixo do método de pagamento.
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, por exemplo Yoco: the test secret key must start with sk_test_ — the previous value was kept. Se a Yoco informar, durante o registro do webhook, que uma chave pertence ao outro modo, a página avisa você.
Chaves e segredos 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.
Webhooks
A Yoco confirma pagamentos e reembolsos na URL exibida em Webhook URL nesta seção. Com URLs amigáveis, ela tem esta aparência: https://your-shop/module/wcp_yoco_pay/webhook, possivelmente com um código de idioma como /en/. Você não precisa criar o webhook no portal da Yoco. Ao salvar as configurações, o módulo registra a URL na Yoco para cada modo que tem uma chave secreta, mas não um segredo de webhook, e armazena o segredo de assinatura no campo desse modo. Ele registra a URL novamente quando a chave secreta desse modo ou a URL do webhook muda. Quando a URL muda, o registro anterior é removido.
Para cada modo (Test e Live), a seção mostra o estado do webhook:
O módulo trata estes eventos (eles também estão listados nesta seção):
Webhooks sem assinatura válida são recusados. Um evento precisa ser assinado com o segredo do modo em que o pagamento foi feito, portanto uma chave secreta de teste nunca confirma um pagamento real. Copie a URL exatamente como as configurações a mostram, pois o webhook precisa chegar à sua loja sem redirecionamento.
Test webhook secret: preenchido automaticamente quando o webhook é registrado. Cole um segredo (whsec_...) somente se você mesmo registrou a URL do webhook.
Live webhook secret: preenchido automaticamente quando o webhook é registrado. Limpe-o e salve para registrar o webhook novamente.
Um segredo de webhook deve ter a forma whsec_ seguido de texto em base64. Qualquer outro valor não é salvo, e o anterior é mantido.
Clear saved secrets: marque uma chave ou um segredo e clique em Save para removê-lo. Um campo vazio mantém o valor salvo. Limpar um segredo de webhook e salvar registra o webhook novamente.
Avançado
Debug log: grava as requisições e os webhooks da Yoco em logs/yoco_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos, como requisições com falha para a Yoco e webhooks recusados, são sempre registrados. Chaves, segredos de webhook e e-mails são mascarados. Padrão: desativado.
Log: mostra o tamanho e as entradas mais recentes do registro. Clique em Clear log para esvaziá-lo.
Delete data: quando ativado, desinstalar o módulo remove as configurações, o registro e os webhooks que o módulo registrou na Yoco. Os dados dos pedidos (IDs de checkout e de pagamento da Yoco, reembolsos) e o status de pedido Yoco payment on hold são sempre mantidos, pois são necessários para reembolsos. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Card or Instant EFT (Yoco)) e confirma. O módulo cria um checkout da Yoco pelo total do carrinho em centavos e envia o cliente para a página de pagamento da Yoco, onde ele paga por cartão ou Instant EFT. Nesse momento, ainda não existe pedido.
Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que a Yoco confirma: o módulo consulta o checkout na Yoco quando o cliente retorna e novamente quando o webhook assinado chega. Então o pedido é criado e o cliente vê a página padrão de confirmação de pedido com Your payment with Yoco has been received. Se a Yoco ainda não tiver confirmado o pagamento quando o cliente voltar, uma página Payment confirmation mostra We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again. com um botão Check again; o webhook cria o pedido assim que chega.
Se o cliente cancelar na página da Yoco, ele volta à finalização de compra com The Yoco payment was cancelled. Your cart is saved — you can pay again 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. O carrinho é mantido.
Antes de uma nova tentativa de pagamento para o mesmo carrinho, o módulo verifica a anterior na Yoco. Se ela já foi paga, o pedido é criado sem nova página de pagamento. Se ainda estiver aberta para o mesmo valor e tiver sido criada há menos de 30 minutos, o cliente recebe novamente a mesma página da Yoco. Caso contrário, é criado um novo checkout da Yoco.
Se a Yoco não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com Yoco could not start the payment. Please try again in a moment or choose another payment method. e o motivo é gravado no registro. Um pedido abaixo de R2,00 recebe Yoco requires an order total of at least R2.00.
O webhook funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.
Os pagamentos são cobrados imediatamente na página da Yoco. O módulo 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
No order yet: o cliente foi enviado à Yoco e não pagou, cancelou na página da Yoco, ou a Yoco ainda não confirmou o pagamento. Existe apenas o carrinho.
Payment accepted: o pagamento foi confirmado. Ele é registrado com o ID de pagamento da Yoco como ID da transação, e uma nota mostra o valor, os IDs de pagamento e de checkout da Yoco, o modo e a forma como o pagamento foi confirmado (o retorno do cliente, o webhook ou uma verificação antes de uma nova tentativa de pagamento).
Yoco payment on hold: a Yoco informou um valor ou uma moeda diferentes do total do carrinho, por exemplo porque o carrinho foi alterado em outra aba depois que o pagamento começou. Nenhum pagamento é registrado, a nota explica o motivo, e o cliente vê We received your payment and are reviewing it. We will contact you if anything else is needed. Verifique o pagamento antes de enviar o pedido. Se o cliente pagar o valor correto em outra tentativa, o pedido passa para Payment accepted.
Cancelled or Refunded: um pagamento que chega para esse tipo de pedido não o altera. Uma nota pede que você reembolse o pagamento no portal da Yoco ou restaure o pedido manualmente. O cliente 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 muda. Uma nota pede que você o reembolse no portal da Yoco.
Bloco de pagamento da Yoco
A página do pedido mostra um bloco Yoco payment com os IDs de pagamento e de checkout da Yoco, o status, o valor pago e reembolsado, um selo Test mode para pagamentos de teste, o histórico de reembolsos, as tentativas de pagamento do carrinho (quando houve mais de uma) e as Yoco notes do pedido.
Reembolsos
No bloco Yoco payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Yoco. Confirme a pergunta Refund this amount through Yoco? This cannot be undone. Reembolsos totais e parciais são suportados. Você precisa ter permissão para editar pedidos. Os reembolsos são feitos sobre o valor cobrado pela Yoco, portanto você pode reembolsar no máximo o que o cliente efetivamente pagou, mesmo que o pedido tenha sido editado depois. O reembolso é enviado no modo em que o pagamento foi feito (teste ou produção), então a chave secreta desse modo deve estar configurada. Um reembolso repetido após uma resposta perdida não é pago duas vezes.
Um reembolso bem-sucedido é incluído no histórico de reembolsos e nas notas, com o ID de reembolso da Yoco. Um reembolso total coloca o pedido em Refunded; um reembolso parcial não altera o status. Se a Yoco recusar o reembolso, o bloco mostra Yoco refused the refund: com o motivo, e nenhum reembolso é registrado. Se a Yoco informar que o reembolso está pendente, o bloco indica que ele ainda está pendente. Não o repita: ele será registrado quando a Yoco o confirmar por webhook. Reembolsos estão disponíveis para pedidos pagos por um checkout da Yoco. Um pedido em Yoco payment on hold não tem checkout pago para reembolsar; reembolse-o no portal da Yoco.
O módulo não gera notas de crédito. Os botões de reembolso padrão do PrestaShop na página do pedido não devolvem dinheiro pela Yoco.
Os reembolsos feitos no portal da Yoco chegam pelo webhook refund.succeeded e são registrados no histórico de reembolsos e nas notas. Quando atingem o valor pago, o pedido passa para Refunded. Um reembolso maior que o valor ainda reembolsável não é registrado, e uma nota pede que você verifique o pedido. Um reembolso falho adiciona uma nota informando que o dinheiro não foi devolvido ao cliente.
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 Yoco Pay Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox Yoco Pay Gateway > Configure, acima das configurações. Insira 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 aparecem a linha Product: presta-payment-yoco e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente 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 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, o módulo continua funcionando com o último status conhecido.
Uma chave funciona em um único domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a sua vaga de domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a Yoco 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 pode 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 exigem 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 Yoco não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado 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 do carrinho deve ser ZAR, e o total do pedido, de pelo menos R2,00. A página de configurações exibe um aviso quando a chave está faltando ou a moeda da loja não é ZAR. Em Payment > Preferences, verifique se o módulo está liberado para ZAR, o país do cliente e o grupo do cliente.
O pagamento foi aprovado, mas nenhum pedido foi criado: 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 manualmente, confirme que ele pertence ao webhook desta URL e deste modo. O pedido também é criado quando o cliente volta para a loja após pagar e quando o cliente tenta pagar novamente.
Não foi possível registrar o webhook: os pagamentos continuam sendo confirmados quando os clientes voltam para a loja. Corrija o motivo exibido na mensagem, por exemplo que a loja precisa estar acessível pela internet via HTTPS, e salve novamente. Você também pode registrar a URL manualmente e colar o segredo de assinatura.
Os webhooks são recusados: webhooks recusados são gravados no registro. 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 novamente.
A URL do webhook mostra apenas POST no navegador: isso é normal. A URL aceita apenas requisições da Yoco.
Erro ao salvar «The secret key must start with sk_test_ / sk_live_»: uma chave foi colada no campo errado. A chave de teste começa com sk_test_, a de produção com sk_live_. O valor anterior foi mantido.
O cliente vê um erro ao escolher a Yoco: consulte o campo Log na página do módulo. Yoco is not available at the moment. Please choose another payment method. significa que o modo atual não tem chave secreta.
O cliente é informado de que um pagamento precisa ser analisado: uma tentativa foi paga com um valor diferente ou depois que o pedido foi cancelado. Leia as notas no bloco Yoco payment e atenda 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. Informe-a e tente novamente.
O reembolso falha com No answer from Yoco: nada foi registrado no PrestaShop. Se a Yoco processou o reembolso, repita o mesmo reembolso: ele não será feito duas vezes.
Desenvolvedores: o hook actionYocoPCheckoutPayload permite que outro módulo altere a requisição que cria o checkout da Yoco.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Yoco Pay 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 estiver ativado, as configurações, o registro e os webhooks que o módulo registrou na Yoco são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os checkouts e reembolsos da Yoco e o status de pedido Yoco payment on hold são sempre mantidos, para que pedidos pagos antes possam ser reembolsados mesmo após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Yoco é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Yoco.