VibeFox DPO for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior com a extensão SimpleXML. O módulo não permite a instalação sem elas.

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

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

Cron do servidor: uma tarefa cron que chama a URL de nova verificação do módulo 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

1. No back office, vá em 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 VibeFox DPO Pay Gateway na lista de módulos depois e clique em Configure.

3. Cole 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. Insira o Company Token e o Service Type de teste e/ou de produção (veja Configuração).

5. Envie a URL de notificação push mostrada na página Configure ao suporte da DPO e peça que configurem-na 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.

Ao ser instalado, o módulo cria o status de pedido DPO payment on hold. O PrestaShop oferece um 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 DPO Pay Gateway > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Quando o módulo está ativado, mas o Company Token ou o Service Type do modo selecionado está vazio, a página avisa que o método de pagamento fica oculto no checkout, e ao salvar aparece o mesmo aviso. Enquanto o modo de teste estiver ativado, a página mostra Test mode is on: payments are created with the test account credentials.

DPO Pay

Enable/Disable: Enable DPO Pay ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o nome do método de pagamento que o cliente vê no checkout. Também é o nome do método de pagamento salvo no pedido. Padrão: DPO Pay. Obrigatório.

Description: o texto exibido abaixo do método de pagamento no checkout. Padrão: Pay securely by card or mobile money on the DPO Pay payment page.

Credenciais de API

A DPO emite um Company Token e um Service Type ID para sua conta de comerciante e outros separados para uma conta de teste. Obtenha-os com seu gerente de conta DPO ou em dpogroup.com.

Test mode: quando ativado, os novos pagamentos são criados com o Company Token e o Service Type de teste. Padrão: ativado. Desative-o para aceitar pagamentos reais com as credenciais de produção. As verificações de status e os cancelamentos de pagamentos existentes sempre usam a conta com a qual 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 DPO de produção.

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

Company Tokens salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo somente se quiser alterá-lo. O 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.

Clear saved Company Tokens: marque um token e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.

Notificações de pagamento

Push notification URL: a notificação push informa à sua loja imediatamente que um pagamento foi feito, mesmo que o cliente feche o navegador após pagar. A URL não é configurada em um painel: peça ao suporte da DPO para definir essa URL para a sua conta. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_dpo_pay/notify, possivelmente com um código de idioma. Copie-a exatamente como a página a mostra. Ela precisa estar acessível pela internet, sem modo de manutenção, firewall ou autenticação básica na frente.

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

Scheduled status re-check (cron): chame esta URL a cada 15 minutos a partir de uma tarefa cron do servidor, por exemplo com curl. Pagamentos não confirmados são verificados novamente 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, então mantenha-a privada. Sem a URL push e o cron, um pedido só é criado quando o cliente volta à loja após pagar.

Pedidos

Successful payment status: o status do pedido após um pagamento bem-sucedido e verificado.

Divergências de valor ou moeda, pagamentos apenas autorizados e transações pagas a mais ou a menos sempre vão para DPO payment on hold.

Avançado

Logging: grava as chamadas à API e as notificações em logs/dpo_p_debug.log.php na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros são sempre registrados. Os tokens são mascarados, e nenhum dado do cliente é registrado. Padrão: desativado.

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

Delete data: quando ativado, desinstalar o módulo remove as configurações dele e o log. Os dados da DPO guardados para os pedidos e o status de pedido DPO payment on hold são sempre mantidos. Desinstalar sem esta opção nunca apaga dados. Padrão: desativado.

Checkout

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão DPO Pay) e vê a nota You will be redirected to the secure DPO Pay payment page. Após confirmar, o módulo cria uma transação DPO pelo valor total do carrinho na moeda do carrinho, com o número do carrinho e o nome da sua loja como descrição, e envia o cliente para a página de pagamento da DPO. Nome, e-mail, telefone e endereço de cobrança do cliente são enviados para pré-preencher a página. Lá, o cliente paga com qualquer método ativado na sua conta DPO. O link de pagamento é válido por 5 horas. Neste ponto, ainda não existe pedido.

Depois de pagar, o cliente retorna à sua loja. O pedido só é marcado como pago quando a DPO confirma: o módulo pede à DPO o resultado da transação quando o cliente retorna, quando chega uma notificação push e nas verificações programadas. Só então o pedido é criado e o cliente vê a página padrão de confirmação do pedido.

Se o pagamento não for confirmado, o cliente volta ao checkout com uma destas mensagens. O carrinho é mantido.

Se o cliente clicar no botão da página da DPO para voltar à loja, a transação é verificada primeiro. Se tiver sido paga, o pedido é criado. Caso contrário, ela é cancelada na DPO e o cliente volta ao checkout com o carrinho.

