VibeFox Culqi for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado com 3.0.5.0) ou 4.0.2 e posterior (testado com 4.1.0.3).

PHP: 8.0 ou superior.

Moeda da loja: o Sol peruano (PEN) ou o Dólar americano (USD) precisa ser uma moeda habilitada na sua loja. A Culqi não aceita outras moedas, e o método de pagamento só é exibido quando o cliente paga 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) são obtidas em integ-panel.culqi.com, e as chaves de produção (reais) em mipanel.culqi.com, em CulqiPanel > Desarrollo > API Keys. A chave pública é usada pelo popup 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: adquirida em vibefox.net. Uma chave funciona em um domínio.

Instalação

O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote para OpenCart 3 wcp_culqi_payment-oc3-(version).ocmod.zip e o pacote para OpenCart 4 wcp_culqi_payment.ocmod.zip. Instale apenas o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_culqi_payment-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, então Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você também pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Vá em Extensions > Extensions e escolha o tipo Payments. Localize VibeFox Culqi Payment e clique em Install (o botão verde +). Seu usuário administrador precisa ter permissão para modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão com o lápis) para abrir a página de configurações. Cole sua chave de licença VibeFox em License key, no bloco de licença no topo da página, 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 ligado enquanto testa e desligue-o para receber pagamentos reais.

OpenCart 4

1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_culqi_payment.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão pelo nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Vá em Extensions > Extensions e escolha o tipo Payments. Localize VibeFox Culqi Payment, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).

4. Informe a chave de licença e as chaves da Culqi como nos passos 3 a 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões.

Uma nova instalação começa com o método de pagamento desativado e o modo de teste ligado.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox Culqi Payment > Edit. As seções são listadas à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, 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 ligado. Ela avisa quando o gateway está habilitado, mas as chaves do modo atual estão faltando, e quando nenhuma moeda habilitada da loja é aceita pela Culqi. Nos dois casos, o método de pagamento fica oculto na finalização de compra. Se a sua moeda padrão não for PEN nem USD, a página informa que a Culqi só é oferecida quando o cliente paga em uma moeda aceita. Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, um valor incorreto não é salvo e mantém o valor anterior, enquanto os outros campos são salvos. A página exibe um erro para cada um desses campos: uma chave com prefixo errado (por exemplo Live Secret Key must start with sk_live_ — the previous value was kept.), um Title vazio ou com mais de 128 caracteres, um Sort Order que não é um número inteiro, um Total que não é um número igual ou maior que 0, ou uma zona geográfica ou status de pedido que não existe.

Culqi

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 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, até 128 caracteres.

Description: o texto mostrado ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay securely with your credit/debit card or Yape via Culqi.

Sort Order: a posição da Culqi entre os métodos de pagamento na finalização de compra. Deixe em branco ou informe um número inteiro.

Geo Zone: oferecer a Culqi somente para endereços de pagamento na zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones.

Total: o total da compra, na moeda padrão da loja, que um pedido precisa atingir antes que a Culqi seja oferecida. Deixe em branco para oferecer a Culqi para qualquer total.

Chaves de API

Copie as chaves de CulqiPanel > Desarrollo > API Keys: as chaves de integração (teste) em integ-panel.culqi.com e as chaves de produção em mipanel.culqi.com (a página traz os links). O modo de teste usa apenas as chaves de teste, e o modo real usa apenas as chaves reais. Cada chave precisa começar com o prefixo do seu campo.

Test Mode: quando ligado, as chaves de teste (pk_test_ / sk_test_) são usadas e nenhum valor real é cobrado. Padrão: ligado. Desligue para receber pagamentos reais com as chaves de produção. Enquanto estiver ligado, os clientes veem TEST MODE: No real charges will be made. na etapa Confirm Order.

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 não 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. Para remover uma chave secreta salva, marque Clear the saved key on save abaixo do campo e clique em Save.

Métodos de pagamento

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

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

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). O pedido só recebe um status depois que a Culqi confirma a cobrança. Cada um dos campos abaixo lista os status de pedido do seu OpenCart.

Order Status After Payment: a Culqi confirmou a cobrança e o valor e a moeda correspondem ao pedido. Padrão: Processing.

On Hold (Review) Status: a Culqi cobrou um valor ou uma moeda que não correspondem ao pedido, ou não capturou o pagamento. Uma nota explica o que verificar no CulqiPanel. Padrão: Pending, porque o OpenCart não tem o status On hold. Você pode criar seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

Refunded Status: o pagamento foi reembolsado integralmente pela página do pedido. Reembolsos parciais apenas adicionam uma nota. Padrão: Refunded.

Avançado

