VibeFox Culqi for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 6.0 ou superior, instalado e ativo. O plugin se recusa a ativar sem ele.

PHP: 8.0 ou superior.

Moeda da loja: sol peruano (PEN) ou dólar americano (USD). A Culqi não aceita outras moedas, e o método de pagamento fica oculto na finalização de compra para qualquer outra moeda da loja.

Conta na Culqi: você precisa da chave pública e da chave secreta da sua conta na Culqi. As chaves de integração (teste) vêm de integ-panel.culqi.com, e as de produção (live) de mipanel.culqi.com, em CulqiPanel > Desarrollo > API Keys. A chave pública é usada pelo pop-up da Culqi no navegador. A chave secreta é usada apenas no seu servidor e nunca é enviada ao navegador. Nenhum webhook é necessário.

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

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > Culqi > 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. Cole as chaves de integração e, para pagamentos reais, as chaves de produção (veja Configuração).

6. Ative Enable/Disable. Mantenha Test Mode ativado enquanto testa e depois desmarque-o para receber pagamentos reais.

7. Confirme que a moeda da loja é PEN ou USD.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Culqi. Acima dos campos, a página mostra Test mode is active: the integration keys are used and no real money is charged. enquanto o modo de teste está ativado. Ela avisa quando o gateway está ativado mas faltam as chaves do modo atual, e quando a moeda da loja não é compatível com a Culqi. Nos dois casos, o método de pagamento fica oculto na finalização de compra. Na lista de métodos de pagamento, a Culqi aparece marcada como precisando de configuração até que as duas chaves do modo atual sejam definidas.

Geral

Enable/Disable: Enable Culqi Payment Gateway liga ou desliga o método de pagamento. Padrão: desligado.

Title: o nome do método de pagamento que os clientes veem na finalização de compra. Padrão: Credit/Debit Card or Yape (Culqi).

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely with your credit/debit card or Yape via Culqi.

Chaves de API

Copie as chaves de CulqiPanel > Desarrollo > API Keys: chaves de integração (teste) em integ-panel.culqi.com, chaves de produção em mipanel.culqi.com. O modo de teste usa apenas as chaves de teste, e o modo de produção apenas as chaves de produção. Cada chave deve começar com o prefixo do seu campo. Uma chave com prefixo errado não é salva: a página mostra um erro e mantém o valor anterior.

Test Mode: Use the Culqi integration (test) environment. Quando ativado, as chaves de teste (pk_test_ / sk_test_) são usadas e nenhum dinheiro real é cobrado. Padrão: ativado. Desmarque-o para receber pagamentos reais com as chaves de produção.

Test Public Key: a chave pública do ambiente de integração. Começa com pk_test_.

Test Secret Key: a chave secreta do ambiente de integração. Começa com sk_test_ e nunca é compartilhada com o navegador.

Live Public Key: a chave pública do ambiente de produção. Começa com pk_live_.

Live Secret Key: a chave secreta do ambiente de produção. Começa com sk_live_ e nunca é compartilhada com o navegador.

Se você atualizar da versão 1.0, o único par de chaves dessa versão é movido para os campos de teste ou de produção de acordo com o prefixo. Confira as chaves após a atualização.

Métodos de pagamento

Os cartões são sempre oferecidos. Transferência bancária, agentes, carteiras e Cuotéalo exigem a Culqi Orders API e não são oferecidos por este plugin.

Yape: Offer Yape in the Culqi popup mostra o Yape ao lado dos cartões na janela da Culqi. Padrão: ativado.

Avançado

Debug log: Log API requests and payment steps grava detalhes em WooCommerce > Status > Logs, origem wcp_culqi_payment. Os erros são sempre registrados. Chaves, dados do cartão e dados do cliente nunca são registrados. Padrão: desligado.

Delete Data on Uninstall: Delete the gateway settings and logs when the plugin is deleted. Desativar o plugin nunca apaga nada. Os dados da Culqi salvos nos pedidos são sempre mantidos. Padrão: desligado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Credit/Debit Card or Yape (Culqi)) e clica no botão de finalizar o pedido. O pop-up do Culqi Checkout abre na mesma página com o nome da sua loja, o total do pedido e a moeda. Ali o cliente digita os dados do cartão ou paga com Yape. Enquanto o modo de teste está ativado, o método de pagamento mostra TEST MODE: No real charges will be made.

A Culqi transforma os dados de pagamento em um token de uso único, e a finalização de compra é enviada à sua loja com esse token. Seu servidor cria a cobrança com a Culqi Charges API pelo total do pedido na moeda do pedido, com o número do pedido na descrição da cobrança. O pedido só é marcado como pago depois que a Culqi confirma a cobrança e o valor e a moeda cobrados coincidem com o pedido. Em seguida, o cliente vai para a página de pedido recebido.

Se o banco exigir 3-D Secure, o cliente vê Your bank requires additional verification (3-D Secure). Please complete it in the window that opens. Após a autenticação, a cobrança é enviada novamente de forma automática. Se a verificação não for concluída, o cliente vê The 3-D Secure verification was not completed. Please try again or use another card.

Se o cartão for recusado, o cliente vê a mensagem da Culqi, por exemplo Payment failed: seguida do motivo, e pode tentar novamente com outro cartão. Se a Culqi não responder, o cliente vê We could not confirm your payment with Culqi. Please check your email or contact us before trying again. Se o cliente fechar a janela da Culqi, nada é cobrado, o cliente vê The payment window was closed before the payment was completed. e pode fazer o pedido novamente.

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. Ele é compatível com o armazenamento de pedidos de alto desempenho (HPOS) do WooCommerce.

