VibeFox DPO for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou superior com a extensão SimpleXML.

Conta DPO Pay: você precisa do Company Token e do Service Type ID da sua conta de comerciante na DPO. A DPO os emite quando a sua conta é aberta; obtenha-os com o seu gerente de conta na DPO ou em dpogroup.com. A DPO também pode fornecer uma conta de teste com token e tipo de serviço próprios. Não há um servidor de testes separado: a DPO usa o mesmo endereço de API para contas de teste e reais, e a conta é escolhida pelo token.

Moeda: a moeda do pedido precisa ser aceita pela sua conta DPO. A DPO aceita no máximo 2 casas decimais, por isso totais de pedido com 3 casas decimais (por exemplo KWD 12.345) não podem ser pagos.

Cron do servidor: um cron job que chama a URL de reverificação da extensão a cada 15 minutos (veja Configuração).

Chave de licença VibeFox: comprada 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_dpo_pay-oc3-(version).ocmod.zip e o pacote para OpenCart 4 wcp_dpo_pay.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 admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_dpo_pay-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. Acesse Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox DPO Pay Gateway e clique em Install (o botão verde +). O seu usuário administrador precisa ter o direito de modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão do lápis) para abrir a página de configurações. Cole a 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. Informe o Company Token e o Service Type de teste e/ou de produção (veja Configuração).

5. Envie à DPO a URL de notificação push exibida na seção Payment notifications e peça ao suporte que a configure para a sua conta. Adicione a URL do cron às tarefas cron do seu servidor.

6. Ative Enable/Disable e clique em Save. Faça um pedido de teste no modo de teste e depois desative Test mode para aceitar pagamentos reais.

OpenCart 4

1. No admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_dpo_pay.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. Acesse Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox DPO Pay Gateway, clique em Install (o botão verde +) e depois em Edit (o botão do lápis).

4. Informe a chave de licença, as credenciais da DPO, configure a URL de notificação push e o cron e teste o pagamento como nos passos 3 a 6 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só a URL de notificação push e a URL do cron são diferentes (veja Notificações de pagamento).

Uma nova instalação começa com o método de pagamento desativado e o modo de teste ligado. Na instalação, a extensão cria a sua tabela de transações e o token secreto da URL do cron.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox DPO Pay Gateway > Edit. As seções ficam listadas à esquerda; o botão Save abaixo da lista salva a página inteira. Quando o método de pagamento está ativado mas o Company Token ou o Service Type do modo selecionado estão vazios, a página avisa que o método de pagamento fica oculto na finalização de compra, e ao salvar aparece o mesmo aviso. Enquanto o modo de teste estiver ligado, a página mostra O modo de teste está ativado: os pagamentos são criados com as credenciais da conta de teste. Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title não pode estar vazio (no máximo 128 caracteres), Sort Order precisa ser um número inteiro e Total precisa ser um número igual ou maior que 0; caso contrário, nada é salvo.

DPO Pay

Enable/Disable: Enable DPO Pay 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: DPO Pay. Obrigatório.

Description: o texto mostrado ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pague com segurança por cartão ou dinheiro móvel na página de pagamento do DPO Pay.

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

Geo Zone: oferecer o DPO Pay somente para endereços de pagamento da 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 para que o DPO Pay seja oferecido. Deixe em branco para oferecer o DPO Pay para qualquer valor.

Credenciais de API

A DPO emite um Company Token e um Service Type ID para a sua conta de comerciante, e outros separados para uma conta de teste. Obtenha-os com o seu gerente de conta na DPO ou em dpogroup.com (a seção traz links para lá).

Test mode: quando ligado, os novos pagamentos são criados com o Company Token e o Service Type de teste. Padrão: ligado. Desligue para aceitar pagamentos reais com as credenciais de produção. Enquanto estiver ligado, os clientes veem Modo de teste: os pagamentos são criados com a conta de teste. na etapa Confirm Order. As consultas de status e os cancelamentos de pagamentos existentes sempre usam a conta com que o pagamento foi criado.

Test Company Token: o Company Token da sua conta de teste da DPO.

Test Service Type: o Service Type ID numérico da sua conta de teste da DPO.

Live Company Token: o Company Token da sua conta de comerciante real da DPO.

Live Service Type: o Service Type ID numérico da sua conta de comerciante real da DPO.

