VibeFox Culqi for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.

Moeda da loja: sol peruano (PEN) ou dólar americano (USD). A Culqi não aceita outras moedas, e o método de pagamento só aparece para carrinhos em PEN ou USD.

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 chaves 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 somente 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 back office, acesse 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 encontre depois o VibeFox Culqi Payment na lista de módulos e clique em Configure.

3. Insira a 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. Cole as chaves de integração e, para pagamentos reais, as chaves de produção (veja Configuração).

5. Ative Enable/Disable e clique em Save. Mantenha Test Mode ativado enquanto testa e depois desative-o para receber pagamentos reais.

6. Certifique-se de que PEN ou USD é uma moeda ativa da sua loja.

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

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Culqi Payment > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. 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 estiver ativado. Ela avisa quando o gateway está ativado, mas faltam as chaves do modo atual, e quando nenhuma moeda da loja é suportada pela Culqi. Nos dois casos, o método de pagamento fica oculto na finalização de compra. Se a moeda padrão da sua loja não for PEN nem USD, a página informa que a Culqi só é oferecida para carrinhos nas moedas suportadas.

Culqi

Enable/Disable: Enable Culqi Payment Gateway 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: Credit/Debit Card or Yape (Culqi). Obrigatório.

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: as chaves de integração (teste) em integ-panel.culqi.com, as de produção em mipanel.culqi.com. O modo de teste usa somente as chaves de teste, e o modo de produção somente 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, por exemplo Live Secret Key must start with sk_live_ — the previous value was kept., e os demais campos são salvos.

Test Mode: quando ativado, são usadas as chaves de teste (pk_test_ / sk_test_) e nenhum dinheiro real é cobrado. Padrão: ativado. Desative para receber pagamentos reais com as chaves de produção. Enquanto estiver ativado, os clientes veem TEST MODE: No real charges will be made. abaixo do método de pagamento.

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.

As chaves secretas salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.

Clear saved secret keys: marque Test Secret Key ou Live Secret Key e clique em Save para removê-la. Um campo vazio mantém o valor salvo.

Métodos de pagamento

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 módulo.

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

Avançado

Debug log: registra as requisições à API e as etapas do pagamento em logs/culqi_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros, incluindo recusas de cartão com o respectivo código, são sempre registrados. Chaves, dados do cartão e dados do cliente nunca são registrados. 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 do gateway, os registros de cobranças e reembolsos da Culqi do módulo e o log. O status do pedido e os dados da Culqi nos pedidos (pagamentos, notas) são sempre mantidos. Padrão: desativado.

Finalização de compra

Na etapa de pagamento, 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 carrinho e a moeda. Ali o cliente digita os dados do cartão ou paga com Yape. Os scripts da Culqi são carregados somente na página de finalização de compra.

A Culqi transforma os dados de pagamento em um token de uso único, e o token é enviado à sua loja. O seu servidor cria a cobrança com a Culqi Charges API pelo total do carrinho, na moeda do carrinho, capturada imediatamente. A cobrança aparece no CulqiPanel como Cart e o número do carrinho, com o e-mail do cliente. Antes desse ponto, não existe pedido. O pedido só é marcado como pago depois que a Culqi confirma: o pedido é criado quando a Culqi responde com uma cobrança bem-sucedida, e o cliente vê a página padrão de confirmação do pedido.

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 carrinho é mantido em todos esses casos. As tentativas com falha são registradas no log do módulo, pois ainda não existe pedido.

Um carrinho nunca é cobrado duas vezes. Se o cliente enviar novamente enquanto um pagamento do mesmo carrinho estiver em andamento, ele vê This order is already being paid. Please wait a moment and check your email before trying again. Se a Culqi tiver cobrado o valor, mas o pedido não puder ser criado, o cliente vê Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. A cobrança é mantida, e a próxima tentativa cria o pedido a partir dela, sem uma nova cobrança.

O módulo 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

No order yet: o cartão foi recusado, o cliente fechou a janela da Culqi ou a Culqi não respondeu. Existe apenas o carrinho. O log do módulo tem os detalhes.

Payment accepted: a cobrança foi confirmada e corresponde ao carrinho. O pagamento é registrado com o ID da cobrança da Culqi (chr_...) como ID da transação, e uma nota mostra o modo (teste ou produção) e se o 3-D Secure foi usado.

