VibeFox Quickpay for WooCommerce — Ajuda

Requisitos

WordPress: 6.2 ou superior.

WooCommerce: 7.1 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

Conta Quickpay: você precisa de dois valores do gerenciador do Quickpay: a chave de API de um usuário de API (para criar pagamentos, capturar e reembolsar) e a chave privada da conta (para verificar a assinatura dos callbacks do Quickpay). Nada mais precisa ser configurado no Quickpay. Seu site precisa estar acessível pela internet, sem senha ou modo de manutenção, para que os callbacks do Quickpay possam chegar.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.

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_quickpay_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > Quickpay > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Cole a chave de API e a chave privada do gerenciador do Quickpay e clique em Test API key (veja Configuração).

6. Escolha o modo de captura e o status do pedido após o pagamento, ative Enable/Disable e salve. Enquanto sua conta Quickpay estiver em modo de teste, ative Test payments e faça um pagamento com um cartão de teste do Quickpay.

Configuração

Todas as configurações ficam em uma página: WooCommerce > Settings > Payments > Quickpay. Até que a chave de API e a chave privada sejam preenchidas, o Quickpay aparece como precisando de configuração na lista de métodos de pagamento e fica oculto na finalização de compra, pois um pagamento não poderia ser criado nem confirmado.

Geral

Enable/Disable: Enable Quickpay 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: Quickpay.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely by card or MobilePay on the Quickpay payment page.

Credenciais da API do Quickpay

No gerenciador do Quickpay (manage.quickpay.net), abra Settings > Integration. Copie a chave de API de um usuário de API (Settings > Users) e a chave privada da conta. A seção também mostra a URL de callback da sua loja, que tem o formato https://your-site/wc-api/qpg_quickpay/. Ela é enviada automaticamente com cada pagamento, então nada precisa ser configurado no Quickpay.

API key: a chave de API de um usuário de API do Quickpay. É usada para criar pagamentos, capturar e reembolsar.

Abaixo do campo, o botão Test API key verifica a chave digitada no campo (ou a salva, se o campo estiver vazio) com uma requisição autenticada ao Quickpay. Ele responde Connection successful — the API key is valid., Quickpay rejected the API key., API key is not configured. ou Connection failed: seguido do motivo.

Private key: a chave privada da conta. Ela é usada para verificar a assinatura (HMAC-SHA256) dos callbacks do Quickpay. Sem ela nenhum pagamento pode ser confirmado, e os callbacks são rejeitados.

Test payments: Accept payments made with Quickpay test cards. O Quickpay não tem sandbox separado: enquanto sua conta Quickpay estiver em modo de teste, os pagamentos são feitos com cartões de teste e marcados como tal. Ative isso somente durante os testes. Quando está desativado, um pagamento de teste nunca marca um pedido como pago, e o pedido recebe uma nota. Quando está ativado, a finalização de compra mostra Test mode: Quickpay test cards are accepted. Padrão: desativado.

Pagamento

Capture: quando o dinheiro é retirado do cartão.

Order status after payment: o status do pedido assim que o Quickpay confirma o pagamento capturado. O status é definido de uma vez, com uma única mudança de status e um único conjunto de e-mails.

Avançado

Debug log: Enable logging. O log fica em WooCommerce > Status > Logs, origem wcp_quickpay_gateway. Erros e avisos, como callbacks rejeitados e erros da API do Quickpay, são sempre registrados. Ative para registrar também cada requisição e callback. Chaves de API, dados de cartão e dados de clientes nunca são registrados. Padrão: desativado.

Delete data: Delete the gateway settings and logs when the plugin is deleted. Desativar o plugin nunca apaga nada. Os dados do pedido (IDs de pagamento do Quickpay, notas) são sempre mantidos. Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Quickpay, exibido com os ícones de Visa e Mastercard) e faz o pedido. O plugin cria para o pedido um pagamento Quickpay na moeda do pedido e um link de pagamento pelo total do pedido, e envia o cliente à janela de pagamento do Quickpay. O cliente paga ali com um dos métodos ativados na sua janela de pagamento do Quickpay. O e-mail de cobrança é passado ao Quickpay. A janela de pagamento abre no idioma do seu site quando o Quickpay oferece esse idioma (dinamarquês, alemão, inglês, espanhol, finlandês, francês, italiano, holandês, norueguês, polonês, sueco), caso contrário em inglês.