O plugin aceita apenas pagamentos únicos com cartão e Yape, capturados imediatamente. Não há códigos PagoEfectivo ou CIP, app bancário, agentes, carteiras ou Cuotéalo, nem cartões salvos, assinaturas ou parcelamento, nem webhooks da Culqi, nem autorização e captura separadas.

Pedidos e reembolsos

Status do pedido

Pending payment: o pedido foi criado mas ainda não foi cobrado, ou a Culqi não respondeu. Nesse caso, uma nota diz Culqi did not confirm the charge. Procure no CulqiPanel uma cobrança deste pedido antes de aceitar outro pagamento.

Processing: o pagamento foi confirmado (o padrão do WooCommerce; pedidos apenas com produtos virtuais para download passam para Concluído). A nota do pedido mostra o ID da cobrança da Culqi, o modo (teste ou produção) e se o 3-D Secure foi usado. O ID da transação é o ID da cobrança da Culqi.

On hold: a Culqi informou uma cobrança cujo valor ou moeda não corresponde ao pedido, ou um pagamento que foi autorizado mas não capturado. A nota do pedido explica e mostra o ID da cobrança. Confira a cobrança no CulqiPanel e conclua ou reembolse o pedido manualmente.

Failed: o cartão foi recusado. A nota do pedido mostra o motivo, o código da recusa e o ID da cobrança. O cliente pode pagar novamente com outro cartão.

Um pedido que já está pago ou que já tem uma cobrança da Culqi, inclusive um pedido com status Aguardando, nunca é cobrado de novo. Apenas uma solicitação de pagamento por pedido é processada por vez.

Reembolsos

Abra o pedido, clique em Refund, informe o valor e clique em Refund via Culqi. Reembolsos totais e parciais são aceitos. O reembolso é enviado com as chaves do modo em que o pagamento foi feito (teste ou produção), mesmo que você tenha trocado de modo desde então, portanto a chave secreta desse modo precisa estar definida. Se a Culqi 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 ID do reembolso da Culqi, o valor e o motivo.

Reembolsos feitos no CulqiPanel não são sincronizados de volta com o WooCommerce. Se necessário, crie um reembolso manual no WooCommerce sem Refund via Culqi.

Chave de licença

O plugin funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Culqi. 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 domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, a Culqi 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 logados 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 Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: os reembolsos continuam funcionando.

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 Culqi não aparece na finalização de compra: confira se a licença está ativa, se Enable/Disable está ligado, se as duas chaves do modo atual estão definidas (Test Public Key e Test Secret Key no modo de teste, Live Public Key e Live Secret Key no modo de produção) e se a moeda da loja é PEN ou USD. A página de configurações mostra um aviso em cada um desses casos.

O pagamento foi concluído, mas o pedido continua em Pending payment: o plugin não usa webhooks. A cobrança só é confirmada pela resposta da Culqi ao seu servidor. Se a Culqi não respondeu a tempo, a nota do pedido diz Culqi did not confirm the charge. Encontre a cobrança deste pedido no CulqiPanel e, se ela existir, conclua o pedido manualmente.

O pedido está em On hold após o pagamento: leia a nota do pedido. O valor ou a moeda cobrados eram diferentes do pedido, ou o pagamento não foi capturado. Confira a cobrança no CulqiPanel (o ID dela está na nota) e depois conclua ou reembolse o pedido.

A chave não é salva: o erro diz que o campo deve começar com um prefixo, por exemplo sk_live_. Cada campo aceita apenas chaves do seu próprio tipo e modo: pk_test_, sk_test_, pk_live_ ou sk_live_.

O cliente vê Payment gateway misconfiguration. Please contact the store owner.: as chaves do modo atual estão ausentes, ou a Culqi rejeitou a chave secreta. Confira as chaves nas configurações.

O cliente vê Payment token is invalid. Please try again.: o token da janela da Culqi pertence ao outro modo, por exemplo após alternar Test Mode com a página de finalização de compra aberta. O cliente deve recarregar a página e pagar novamente.

A janela da Culqi não abre: o cliente vê The Culqi payment window could not be loaded. Please reload the page and try again. Confira se os scripts de js.culqi.com e 3ds.culqi.com não estão bloqueados na sua página de finalização de compra, por exemplo por um plugin de otimização.

O cliente vê This order is already being paid: outra solicitação de pagamento do mesmo pedido estava em andamento no mesmo momento. O cliente deve esperar e verificar o e-mail antes de tentar novamente.

O reembolso falha com uma mensagem sobre as chaves: o pagamento foi feito no modo de teste ou de produção, e a chave secreta desse modo não está definida. Informe-a e tente novamente.

O bloco de licença mostra um erro: siga a mensagem do bloco. Por exemplo, se a chave já está 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 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.

Para desenvolvedores, a documentação do plugin lista os filtros culqi_p_supported_currencies, culqi_p_charge_data, culqi_p_icon e culqi_p_lock_timeout.

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 e os logs só são removidos se Delete Data on Uninstall estava ativado. Caso contrário, eles ficam para uma reinstalação posterior. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

Culqi é uma marca registrada do respectivo proprietário. Este plugin não é afiliado à Culqi nem endossado por ela.