Company Tokens salvos nunca são exibidos novamente. O campo fica vazio e mostra Salvo: deixe em branco para mantê-lo. Informe um novo valor apenas se quiser alterá-lo. Para remover um token salvo, marque Clear the saved Company Token on save abaixo do campo e clique em Save. Um Service Type precisa ser um número. Qualquer outro valor não é salvo: a página mostra um aviso e mantém o valor anterior, e as demais configurações são salvas.

Notificações de pagamento

Push notification URL: a notificação push avisa a sua loja imediatamente que um pagamento foi feito, mesmo que o cliente feche o navegador depois de pagar. A URL não é configurada em um painel: peça ao suporte da DPO que a defina para a sua conta. No OpenCart 3 ela tem o formato https://your-store/index.php?route=extension/payment/wcp_dpo_pay/notify, e no OpenCart 4: https://your-store/index.php?route=extension/wcp_dpo_pay/payment/wcp_dpo_pay.notify. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart. Copie-a exatamente como a página a mostra. Ela precisa estar acessível pela internet, sem firewall ou autenticação básica na frente.

As notificações push da DPO não têm assinatura, por isso o conteúdo delas nunca é considerado confiável. A extensão as usa apenas para localizar o pagamento pelo token de transação e, em seguida, verifica o resultado com a própria DPO. Um token que a sua loja não criou é rejeitado sem nenhuma requisição à DPO.

Reverificação programada do status (cron): chame esta URL a cada 15 minutos a partir de um cron job do servidor, por exemplo com curl. Pagamentos não confirmados são reverificados na DPO 15 minutos após o redirecionamento e de novo após o limite de tempo de pagamento. A URL contém um token secreto, por isso mantenha-a privada. No OpenCart 4 ela tem o formato https://your-store/index.php?route=extension/wcp_dpo_pay/payment/wcp_dpo_pay.cron&token= e o token. Sem a URL push e o cron, um pedido só recebe o status quando o cliente volta à loja depois de pagar.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). O pedido só recebe um status depois que a DPO confirma o pagamento. Cada campo abaixo lista os seus status de pedido do OpenCart.

Successful payment status: o status do pedido após um pagamento bem-sucedido e verificado. Padrão: Em processamento. Escolha Concluído se cada pedido pago deve ser concluído, ou o seu próprio status de revisão para aprovação manual de cada pedido.

DPO payment on hold status: o status para um pagamento que precisa da sua revisão: divergência de valor ou moeda, um pagamento apenas autorizado, uma transação com excesso ou falta de pagamento, ou um pagamento feito depois que o cliente cancelou. Uma observação no histórico do pedido explica o motivo. Padrão: Pendente, porque o OpenCart não tem o status On hold. Você pode criar o seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

Cancelled order status: quando você define um pedido do DPO Pay não pago com este status, o pagamento aberto dele na DPO também é cancelado. Padrão: Cancelado.

Avançado

Logging: grava as chamadas de API e as notificações em dpo_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 dpo_p_debug.old.log.php. Erros são sempre registrados. Tokens são mascarados e nenhum dado do cliente é registrado. Padrão: desligado.

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

Delete data: quando ligado, desinstalar a extensão remove as configurações do gateway e o log. Os dados da DPO armazenados para os pedidos são sempre mantidos. Desinstalar sem esta opção nunca apaga dados. Padrão: desligado.

Importação / Exportação

Export: Download JSON salva as configurações em um arquivo JSON. Os Company Tokens não são exportados.

Import: cole o JSON exportado anteriormente e clique em Import para restaurar as configurações. Os Company Tokens salvos são mantidos.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, o DPO Pay). Na etapa Confirm Order, o cliente vê a sua descrição e a nota Você será redirecionado para a página de pagamento segura do DPO Pay. O OpenCart cria o pedido nesta etapa, ainda sem status. Quando o cliente clica em Confirm Order, a extensão cria uma transação na DPO pelo total do pedido, na moeda do pedido, com o número do pedido e o nome da sua loja como descrição, e envia o cliente para a página de pagamento da DPO. O nome, o e-mail, o telefone e o endereço de cobrança do cliente são enviados para preencher a página previamente. Lá, o cliente paga com qualquer método habilitado na sua conta DPO. O link de pagamento é válido por 5 horas. 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 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), é enviado o endereço de entrega.

Depois de pagar, o cliente volta à sua loja. O pedido só é marcado como pago quando a DPO confirma: a extensão consulta a DPO sobre o resultado da transação quando o cliente retorna, quando chega uma notificação push e nas reverificações programadas. Depois, o pedido recebe o status da forma padrão do OpenCart, com os e-mails de pedido habituais e a atualização do estoque, e o cliente vê a página de sucesso do pedido do OpenCart. No OpenCart 4, o navegador não envia a sessão da loja quando a DPO devolve o cliente, então a extensão primeiro mostra uma página curta que abre novamente o mesmo endereço de retorno a partir da sua loja: o cliente mantém o carrinho e o login.

