VibeFox Conekta 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.

Moeda: a moeda do carrinho deve ser MXN ou USD. Para outras moedas, o método de pagamento fica oculto.

Conta Conekta: você precisa das chaves privadas de API da sua conta Conekta (teste e produção) e de um webhook no painel da Conekta (veja Configuração). Somente as chaves privadas são usadas. A chave pública 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 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 Conekta Gateway na lista de módulos e clique em Configure.

3. Informe 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 suas chaves privadas de teste e de produção, escolha o modo e adicione o webhook no painel da Conekta (veja Configuração).

5. Ative Enable / Disable e clique em Save. Teste um pagamento no modo de teste e depois desative Test mode.

Ao ser instalado, o módulo cria dois status de pedido, Awaiting Conekta payment e Conekta payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-lo em Payment > Preferences.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Conekta 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 a Conekta está ativada, mas a chave privada do modo atual está vazia (nesse caso o método de pagamento fica oculto na finalização de compra), e quando a moeda padrão da loja não é MXN nem USD. Enquanto o modo de teste estiver ativado, ela mostra O modo de teste está ativado: os pagamentos são simulados com a chave privada de teste. Ao salvar um gateway ativado sem a chave do modo atual, um aviso pede que você a informe.

Conekta

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. Também é o nome do método de pagamento salvo no pedido. Padrão: Conekta. Obrigatório.

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: card, cash and bank transfer. Dinheiro, SPEI e BNPL estão disponíveis somente para pedidos em MXN (pedidos em USD aceitam apenas cartões) e precisam estar habilitados na sua conta Conekta. Se nada for selecionado, o cartão é usado e a página avisa você ao salvar.

Credit / debit card: pagamento com cartão.

Cash (OXXO and other stores): o cliente recebe uma referência e paga em dinheiro em uma loja.

Bank transfer (SPEI): o cliente recebe uma referência e paga por transferência bancária.

Buy now, pay later (BNPL): pagamento por uma opção BNPL, se estiver habilitada na sua conta Conekta.

Chaves de API

Copie suas chaves privadas do painel da Conekta em Developers > API keys. As chaves de teste e de produção são diferentes.

Test mode: usa a chave privada de teste. Nenhum dinheiro real é cobrado, e um selo TEST MODE com Nenhuma cobrança real será feita. aparece abaixo do método de pagamento 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 chave privada de API do modo de teste da sua conta Conekta.

Live private key: a chave privada de API do modo de produção da sua conta Conekta. Mantenha-a em sigilo.

As chaves salvas nunca são exibidas novamente. O campo fica vazio e mostra Salva — deixe vazio para mantê-la. Digite um novo valor somente se quiser alterá-la.

Clear saved keys: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.

Cada pedido na Conekta guarda 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 a sua loja sobre pagamentos, por exemplo pagamentos por OXXO ou SPEI feitos depois que o cliente saiu da página da Conekta. No painel da Conekta, vá em Developers > Webhooks e adicione a URL exibida no campo Webhook da seção API keys, tanto para o modo de teste quanto para o de produção. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_conekta_gateway/webhook, possivelmente com um código de idioma, como /en/. Copie a URL exatamente como as configurações a mostram.

Selecione estes eventos (eles também estão listados nas configurações):

order.paid: o pedido foi pago.

order.pending_payment: o pedido aguarda pagamento, por exemplo quando uma referência OXXO ou SPEI foi emitida.

order.declined: o pagamento foi recusado.

order.expired: a finalização ou a referência de pagamento expirou.

order.canceled: o pedido na Conekta foi cancelado.

order.refunded: o pagamento foi reembolsado, por exemplo no painel da Conekta.

order.charged_back: o cliente contestou o pagamento (chargeback); o módulo adiciona uma nota ao pedido.

O corpo do webhook apenas informa ao módulo qual pedido na Conekta foi alterado. Cada notificação é verificada lendo o pedido novamente pela API da Conekta com a chave privada do seu modo; o cabeçalho de assinatura Digest do webhook não é usado. Notificações de pedidos na Conekta que não foram criados por esta loja para aquele carrinho são confirmadas e ignoradas. Sem o webhook, um pedido só é criado quando o cliente volta para a loja depois de pagar, ou na próxima tentativa de pagamento do mesmo carrinho.

Avançado