Depois de pagar, o cliente volta para a página de pedido recebido da sua loja. O retorno em si não marca nada como pago. O pedido só é marcado como pago depois que o Quickpay o confirma com o callback assinado e o valor e a moeda conferem com o pedido. Com Authorize only, o pedido passa a Em espera, e você captura o pagamento depois.

Se o cliente cancelar na janela de pagamento durante a finalização de compra, o pedido não pago é cancelado da forma padrão do WooCommerce e o carrinho é restaurado. Na página Pay for order, o cancelamento devolve o cliente a essa página, então o pedido continua pagável. Um pagamento com falha ou cancelado pode ser tentado novamente: a nova tentativa reutiliza o pagamento Quickpay do pedido com um link novo, então um link antigo nunca pode ser pago em paralelo. Quando um pedido não pago é cancelado, o link de pagamento dele é excluído no Quickpay.

Se o pagamento não puder ser iniciado, o cliente vê The Quickpay payment could not be started. Please try again or choose another payment method. O motivo técnico é adicionado às notas do pedido e ao log. Se as chaves estiverem faltando, o cliente vê Quickpay is not available at the moment. Please choose another payment method.

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).

O plugin aceita apenas pagamentos únicos. Não há assinaturas nem pagamentos recorrentes, cartões salvos, taxas de pagamento, não envia itens do carrinho ou linhas de fatura ao Quickpay e não tem métodos separados de MobilePay, Apple Pay ou Klarna: o cliente escolhe entre os métodos da sua janela de pagamento do Quickpay.

Pedidos e reembolsos

Status do pedido

Pending payment: o cliente foi enviado ao Quickpay e ainda não pagou. Com captura automática, um pagamento autorizado aguardando a captura fica registrado no pedido.

Processing or Completed: o Quickpay confirmou o pagamento capturado com o valor e a moeda corretos. O status segue Order status after payment. A nota do pedido mostra o ID do pagamento Quickpay (marcado como TEST em pagamentos de teste), e ele é salvo como ID da transação do pedido.

On hold: o pagamento está apenas autorizado e aguarda Capture Quickpay payment; ou o Quickpay informou um valor ou moeda diferente do total do pedido (por exemplo, o pedido foi editado depois que o pagamento começou, ou um valor diferente foi capturado no gerenciador do Quickpay); ou a captura falhou e o valor ainda está apenas reservado. A nota do pedido explica isso, também quando o pedido já estava em espera.

Failed: a tentativa de pagamento foi recusada. O cliente pode pagar novamente.

Cancelled: o cliente cancelou na janela de pagamento, o pedido foi cancelado por você ou pelo tempo limite de reserva de estoque do WooCommerce, ou o pagamento foi cancelado no gerenciador do Quickpay.

Um pagamento recebido para um pedido que já está pago, cancelado ou reembolsado não altera o pedido. Uma nota pede que você verifique o pagamento no gerenciador do Quickpay, por exemplo para reembolsar um pagamento duplicado.

Captura

Com Authorize only, abra o pedido, escolha Capture Quickpay payment nas ações do pedido e clique no botão de atualizar. O total do pedido é capturado; a captura parcial não está disponível. Se o Quickpay confirmar imediatamente, o pedido é marcado como pago. Caso contrário, uma nota informa que a captura foi solicitada, e o pedido é marcado como pago quando o callback do Quickpay confirmar. Uma captura recusada é exibida na tela do pedido e anotada no pedido.

Cancelar um pedido autorizado não libera automaticamente o valor reservado. A nota do pedido lembra você de cancelar o pagamento no gerenciador do Quickpay; caso contrário, a reserva termina quando a autorização expira.