Se o pagamento não for confirmado, o cliente volta à finalização de compra com uma destas mensagens (no OpenCart 4, elas são exibidas acima da página de finalização de compra). O carrinho é mantido.

Se o cliente clicar no botão da página da DPO para voltar à loja, a transação é verificada primeiro. Se foi paga, o cliente vê a página de sucesso. Caso contrário, ela é cancelada na DPO e o cliente volta à finalização de compra com o carrinho.

O OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida; o OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza, e uma nova tentativa é uma nova transação da DPO do mesmo pedido. Antes de um novo pagamento, são verificadas as transações abertas na DPO do pedido e dos pedidos anteriores do mesmo carrinho. Se uma foi paga, esse pagamento é confirmado e o cliente vai à página de sucesso sem uma segunda cobrança. Se uma ainda está em processamento, o cliente vê Seu pagamento anterior para este pedido ainda está sendo processado pela DPO. Aguarde alguns minutos antes de tentar novamente. Caso contrário, as transações antigas são canceladas na DPO e uma nova é criada.

No OpenCart 4, o pedido permanece na finalização de compra até a página de sucesso ser exibida. Se, nesse meio tempo, esse pedido foi fechado (por exemplo, cancelado ou reembolsado), o Confirm Order ou o retorno da DPO devolve o cliente à finalização de compra: com The payment was declined or cancelled. Please try again or choose another payment method., se o pedido não tinha pagamento, ou com Your previous order was closed by the store. Please confirm the order again: the cart will be paid with a new order., se tinha. Se o pedido já estiver pago e o carrinho tiver mudado desde então (outros produtos ou quantidades), a mensagem é Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. Em todos esses casos, o próximo Confirm Order paga um novo pedido do carrinho.

Se a DPO não conseguir iniciar o pagamento, o cliente permanece na etapa Confirm Order com uma breve mensagem acima do botão, escolhida conforme o código de erro da DPO, por exemplo O DPO Pay não oferece suporte à moeda deste pedido. Escolha outro método de pagamento. ou O valor excede o limite permitido pelo DPO Pay. Escolha outro método de pagamento ou entre em contato conosco. Outros erros mostram O DPO Pay está temporariamente indisponível. Tente novamente ou escolha outro método de pagamento. O motivo técnico é gravado no log.

A notificação push e a URL do cron também funcionam enquanto a loja está em modo de manutenção: o OpenCart 3 deixa passar as requisições das extensões de pagamento, e no OpenCart 4 a extensão adiciona uma ação de inicialização (startup action) que deixa passar essas requisições e o retorno do cliente. Pagamentos já iniciados são confirmados mesmo se você desligar o método de pagamento.

A extensão aceita apenas pagamentos únicos na página da DPO. Não há reembolsos pela loja, cartões salvos, assinaturas ou pagamentos recorrentes, campos de cartão no seu site nem captura de pagamentos apenas autorizados.

Pedidos

Status do pedido

Sem status (pedido ausente): o cliente foi enviado à DPO e não pagou, o pagamento foi recusado ou cancelado, ou a DPO ainda não confirmou o pagamento. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders.

Successful payment status (padrão Em processamento): o pagamento foi verificado. Uma observação no histórico do pedido mostra o valor, a moeda, o código de aprovação e o início do token de transação da DPO.

DPO payment on hold status (padrão Pendente): a DPO confirmou um pagamento, mas o valor ou a moeda diferem do pedido, o pagamento está apenas autorizado e não capturado, a transação teve excesso ou falta de pagamento, ou o cliente havia cancelado o pagamento ou o pedido já estava cancelado. A observação explica o motivo. Verifique a transação no portal da DPO. Capture ou anule um pagamento apenas autorizado no portal da DPO e depois atualize o status do pedido.

Cancelled order status (padrão Cancelado): quando você define com este status um pedido não pago da extensão (por exemplo, um retido por um pagamento apenas autorizado), a sua transação aberta na DPO também é cancelada.

