VibeFox Peach Payments for WooCommerce — Ajuda
Requisitos
WordPress: 6.2 ou superior.
WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não permite ativação sem ele.
PHP: 8.0 ou superior.
Currency: a moeda da loja deve ser ZAR, KES ou MUR. Com outras moedas o método fica oculto e a página de configurações informa isso.
Peach Payments account: você precisa das credenciais da Card API da sua conta Peach Payments: Entity ID e Access Token. As credenciais de teste vêm do painel do sandbox da Peach Payments, e as de produção, do painel da Peach Payments; são diferentes. Para webhooks você também precisa de uma chave de descriptografia que a Peach Payments envia ao habilitar os webhooks Card para sua loja (veja Configuração). Seu site deve estar acessível pela internet para receber webhooks.
VibeFox license key: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_peach_pay para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Peach Payments > Manage, ou clique em Settings abaixo do nome do plugin na página de plugins.
4. Informe sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Informe o Entity ID e o Access Token de teste do painel do sandbox da Peach Payments e peça à Peach Payments que habilite webhooks Card para a URL mostrada nas configurações (veja Configuração).
6. Ative Enable/Disable e salve. Mantenha Test mode ativado e faça um pagamento com um cartão de teste do sandbox da Peach Payments. Depois desmarque Test mode, informe as credenciais e a chave de webhook de produção e salve.
As configurações da versão 1.0 são movidas automaticamente para os novos campos após a atualização.
Configuração
Todas as configurações ficam em uma página: WooCommerce > Settings > Payments > Peach Payments. Acima dos campos aparecem avisos: Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.; um aviso se faltar Entity ID ou Access Token do modo atual (até lá o método não aparece na finalização de compra); um aviso se faltar a chave de descriptografia de webhook do modo atual (os pagamentos só serão confirmados quando o cliente retornar); e um aviso se a moeda não for aceita. Na lista de métodos, Peach Payments é marcado como precisando de configuração até que o modo atual tenha Entity ID e Access Token. Ao salvar, espaços são removidos das credenciais, e uma chave de webhook que não seja um valor hexadecimal de 64 caracteres gera um erro.
Enable/Disable: Enable Peach Payments ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o nome do método exibido ao cliente na finalização de compra. Padrão: Credit / Debit Card (Peach Payments).
Description: o texto abaixo do método na finalização de compra. Padrão: Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.
Credenciais da API
O Access Token e o Entity ID da Card API aparecem no painel da Peach Payments (credenciais de teste: painel do sandbox). A seção tem links para os dois painéis e para a documentação de desenvolvedores da Peach Payments.
Test mode: Enable test mode envia novos pagamentos ao sandbox da Peach Payments com as credenciais de teste, sem cobrar dinheiro real. Desmarque para aceitar pagamentos reais com as credenciais de produção. Um pagamento iniciado em um modo sempre é verificado nesse modo, mesmo após a troca. Padrão: ativado.
Test Entity ID: o Entity ID (canal 3-D Secure) da sua conta sandbox.
Test Access Token: o token de acesso bearer da sua conta sandbox.
Test Webhook Decryption Key: a chave hexadecimal de 64 caracteres para descriptografar os webhooks Card do sandbox.
Live Entity ID: o Entity ID (canal 3-D Secure) da sua conta de produção.
Live Access Token: o token de acesso bearer da sua conta de produção.
Live Webhook Decryption Key: a chave hexadecimal de 64 caracteres para descriptografar os webhooks Card da conta de produção.
Webhook
Webhooks confirmam pagamentos mesmo que o cliente feche o navegador antes de voltar à loja. A seção mostra a URL do webhook da sua loja, como https://your-site/wp-json/peach-pay/v1/webhook. Copie a URL exatamente como aparece nas configurações. Peça à Peach Payments (support@peachpayments.com) para habilitar webhooks Card na sua conta com essa URL, depois informe a chave recebida no campo Webhook Decryption Key do mesmo modo.
A Peach Payments criptografa cada webhook (AES-256-GCM). Um webhook que não possa ser descriptografado com a chave de teste ou produção é rejeitado, para que apenas a Peach Payments possa alterar seus pedidos. Um webhook descriptografado com a chave de um modo só é aplicado a pagamentos iniciados nesse modo. O plugin usa notificações de pagamento:
Outras notificações, como a de teste enviada ao ativar o webhook, recebem resposta OK e são ignoradas. Sem chave de webhook, o pedido só é confirmado quando o cliente retorna à loja após pagar.
Formulário de pagamento
Card brands: as bandeiras exibidas no formulário da Peach Payments: Visa, Mastercard, American Express, Diners Club. Selecione apenas as habilitadas para seu Entity ID. Padrão: Visa e Mastercard.
Avançado
Logging: Log API requests and payment results grava informações de depuração em WooCommerce > Status > Logs, origem wcp_peach_pay. Erros e avisos sempre são registrados. Os logs não contêm dados de cartão, chaves ou dados do cliente. Padrão: desativado.
Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. Desativar o plugin nunca exclui nada. Os dados da Peach Payments nos pedidos são mantidos. Padrão: desativado.
Finalização de compra
O cliente escolhe o método (por padrão Credit / Debit Card (Peach Payments)) e clica em Continue to payment. Ele é levado à página Pay for order da sua loja. Nela o plugin prepara uma finalização de compra Peach Payments para o total na moeda do pedido e exibe o formulário de cartão da Peach Payments com as bandeiras selecionadas, no idioma do site se aceito pela Peach Payments. No modo de teste a página mostra Test mode: use a Peach Payments test card, no real payment will be made.. Os dados do cartão são digitados no formulário da Peach Payments, e o script é carregado com um hash de Subresource Integrity.
Após pagar, o cliente retorna à loja. O pedido só é marcado como pago após confirmação da Peach Payments: a loja consulta o resultado da finalização de compra desse pedido na API da Peach Payments, no modo em que foi criada, e verifica se o pagamento pertence ao pedido. O webhook faz o mesmo de forma independente: o primeiro a chegar aplica o resultado, e o outro não altera nada. O cliente que pagou vê a página Order received.
Se o pagamento não for concluído, o cliente volta à página Pay for order com uma mensagem e pode tentar novamente: Payment failed: seguido do motivo da Peach Payments e Please try again or use another card., ou The payment was not completed. Please try again.. Se ainda não for possível confirmar (por exemplo, a Peach Payments não respondeu ou o webhook está processando o mesmo pedido), aparece We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again.. Se não houver chave de webhook para o modo, o cliente é orientado a entrar em contato com você informando o número do pedido.
Se não for possível preparar o formulário, o cliente vê uma mensagem breve e um botão Try again: The payment form is not available right now (payment configuration error). Please contact us or choose another payment method. (credenciais incorretas), uma mensagem de que alguns dados de cobrança não foram aceitos pelo provedor ou The payment form could not be loaded. Please try again in a moment.. O pedido recebe uma nota com código e descrição da Peach Payments.
O método funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. É compatível com WooCommerce High-Performance Order Storage (HPOS).
O plugin não tem formulário de cartão na própria página de finalização de compra, cartões salvos, assinaturas, pré-autorização e captura, nem EFT, BNPL, QR ou outros métodos sem cartão.
Pedidos
Status dos pedidos
Pending payment: o cliente ainda não pagou ou o pagamento não foi concluído. Ele pode pagar o mesmo pedido novamente.
Processing: o pagamento foi confirmado e o valor e a moeda correspondem ao pedido. A nota mostra código do resultado, descrição e ID do pagamento da Peach Payments; esse ID é o ID de transação do pedido. Se a Peach Payments sinalizar revisão manual, a nota pede que você verifique o pagamento no painel da Peach Payments antes do envio.
On hold: o pagamento aguarda confirmação da Peach Payments (o webhook o conclui depois ou o marca como malsucedido); o valor ou a moeda pagos diferem do pedido (nota amount/currency mismatch — manual review required); ou o pagamento chegou após o cancelamento do pedido. A nota explica o que verificar.
Failed: a Peach Payments recusou o pagamento de um pedido com Pagamento pendente ou o pagamento aguardado por um pedido Em espera. Uma tentativa recusada nunca altera um pedido pago, em espera por outro motivo ou cancelado. O cliente pode pagar novamente.
Se um segundo pagamento de um pedido já pago for aprovado, o pedido não muda. Uma nota informa o pagamento duplicado e pede o reembolso no painel da Peach Payments. Um pagamento para um pedido reembolsado é apenas anotado.
Reembolsos
Não há reembolsos pela tela do pedido do WooCommerce. Reembolse no painel da Peach Payments e registre um reembolso manual no WooCommerce. Com o webhook configurado, reembolsos, anulações e contestações na Peach Payments são adicionados como notas com valor e ID; o status do pedido não muda.
Chave de licença
O plugin funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Peach Payments. Cole a chave em License key e clique em Activate. O bloco mostra o status, como validade da licença e domínio. Use Check now para verificar novamente, Change key para informar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre sua conta vibefox.net.
Uma chave funciona em um domínio. Removê-la do site não libera a vaga do domínio. Libere a vaga na sua conta vibefox.net.
Sem chave ativa, Peach Payments não aparece para 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.. Gerentes da loja conectados ainda veem o método, marcado (unlicensed — visible to admins only), para que você configure e teste o plugin antes de comprar uma chave. Um lembrete aparece na página de plugins e nas páginas WooCommerce. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados pelo retorno do cliente e pelo webhook.
Quando a licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado automaticamente em segundo plano.
Solução de problemas
Peach Payments não aparece na finalização de compra: confira se a licença está ativa, Enable/Disable ativado, Entity ID e Access Token do modo atual preenchidos (Test Entity ID e Test Access Token em teste, Live Entity ID e Live Access Token em produção) e a moeda é ZAR, KES ou MUR. Os avisos no topo das configurações indicam o problema. Desenvolvedores podem mudar as moedas pelo filtro peach_p_supported_currencies; adicione apenas as processadas pela sua conta Peach Payments.
O pagamento foi feito, mas o pedido continua Pending payment: o cliente não retornou e o webhook não chegou. Confira se a Peach Payments habilitou webhooks Card para a URL exata das configurações, se Webhook Decryption Key do modo usado foi informada e se manutenção, firewall ou senha não bloqueiam a URL. Procure webhooks rejeitados em WooCommerce > Status > Logs, origem wcp_peach_pay.
O webhook responde Decryption failed: não foi possível descriptografá-lo com a chave de teste ou produção. A chave está errada ou pertence a outra conta ou modo. Informe a chave enviada pela Peach Payments para essa URL.
O webhook responde Webhook key not configured: nenhuma chave webhook está configurada ou válida. Informe a chave de 64 caracteres. A Peach Payments reenviará o webhook mais tarde.
O webhook responde Order busy, retry later: o pedido estava sendo atualizado pelo retorno do cliente ao mesmo tempo. Nada mudou e a Peach Payments reenvia o webhook.
O webhook responde Missing or malformed data: a solicitação não tinha corpo criptografado ou cabeçalhos X-Initialization-Vector / X-Authentication-Tag, por exemplo por alteração de um proxy. Nada mudou.
O webhook responde ignored: a notificação é autêntica, mas não pertence a uma finalização de compra desta loja (outra loja com o mesmo Entity ID, pedido excluído), ou veio de outro modo. Nada mudou.
O cliente vê The payment form is not available right now: o Access Token ou Entity ID do modo atual está errado. Confira as credenciais e o modo e leia o código da Peach Payments na nota do pedido.
O pedido fica On hold após o pagamento: leia a nota. O valor ou a moeda diferiam, o pagamento chegou após o cancelamento ou a Peach Payments ainda aguarda confirmação. Confira o pagamento no painel da Peach Payments, depois processe o pedido ou reembolse.
Ao salvar é exigida uma chave webhook hexadecimal de 64 caracteres: o valor não é a chave da Peach Payments. Os webhooks não podem ser descriptografados até a correção.
O bloco de licença mostra um erro: siga a mensagem. Se a chave estiver em outro domínio, libere uma vaga na conta vibefox.net e clique em Check now. Se o endereço mudou, clique em Check now para ativá-la no novo domínio. Se o servidor de licenças estiver inacessível, o plugin usa o último status conhecido.
Desinstalação
Desativar o plugin mantém todos os dados. Para removê-lo, desative e exclua na página Plugins. A chave e o status de licença sempre são removidos. Configurações e logs (arquivos e entradas no banco de dados da origem wcp_peach_pay) só são removidos se Delete data on uninstall estava ativado. Caso contrário, ficam para uma reinstalação futura. Os pedidos existentes mantêm notas de pagamento, IDs de transação e dados de finalização de compra Peach Payments.
Peach Payments é uma marca comercial de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela Peach Payments.