VibeFox OpenPay 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 anteriores do PHP.
HTTPS: sua loja precisa usar HTTPS, porque o formulário de cartão fica na sua página de finalização de compra.
Conta OpenPay: uma conta OpenPay do México, da Colômbia ou do Peru. Você precisa do Merchant ID, da chave privada (sk_...) e da chave pública (pk_...). Os painéis de sandbox e de produção têm Merchant IDs e chaves diferentes, e o módulo os mantém separados.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
O cartão é digitado na sua página de finalização de compra, mas é lido e tokenizado no navegador pelo openpay.js. Os campos do cartão não têm nome e nunca são enviados ao seu servidor. Como o formulário de cartão fica na sua página, o escopo PCI DSS é SAQ A-EP; consulte sua adquirente.
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 encontre VibeFox OpenPay Gateway depois na lista de módulos e clique em Configure.
3. Cole 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. Escolha o Account country e insira as chaves de sandbox e de produção (veja Configuração).
5. Recomendado: adicione a URL do webhook no painel da OpenPay (veja Configuração).
6. Ative Enable / Disable e clique em Save. Teste um pagamento com os cartões de teste do sandbox da OpenPay e depois desative Sandbox mode para receber pagamentos reais.
Na instalação, o módulo cria dois status de pedido, Awaiting OpenPay payment e OpenPay payment on hold. O PrestaShop oferece um novo módulo de pagamento para as moedas, países e grupos de clientes da sua loja. Você pode limitá-los em Payment > Preferences.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox OpenPay Gateway > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa quando as chaves do modo atual estão incompletas (o método de pagamento fica oculto na finalização de compra), quando a moeda padrão da sua loja não é aceita pelo país da conta selecionado, e mostra Sandbox mode is enabled — no real charges are made. enquanto o modo sandbox estiver ativo.
Ao salvar, as chaves são verificadas. Um Merchant ID pode conter apenas letras e números, uma chave privada deve começar com sk_ e uma chave pública com pk_. Um valor inválido não é salvo: o valor anterior é mantido e um erro é exibido, por exemplo Sandbox: The private key must start with sk_. Se o método de pagamento estiver ativado, mas as chaves do modo atual estiverem incompletas, você também verá uma mensagem informando que o gateway continua oculto na finalização de compra. Um Title vazio é recusado com Enter a title for the payment method.
OpenPay
Enable / Disable: Enable OpenPay card payments ativa ou desativa o método de pagamento. Padrão: desativado.
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: Credit or debit card (OpenPay). Obrigatório.
Description: o texto exibido acima do formulário de cartão na finalização de compra. Padrão: Pay securely with your credit or debit card. Your bank may ask you to confirm the payment (3D Secure).
Conta OpenPay
O Merchant ID, a chave privada (sk_) e a chave pública (pk_) ficam no seu painel da OpenPay, em Settings (Configuración). A seção tem links para os painéis de sandbox e de produção do México, da Colômbia e do Peru.
Account country: o país da sua conta OpenPay. Ele define a API da OpenPay, a biblioteca openpay.js desse país e as moedas aceitas. Padrão: Mexico.
Sandbox mode: usa o sandbox da OpenPay (chaves de teste, sem cobranças reais) e troca tanto as chaves quanto a API para o sandbox. Um selo SANDBOX MODE aparece na finalização de compra enquanto estiver ativo. Padrão: ativado. Desative para receber pagamentos reais.
Sandbox Merchant ID: o Merchant ID do painel de sandbox, Settings (Configuración), chaves de API.
Sandbox Private Key: a chave privada do sandbox. Começa com sk_. É usada apenas no servidor; nunca a compartilhe.
Sandbox Public Key: a chave pública do sandbox. Começa com pk_. O openpay.js a usa no navegador para tokenizar o cartão.
Live Merchant ID: o Merchant ID do painel de produção, Settings (Configuración), chaves de API.
Live Private Key: a chave privada de produção (sk_...).
Live Public Key: a chave pública de produção (pk_...).
As chaves privadas salvas nunca são mostradas novamente. O campo fica vazio e exibe Saved — leave empty to keep it. Digite um valor novo somente se quiser alterá-lo.
Clear saved secrets: marque uma chave privada e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Webhook
O webhook não é obrigatório, mas é recomendado. Ele confirma os pagamentos quando o cliente não volta da página do 3D Secure, por exemplo depois de fechar o navegador. No painel da OpenPay, vá em Settings > Webhooks e adicione a URL mostrada em Webhook URL nesta seção. Com URLs amigáveis, ela tem a forma https://your-shop/module/wcp_openpay_gateway/webhook, possivelmente com um código de idioma como /en/. Copie-a exatamente como as configurações a mostram. Adicione o webhook no painel de cada modo que você usa (sandbox e produção).
Ao adicionar o webhook, a OpenPay envia um código de verificação para esta URL. O código aparece nesta seção com a data em que chegou, para que você possa confirmar o webhook no painel da OpenPay.
Selecione estes eventos (eles também estão listados nesta seção):
A OpenPay não assina os webhooks, então o módulo nunca confia na notificação em si. Ele a usa apenas para localizar a cobrança e depois lê a cobrança na API da OpenPay com a chave privada do modo e do país da conta em que o pagamento foi feito. Uma notificação de uma cobrança que esta loja não criou é ignorada. O webhook funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.
Avançado
Debug log: registra as etapas do pagamento em logs/wc_opy_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são registrados mesmo quando está desativado. Chaves, dados de cartão e dados do cliente nunca são registrados. Padrão: desativado.
Log: mostra o tamanho e as últimas entradas do registro. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: quando ativado, desinstalar o módulo remove as configurações do gateway, o código de verificação do webhook salvo e os registros. Os registros de cobrança da OpenPay dos pedidos são histórico de pagamentos e são sempre mantidos, para que os pedidos ainda possam ser reembolsados após uma reinstalação. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Credit or debit card (OpenPay)) e preenche Cardholder name, Card number, Expiry (MM/YY) e Card code (CVV). No modo sandbox, o formulário mostra SANDBOX MODE — Test environment. No real charges will be made. Quando o cliente confirma, o openpay.js transforma o cartão em um token de uso único no navegador, e a biblioteca antifraude adiciona um ID de sessão do dispositivo. Só esses dois valores e o número do carrinho são enviados à sua loja. Se o formulário estiver incompleto, aparece Please fill in all card fields. abaixo dele.
O módulo então cria a cobrança com 3D Secure pelo total do carrinho na moeda do carrinho e envia o cliente para a página do 3D Secure do banco dele, servida pela OpenPay. Cada tentativa recebe sua própria referência de pedido na OpenPay. A descrição da cobrança é Cart #, o número do carrinho e o nome da sua loja. O nome, o e-mail e o telefone do cliente são enviados à OpenPay; nenhuma conta de cliente é criada na OpenPay. Nenhum pedido existe ainda neste ponto.
Quando o cliente volta, o módulo lê a cobrança na API da OpenPay. O pedido só é marcado como pago depois que a OpenPay confirma: a cobrança precisa pertencer a este carrinho, estar concluída e corresponder exatamente ao total e à moeda do carrinho. Então o pedido é criado e o cliente vê a página de confirmação do pedido com Your card payment has been received. Se a OpenPay informar que a cobrança está em andamento, o pedido é criado em Awaiting OpenPay payment e a página mostra We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. Se o resultado ainda não for conhecido, uma página Payment confirmation mostra o mesmo texto com um botão Check again e um botão Back to checkout; o webhook cria o pedido assim que chegar. Se uma cobrança em andamento falhar depois, a página de confirmação do pedido mostra Your OpenPay card payment was not completed. Please contact us about this order.
Se o cartão for recusado ou o 3D Secure falhar, o cliente volta à finalização de compra com The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. e pode pagar de novo. O carrinho é mantido. Antes de uma nova tentativa, o módulo verifica a cobrança anterior do carrinho: se ela de fato foi paga, o pedido é criado a partir dela sem uma segunda cobrança; se ainda estiver em andamento, o pedido é criado em Awaiting OpenPay payment; se o estado não puder ser verificado, nenhuma nova cobrança é feita e o cliente vê We could not confirm the status of your previous payment attempt. Please try again in a few minutes. Um carrinho que já tem pedido nunca é cobrado novamente.
Cartões recusados recebem uma mensagem clara, por exemplo The card has insufficient funds. Please use another card., The card has expired. Please use another card. ou The security code (CVV) is not valid. Please check it and try again. Erros técnicos da OpenPay nunca são mostrados aos clientes; eles vão para o registro.
Se um cupom no carrinho deixar de ser válido entre o pagamento e a sua confirmação, ele é removido do pedido. O pedido então vai para OpenPay payment on hold com uma nota, porque o cliente pagou o preço com o desconto.
O método de pagamento fica oculto na finalização de compra quando está desativado, quando as chaves do modo atual estão incompletas ou quando a moeda do carrinho não é aceita pelo país da conta.
O módulo aceita apenas pagamentos com cartão, com captura imediata. Não tem cartões salvos, assinaturas, parcelamento sem juros (MSI) ou em parcelas, pagamento com pontos do cartão, dinheiro, SPEI, PSE ou CoDi, nem autorização e captura separadas.
Pedidos e reembolsos
Status do pedido
Ainda sem pedido: o cliente está na página do 3D Secure, não concluiu o pagamento ou o cartão foi recusado. Existe apenas o carrinho.
Payment accepted: o pagamento foi confirmado. O pagamento é registrado com o ID da cobrança da OpenPay como ID da transação, e uma nota mostra o ID da cobrança e o modo (produção ou sandbox).
Awaiting OpenPay payment: a OpenPay informa que a cobrança está em andamento (ainda não capturada). O pedido passa para Payment accepted quando a cobrança é concluída, ou para Payment error se ela falhar.
OpenPay payment on hold: a OpenPay informa uma cobrança concluída com valor ou moeda diferentes do carrinho (o pedido não é marcado como pago, e a nota mostra a diferença), um cupom foi removido, ou chegou um pagamento para um pedido que já havia sido cancelado ou reembolsado (o pagamento é registrado). Verifique o pedido e processe-o, ou reembolse o pagamento no painel da OpenPay.
Payment error: uma cobrança em andamento falhou, foi cancelada ou expirou.
Refunded: a cobrança foi totalmente reembolsada pelo módulo.
Se chegar uma segunda cobrança concluída para um pedido que já está pago, o pedido não é alterado. Uma nota começando com WARNING pede que você reembolse a duplicata no painel da OpenPay.
Bloco de pagamento OpenPay
A tela do pedido mostra um bloco OpenPay payment com o ID da cobrança, o status da cobrança, o ambiente e o país da conta, o valor cobrado e o total do pedido, o valor reembolsado, um selo Sandbox para pagamentos de sandbox, o histórico de reembolsos e as OpenPay notes do pedido.
Reembolsos
Para contas do México e do Peru: no bloco OpenPay payment, digite o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via OpenPay. Confirme a pergunta Refund this amount through OpenPay? This cannot be undone. Reembolsos totais e parciais são suportados, até o valor cobrado pela OpenPay. Você precisa ter permissão para editar pedidos. O reembolso é enviado com as chaves do modo e do país da conta em que a cobrança foi feita, então as chaves desse modo precisam estar configuradas: mantenha as chaves do sandbox enquanto ainda puder reembolsar pedidos de sandbox. Se a OpenPay não aceitar o reembolso, o bloco mostra o erro, por exemplo OpenPay refund failed: ..., e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o ID do reembolso da OpenPay. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status. Os reembolsos estão disponíveis somente depois que a OpenPay confirma o pagamento; um pedido em espera após divergência de valor não é reembolsado pelo módulo.
A OpenPay Colômbia não oferece suporte a reembolsos de cartão pela API, como nos plugins oficiais da OpenPay. Para cobranças colombianas, o bloco não oferece formulário de reembolso; reembolse a cobrança no painel da OpenPay.
O módulo não cria notas de crédito. Os botões padrão de reembolso do PrestaShop na tela do pedido não devolvem dinheiro pela OpenPay.
Reembolsos e contestações feitos no painel da OpenPay chegam por webhook e são adicionados às notas uma única vez. O status do pedido e as notas de crédito não são alterados automaticamente. Atualize-os manualmente, se necessário.
Chave de licença
O módulo funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença License — VibeFox OpenPay Gateway é o primeiro bloco de Modules > Module Manager > VibeFox OpenPay Gateway > Configure, 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-payment-openpay e o link Manage licenses and domains in your account, que abre a sua conta em 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 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 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 em vibefox.net.
Sem uma chave ativa, a OpenPay 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 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, e os reembolsos funcionam.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de 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. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A OpenPay não aparece na finalização de compra: verifique se a licença está ativa, se Enable / Disable está ativado e se o modo atual tem as três chaves: as chaves do sandbox no modo sandbox, as chaves de produção no modo de produção. Verifique se a moeda do carrinho é aceita pelo Account country (México: MXN, USD; Colômbia: COP, USD; Peru: PEN, USD). A página de configurações mostra um aviso em cada um desses casos. Em Payment > Preferences, verifique se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo de clientes.
O pagamento foi feito, mas nenhum pedido foi criado: o cliente não voltou da página do 3D Secure e o webhook não está funcionando. Verifique se a URL do webhook foi adicionada no painel da OpenPay do modo que você usa, exatamente como as configurações a mostram, com os eventos listados acima. Verifique se as chaves do modo em que o pagamento foi feito estão preenchidas: sem elas, o webhook responde not configured e a OpenPay tenta novamente mais tarde. O pedido também é criado quando o cliente volta para a loja ou quando tenta pagar o mesmo carrinho novamente.
O webhook responde ignored (unknown order): a cobrança não foi criada por esta loja, por exemplo uma cobrança de outra loja na mesma conta da OpenPay. Nada é alterado.
O webhook responde verification failed: não foi possível acessar a API da OpenPay para ler a cobrança. A OpenPay tenta o webhook novamente.
O webhook responde busy: o carrinho estava sendo atualizado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). A OpenPay tenta o webhook novamente. Ative o Debug log para ver o motivo.
O cliente vê The secure card form could not be loaded: o openpay.js ou a biblioteca antifraude da OpenPay não carregou no navegador, ou o ID de sessão do dispositivo não pôde ser criado. Peça ao cliente que recarregue a página e tente novamente.
O cliente vê The payment could not be processed right now: a OpenPay recusou a requisição ou não respondeu. O motivo está no registro. Um Merchant ID ou uma chave privada incorretos é uma causa comum. Se a OpenPay não respondeu, verifique a cobrança no painel da OpenPay antes que o cliente pague de novo.
O cliente vê This test card cannot be used for real payments: foi usado um cartão de teste do sandbox com o modo sandbox desativado.
O pedido está em OpenPay payment on hold após o pagamento: leia as OpenPay notes do bloco (veja Status do pedido) e depois processe o pedido ou reembolse o pagamento.
O reembolso falha com uma mensagem sobre o modo: o pedido foi pago no modo sandbox ou no de produção, e as chaves desse modo não estão configuradas. Insira-as e tente novamente.
O reembolso falha com The order is being updated right now: um webhook ou outra requisição estava atualizando o pedido no mesmo momento. Tente novamente em instantes.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox OpenPay 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 ativado, as configurações do gateway, o código de verificação do webhook salvo e os registros são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os registros de cobranças e reembolsos da OpenPay e os status de pedido Awaiting OpenPay payment e OpenPay payment on hold são sempre mantidos, para que os pedidos pagos antes ainda possam ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A OpenPay é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela OpenPay.