VibeFox Conekta for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior.
Moeda: a moeda da loja precisa ser MXN ou USD. Para outras moedas, o método de pagamento fica oculto.
Conta Conekta: você precisa das Private Keys da API da sua conta Conekta (teste e produção) e de um webhook no painel da Conekta (veja Configuração). Somente as Private Keys são usadas. A Public Key não é necessária, porque o pagamento acontece na página de pagamento hospedada pela Conekta.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.
Instalação
1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_conekta_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Conekta > Manage, ou clique em Settings abaixo do nome do plugin na página de Plugins.
4. Digite a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Informe as suas Private Keys de teste e de produção, escolha o modo e adicione o webhook no painel da Conekta (veja Configuração).
6. Ative Enable / Disable e salve. Faça um pagamento de teste no modo de teste e depois desmarque Test mode.
Configuração
Todas as configurações ficam em uma só página: WooCommerce > Settings > Payments > Conekta. Acima dos campos, a página avisa quando a Conekta está ativada, mas a Private Key do modo atual está vazia (o método de pagamento fica oculto na finalização de compra), e quando a moeda da loja não é MXN nem USD. Enquanto o modo de teste está ativo, ela mostra Test mode is on: payments are simulated with the test private key. Ao salvar um gateway ativado sem a chave do modo atual, uma mensagem de erro pede que você a informe.
Geral
Enable / Disable: Enable Conekta payments 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. Padrão: Conekta.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely with card, OXXO cash or SPEI transfer. You will be redirected to Conekta to complete your payment.
Payment methods: os métodos oferecidos na página de pagamento da Conekta. Padrão: cartão, dinheiro e transferência bancária. Dinheiro, SPEI e BNPL estão disponíveis somente para pedidos em MXN (pedidos em USD aceitam apenas cartões) e precisam estar ativados na sua conta Conekta. Se nada for selecionado, o cartão é usado.
Chaves de API
Copie as suas Private Keys do painel da Conekta em Developers > API keys. As chaves de teste e de produção são diferentes.
Test mode: Enable test mode usa a Private Key de teste. Nenhum dinheiro real é cobrado, e um selo TEST MODE aparece na finalização de compra. Os reembolsos sempre usam a chave do modo em que o pagamento foi feito. Padrão: ativado.
Test private key: a Private Key da API do modo de teste da sua conta Conekta.
Live private key: a Private Key da API do modo de produção da sua conta Conekta. Mantenha-a em segredo.
Cada pedido da Conekta lembra o seu modo: notificações e reembolsos usam a chave correspondente. Mantenha as duas chaves preenchidas enquanto houver pedidos de teste antigos em aberto.
Webhook
O webhook informa à sua loja sobre pagamentos feitos depois que o cliente saiu da página da Conekta, por exemplo pagamentos por OXXO ou SPEI. No painel da Conekta, acesse Developers > Webhooks e adicione a URL mostrada nesta seção para o modo de teste e para o modo de produção. Ela tem este formato: https://your-site/wc-api/webhook_wc_conekta/.
Selecione estes eventos:
O corpo do webhook apenas informa ao plugin qual pedido da Conekta foi alterado. Cada notificação é verificada relendo o pedido na API da Conekta com a Private Key do seu modo; o cabeçalho de assinatura Digest do webhook não é usado. Notificações de pedidos da Conekta que não foram criados por esta loja para aquele pedido são aceitas e ignoradas. Sem o webhook, um pedido só é confirmado quando o cliente volta à loja após pagar, ou na próxima tentativa de pagamento do mesmo pedido.
Avançado
Debug log: Log API calls and notifications grava detalhes em WooCommerce > Status > Logs, origem wcp_conekta_gateway. Erros são sempre registrados. Os logs nunca contêm chaves de API nem dados de contato do cliente. Padrão: desativado.
Delete data on uninstall: Remove the settings, Conekta order references 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 Conekta) e faz o pedido. O plugin cria um pedido na Conekta pelo total do pedido na moeda do pedido, com os itens, o frete, os impostos e os descontos, e envia o cliente para a página de pagamento hospedada pela Conekta. Lá o cliente paga com um dos métodos permitidos.
Após o pagamento, o cliente volta à sua loja. O pedido só é marcado como pago depois que a Conekta confirma: o plugin lê o pedido na API da Conekta quando o webhook chega e quando o cliente retorna. Se o pagamento ainda não puder ser confirmado, a página de pedido recebido mostra We are confirming your payment with Conekta. The order will be updated automatically — please do not pay again. Quando o cliente escolheu OXXO ou SPEI e recebeu uma referência de pagamento, o pedido vai para “Aguardando” e a página mostra Your Conekta payment reference has been issued. The order will be confirmed as soon as the payment is received.
Se o pagamento for recusado, o pedido é marcado como “Malsucedido” e o cliente volta à página Pay for order com The Conekta payment was not completed. Please try again or choose another payment method. Se a página de pagamento expirou ou foi cancelada, o cliente vê The Conekta payment has expired or was cancelled. Please place the order again. Quando o cliente paga um pedido novamente, uma página de pagamento da Conekta ainda aberta, com o mesmo valor, é reutilizada; caso contrário, a anterior é cancelada na Conekta antes da criação de uma nova, para que um link antigo não possa ser pago duas vezes. Se a página anterior já tiver sido paga, o pagamento é registrado em vez de cobrar de novo.
Se a Conekta não conseguir iniciar o pagamento, o cliente vê uma mensagem curta, por exemplo The payment could not be started. Please try again in a moment or choose another payment method. O motivo técnico é gravado no 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). Os textos foram traduzidos para o espanhol (México).
O plugin aceita pagamentos somente na página da Conekta. Não há formulário de cartão na sua finalização de compra, nem cartões salvos, assinaturas, pré-autorização e captura ou parcelamento mensal (MSI).
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado para a Conekta e ainda não pagou. A nota do pedido mostra o pedido da Conekta e o modo.
Processing: a Conekta confirmou o pagamento com o mesmo valor e a mesma moeda (pedidos com apenas produtos virtuais para download passam para “Concluído”, o padrão do WooCommerce). A nota do pedido mostra o método de pagamento (por exemplo, a bandeira do cartão e os últimos quatro dígitos, OXXO / dinheiro ou transferência SPEI), o pedido da Conekta e a cobrança. O ID da transação do pedido é o ID da cobrança na Conekta (charge ID).
On hold, waiting for OXXO or SPEI: o cliente recebeu uma referência de pagamento. O pedido passa para “Processando” quando a Conekta informa o pagamento.
On hold after payment: o valor ou a moeda recebidos da Conekta não correspondem ao pedido, um pagamento em modo de teste chegou enquanto a loja estava em modo de produção (nenhum dinheiro real foi recebido), ou o pagamento chegou para um pedido já cancelado. A nota do pedido explica isso. Verifique o pagamento e depois conclua o pedido ou reembolse-o. Um pedido que está apenas pré-autorizado na Conekta também fica em “Aguardando”, com uma nota para capturar ou anular no painel da Conekta.
Failed: o pagamento foi recusado. A nota mostra o motivo. O cliente pode pagar novamente.
Cancelled: a página de pagamento atual da Conekta expirou ou foi cancelada.
Um pedido pago ou reembolsado nunca é rebaixado nem reaberto. Se chegar outro pagamento da Conekta para um pedido já pago, uma nota WARNING pede que você o reembolse no painel da Conekta.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Conekta (o botão mostra o título do método de pagamento). Reembolsos totais e parciais são aceitos. O reembolso vai para o pedido da Conekta que contém o pagamento e usa a chave do modo em que o pagamento foi feito, por isso essa chave precisa estar configurada. Se a Conekta não aceitar o reembolso, o WooCommerce mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o valor, o modo, o pedido da Conekta, o ID do reembolso e o motivo.
Reembolsos feitos no painel da Conekta chegam pelo webhook e são adicionados como nota, com o valor reembolsado na Conekta e no WooCommerce. Eles não são registrados automaticamente como reembolsos do WooCommerce. Registre-os manualmente sem usar Refund via Conekta. Um chargeback informado pela Conekta também é adicionado como nota.
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 > Conekta. 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 em vibefox.net.
Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga de domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, a Conekta 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 que estiverem conectados continuam vendo 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 de Plugins e nas páginas do WooCommerce. Os 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 renovação. O status é verificado novamente de forma automática em segundo plano.
Solução de problemas
A Conekta não aparece na finalização de compra: verifique se a licença está ativa, se Enable / Disable está ativado, se a Private Key do modo atual está preenchida (Test private key no modo de teste, Live private key no modo de produção) e se a moeda da loja é MXN ou USD. A página de configurações mostra um aviso para cada uma dessas condições.
O pagamento foi feito, mas o pedido continua em Pending payment: o webhook não está funcionando. No painel da Conekta, verifique se o webhook existe para o modo que você usa (teste ou produção), se a URL dele é exatamente a mostrada nas configurações e se os eventos estão selecionados. Verifique se a Private Key desse modo está configurada, pois cada notificação é verificada com ela. O pedido também é confirmado quando o cliente volta à loja ou quando tenta pagar o mesmo pedido novamente.
O webhook responde Temporarily unavailable: não foi possível acessar a API da Conekta, a Private Key do modo do pedido está ausente, ou o pedido estava sendo processado por outra requisição. A Conekta tenta o webhook novamente.
O webhook responde Verification failed, Invalid payload ou Invalid order id: a API da Conekta não confirmou o pedido, ou a notificação não era um evento válido de pedido da Conekta.
O webhook responde Ignored: a notificação pertence a um pedido da Conekta que não foi criado por esta loja para aquele pedido (por exemplo, outra loja ou um link de pagamento na mesma conta), ou a um objeto diferente de um pedido.
O cliente vê We could not check the status of your previous payment attempt: a página de pagamento anterior do pedido na Conekta não pôde ser lida, então uma nova não é criada para evitar pagamento duplicado. Tente novamente em instantes.
O cliente vê Payment gateway is not configured: a Private Key do modo atual está ausente.
O pedido está On hold: leia as notas do pedido. O cliente ainda não pagou a referência OXXO ou SPEI, o valor ou a moeda não correspondiam, ou um pagamento em modo de teste chegou enquanto a loja estava em modo de produção.
O reembolso falha com uma mensagem sobre modo de teste ou de produção: o pagamento foi feito nesse modo, e a Private Key dele não está configurada. Informe a chave e tente novamente.
O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta em 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.
Para desenvolvedores, o readme lista o filtro wc_ckt_supported_currencies para a lista de moedas.
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 de licença deste plugin são sempre removidos. As configurações do gateway, as referências da Conekta salvas nos pedidos e os logs são removidos somente se Delete data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
Conekta é marca de seu respectivo proprietário. Este plugin não é afiliado à Conekta nem endossado por ela.