Reembolsos

Abra o pedido, clique em Refund, informe o valor e clique em Refund via Quickpay. Reembolsos totais e parciais são suportados para pagamentos capturados. O Quickpay processa reembolsos de forma assíncrona: uma nota informa que o reembolso foi solicitado, e o callback adiciona o resultado final, confirmed ou FAILED com o motivo. Se o Quickpay recusar o reembolso imediatamente, o WooCommerce mostra o erro e nenhum reembolso é registrado. Um pagamento autorizado que nunca foi capturado não pode ser reembolsado; cancele-o no gerenciador do Quickpay.

Pagamentos e reembolsos feitos diretamente no gerenciador do Quickpay são apenas anotados no pedido. Eles não são registrados automaticamente como reembolsos do WooCommerce. Se necessário, crie um reembolso manual no WooCommerce sem usar Refund via Quickpay.

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 > Quickpay. 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 inserir 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 de domínio dela. Libere a vaga na sua conta da vibefox.net.

Sem uma chave ativa, o Quickpay não é mostrado 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 captura e reembolsos funcionam.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática em segundo plano.

Solução de problemas

O Quickpay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se API key e Private key estão preenchidas. Sem as duas chaves, o método fica oculto.

O pagamento foi feito, mas o pedido continua Pending payment: o callback do Quickpay não chegou à sua loja ou foi rejeitado. Verifique se o seu site está acessível pela internet (sem proteção por senha ou modo de manutenção) e se Private key é a chave privada da mesma conta Quickpay. Callbacks rejeitados são sempre registrados em WooCommerce > Status > Logs, origem wcp_quickpay_gateway. Ative o Debug log para ver cada callback.

O log mostra Callback rejected: invalid checksum.: a chave privada nas configurações não pertence à conta que enviou o callback. Copie-a novamente em Settings > Integration no gerenciador do Quickpay.

O log mostra Callback rejected: the private key is not configured.: insira a chave privada. Os callbacks nunca são aceitos sem ela.

O log mostra Callback: no order found for payment …: o callback pertence a um pagamento Quickpay que nenhum pedido desta loja conhece, por exemplo um pagamento criado fora do WooCommerce ou para um pedido excluído.

O log mostra Callback: order #… is locked by another request.: outro callback do mesmo pedido estava sendo aplicado naquele momento. O callback recebe uma resposta de erro, então não é considerado tratado. Se o pedido continuar sem alterações, verifique o pagamento no gerenciador do Quickpay.

Um pagamento de teste não marcou o pedido como pago: Test payments está desativado. A nota do pedido diz que o pagamento de teste não foi aceito. Ative a opção durante os testes e desative quando sua conta entrar em produção.

O pedido está On hold após o pagamento: leia a nota do pedido. O pagamento pode estar apenas autorizado e aguardando Capture Quickpay payment, o valor ou a moeda pagos podem ser diferentes do pedido, ou a captura falhou. Capture, processe o pedido ou reembolse o pagamento no gerenciador do Quickpay.

Test API key says Quickpay rejected the API key.: a chave está errada ou pertence a um usuário sem acesso à API. Copie a chave de API de um usuário de API no gerenciador do Quickpay.

O cliente vê The Quickpay payment could not be started.: abra as notas do pedido ou o log. A nota mostra o erro do Quickpay, por exemplo uma moeda que a sua conta Quickpay não aceita.

O reembolso falha: o pedido precisa ter um pagamento Quickpay capturado. A mensagem The Quickpay payment of this order has not been captured — there is nothing to refund. significa que o pagamento está apenas autorizado; cancele-o no gerenciador do Quickpay.

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 para o 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 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 e os logs do plugin (arquivos de log, incluindo os rotacionados, e entradas de log no banco de dados) são removidos somente se Delete data estiver ativado. Caso contrário, permanecem para uma reinstalação posterior. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

O Quickpay é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado nem endossado pelo Quickpay.