VibeFox PayPal for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 ou superior (testado na 4.1.0.3).
PHP: 8.0 ou superior.
Conta PayPal: uma conta PayPal Business com um aplicativo de API REST 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: a extensão 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
O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém README.txt, o pacote do OpenCart 3 wcp_paypal_gateway-oc3-(version).ocmod.zip e o pacote do OpenCart 4 wcp_paypal_gateway.ocmod.zip. Instale apenas o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.
OpenCart 3
1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_paypal_gateway-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, então Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.
2. Acesse Extensions > Extensions e escolha o tipo Payments. Localize VibeFox PayPal Gateway e clique em Install (o botão verde +). Seu usuário administrador precisa do direito de modificar a lista de extensões de pagamento.
3. Clique em Edit (o botão com o lápis) para abrir a página de configurações. Digite sua chave de licença VibeFox em License key, no bloco de licença no topo da página, e clique em Activate (veja License key).
4. No PayPal Developer Dashboard, crie um aplicativo de API REST (sandbox e/ou produção) e copie o Client ID e o Secret dele para a seção API credentials.
5. Escolha Capture ou Authorize, ative Enable/Disable e clique em Save.
6. Teste com uma conta compradora de sandbox do PayPal; depois desative Sandbox mode e informe as credenciais de produção.
OpenCart 4
1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_paypal_gateway.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão do nome do arquivo, e um pacote renomeado não funciona.
2. O pacote aparece na lista de extensões instaladas na mesma página. Clique em Install (o botão verde +) ao lado dele.
3. Acesse Extensions > Extensions e escolha o tipo Payments. Localize VibeFox PayPal Gateway, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).
4. Informe a chave de licença, as credenciais do PayPal e a ação de pagamento seguindo as etapas 3 a 6 do OpenCart 3. A página de configurações e seus campos são os mesmos nas duas versões. A extensão não altera a extensão do PayPal que vem com o OpenCart 4: as duas podem ser instaladas na mesma loja.
Uma nova instalação começa com o método de pagamento desativado e o sandbox ativado.
Configuração
Todas as configurações estão na página da extensão: Extensions > Extensions > Payments > VibeFox PayPal Gateway > Edit. As seções aparecem à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, 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. Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.
Ao salvar, Title não pode estar vazio (até 128 caracteres), Sort Order precisa ser um número inteiro (números negativos são permitidos), Total precisa ser um número igual ou maior que 0, e os status de pedido precisam existir. Se alguma verificação falhar, nada é salvo e a página lista os erros. Salvar as configurações descarta os tokens de acesso do PayPal em cache, para que as novas credenciais sejam usadas imediatamente.
Geral
Enable/Disable: Enable PayPal Gateway 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 salvo no pedido. Padrão: PayPal. Obrigatório, até 128 caracteres.
Description: o texto mostrado ao cliente na etapa Confirm Order, acima do botão do PayPal. Padrão: Pay with your PayPal account or a card via PayPal.
Sort Order: a posição do PayPal entre os métodos de pagamento na finalização de compra. Deixe em branco ou digite um número inteiro.
Geo Zone: oferece o PayPal somente para endereços de pagamento na zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones.
Total: o total da finalização de compra, na moeda padrão da loja, que o pedido precisa atingir antes de o PayPal ser oferecido. Deixe em branco para oferecer o PayPal com qualquer total.
API credentials
Crie um aplicativo de API REST no PayPal Developer Dashboard e copie o Client ID e o Secret. A seção tem links para os aplicativos de sandbox e para os aplicativos de produção. Somente os campos do modo selecionado são exibidos; as credenciais dos dois modos continuam salvas.
Sandbox mode: os pagamentos vão ao sandbox do PayPal com as credenciais de sandbox; nenhum dinheiro real é movimentado. Padrão: ativado. Desative para aceitar pagamentos reais. Capturas, anulações e reembolsos sempre usam o ambiente em que o pedido foi pago. Enquanto estiver ativado, o cliente vê Sandbox mode: pay with a PayPal sandbox buyer account — no real money is charged. na etapa Confirm Order.
Sandbox Client ID: o Client ID do seu aplicativo de API REST de sandbox.
Sandbox Secret: o Secret do seu aplicativo de API REST de sandbox.
Live Client ID: o Client ID do seu aplicativo de API REST de produção.
Live Secret: o Secret do seu aplicativo de API REST de produção.
Os segredos salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo somente se quiser alterá-lo. Para remover um segredo salvo, marque Clear the saved secret on save abaixo do campo e clique em Save.
Pagamento
Payment action: o que acontece quando o cliente aprova o pagamento. Padrão: Capture.
Pedidos
O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). O pedido só recebe um status depois que o PayPal responde à captura ou à autorização no seu servidor. Um pagamento recusado deixa o pedido sem status, e o cliente permanece na etapa Confirm Order. Cada campo abaixo lista os seus status de pedido do OpenCart.
Order Status After Payment: a captura foi concluída, também quando uma autorização é capturada ou uma captura pendente é concluída na aba do pedido. Padrão: Processando.
Awaiting Payment Status: a captura está PENDING no PayPal (análise do pagamento, valores ainda não liberados). Padrão: Pendente.
Authorized Status: ação de pagamento Authorize: os valores estão reservados, mas ainda não pagos. Padrão: Pendente.
On Hold (Review) Status: o PayPal cobrou valores, mas o pagamento não pôde ser lido, ou o valor ou a moeda não correspondem ao pedido. Uma observação explica o que verificar. Padrão: Pendente, porque o OpenCart não tem um status On hold. Você pode criar seus próprios status em System > Localisation > Order Statuses e selecioná-los aqui.
Voided Status: a autorização foi anulada na aba do pedido e os valores reservados foram liberados. Padrão: Cancelado.
Refunded Status: o pagamento está totalmente reembolsado. Reembolsos parciais apenas acrescentam uma observação. Padrão: Reembolsado.
Failed Status: uma captura pendente foi recusada pelo PayPal. Padrão: Falhou.
Avançado
Debug log: registra as requisições à API em wc_plg_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web e, ao atingir 5 MB, é movido para wc_plg_debug.old.log.php. Erros e avisos são sempre registrados, mesmo com esta chave desativada. Credenciais, tokens e dados dos compradores nunca são registrados. Padrão: desativado.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: quando ativado, desinstalar a extensão remove as configurações do gateway e o log. Os tokens em cache são sempre removidos. Os dados de pagamento dos pedidos (IDs do PayPal dos pedidos e reembolsos) são sempre mantidos, para que pedidos pagos antes ainda possam ser reembolsados, capturados ou anulados após uma reinstalação. Padrão: desativado.
Importar / Exportar
Export: Download JSON salva as configurações em um arquivo JSON. Os segredos não são exportados.
Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. Os segredos salvos são mantidos.
Finalização de compra
Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, PayPal). O OpenCart cria o pedido na etapa Confirm Order, ainda sem status. Ali o cliente vê a sua descrição e o botão do PayPal. Um clique no botão cria no seu servidor um pedido no PayPal pelo total do pedido, na moeda do pedido. O valor é sempre calculado no servidor, nunca no navegador. No OpenCart 4, o cliente escolhe o método de pagamento com o botão Choose do bloco do método de pagamento, na janela Payment method options; a descrição e o botão do PayPal aparecem então no bloco de confirmação no fim da página de finalização de compra, com o botão Confirm Order.
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 conclui o pedido sozinha. Se o cliente clicar em Confirm Order sem aprovar um pagamento, a mensagem é Please click the PayPal button and approve the payment first.
Em seguida, o seu servidor lê o pedido no PayPal e verifica se ele está aprovado, se foi criado nesta finalização de compra, se não pertence a outro pedido e se o valor e a moeda correspondem ao pedido. Só então o pagamento é capturado (ou autorizado). O pedido só é marcado como pago depois que o PayPal confirma. Ele recebe então o seu status da forma padrão do OpenCart, com os e-mails habituais do pedido e a atualização do estoque; o carrinho é esvaziado e o cliente vê a página de sucesso do pedido do OpenCart.
Se o total do pedido mudou 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 pedido fica sem status e o cliente é orientado a clicar de novo no botão do PayPal ou a escolher outra forma de pagamento. 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 fica guardada para este carrinho, mesmo depois de recarregar a página: a finalização de compra mostra PayPal payment approved. Click "Confirm Order" to complete it. e Confirm Order a usa novamente. Se o PayPal já tiver concluído a tentativa anterior, esse pagamento é usado e uma nova aprovação não é capturada. Se o pagamento foi cobrado, mas não foi possível definir o status do pedido, 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 define o status a partir do pagamento guardado, sem cobrar novamente.
O OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida, e o OpenCart 4 atualiza o pedido da finalização de compra, então o pagamento pertence ao carrinho: uma aprovação feita para um pedido anterior do mesmo carrinho paga o pedido atual se o total for o mesmo, e um carrinho já pago nunca é cobrado de novo. Uma alteração no carrinho, inclusive uma nova quantidade, conta como um novo carrinho que precisa de pagamento próprio. O script do PayPal só é carregado do PayPal na etapa Confirm Order e em seu próprio namespace, para não conflitar com outra extensão do PayPal na página.
O OpenCart 4 mantém o pedido da finalização de compra até que a página de sucesso seja exibida. Se esse pedido foi fechado entretanto (por exemplo, você o cancelou ou a captura pendente foi recusada), ou se já foi pago por um carrinho anterior, o cliente vê Your previous order of this checkout is already closed or paid. Please refresh the page and confirm the order again — a new order will be created. Depois de recarregar a página, o próximo pagamento paga um novo pedido. Um pedido pago nunca é mostrado como pago para outro carrinho.
A extensão não tem webhooks do PayPal, mensagens de 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 OpenCart, e não um endereço do PayPal.
Pedidos e reembolsos
Status de pedido
Sem status (pedido ausente): o cliente não aprovou o pagamento, ou o PayPal o recusou. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders.
Status do pedido após o pagamento (padrão Processando): a captura foi concluída. Uma observação mostra o valor, o pedido no PayPal e a captura.
Status autorizado (padrão Pendente): o pagamento foi autorizado e aguarda a captura (ação de pagamento Authorize).
Status de aguardando pagamento (padrão Pendente): a captura está PENDING no PayPal, por exemplo em análise de pagamento.
Status em análise (padrão Pendente): o valor ou a moeda pagos diferem do pedido, ou o pagamento não pôde ser lido na resposta do PayPal. A observação explica isso. Confira o pedido e atenda-o ou reembolse o valor pago.
Status anulado (padrão Cancelado): a autorização foi anulada com Void PayPal authorization.
Status com falha (padrão Falhou): uma captura pendente foi recusada ou falhou.
Status reembolsado (padrão Reembolsado): o pagamento foi totalmente reembolsado pela extensão.
Se chegar um segundo pagamento para um carrinho que já está pago, o pedido pago não é alterado. Uma observação pede que você verifique isso na sua conta do PayPal e faça o reembolso.
As observações são entradas do History do pedido que o cliente não vê. As alterações de status feitas na aba do pedido (captura, anulação, consulta de status, reembolso) são gravadas diretamente, sem avisar o cliente e sem alterar o estoque.
Aba VibeFox PayPal Gateway
Em Sales > Orders, abra um pedido pago com PayPal. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox PayPal Gateway mostra o PayPal order ID e a intenção, com a etiqueta Sandbox nos pagamentos de sandbox, o Capture ID (com link para o pagamento na sua conta do PayPal, sandbox ou produção), o Authorization ID, o Status do pagamento, o Amount, os valores Paid / refunded, o histórico de reembolsos e as PayPal notes do pedido. A aba é exibida para usuários que têm acesso à extensão; os botões dela exigem o direito de modificar a extensão (definido em System > Users > User Groups). O resultado de cada ação é mostrado na aba.
Reembolsos
Na aba VibeFox PayPal Gateway, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um Reason (optional, sent to the buyer), e clique em Refund via PayPal. Confirme a pergunta Refund this amount through PayPal? This cannot be undone. São aceitos reembolsos totais e parciais. O motivo é enviado ao PayPal como uma nota para o comprador. Os reembolsos são feitos no valor e na moeda que o PayPal cobrou; assim, após uma divergência de valor ou de 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), então as credenciais desse ambiente precisam estar configuradas. Se o PayPal não aceitar o reembolso, a aba mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é incluído no histórico de reembolsos e nas observações, 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 Status. Um reembolso parcial não altera o status.
Um pagamento apenas autorizado não pode ser reembolsado: use Void PayPal authorization no lugar. As devoluções de produtos em Sales > Returns não devolvem dinheiro pelo PayPal. Reembolsos, contestações e estornos feitos na sua conta do PayPal não são sincronizados com o OpenCart.
Chave de licença
A extensão funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox PayPal Gateway é o primeiro bloco em Extensions > Extensions > Payments > VibeFox PayPal Gateway > Edit, acima das configurações. Cole 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: opencart-payment-paypal e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel administrativo (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 que você liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, a extensão continua funcionando com o último status conhecido.
Uma chave funciona em um domínio: o endereço da loja nas configurações do OpenCart. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, o PayPal não é mostrado aos clientes na finalização de compra. Se mesmo assim um pagamento for iniciado, a loja recusa criar o pedido no PayPal e o cliente vê An error occurred during PayPal checkout. Please try again. Um usuário administrador conectado ao painel administrativo no mesmo navegador ainda vê o método de pagamento na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa prévia não está disponível: a loja não vê o login do administrador, então sem uma chave ativa o método de pagamento fica oculto para todos. Depois que você abrir uma vez a página Edit, um lembrete aparece no Dashboard do painel administrativo. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: os reembolsos e as ações da aba do pedido continuam funcionando.
Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática quando você abre o Dashboard do painel administrativo ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário nenhum cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.
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á ativado, se o Client ID e o Secret do modo selecionado estão preenchidos, se a moeda do pedido é suportada pelo PayPal e se o total do pedido é maior que zero. A página de configurações mostra um aviso quando as credenciais ou a moeda da loja são o problema. Verifique também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.
O pagamento foi feito, mas o pedido continua sem status: a extensão 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 não foi possível definir o status do pedido. Ative o Debug log e consulte o campo Log, verifique o pagamento na sua conta do PayPal, ou deixe o cliente tentar de novo: uma nova tentativa nunca cobra duas vezes e define o status a partir do pagamento guardado.
Não foi possível carregar o PayPal: o script do PayPal não foi carregado no navegador, por exemplo porque uma extensão do navegador bloqueia www.paypal.com ou por um problema de rede.
O PayPal não está disponível no momento: as credenciais estão incorretas ou pertencem ao outro modo. Copie novamente o Client ID e o Secret do aplicativo correto.
Sua aprovação do PayPal não pôde ser associada a esta finalização de compra: o pedido no PayPal não foi criado nesta finalização, por exemplo depois que a sessão expirou. O cliente clica de novo no botão do PayPal.
Sua sessão expirou. Atualize a página e tente novamente: a página de finalização de compra ficou aberta por tempo demais. O cliente recarrega a página.
Este pagamento já está em processamento: o mesmo carrinho foi enviado duas vezes no mesmo momento. O cliente aguarda um momento e verifica o e-mail antes de tentar novamente.
O pedido está em análise ou pendente após o pagamento: leia as observações na aba VibeFox PayPal Gateway. 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).
A captura de uma autorização falha: a autorização pode ter mais de 29 dias ou já ter sido anulada. A aba e as observações mostram o erro do PayPal.
Não há botões na aba: a aba informa o motivo: o seu grupo de usuários não tem o direito de modificar a extensão, o pagamento está totalmente reembolsado, ou o Client ID e o Secret do ambiente em que o pagamento foi feito não estão configurados.
O reembolso falha: o pedido não tem uma captura do PayPal (apenas uma autorização), o valor supera o que resta a reembolsar, ou as credenciais do ambiente em que o pagamento foi feito estão ausentes. A aba indica qual é o caso.
Desinstalação
Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox PayPal Gateway. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as configurações próprias da extensão: Enable/Disable, Sort Order, Geo Zone, Total e os status de pedido da seção Orders, que voltam aos padrões em uma reinstalação. Os tokens de acesso do PayPal em cache são sempre removidos. Se Delete data on uninstall estiver ativado, as demais configurações do gateway (título, descrição, modo sandbox, credenciais, ação de pagamento, registro de log) e o log são removidos. Se estiver desativado, elas são mantidas para uma reinstalação futura. As transações e os reembolsos do PayPal são sempre mantidos, então pedidos pagos antes podem ser reembolsados, capturados ou anulados mesmo depois de uma reinstalação. Os pedidos existentes mantêm suas observações de pagamento.
No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox PayPal Gateway na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.
PayPal é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pelo PayPal.