Debug log: registra chamadas de API e notificações em logs/wc_ckt_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados, mesmo quando esta opção está desativada. Os logs nunca contêm chaves de API nem dados de contato do cliente. 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 o módulo remove as configurações e o log. As transações e os reembolsos da Conekta, os status de pedido e os pedidos são sempre mantidos, para que pedidos antigos possam ser confirmados e 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, Conekta) e confirma. O módulo cria um pedido na Conekta pelo total do carrinho na moeda do carrinho, com os produtos, embrulho para presente, descontos, impostos e frete, e envia o cliente para a página de pagamento hospedada pela Conekta. O pagamento aparece na página da Conekta como Order # e o número do carrinho. Ali o cliente paga com um dos métodos permitidos. Nesse momento, ainda não existe pedido.

Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que a Conekta confirma: o módulo lê o pedido na API da Conekta quando o webhook chega e quando o cliente retorna. Só então o pedido é criado, e o cliente vê a página padrão de confirmação do pedido com Recebemos o seu pagamento com a Conekta. Quando o cliente escolheu OXXO ou SPEI e recebeu uma referência de pagamento, o pedido é criado como Awaiting Conekta payment e a página mostra A sua referência de pagamento da Conekta foi emitida. O pedido será confirmado assim que o pagamento for recebido. Se a referência expirar depois, o pedido é cancelado e a sua página de confirmação mostra O seu pagamento pela Conekta não foi concluído. Entre em contato conosco sobre este pedido.

Se o pagamento ainda não puder ser confirmado quando o cliente voltar, uma página de Confirmação de pagamento mostra Estamos confirmando o seu pagamento com a Conekta. O pedido será atualizado automaticamente — por favor, não pague novamente. e um botão Check again. O webhook cria o pedido assim que chega.

Se o pagamento for recusado, nenhum pedido é criado e o cliente volta à finalização de compra com O pagamento pela Conekta não foi concluído. Tente novamente ou escolha outro método de pagamento. Se a finalização expirou ou foi cancelada, a mensagem é O pagamento pela Conekta expirou ou foi cancelado. Tente novamente. O carrinho é mantido. Quando o cliente paga de novo, uma página de pagamento da Conekta ainda aberta, com o mesmo valor, é reutilizada; caso contrário, a anterior é cancelada na Conekta antes de ser criada uma nova, para que um link antigo não possa ser pago duas vezes. Se a página anterior já tiver sido paga, o pedido é criado em vez de cobrar novamente.

Se a Conekta não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo Não foi possível iniciar o pagamento. Tente novamente em instantes ou escolha outro método de pagamento. Mensagens de validação enviadas pela Conekta, como um valor mínimo, são exibidas como a Conekta as envia. O motivo técnico é gravado no log.

O webhook funciona com a loja em modo de manutenção e não é bloqueado pela restrição de países da sua loja.

O módulo aceita pagamentos somente na página da Conekta. Não há formulário de cartão na sua página de pagamento, nem cartões salvos, assinaturas, pré-autorização e captura ou parcelamento mensal (MSI).

Pedidos e reembolsos

Status do pedido

No order yet: o cliente foi enviado à Conekta e não pagou, o pagamento foi recusado ou a Conekta ainda não confirmou o pagamento. Existe apenas o carrinho.

Payment accepted: a Conekta confirmou o pagamento com o mesmo valor e moeda. O pagamento é registrado com o ID da cobrança da Conekta como ID da transação, e uma nota mostra o método de pagamento (por exemplo, a bandeira do cartão e os quatro últimos dígitos, OXXO / dinheiro ou transferência SPEI), o pedido na Conekta e a cobrança.

Awaiting Conekta payment: o cliente recebeu uma referência de pagamento OXXO ou SPEI. O pedido passa para Payment accepted quando a Conekta informa o pagamento.

Conekta payment on hold: o valor ou a moeda recebidos da Conekta não correspondem ao carrinho (por exemplo, o carrinho foi alterado depois que o pagamento começou), chegou um pagamento em modo de teste enquanto a loja estava em modo de produção (nenhum dinheiro real foi recebido), ou o pagamento chegou para um pedido que já estava cancelado. A nota explica o motivo, e o pagamento é registrado com o valor efetivamente pago. Verifique o pedido e, em seguida, processe-o ou reembolse o pagamento. Um pedido apenas pré-autorizado na Conekta também fica retido, com uma nota para capturá-lo ou cancelá-lo no painel da Conekta.

Canceled: a referência OXXO ou SPEI de um pedido pendente expirou, ou o pedido na Conekta foi cancelado.

Refunded: o pagamento foi reembolsado integralmente pelo módulo.

Um pedido pago ou reembolsado nunca é rebaixado nem reaberto. Se chegar outro pagamento da Conekta para um pedido que já está pago, uma nota WARNING pede que você o reembolse no painel da Conekta.

