VibeFox OpenPay for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não ativa sem ele.
PHP: 8.0 ou superior.
HTTPS: seu site precisa usar HTTPS, pois 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 plugin 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 WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_openpay_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > OpenPay > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Digite sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Escolha o Account country e informe as chaves de sandbox e de produção (veja Configuração).
6. Recomendado: adicione a URL do webhook no painel da OpenPay (veja Configuração).
7. Ative Enable / Disable e salve. Teste um pagamento com os cartões de teste do sandbox da OpenPay e depois desmarque Sandbox mode para receber pagamentos reais.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > OpenPay. Acima dos campos, a página avisa quando as chaves do modo atual estão incompletas (nesse caso o método de pagamento fica oculto na finalização de compra), quando a moeda da 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. Na lista de métodos de pagamento, a OpenPay aparece como pendente de configuração até que o modo atual tenha as três chaves, e um selo de modo de teste é exibido 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.
Geral
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. Padrão: Credit or debit card (OpenPay).
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_) estão 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: Use the OpenPay sandbox (test keys, no real charges) alterna tanto as chaves quanto a API para o sandbox. Um selo SANDBOX MODE é exibido na finalização de compra enquanto estiver ativo. Padrão: ativado. Desmarque para receber pagamentos reais.
Sandbox Merchant ID: o Merchant ID do painel do sandbox, Settings (Configuración), chaves de API.
Sandbox Private Key: a chave privada do sandbox. Começa com sk_. É usada somente 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 da versão 1.0 do plugin (um conjunto de chaves e um indicador de sandbox) são movidas automaticamente para os campos de sandbox ou de produção.
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 nesta seção das configurações. Ela tem a forma https://your-site/wc-api/webhook_wc_openpay/. 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 essa URL. O código aparece nesta seção com a data de chegada, para que você possa confirmar o webhook no painel da OpenPay.
Selecione estes eventos:
A OpenPay não assina os webhooks, por isso o plugin nunca confia na notificação em si. Ele só a usa para localizar a cobrança e depois relê a cobrança na API da OpenPay com a chave privada do modo em que o pedido foi pago. Uma notificação de uma cobrança que esta loja não criou é ignorada.
Avançado
Debug log: Log payment steps (errors are always logged) grava as etapas do pagamento em WooCommerce > Status > Logs, origem wcp_openpay_gateway. Erros e avisos são registrados mesmo quando desativado. Chaves, dados do cartão e dados do cliente nunca são registrados. Padrão: desativado.
Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Padrão: desativado.
Finalização de compra
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). Ao fazer o pedido, o openpay.js transforma o cartão em um token de uso único no navegador, e a biblioteca antifraude da OpenPay adiciona um ID de sessão do dispositivo. Somente esses dois valores são enviados à sua loja.
Em seguida, o plugin cria a cobrança com 3D Secure pelo total do pedido, na moeda do pedido, e envia o cliente à página de 3D Secure do banco dele, servida pela OpenPay. Cada tentativa recebe sua própria referência de pedido na OpenPay (o número do pedido e um sufixo curto). A descrição da cobrança é Order #, o número do pedido e o nome do seu site. Nome, e-mail e telefone do cliente são enviados à OpenPay; nenhuma conta de cliente é criada na OpenPay. O pedido permanece em Pagamento pendente enquanto o cliente está na página do 3D Secure.
Quando o cliente volta, o plugin 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 pedido, estar concluída e corresponder exatamente ao total e à moeda do pedido. Se o resultado ainda não for conhecido, a página de pedido recebido mostra We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. Em seguida, o webhook atualiza o pedido.
Se o cartão for recusado ou o 3D Secure falhar, o cliente volta à página Pay for order com a mensagem The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. e pode pagar novamente. Antes de uma nova tentativa, o plugin verifica a cobrança anterior do pedido: se ela de fato estiver paga, o pedido é marcado como pago sem uma segunda cobrança; se ainda estiver em processamento, o cliente vê que um pagamento anterior ainda está sendo processado e não deve pagar de novo; se o status não puder ser verificado, nenhuma nova tentativa é feita e o cliente é orientado a tentar novamente em alguns minutos.
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 as notas do pedido e para o log.
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. É compatível com o WooCommerce High-Performance Order Storage (HPOS). Fica oculto na finalização de compra quando está desativado, quando as chaves do modo atual estão incompletas ou quando a moeda do pedido não é aceita pelo país da conta.
O plugin aceita apenas pagamentos com cartão, com captura imediata. Não há cartões salvos, assinaturas, parcelamento sem juros (MSI) ou parcelado, pagamento com pontos do cartão, dinheiro, SPEI, PSE ou CoDi, nem autorização e captura separadas.
Pedidos e reembolsos
Status do pedido
Pagamento pendente: o cliente está na página do 3D Secure ou não concluiu o pagamento. Uma nota mostra o ID da cobrança.
Processando: o pagamento foi confirmado. É o status padrão do WooCommerce após o pagamento; pedidos com apenas produtos virtuais para download passam a Concluído. A nota do pedido mostra o ID da cobrança e o modo (produção ou sandbox). O ID da transação é o ID da cobrança na OpenPay.
Em espera: a cobrança está em andamento e ainda não foi capturada; ou a OpenPay informa uma cobrança concluída com valor ou moeda diferentes do pedido (o pedido não é marcado como pago e a nota mostra a diferença); ou chegou um pagamento para um pedido que já havia sido cancelado. Confira o pedido no painel da OpenPay e conclua-o ou reembolse o pagamento por lá.
Falhou: o cartão foi recusado ao criar a cobrança, ou a última tentativa falhou, foi cancelada ou expirou. O cliente pode pagar novamente.
Se chegar uma segunda cobrança concluída para um pedido que já está pago, o pedido não é alterado. Uma nota que começa com WARNING pede que você reembolse a duplicata no painel da OpenPay.
Reembolsos
Para contas do México e do Peru: abra o pedido, clique em Refund, informe o valor e clique em Refund via Credit or debit card (OpenPay) (o botão mostra o título do seu método de pagamento). Reembolsos totais e parciais são aceitos. O reembolso é enviado no modo e no país da conta em que o pedido foi pago, então mantenha preenchidas as chaves do sandbox enquanto houver pedidos de sandbox a reembolsar. Se a OpenPay não aceitar o reembolso, o WooCommerce mostra o erro, por exemplo OpenPay refund failed: ..., e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o ID de reembolso da OpenPay.
A OpenPay Colômbia não oferece reembolsos de cartão pela API, assim como nos plugins oficiais da OpenPay. Para a Colômbia, o botão de reembolso não é oferecido; reembolse a cobrança no painel da OpenPay.
Reembolsos e contestações feitos no painel da OpenPay chegam por webhook e são adicionados uma única vez às notas do pedido. Eles não são registrados automaticamente como reembolsos do WooCommerce. Se necessário, crie um reembolso manual no WooCommerce, sem usar o botão da OpenPay.
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 > OpenPay. 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 informar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta na 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 vaga na sua conta na 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. Os gerentes da loja conectados ainda veem o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem a renovação. O status é verificado de novo automaticamente em segundo plano.
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 do sandbox no modo sandbox e as de produção no modo produção. Verifique se a moeda da loja é 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.
O pagamento foi feito, mas o pedido continua em Pagamento pendente: o cliente não voltou da página do 3D Secure e o webhook não está funcionando. Verifique se a URL do webhook está adicionada no painel da OpenPay do modo que você usa, exatamente como as configurações mostram, com os eventos listados acima. Verifique se as chaves do modo em que o pedido foi pago estão preenchidas: sem elas, o webhook responde not configured e a OpenPay tenta novamente mais tarde.
O webhook responde ignored (unknown order): a cobrança não foi criada por esta loja para este pedido, por exemplo uma cobrança de outra loja na mesma conta 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 pedido estava sendo atualizado por outra requisição no mesmo momento. A OpenPay tenta o webhook novamente.
O cliente vê «The secure card form could not be loaded»: o openpay.js ou a biblioteca antifraude da OpenPay não carregaram no navegador, ou o ID da 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á nas notas do pedido e no log, origem wcp_openpay_gateway. Uma causa comum é um Merchant ID ou uma chave privada incorretos. Se a OpenPay não respondeu, verifique a cobrança no painel da OpenPay antes que o cliente pague novamente.
«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 fica Em espera após o pagamento: leia a nota do pedido. A cobrança ainda está em andamento, o valor ou a moeda pagos diferem do pedido, ou o pagamento chegou depois que o pedido foi cancelado.
O reembolso falha com uma mensagem sobre o modo: o pedido foi pago no modo sandbox ou de produção, e as chaves desse modo não estão configuradas. Informe-as e tente de novo.
O bloco de licença mostra um erro: siga a mensagem do bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta da 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, o código de verificação do webhook armazenado e os logs do plugin só são removidos se Delete data on uninstall estava ativado. Caso contrário, eles ficam guardados para uma reinstalação futura. Os dados dos pedidos são sempre mantidos: os pedidos existentes conservam suas notas de pagamento, IDs de transação e os dados de cobrança necessários para reembolsos após uma reinstalação.
A OpenPay é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela OpenPay.