Culqi payment on hold: a Culqi informou uma cobrança cujo valor ou moeda não corresponde ao carrinho, ou um pagamento autorizado, mas não capturado. A nota explica isso e mostra o ID da cobrança. Uma cobrança capturada na moeda do carrinho é registrada como pagamento do valor efetivamente cobrado. Verifique a cobrança no CulqiPanel e depois processe o pedido ou reembolse o pagamento.

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

Se chegar uma segunda cobrança para um carrinho que já tem um pedido, o pedido não é alterado. Uma nota pede que você verifique a cobrança no CulqiPanel e a reembolse, se necessário.

Bloco Culqi payment

A página do pedido mostra um bloco Culqi payment com o ID da cobrança, o valor cobrado (com 3-D Secure, se usado), um selo Test para pagamentos de teste, uma indicação de revisão para pedidos em espera, os valores pagos e reembolsados e o histórico de reembolsos.

Reembolsos

No bloco Culqi payment, informe o valor (o valor ainda não reembolsado é preenchido automaticamente), opcionalmente um motivo, e clique em Refund via Culqi. Confirme a pergunta Refund this amount through Culqi? This cannot be undone. Reembolsos totais e parciais são suportados. Você precisa da permissão para editar pedidos; o acesso aos módulos não é necessário. Os reembolsos são feitos no valor e na moeda cobrados pela Culqi, então, após uma divergência de valor, você pode reembolsar até o montante que o cliente efetivamente pagou, e não o total do pedido. 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 depois, por isso a chave secreta desse modo precisa estar configurada. Se a Culqi 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 do pedido, com o ID do reembolso da Culqi, o valor e o seu motivo. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status.

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 Culqi. Os reembolsos feitos no CulqiPanel não são sincronizados com o PrestaShop. Atualize o pedido manualmente, se necessário.

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 Culqi Payment é o primeiro bloco da página Modules > Module Manager > VibeFox Culqi Payment > Configure, acima das configurações. Cole 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-payment-culqi e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente funcionários com a permissão Configure para o 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 que você 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 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. A loja 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ê: você pode 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 uma 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 inserção da chave, 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 Culqi não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se as duas chaves do modo atual estão preenchidas (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 do carrinho é PEN ou USD. A página de configurações mostra um aviso quando faltam chaves. 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 módulo não usa webhooks. A cobrança é confirmada somente pela resposta da Culqi ao seu servidor. Se a Culqi não respondeu a tempo, o log do módulo mostra Culqi did not confirm the charge com o número do carrinho. Procure a cobrança com este cart_id no CulqiPanel. Se o cliente viu a mensagem de que o pedido não pôde ser concluído, a próxima tentativa de pagamento do mesmo carrinho cria o pedido sem cobrar novamente.

O pedido está em Culqi payment on hold após o pagamento: leia a nota no pedido. O valor ou a moeda cobrados foram diferentes do carrinho, ou o pagamento não foi capturado. Verifique a cobrança no CulqiPanel (o ID está na nota) e depois processe o pedido ou reembolse o pagamento.

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

O cliente vê Payment gateway misconfiguration. Please contact the store owner.: faltam as chaves do modo atual, ou a Culqi recusou a chave secreta. Verifique 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 trocar o 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. Verifique se os scripts de js.culqi.com e 3ds.culqi.com não estão bloqueados na página de finalização de compra, por exemplo por um módulo de cache ou otimização.

O cliente vê Security check failed. Please reload the page and try again.: a página de finalização de compra ficou aberta por tempo demais ou em outra sessão. Recarregar a página resolve.

O cliente vê This order is already being paid: outra solicitação de pagamento do mesmo carrinho estava em andamento ao mesmo tempo. O cliente deve aguardar e verificar o e-mail antes de tentar de novo.

Um cartão foi recusado e você quer saber o motivo: veja o campo Log na página do módulo. As recusas são registradas com o código de recusa da Culqi, mesmo com o Debug log desativado.

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á configurada. Informe a chave e tente novamente.

Desinstalação

Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Culqi Payment 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 do gateway, os registros de cobranças e reembolsos da Culqi do módulo e o log são removidos. Pedidos pagos antes não poderão mais ser reembolsados pela página do pedido. Se estiver desativado, tudo é mantido para uma reinstalação posterior. O status de pedido Culqi payment on hold é sempre mantido. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

A Culqi é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Culqi.