Bloco de pagamento da Conekta

A página do pedido mostra um bloco Conekta payment com o pedido na Conekta, a cobrança, o status do pagamento, o valor pago e reembolsado, um selo Test mode para pagamentos de teste, o histórico de reembolsos e as Conekta notes do pedido.

Reembolsos

No bloco Conekta payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Conekta. Confirme a pergunta Reembolsar este valor pela Conekta? Esta ação não pode ser desfeita. Reembolsos totais e parciais são suportados. Você precisa ter permissão para editar pedidos. Os reembolsos são limitados ao valor e à moeda que a Conekta de fato cobrou; por isso, após uma divergência de valor, você pode reembolsar até o que o cliente pagou, e não o total do pedido. O reembolso vai para o pedido na Conekta que contém o pagamento e usa a chave do modo em que o pagamento foi feito, então essa chave precisa estar configurada. Se a Conekta não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o valor, o modo, o pedido na Conekta, o ID do reembolso e o motivo. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis depois que a Conekta informa o pagamento.

O módulo não gera notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Conekta.

Reembolsos feitos no painel da Conekta chegam pelo webhook e são adicionados como nota, com o valor reembolsado na Conekta e no PrestaShop. Eles não são registrados automaticamente. Atualize o pedido manualmente, sem usar Refund via Conekta. Um chargeback informado pela Conekta também é adicionado como nota.

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 Conekta Gateway é o primeiro bloco de Modules > Module Manager > VibeFox Conekta Gateway > 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 ficam a linha Product: presta-payment-conekta e o link Gerenciar licenças e domínios na sua conta, que abre a sua conta 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 de 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 vibefox.net.

Sem uma chave ativa, a Conekta não é exibida aos clientes na finalização de compra. Se, mesmo assim, um pagamento for iniciado, o cliente vê Este método de pagamento não está disponível. Escolha outro. 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ê: é possível 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 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 Conekta não aparece na finalização de compra: verifique se a licença está ativa, se Enable / Disable está ativado, se a chave privada do modo atual está preenchida (Test private key no modo de teste, Live private key no modo de produção) e se a moeda do carrinho é MXN ou USD. A página de configurações mostra um aviso quando a chave está faltando ou quando a moeda da loja não é compatível. 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: 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 exibida nas configurações e se os eventos estão selecionados. Confira se a chave privada desse modo está preenchida, porque cada notificação é verificada com ela. O pedido também é criado quando o cliente volta à loja ou quando tenta pagar de novo o mesmo carrinho.

O webhook responde Temporarily unavailable: não foi possível acessar a API da Conekta, a chave privada do modo do pedido está faltando, outra requisição estava processando o carrinho, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A Conekta tenta o webhook novamente. Veja o campo Log para o motivo.

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 na Conekta que não foi criado por esta loja para aquele carrinho (por exemplo, outra loja ou um link de pagamento na mesma conta), ou a um objeto que não é um pedido.

A URL do webhook mostra Method not allowed no navegador: isso é normal. A URL aceita apenas requisições da Conekta.

O cliente vê Não foi possível verificar o status da sua tentativa de pagamento anterior: a página de pagamento anterior da Conekta do carrinho não pôde ser lida, então uma nova não é criada para evitar pagamento duplicado. Tente novamente em instantes.

O cliente vê O gateway de pagamento não está configurado: a chave privada do modo atual está faltando.

O cliente vê A verificação do pagamento falhou: o link de retorno da Conekta não correspondeu ao carrinho. Verifique o pedido no painel da Conekta; o webhook continua confirmando um pagamento real.

O pedido está em Awaiting Conekta payment ou Conekta payment on hold: leia as Conekta notes no bloco do pedido. O cliente ainda não pagou a referência OXXO ou SPEI, o valor ou a moeda não correspondiam, chegou um pagamento em modo de teste enquanto a loja estava em modo de produção, ou o pagamento está apenas pré-autorizado.

O reembolso falha com uma mensagem sobre modo de teste ou de produção: o pagamento foi feito nesse modo, e a chave privada dele não está preenchida. Informe-a e tente novamente.

Para desenvolvedores, o README lista os hooks actionWcpConektaSupportedCurrencies, actionWcpConektaOrderRequest, actionWcpConektaAllowedPaymentMethods e actionWcpConektaRefundReason.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Conekta 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 e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. As transações e os reembolsos da Conekta e os status de pedido Awaiting Conekta payment e Conekta payment on hold são sempre mantidos, para que 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 Conekta é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Conekta.