VibeFox PayPal for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

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

PHP: 8.0 ou superior.

HTTPS: seu site deve usar HTTPS para pagamentos em produção.

Conta do PayPal: uma conta Business do PayPal com um aplicativo REST API no PayPal Developer Dashboard. Você precisa do Client ID e do Secret do aplicativo. Aplicativos de sandbox e de produção têm credenciais diferentes. Nenhum webhook é necessário: o plugin confirma cada pagamento no seu servidor enquanto o cliente está na finalização de compra.

Moeda: uma das moedas suportadas pelo PayPal: AUD, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, MYR, NOK, NZD, PHP, PLN, SEK, SGD, THB, TWD ou USD.

Chave de licença VibeFox: 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_paypal_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. No PayPal Developer Dashboard, crie um aplicativo REST API (sandbox e/ou produção) e copie o Client ID e o Secret.

4. Abra as configurações: WooCommerce > Settings > Payments > PayPal (Smart Buttons) > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.

5. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

6. Insira as credenciais do modo que você usa, escolha Capture ou Authorize, ative Enable/Disable e salve.

7. Faça um teste com uma conta de comprador sandbox do PayPal e, depois, desmarque Sandbox mode e insira as credenciais de produção.

Configuração

Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > PayPal (Smart Buttons). Acima dos campos, a página avisa quando o método de pagamento está ativado mas o Client ID ou o Secret do modo selecionado estão vazios, e quando o PayPal não oferece suporte à moeda da loja. Nos dois casos, o método de pagamento fica oculto na finalização de compra. Na lista de métodos de pagamento, o PayPal exibe um selo Test mode no modo sandbox e aparece como pendente de configuração até que as credenciais do modo selecionado sejam preenchidas.

Geral

Enable/Disable: Enable PayPal Gateway ativa ou desativa o método de pagamento. Padrão: off.

Title: o nome do método de pagamento que os clientes veem na finalização de compra. Padrão: PayPal.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay with your PayPal account or a card via PayPal.

Credenciais de API

Crie um aplicativo REST API no PayPal Developer Dashboard e copie o Client ID e o Secret. A seção tem links para os aplicativos sandbox e para os aplicativos de produção. Apenas os campos do modo selecionado são exibidos.

Sandbox mode: Enable sandbox (test) mode. Os pagamentos vão para o sandbox do PayPal com as credenciais de sandbox; nenhum dinheiro real é movimentado. Padrão: on. Desmarque para aceitar pagamentos reais.

Sandbox Client ID: o Client ID do seu aplicativo REST API de sandbox.

Sandbox Secret: o Secret do seu aplicativo REST API de sandbox.

Live Client ID: o Client ID do seu aplicativo REST API de produção.

Live Secret: o Secret do seu aplicativo REST API de produção.

Pagamento

Payment action: o que acontece quando o cliente aprova o pagamento. Padrão: Capture.

Capture: o cliente é cobrado imediatamente e o pedido passa para Processando.

Authorize: os valores são apenas reservados e o pedido fica em Aguardando. Capture ou anule o pagamento na tela do pedido, pelo menu Order actions. As autorizações do PayPal podem ser capturadas em até 29 dias.

Avançado

Debug log: Log API requests (errors are always logged). Os registros são salvos em WooCommerce > Status > Logs, origem wcp_paypal_gateway. Credenciais e dados dos compradores nunca são registrados. Padrão: off.

Delete data on uninstall: Delete the gateway settings when the plugin is deleted. Os dados de pagamento dos pedidos (os IDs do PayPal nos pedidos) são sempre mantidos. Padrão: off.

Finalização de compra

Quando o cliente escolhe o PayPal (por padrão, PayPal), o botão do PayPal substitui Place order. No modo sandbox, a finalização de compra exibe Modo sandbox: pague com uma conta de comprador sandbox do PayPal; nenhum valor real é cobrado. Ao clicar no botão, seu servidor cria um pedido no PayPal pelo total do carrinho (ou pelo total do pedido na página Pay for order). O valor é sempre calculado no servidor, nunca no navegador.

O cliente aprova o pagamento na janela do PayPal com uma conta PayPal ou outra fonte de financiamento oferecida pelo PayPal. A finalização de compra exibe então Pagamento do PayPal aprovado. Concluindo seu pedido… e envia o pedido. Seu servidor lê o pedido no PayPal e verifica se ele está aprovado, se foi criado nesta finalização de compra, se não está sendo usado por outro pedido e se o valor e a moeda correspondem ao pedido. Só então o pagamento é capturado (ou autorizado) e o cliente chega à página de pedido recebido.

Se o total do carrinho mudar depois da aprovação, nada é capturado. O cliente vê O total do pedido mudou depois que você aprovou o pagamento no PayPal. Clique no botão do PayPal novamente para aprovar o novo total. Se algum campo da finalização de compra estiver faltando, a aprovação é mantida: depois de corrigi-lo, o cliente clica em Place order para concluir o pagamento. Se o PayPal recusar o pagamento, o cliente é orientado a clicar no botão do PayPal e escolher outra forma de pagamento. Se o cliente fechar a janela do PayPal, a finalização de compra exibe Você cancelou o pagamento do PayPal.

Se o PayPal não responder durante a captura, o cliente vê Ainda não conseguimos confirmar seu pagamento no PayPal. Tente novamente em instantes: você não será cobrado duas vezes. Uma nova tentativa usa a mesma aprovação e, se o PayPal tiver concluído a tentativa anterior, esse pagamento é usado e a nova aprovação não é capturada.

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. O script do PayPal é carregado no próprio namespace, então não conflita com outro plugin do PayPal na página. É compatível com o High-Performance Order Storage (HPOS) do WooCommerce.