Debug log: registra as requisições à API e as etapas do pagamento em culqi_p_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web e, ao atingir 5 MB, é movido para culqi_p_debug.old.log.php. Erros, incluindo recusas de cartão com o respectivo código, são sempre registrados. Chaves, dados de cartão e dados do cliente nunca são registrados. Padrão: desligado.

Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.

Delete data on uninstall: quando ligado, desinstalar a extensão remove as configurações do gateway e o log. As cobranças e os reembolsos da Culqi sempre são mantidos, então pedidos pagos antes ainda podem ser reembolsados após uma reinstalação. Padrão: desligado.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. As chaves secretas não são exportadas.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. As chaves secretas salvas são mantidas.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão Credit/Debit Card or Yape (Culqi)). Na etapa Confirm Order, o cliente vê a sua descrição, e o OpenCart cria o pedido, ainda sem status. Quando o cliente clica em Confirm Order, a janela Culqi Checkout abre na mesma página com o nome da sua loja, o total do pedido e a moeda. Ali o cliente informa os dados do cartão ou paga com Yape. Os scripts da Culqi são sempre carregados a partir da Culqi. No OpenCart 4, o cliente escolhe o método de pagamento com o botão Choose do bloco do método de pagamento, na janela Payment method options, e clica em Confirm Order no bloco de confirmação na parte inferior da página de finalização de compra. Se a loja não pedir um endereço de pagamento (padrão do OpenCart 4), os dados do cliente enviados com a cobrança são obtidos do endereço de entrega e do nome do cliente.

A Culqi transforma os dados de pagamento em um token de uso único, e somente esse token é enviado à sua loja. O seu servidor cria a cobrança com a API Culqi Charges pelo total do pedido na moeda do pedido, capturada imediatamente. A cobrança aparece no CulqiPanel como Order e o número do pedido, com o e-mail do cliente. O pedido só é marcado como pago depois que a Culqi confirma. Em seguida, ele recebe o status da forma padrão do OpenCart, com os e-mails habituais de pedido e a atualização do estoque, e o cliente vê a página de sucesso do pedido do OpenCart.

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 após Payment failed: e pode tentar novamente com outro cartão na mesma etapa. 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. Nesses casos, o pedido fica sem status e uma nota no histórico do pedido registra a tentativa. Se o cliente fechar a janela da Culqi, nada é cobrado e o botão Confirm Order pode ser clicado novamente. O carrinho é mantido em todos esses casos.

Um pedido nunca é cobrado duas vezes. Se o cliente enviar novamente enquanto um pagamento do mesmo pedido está em andamento, ele vê This order is already being paid. Please wait a moment and check your email before trying again. Se a Culqi cobrou o valor, mas não foi possível definir o status do pedido, 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 com o mesmo carrinho define o status do pedido a partir dela, sem nova cobrança. Um carrinho é pago apenas uma vez: se outro pedido do mesmo carrinho (o OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida) já estiver pago, o cliente vai para a página de sucesso e não é cobrado novamente. O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza, portanto, após um cartão recusado, o cliente paga o mesmo pedido.

No OpenCart 4, o pedido permanece na finalização de compra até a página de sucesso ser exibida. Se esse pedido foi fechado pela loja nesse meio tempo (por exemplo, cancelado ou reembolsado), ou se já está pago e o carrinho mudou desde então (outros produtos ou quantidades), o Confirm Order devolve o cliente à finalização de compra, que cria um novo pedido do carrinho com um pagamento próprio. Um pedido que foi pago e depois fechado não mantém mais o carrinho.

A extensão aceita apenas pagamentos únicos com cartão e Yape, capturados imediatamente. Não há app bancário, agentes, carteiras ou Cuotéalo, nem cartões salvos, assinaturas ou parcelamentos, nem webhooks da Culqi, nem autorização e captura separadas.

Pedidos e reembolsos

Status do pedido

No status (missing order): o cliente ainda não pagou, o cartão foi recusado ou a Culqi não respondeu. Em Sales > Orders, esses pedidos aparecem apenas com o filtro Order Status definido como Missing Orders. As notas no histórico do pedido explicam as tentativas com falha.

Order Status After Payment (default Processing): a cobrança foi confirmada e corresponde ao pedido. Uma nota mostra Culqi payment successful com o modo (teste ou real), o 3-D Secure, se usado, e o ID da cobrança na Culqi (chr_...).

On Hold (Review) Status (default Pending): 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 explica isso e mostra o ID da cobrança. Verifique a cobrança no CulqiPanel e, em seguida, atenda o pedido ou reembolse o pagamento.

Refunded Status (default Refunded): o pagamento foi reembolsado integralmente pela extensão.