Um resultado posterior de recusa nunca altera um pedido, e resultados de transações antigas nunca fazem a tentativa atual falhar. Se a DPO confirmar um segundo pagamento bem-sucedido para um pedido já pago, o pedido não é alterado e recebe uma observação sobre um possível pagamento em duplicidade, para que você possa reembolsá-lo no portal da DPO. O mesmo tipo de observação é adicionado ao pedido pago quando o mesmo carrinho (mesma sessão do cliente e mesmo conteúdo) foi pago de novo com outro pedido, por exemplo em uma segunda aba do navegador; esse outro pedido não recebe status. Um pedido que você tenha mudado para outro status (por exemplo, reembolsado) nunca é reaberto; um pagamento tardio apenas acrescenta uma observação.

As observações são entradas do History do pedido que o cliente não vê. A extensão não tem uma aba na página do pedido.

Reembolsos

Reembolsos pela loja não estão disponíveis nesta versão. Reembolse o pagamento no portal de comerciante da DPO e depois altere o status do pedido no OpenCart.

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 DPO Pay Gateway é o primeiro bloco em Extensions > Extensions > Payments > VibeFox DPO Pay Gateway > 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-dpo e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do admin (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 único domínio: o endereço da loja 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, o DPO Pay não é exibido 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. Um usuário administrador conectado ao admin 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 admin, então, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois de abrir a página Edit uma vez, aparece um lembrete no Dashboard do admin. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática quando você abre o Dashboard ou a página Edit do admin: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário nenhum cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

O DPO Pay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se o Company Token e o Service Type do modo selecionado estão definidos: os campos de teste no modo de teste, os de produção caso contrário. A página de configurações mostra um aviso quando 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: provavelmente a URL de notificação push não foi definida para a sua conta na DPO, e o cliente não voltou à loja. Peça ao suporte da DPO que defina a URL exibida nas configurações e verifique se o cron chama a URL de reverificação a cada 15 minutos. Ative o Logging e veja o campo Log na página da extensão.

A notificação push responde Unknown transaction: o token de transação não pertence a um pagamento do DPO Pay desta loja, por exemplo porque a notificação veio de outra loja na mesma conta da DPO.

A notificação push responde Verification failed: não foi possível contatar a DPO para verificar o pagamento, o pedido estava sendo processado por outra requisição no mesmo momento, ou não foi possível definir o status do pedido. A DPO repete a notificação, e a reverificação programada também confirma o pedido. O motivo está no log.

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

A URL do cron responde Forbidden: o token na URL está errado. Copie a URL novamente a partir da página de configurações. Uma chamada correta responde OK checked= e o número de pagamentos verificados.

O Service Type não é salvo: ele precisa ser o Service Type ID numérico fornecido pela DPO.

O cliente vê This payment method is not available. Please reload the checkout page.: a sessão da finalização de compra não corresponde mais ao pedido, ou o método de pagamento foi desligado nesse meio tempo. O cliente recarrega a finalização de compra.

O cliente vê DPO Pay is temporarily unavailable: a DPO recusou criar a transação, por exemplo por causa de um Company Token ou Service Type errado, ou de um token do outro modo. O código de resultado da DPO está no log.

O cliente vê que a DPO aceita no máximo 2 casas decimais: o total do pedido tem 3 casas decimais. A DPO não pode cobrar valores assim.

O cliente vê This order has already been paid with DPO Pay: a DPO recusou um segundo pagamento para o mesmo pedido. Verifique o pagamento no portal da DPO e o pedido no OpenCart.

O pedido está no status de revisão após o pagamento: leia a observação no History do pedido (veja Status do pedido) e depois verifique a transação no portal da DPO.

Para desenvolvedores: a extensão dispara os eventos do OpenCart wcp_dpo_pay_customer_data (os dados do cliente enviados à DPO) e wcp_dpo_pay_payment_time_limit (o limite de tempo de pagamento em horas).

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox DPO Pay Gateway. 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. O evento do OpenCart da extensão também é removido (no OpenCart 4, seus eventos e a ação de inicialização, que deixa a DPO e o cron passar no modo de manutenção). Se Delete data estiver ligado, as demais configurações do gateway (título, descrição, modo de teste, Company Tokens, Service Types, registro de log) e o log são removidos, e uma reinstalação cria uma nova URL de cron. Se estiver desligado, elas são mantidas para uma reinstalação futura. Os dados da DPO armazenados para os pedidos são sempre mantidos, então notificações tardias e reverificações de pagamentos antigos continuam funcionando após uma reinstalação. Os pedidos existentes mantêm as suas observações 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 DPO Pay Gateway na lista de extensões instaladas e depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

O DPO Pay é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada ao DPO Pay nem endossada por ele.