O plugin não tem webhooks do PayPal, mensagens do Pay Later, campos de cartão, configurações do Venmo, Apple Pay, Google Pay ou Fastlane, métodos de pagamento salvos ou assinaturas, nem botões nas páginas de produto ou de carrinho. É usado o endereço de entrega informado na finalização de compra do WooCommerce, e não um endereço do PayPal.

Pedidos e reembolsos

Order statuses

Pending payment: o pedido foi criado, mas o pagamento ainda não foi capturado, por exemplo depois de uma resposta desconhecida do PayPal.

Processing: a captura foi concluída. Pedidos com apenas produtos virtuais para download passam para Concluído, o padrão do WooCommerce. A nota do pedido mostra o valor, o pedido do PayPal e a captura. O ID da transação é o ID da captura do PayPal e, na tela do pedido, leva ao pagamento na sua conta do PayPal (sandbox ou produção).

On hold: o pagamento foi autorizado e aguarda a captura (ação de pagamento Authorize); ou a captura está PENDING no PayPal, por exemplo em análise de pagamento; ou o valor ou a moeda pagos diferem do pedido; ou o pagamento não pôde ser lido na resposta do PayPal. A nota do pedido explica o motivo.

Failed: o PayPal recusou a captura ou a autorização.

Cancelled: a autorização foi anulada com Void PayPal authorization.

Ações do pedido

Abra o pedido, escolha uma ação em Order actions e clique na seta.

Capture PayPal payment: captura um pagamento autorizado pelo total do pedido. Uma captura concluída coloca o pedido em Processando. Aparece enquanto a autorização não estiver capturada.

Void PayPal authorization: libera os valores reservados e cancela o pedido.

Check PayPal payment status: lê novamente uma captura PENDING. COMPLETED coloca o pedido em Processando; DECLINED ou FAILED o coloca em Falhou. Uma captura concluída por outro valor ou outra moeda mantém o pedido em Aguardando, com uma nota de divergência.

Reembolsos

Abra o pedido, clique em Refund, informe o valor e clique em Refund via PayPal (o botão mostra o título do seu método de pagamento). Reembolsos totais e parciais são suportados. O reembolso é enviado ao ambiente do PayPal em que o pagamento foi feito (sandbox ou produção), por isso as credenciais desse ambiente precisam estar configuradas. O motivo é enviado ao PayPal como uma nota para o comprador. Se o PayPal não aceitar o reembolso, o WooCommerce exibe o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o ID e o status do reembolso no PayPal; um reembolso PENDING é concluído pelo PayPal mais tarde.

Um pagamento apenas autorizado não pode ser reembolsado: use Void PayPal authorization no lugar. Reembolsos, disputas e estornos feitos na sua conta do PayPal não são sincronizados com o 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 > PayPal (Smart Buttons). 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 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 na sua conta em vibefox.net.

Sem uma chave ativa, o PayPal não aparece para os 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. Os gerentes da loja conectados ainda veem o método de pagamento, marcado como (unlicensed — visible to admins only), para que possam 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: reembolsos e ações nos pedidos continuam funcionando.

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

Solução de problemas

O PayPal não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, se o Client ID e o Secret do modo selecionado estão preenchidos, se a moeda da loja é suportada pelo PayPal e se o total do carrinho é maior que zero. A página de configurações mostra um aviso quando as credenciais ou a moeda são o problema. Uma extensão do navegador que bloqueie www.paypal.com também oculta o botão.

O pagamento foi feito, mas o pedido continua em Pagamento pendente: o plugin não tem webhook, então o pagamento só é confirmado durante a finalização de compra. Isso acontece quando o PayPal não respondeu durante a captura. Leia a nota do pedido, confira o pagamento na sua conta do PayPal e conclua o pedido manualmente, ou deixe o cliente tentar novamente: uma nova tentativa nunca cobra duas vezes.

O PayPal não está disponível agora: as credenciais estão incorretas ou pertencem ao outro modo. Copie novamente o Client ID e o Secret do aplicativo certo.

Sua aprovação do PayPal não pôde ser associada a esta finalização de compra: o pedido do PayPal não foi criado nesta sessão de finalização de compra, por exemplo porque a sessão expirou. O cliente clica novamente no botão do PayPal.

O pedido está em Aguardando depois do pagamento: leia a nota do pedido. O pagamento foi autorizado (capture-o com Capture PayPal payment), a captura está PENDING no PayPal (use Check PayPal payment status mais tarde), ou o valor ou a moeda pagos não correspondiam ao pedido.

A captura de uma autorização falha: a autorização pode ter mais de 29 dias ou já ter sido anulada. A nota do pedido mostra o erro do PayPal.

O reembolso falha: o pedido não tem uma captura no PayPal (apenas uma autorização), ou as credenciais do ambiente em que o pagamento foi feito não estão preenchidas. Desenvolvedores podem alterar a lista de moedas com o filtro wc_plg_supported_currencies.

O bloco de licença exibe 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 da licença deste plugin são sempre removidos. As configurações do gateway e os tokens de acesso do PayPal em cache são removidos somente se Delete data on uninstall estava ativado. Caso contrário, eles permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento, IDs de transação e IDs do PayPal.

PayPal é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado nem endossado pelo PayPal.