VibeFox PayPal 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 mais antigas do PHP.
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 módulo 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 back office, acesse 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 o VibeFox PayPal Gateway na lista de módulos e clique em Configure.
3. Insira a sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. No PayPal Developer Dashboard, crie um aplicativo REST API (sandbox e/ou produção) e copie o seu Client ID e o seu Secret.
5. Insira as credenciais do modo que você usa, escolha Capture ou Authorize, ative Enable/Disable e clique em Save.
6. Teste com uma conta de comprador sandbox do PayPal; depois desative o Sandbox mode e insira as credenciais de produção.
Na instalação, o módulo cria três status de pedido: PayPal payment authorized, Awaiting PayPal payment e PayPal payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode restringi-los em Payment > Preferences.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox PayPal 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 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 suporta a moeda padrão da loja. Nos dois casos, o método de pagamento fica oculto na finalização de compra. Enquanto o modo sandbox estiver ativado, a página mostra Sandbox mode is on: payments go to the PayPal sandbox, no real money is moved. Salvar as configurações descarta os tokens de acesso do PayPal em cache, para que as novas credenciais sejam usadas imediatamente.
General
Enable/Disable: Enable PayPal Gateway liga ou desliga o método de pagamento. Padrão: desligado.
Title: o nome do método de pagamento que os clientes veem na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: PayPal. Obrigatório.
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 seu Client ID e o seu Secret. A seção tem links para os aplicativos sandbox e para os aplicativos de produção. Só os campos do modo selecionado são exibidos; as credenciais dos dois modos continuam salvas.
Sandbox mode: os pagamentos vão para o sandbox do PayPal com as credenciais sandbox; nenhum dinheiro real é movimentado. Padrão: ligado. Desligue para aceitar pagamentos reais. Capturas, anulações e reembolsos sempre usam o ambiente em que o pedido foi pago. Enquanto estiver ligado, os clientes veem Sandbox mode: pay with a PayPal sandbox buyer account — no real money is charged. abaixo do método de pagamento.
Sandbox Client ID: o Client ID do seu aplicativo REST API sandbox.
Sandbox Secret: o Secret do seu aplicativo REST API 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.
Os secrets salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo apenas se quiser alterá-lo.
Clear saved secrets: marque um secret e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.
Pagamento
Payment action: o que acontece quando o cliente aprova o pagamento. Padrão: Capture.
Avançado
Debug log: registra as solicitações de API em logs/wc_plg_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados, mesmo com esta opção desligada. Credenciais, tokens e dados do comprador nunca são registrados. Padrão: desligado.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: quando ligado, desinstalar o módulo remove as configurações do gateway, os tokens em cache e o log. Os dados de pagamento dos pedidos (IDs do PayPal dos pedidos, reembolsos) e os status dos pedidos são sempre mantidos. Padrão: desligado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, PayPal) e o botão do PayPal aparece no lugar do formulário de pagamento. Um clique no botão cria no seu servidor um pedido do PayPal pelo total do carrinho, na moeda do carrinho. O valor é sempre calculado no servidor, nunca no navegador. Até este ponto, nenhum pedido existe.
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 então mostra PayPal payment approved. Completing your order… e cria o pedido. Se os termos de serviço ainda não tiverem sido aceitos, a finalização de compra mostra PayPal payment approved. Click "Place order" to complete it. Se o cliente clicar em Place order sem aprovar um pagamento, a mensagem é Please click the PayPal button and approve the payment first.
Seu servidor então lê o pedido do PayPal e verifica se ele está aprovado, se foi criado para este carrinho, se não está sendo usado por outro carrinho e se o valor e a moeda correspondem ao carrinho. Só então o pagamento é capturado (ou autorizado), o pedido é criado e o cliente vê a página padrão de confirmação do pedido.
Se o total do carrinho mudar após a aprovação, nada é capturado. O cliente vê The order total changed after you approved the payment in PayPal. Please click the PayPal button again to approve the new total. Se o PayPal recusar o pagamento, o cliente volta à etapa de pagamento e é convidado a clicar no botão do PayPal e escolher outra forma de pagamento. Nenhum pedido é criado. Se o cliente fechar a janela do PayPal, a finalização de compra mostra You cancelled the PayPal payment.
Se o PayPal não responder durante a captura, o cliente vê We could not confirm your PayPal payment yet. Please try again in a moment — you will not be charged twice. A aprovação é mantida, inclusive após recarregar a página, e Place order a usa novamente. Se o PayPal tiver concluído a tentativa anterior, esse pagamento é usado e uma nova aprovação não é capturada. Se o pagamento foi feito mas o pedido não pôde ser criado, o cliente vê Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. A próxima tentativa cria o pedido a partir do pagamento salvo, sem cobrar novamente.
O script do PayPal é carregado somente na página de finalização de compra e em seu próprio namespace, para não entrar em conflito com outro módulo do PayPal na página. O módulo funciona com os temas Classic e Hummingbird.
O módulo não tem webhooks do PayPal, mensagens do Pay Later, campos de cartão, 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. São usados os endereços informados na finalização de compra do PrestaShop, não um endereço do PayPal.
Pedidos e reembolsos
Status do pedido
No order yet: o cliente não aprovou o pagamento, ou o PayPal o recusou. Existe apenas o carrinho.
Payment accepted: a captura foi concluída. O pedido só é marcado como pago depois que o PayPal confirma. O pagamento é registrado com o ID de captura do PayPal como ID da transação, e uma nota mostra o valor, o pedido do PayPal e a captura.
PayPal payment authorized: o pagamento foi autorizado e aguarda a captura (ação de pagamento Authorize).
Awaiting PayPal payment: a captura está PENDING no PayPal, por exemplo em análise do pagamento.
PayPal payment on hold: o valor ou a moeda pagos diferem do pedido, ou o pagamento não pôde ser lido na resposta do PayPal. A nota explica o motivo. Quando o PayPal cobrou na moeda do pedido, o valor efetivamente pago é registrado como pagamento. Verifique o pedido e atenda-o ou reembolse o pagamento.
Canceled: a autorização foi anulada com Void PayPal authorization.
Payment error: uma captura pendente foi recusada ou falhou.
Refunded: o pagamento foi reembolsado integralmente pelo módulo.
Se chegar um segundo pagamento para um carrinho que já tem pedido, o pedido não é alterado. Uma nota pede que você verifique o pagamento na sua conta do PayPal e o reembolse.
Bloco de pagamento do PayPal
A página do pedido mostra um bloco PayPal payment com o ID do pedido do PayPal e o intent, o ID da captura (vinculado ao pagamento na sua conta do PayPal, sandbox ou produção), o ID da autorização, o status do pagamento, o valor, os valores pago e reembolsado, um selo Sandbox para pagamentos sandbox, o histórico de reembolsos e as PayPal notes do pedido. Os botões do bloco exigem a permissão para editar pedidos, mas não o acesso às páginas de módulos. O resultado de cada ação aparece no bloco.
Reembolsos
No bloco PayPal payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via PayPal. Confirme a pergunta Refund this amount through PayPal? This cannot be undone. Reembolsos totais e parciais são suportados. O motivo é enviado ao PayPal como uma nota para o comprador. Os reembolsos são feitos no valor e na moeda cobrados pelo PayPal; portanto, após uma divergência de valor ou moeda, você pode reembolsar até o que o cliente realmente pagou, e não o total do pedido. 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 preenchidas. Se o PayPal não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas com o ID e o status do reembolso no PayPal; um reembolso PENDING é concluído pelo PayPal depois. Um reembolso total define o pedido como Refunded. Um reembolso parcial não altera o status.
Um pagamento apenas autorizado não pode ser reembolsado: use Void PayPal authorization em vez disso. O módulo não cria notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pelo PayPal. Reembolsos, disputas e estornos feitos na sua conta do PayPal não são sincronizados com o PrestaShop.
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 PayPal Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox PayPal 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 deles ficam a linha Product: presta-payment-paypal 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 do 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 domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, o PayPal não é exibido aos clientes na finalização de compra. Se um pagamento for iniciado mesmo assim, a loja se recusa a criar o pedido do PayPal e o cliente vê An error occurred during PayPal checkout. Please try again. A vitrine do PrestaShop não sabe que você está logado no 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 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: os reembolsos e as ações do bloco do PayPal continuam funcionando.
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. Não é necessário cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
PayPal does not appear at checkout: 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 do carrinho é 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. Em Payment > Preferences, verifique se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente. Uma extensão do navegador que bloqueie o www.paypal.com também oculta o botão.
The payment went through, but no order was created: o módulo 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 ou quando o pedido não pôde ser criado. Ative o Debug log e veja o campo Log, verifique o pagamento na sua conta do PayPal, ou deixe o cliente tentar novamente: uma nova tentativa nunca cobra duas vezes e cria o pedido a partir do pagamento salvo.
PayPal could not be loaded: o script do PayPal não carregou no navegador, por exemplo por causa de um bloqueador ou de um problema de rede.
PayPal is not available right now: as credenciais estão erradas ou pertencem ao outro modo. Copie novamente o Client ID e o Secret do aplicativo correto.
Your PayPal approval could not be matched to this checkout: o pedido do PayPal não foi criado para este carrinho, por exemplo após a expiração da sessão. O cliente clica novamente no botão do PayPal.
This payment is already being processed: o mesmo carrinho foi enviado duas vezes ao mesmo tempo. O cliente aguarda um instante e verifica o e-mail antes de tentar novamente.
The order is on hold after payment: leia as notas no bloco PayPal payment. O pagamento foi autorizado (capture-o com Capture PayPal payment), a captura está PENDING no PayPal (use Check PayPal payment status depois), ou o valor ou a moeda pagos não correspondiam ao pedido (atenda o pedido ou reembolse o valor pago).
Capture of an authorization fails: a autorização pode ter mais de 29 dias ou já ter sido anulada. O bloco e as notas mostram o erro do PayPal.
Refund fails: o pedido não tem captura do PayPal (apenas uma autorização), o valor é maior do que o que resta a reembolsar, ou as credenciais do ambiente em que o pagamento foi feito estão ausentes. O bloco informa qual é o caso.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox PayPal 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 on uninstall estiver ligado, as configurações do gateway, os tokens de acesso do PayPal em cache e o log são removidos. Se estiver desligado, todas as configurações são mantidas para uma reinstalação posterior. As transações e os reembolsos do PayPal e os status de pedido PayPal payment authorized, Awaiting PayPal payment e PayPal payment on hold são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados após uma reinstalação. Os pedidos existentes mantêm as suas notas de pagamento e os IDs de transação.
PayPal é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pelo PayPal.