Quando o cliente paga novamente pelo mesmo carrinho, a transação DPO anterior é verificada primeiro. Se tiver sido paga, o pedido é criado sem uma segunda cobrança. Se ainda estiver em processamento, o cliente vê Your previous payment for this order is still being processed by DPO. Please wait a few minutes before trying again. Caso contrário, a transação antiga é cancelada na DPO e uma nova é criada.

Se a DPO não conseguir iniciar o pagamento, o cliente permanece no checkout com uma mensagem curta escolhida pelo código de erro da DPO, por exemplo DPO Pay does not support the currency of this order. Please choose another payment method. ou The amount exceeds the limit allowed by DPO Pay. Please choose another payment method or contact us. Outros erros exibem DPO Pay is temporarily unavailable. Please try again or choose another payment method. O motivo técnico é gravado no log.

A notificação push e a URL do cron funcionam enquanto a loja está em modo de manutenção e não são bloqueadas pela restrição de países da sua loja.

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

No order yet: o cliente foi enviado à DPO e não pagou, o pagamento foi recusado ou cancelado, ou a DPO ainda não confirmou o pagamento. Existe apenas o carrinho.

Payment accepted, Delivered or DPO payment on hold: o pagamento foi verificado. O status segue Successful payment status. O pagamento é registrado com o token da transação DPO como ID da transação. Uma nota privada na página do pedido mostra o valor, a moeda, o código de aprovação e o início do token.

DPO payment on hold after payment: a DPO confirmou um pagamento, mas o valor ou a moeda diferem do carrinho, o pagamento é apenas autorizado e não capturado, a transação foi paga a mais ou a menos, ou o cliente havia cancelado o pagamento ou o pedido já estava cancelado. A nota privada explica o motivo. Verifique a transação no portal da DPO. Capture ou cancele um pagamento apenas autorizado no portal da DPO e depois atualize o status do pedido.

Cancelled: quando você cancela um pedido não pago do módulo (por exemplo, um em espera por um pagamento apenas autorizado), a transação DPO aberta dele também é cancelada na DPO.

Um resultado de recusa posterior 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 nota sobre um possível pagamento duplicado, para que você possa reembolsá-lo no portal da DPO. Um pedido pago ou reembolsado nunca é reaberto.

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

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 DPO Pay Gateway é o primeiro bloco de Modules > Module Manager > VibeFox DPO Pay Gateway > 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-dpo e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Apenas funcionários com a permissão Configure do 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 único 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 vibefox.net.

Sem uma chave ativa, o DPO Pay não é exibido aos clientes no checkout. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. A vitrine 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 no checkout. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de 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 chave ser inserida, depois uma vez por semana. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.

Solução de problemas

DPO Pay does not appear at checkout: verifique se a licença está ativa, se Enable/Disable está ativado e se o Company Token e o Service Type do modo selecionado estão preenchidos: os campos de teste no modo de teste, os de produção nos demais casos. A página de configurações mostra um aviso quando eles estão faltando. 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.

The payment went through, but no order was created: provavelmente a URL de notificação push não foi configurada para a sua conta DPO, e o cliente não voltou à loja. Peça ao suporte da DPO que configure a URL mostrada nas configurações e verifique se o cron chama a URL de nova verificação a cada 15 minutos. Ative Logging e veja o campo Log na página do módulo.

Push notification answers Unknown transaction: o token de transação não pertence a um pagamento DPO Pay desta loja, por exemplo quando a notificação veio de outra loja na mesma conta DPO.

Push notification answers Verification failed: não foi possível contatar a DPO para verificar o pagamento, o carrinho estava sendo processado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A DPO repete a notificação, e a verificação programada também confirma o pedido. O motivo está no log.

The push URL shows Method not allowed in the browser: isso é normal. A URL aceita apenas requisições da DPO.

The cron URL answers Forbidden: o token na URL está errado. Copie a URL novamente da página Configure. Uma chamada correta responde OK checked= seguido do número de pagamentos verificados.

The Service Type is not saved: ele precisa ser o Service Type ID numérico da DPO.

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

The customer sees that DPO accepts at most 2 decimal places: o total do carrinho tem 3 casas decimais. A DPO não consegue cobrar esses valores.

The customer sees This order has already been paid with DPO Pay: a DPO recusou um segundo pagamento para o mesmo carrinho. Verifique o pagamento no portal da DPO e o pedido no PrestaShop.

Order is DPO payment on hold after payment: leia a nota privada na página do pedido (veja Status do pedido) e depois revise a transação no portal da DPO.

Desenvolvedores podem alterar os dados do cliente enviados à DPO com o hook actionWcpDpoPayCustomerData e o limite de tempo de pagamento com actionWcpDpoPayPaymentTimeLimit.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox DPO Pay Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete data estiver ativado, as configurações do módulo e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os dados da DPO guardados para os pedidos e o status de pedido DPO payment on hold são sempre mantidos, então notificações atrasadas de pagamentos antigos continuam funcionando após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

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