As notas são entradas do History do pedido que o cliente não vê.

Aba VibeFox Culqi Payment

Em Sales > Orders, abra um pedido pago com a Culqi. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Culqi Payment mostra o Charge ID com a etiqueta Test para pagamentos de teste, o Amount cobrado (com 3-D Secure, se usado), uma indicação Review para pedidos em espera, os valores Paid / refunded, o formulário de reembolso, o histórico de reembolsos e as Culqi notes do pedido. A aba é exibida para os usuários que têm acesso à extensão.

Reembolsos

Na aba VibeFox Culqi Payment, informe o Amount (o valor ainda não reembolsado é preenchido), opcionalmente um Reason (optional), 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 ter o direito de modificar a extensão (definido em System > Users > User Groups). Os reembolsos são feitos no valor e na moeda que a Culqi cobrou, então, após uma divergência de valor, você pode reembolsar até o montante que o cliente realmente pagou, e não o total do pedido. O reembolso é enviado com as chaves do modo em que o pagamento foi feito (teste ou real), 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, a aba exibe o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o ID do reembolso da Culqi, o valor e o seu motivo. Um reembolso total define o pedido como Refunded Status sem notificar o cliente e sem devolver os produtos ao estoque, como uma mudança manual de status. Um reembolso parcial não altera o status.

Devoluções de produtos em Sales > Returns não devolvem dinheiro pela Culqi. Reembolsos feitos no CulqiPanel não são sincronizados de volta com o OpenCart. Atualize o pedido manualmente, se necessário.

Chave de licença

A extensão funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Culqi Payment é o primeiro bloco em Extensions > Extensions > Payments > VibeFox Culqi Payment > Edit, 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: opencart-payment-culqi e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Apenas usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel administrativo (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, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o endereço da loja definido na configuração do OpenCart. 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 é mostrada 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. Um usuário administrador conectado ao painel administrativo no mesmo navegador ainda vê o método de pagamento na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4, essa prévia não está disponível: a loja não enxerga o login do painel administrativo, então, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois que você abrir a página Edit uma vez, um lembrete aparece no Dashboard do painel administrativo. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática quando você abre o Dashboard ou a página Edit do painel administrativo: uma vez por dia nos primeiros 14 dias após a chave ser informada, e depois uma vez por semana. Nenhum cron job é necessário. Desinstalar a extensão 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á ligado, 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 real) e se o cliente paga em PEN ou USD. A página de configurações mostra um aviso quando as chaves estão faltando. Verifique também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.

O pagamento foi feito, mas o pedido continua sem status: a extensão não usa webhooks. A cobrança só é confirmada pela resposta da Culqi ao seu servidor. Se a Culqi não respondeu a tempo, o pedido recebe a nota Culqi did not confirm the charge. Procure a cobrança deste pedido 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 na mesma sessão do cliente define o status sem cobrar novamente.

O pedido está em status de revisão após o pagamento: leia as notas na aba VibeFox Culqi Payment. O valor ou a moeda cobrados eram diferentes do pedido, ou o pagamento não foi capturado. Verifique a cobrança no CulqiPanel e, em seguida, atenda 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 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 faltando, ou a Culqi rejeitou 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 enquanto a página de finalização de compra estava 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 uma extensão 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 estava aberta em outra sessão. Recarregar a página resolve.

O cliente vê This payment method is not available.: a sessão de finalização de compra não tem mais um pedido da Culqi, ou o método de pagamento foi desativado nesse meio tempo. O cliente recarrega a finalização de compra.

Um cartão foi recusado e você quer o motivo: leia a nota no pedido ou o campo Log na página da extensão. As recusas são registradas com o código de recusa da Culqi, mesmo quando Debug log está desligado.

Não há formulário de reembolso na aba: a aba informa o motivo: o pagamento foi reembolsado integralmente, o seu grupo de usuários não tem o direito de modificar a extensão, ou falta a chave secreta do modo de pagamento.

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

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Culqi Payment. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as próprias configurações da extensão: Enable/Disable, Sort Order, Geo Zone, Total e os status de pedido da seção Orders, que voltam aos padrões em uma reinstalação. Se Delete data on uninstall estiver ligado, as demais configurações do gateway (título, descrição, modo de teste, chaves, Yape, registro) e o log são removidos. Se estiver desligado, eles são mantidos para uma reinstalação posterior. As cobranças e os reembolsos da Culqi são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados após uma reinstalação. Os pedidos existentes mantêm as suas notas de pagamento.

No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer depois da desinstalação, clique em Uninstall (o botão laranja −) ao lado de VibeFox Culqi Payment na lista de extensões instaladas e depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

A Culqi é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pela Culqi.