VibeFox 2C2P 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 2C2P: você precisa do Merchant ID e da Secret Key da sua conta de comerciante 2C2P. Eles são emitidos pela 2C2P quando a sua conta de comerciante é aberta. Contas sandbox e de produção têm chaves diferentes. A documentação para desenvolvedores e os cartões de teste do sandbox estão em developer.2c2p.com.
Moeda: a moeda do carrinho deve ser compatível com o módulo e estar ativada na sua conta 2C2P. São compatíveis, entre outras, THB, SGD, MYR, PHP, IDR, VND, MMK, KHR, LAK, CNY, HKD, TWD, JPY, KRW, INR, AUD, NZD, USD, EUR e GBP. Se a moeda do carrinho não for compatível, o método de pagamento fica oculto na finalização de compra.
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 2C2P Payment 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. Informe o seu Merchant ID e a sua Secret Key de sandbox, ative Enable/Disable, clique em Save e faça um pedido de teste.
5. Quando estiver pronto, informe as credenciais de produção e desative Sandbox Mode.
Ao ser instalado, o módulo cria dois status de pedido: Awaiting 2C2P payment e 2C2P payment on hold. O PrestaShop habilita o novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode restringir isso em Payment > Preferences. As URLs de retorno e de notificação são enviadas em cada pagamento. Nada precisa ser configurado no portal da 2C2P.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox 2C2P Payment > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, a página mostra Sandbox mode is active. No real transactions will be processed. enquanto o modo sandbox estiver ativo. Ela avisa quando o gateway está ativado, mas o Merchant ID ou a Secret Key do modo atual estão vazios, e quando a moeda padrão da loja não é compatível. Nos dois casos, o método de pagamento fica oculto na finalização de compra. Se você salvar com Sandbox Mode desativado, o módulo mostra Please enter your live Merchant ID. ou Please enter your live Secret Key. caso algum campo de produção esteja vazio. As configurações são salvas mesmo assim.
2C2P
Enable/Disable: Enable 2C2P Payment Gateway liga ou desliga o método de pagamento. Padrão: desligado.
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: 2C2P Payment.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely via credit/debit card, e-wallet, or internet banking through 2C2P. No modo sandbox, (TEST MODE) é acrescentado ao texto.
Modo de teste (sandbox)
Sandbox Mode: envia os pagamentos para o sandbox da 2C2P (demo2.2c2p.com) com as credenciais de sandbox abaixo. Padrão: ligado. Desative para receber pagamentos reais.
Sandbox Merchant ID: o seu Merchant ID de sandbox da 2C2P.
Sandbox Secret Key: a sua Secret Key de sandbox da 2C2P.
Credenciais da API de produção
Usadas quando o modo sandbox está desativado.
Merchant ID: o seu Merchant ID de produção da 2C2P.
Secret Key: a sua Secret Key de produção da 2C2P. A chave é salva exatamente como foi informada, incluindo aspas e barras invertidas.
As Secret Keys salvas nunca são mostradas novamente. O campo fica vazio e exibe Saved — leave empty to keep it. Digite um novo valor apenas se quiser alterá-la.
Limpar segredos salvos: marque Sandbox Secret Key ou Secret Key e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Os resultados são sempre verificados com o Merchant ID e a Secret Key do modo em que o pagamento foi feito. Um pagamento iniciado no modo sandbox continua sendo verificado com a chave de sandbox depois que você muda para produção, e um resultado assinado com a chave do outro modo é rejeitado.
Página de pagamento
URLs de resultado: mostra, para referência, a Frontend return URL e a Backend notification URL. Com URLs amigáveis, elas têm este formato: https://your-shop/module/wcp_2c2p_payment/return e https://your-shop/module/wcp_2c2p_payment/notify, possivelmente com um código de idioma como /en/. Elas são enviadas automaticamente em cada pagamento.
Payment Page Language: o idioma da página de pagamento da 2C2P. Padrão: English.
Redirect API version: mantenha 8.5, a menos que a 2C2P tenha informado que a sua conta ainda usa a versão antiga 7.0 (assinaturas SHA-1). Os resultados de pagamentos iniciados antes de uma troca continuam sendo verificados.
Order ID prefix: opcional, somente letras e dígitos (máximo de 10), por exemplo SHOP1. A 2C2P rejeita um ID de pedido que já tenha recebido. Defina um prefixo exclusivo quando várias lojas compartilharem uma conta 2C2P e no sandbox, onde as contas de comerciante de teste são compartilhadas. Os demais caracteres são removidos ao salvar, com um aviso.
Configurações avançadas
Enable Logging: grava os eventos da 2C2P em logs/tc2p_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Nenhum dado de cartão, chave secreta, e-mail de cliente ou token de pagamento é registrado. Padrão: desligado. Enquanto estiver desligado, nada é gravado, nem mesmo erros.
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 e o log. As transações, os pedidos e os status de pedido do módulo na 2C2P sempre são mantidos, então um resultado atrasado de um pagamento antigo continua sendo processado após uma reinstalação. Padrão: desligado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, 2C2P Payment) e confirma. A página seguinte mostra Thank you for your order. You will be redirected to 2C2P to complete your payment. e envia o cliente à página de pagamento da 2C2P depois de um instante. Se isso não acontecer, o cliente clica em Pay via 2C2P. A página também tem um botão Back to checkout. Neste ponto, ainda não existe nenhum pedido.
Na página da 2C2P, o cliente paga com qualquer método ativado na sua conta 2C2P, por exemplo cartões, carteiras digitais, pagamentos por QR code, internet banking ou pagamentos em dinheiro. O módulo envia o total do carrinho na moeda do carrinho, o e-mail do cliente e os nomes dos produtos do carrinho. O pagamento pode ser concluído em até 24 horas. Cada tentativa de pagamento recebe o seu próprio ID de pedido na 2C2P (o número do carrinho e o número da tentativa, depois do prefixo opcional), porque a 2C2P nunca aceita o mesmo ID de pedido duas vezes.
A 2C2P informa o resultado duas vezes: o navegador do cliente volta para a loja, e a 2C2P envia uma notificação servidor a servidor. Os dois são tratados da mesma forma. O pedido só é marcado como pago depois que a 2C2P confirma com uma assinatura válida. O resultado também precisa pertencer ao pagamento: o ID de pedido na 2C2P precisa ter sido emitido pela sua loja, e o Merchant ID e o token aleatório da tentativa são verificados. Resultados sem assinatura válida são rejeitados. A notificação funciona mesmo com a loja em modo de manutenção e não é bloqueada pela restrição de países da sua loja.
Depois de um pagamento bem-sucedido, o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Your 2C2P payment has been received. Para um pagamento pendente, a página mostra Your 2C2P payment is pending (for example a cash or bank payment that is not made yet). The order will be processed as soon as 2C2P confirms the payment. Para um pedido em espera, mostra Your payment was received and is being reviewed by the shop. Se um pagamento pendente for cancelado depois, mostra Your 2C2P payment was not completed. Please contact us about this order.
Se o pagamento não foi concluído, nenhum pedido é criado. O cliente volta à finalização de compra com a mensagem Payment was not completed. Please try again or choose a different payment method. O carrinho é mantido, e o cliente pode pagar de novo ou escolher outro método de pagamento. Se o resultado não puder ser confirmado, o cliente vê We could not confirm the payment result. If your account was charged, please contact us before paying again. Se o pagamento não puder ser iniciado, por exemplo porque a moeda do carrinho não é compatível, a mensagem é This payment method is currently unavailable for this order. Please contact us or choose another payment method.
Se o carrinho já tiver um pedido (pago ou aguardando um pagamento pendente), nenhum segundo formulário de pagamento é gerado. O cliente é enviado à página de confirmação do pedido.
O módulo não faz reembolsos pelo PrestaShop, não salva cartões, não processa pagamentos recorrentes ou assinaturas, não tem campos de cartão no seu site e não oferece suporte à API 2C2P PGW 4.x.
Pedidos
Status do pedido
No order yet: o cliente foi enviado à 2C2P e nenhum resultado chegou ainda, ou o pagamento falhou. Só existe o carrinho.
Payment accepted: a 2C2P informou um pagamento bem-sucedido (status 000). O pagamento é registrado com a referência da transação da 2C2P como ID da transação. Uma nota privada no pedido mostra a transação na 2C2P, o código de aprovação, a data e o canal de pagamento.
Awaiting 2C2P payment: o pagamento está pendente na 2C2P (status 001), por exemplo um pagamento em dinheiro que o cliente ainda não fez. O pedido passa para Payment accepted quando a 2C2P informa o pagamento.
2C2P payment on hold: a 2C2P informou um valor ou uma moeda diferente do total do pedido. A nota mostra os valores recebidos e os esperados. Verifique o pedido e a transação no portal da 2C2P.
Canceled: um pagamento pendente foi depois recusado, cancelado ou falhou (status 002, 003, 999). A nota mostra o status e o motivo. Um resultado de falha de uma tentativa anterior não cancela um pedido criado por outra tentativa.
Um pedido pago nunca é alterado por um resultado posterior, e um resultado antigo repetido não reabre um pedido que foi cancelado. Se chegar um segundo pagamento para um pedido que já está pago, o pedido não muda. Uma nota pede que você verifique e reembolse a duplicata no portal de comerciante da 2C2P.
Bloco de pagamento da 2C2P
A página do pedido mostra um bloco 2C2P payment com o ID do pedido na 2C2P, a transação, o status do pagamento, o canal, o código de aprovação, o número do cartão mascarado, a data, a resposta do canal e o valor recebido, além de um selo Sandbox para pagamentos de sandbox.
Reembolsos
Reembolsos pelo PrestaShop não são suportados. Reembolse o pagamento no portal de comerciante da 2C2P e, em seguida, registre o reembolso manualmente no 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 2C2P Payment é o primeiro bloco de Modules > Module Manager > VibeFox 2C2P Payment > Configure, acima das configurações. Informe 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: presta-payment-2c2p 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 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, 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 vaga de domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a 2C2P 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.
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 informada e depois uma vez por semana. Não é necessário nenhum 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
A 2C2P não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se o modo atual tem Merchant ID e Secret Key: os campos de sandbox no modo sandbox, os campos de produção no modo de produção. Verifique se a moeda do carrinho é compatível. A página de configurações mostra um aviso nos dois casos. 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.
O pagamento foi feito, mas nenhum pedido foi criado: nenhum resultado válido chegou à sua loja. Verifique se o Merchant ID e a Secret Key do modo em que o pagamento foi feito correspondem à conta 2C2P, e se Redirect API version corresponde à sua conta. Um resultado com assinatura errada ou de outro Merchant ID é rejeitado. Ligue Enable Logging e procure mensagens de hash ou de Merchant ID no campo Log. Verifique também se o seu servidor aceita as requisições da 2C2P para a URL de notificação do backend.
A notificação do backend responde 400 FAIL: o resultado tem campos ausentes, assinatura errada, outro Merchant ID ou um token incorreto. 404 FAIL significa que o ID do pedido na 2C2P não foi emitido por esta loja. 503 RETRY significa que o pedido estava sendo confirmado por outra requisição no mesmo momento, ou que o pedido não pôde ser criado (por exemplo, porque o módulo está desativado); a 2C2P tentará de novo depois. Ligue Enable Logging para ver o motivo.
A URL de notificação mostra FAIL no navegador: é normal. A URL aceita apenas requisições POST da 2C2P.
A 2C2P diz que o ID do pedido já existe: a 2C2P não aceita o mesmo ID de pedido duas vezes. Isso acontece quando várias lojas compartilham uma conta 2C2P ou no sandbox, onde contas de comerciante de demonstração são compartilhadas por muitos desenvolvedores. Defina um Order ID prefix exclusivo.
Um pagamento foi feito, mas o pedido está em Awaiting 2C2P payment ou 2C2P payment on hold: ou o pagamento ainda está pendente na 2C2P (por exemplo, um pagamento em dinheiro que o cliente ainda não fez), ou o valor ou a moeda pagos não coincidiram com o pedido. Verifique as notas do pedido e a transação no portal da 2C2P.
O cliente vê This payment method is currently unavailable for this order: a moeda do carrinho não é compatível, o Merchant ID ou a Secret Key do modo atual estão vazios, ou o total do carrinho é zero.
Please enter your live Merchant ID ou Please enter your live Secret Key ao salvar: o modo sandbox está desativado e um campo de produção está vazio. Informe as credenciais de produção ou mantenha Sandbox Mode ligado.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox 2C2P Payment 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 e o log são removidos. Se estiver desligado, todas as configurações são mantidas para uma reinstalação futura. As transações da 2C2P e os status de pedido Awaiting 2C2P payment e 2C2P payment on hold são sempre mantidos. Os pedidos existentes mantêm as suas notas de pagamento e os IDs de transação.
A 2C2P é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela 2C2P.