VibeFox Datatrans for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões mais antigas do PHP.
Conta na Datatrans: você precisa do Merchant ID, da senha de API servidor a servidor e, recomendada, da chave de assinatura HMAC-SHA256 para os webhooks. As credenciais de sandbox são obtidas no Web Admin de sandbox da Datatrans (admin.sandbox.datatrans.com), e as de produção, no Web Admin de produção (admin.datatrans.com). Sandbox e produção são contas separadas na Datatrans, com Merchant IDs e chaves diferentes.
Loja acessível: a Datatrans envia os webhooks a partir dos próprios servidores, por isso a sua loja precisa estar acessível pela internet.
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, mais tarde, encontre VibeFox Datatrans Gateway na lista de módulos e clique em Configure.
3. Digite 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. Digite as credenciais de sandbox do Web Admin de sandbox da Datatrans (veja Configuração).
5. Ative Enable/Disable e clique em Save. Faça um pagamento de teste no modo sandbox. Quando tudo estiver funcionando, digite as credenciais de produção e desative Sandbox mode.
Na instalação, o módulo cria o status de pedido Datatrans payment on hold. O PrestaShop habilita por padrão o novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences; a Datatrans só é exibida para as moedas permitidas ali.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Datatrans Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Quando o método de pagamento está ativado, mas o ambiente atual não tem Merchant ID ou senha de API, a página mostra Datatrans is hidden at checkout until these settings are filled in: com os campos que faltam. Enquanto o modo sandbox estiver ativo, a página mostra Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged.
Datatrans
Enable/Disable: Enable Datatrans Payment 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: Datatrans. Obrigatório.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely via Datatrans.
Sandbox mode: usa o sandbox da Datatrans: pagamentos de teste, sem dinheiro real. Essa opção troca tanto os servidores da Datatrans quanto as credenciais usadas nos novos pagamentos. Padrão: ativado. Desative-a para receber pagamentos reais. Enquanto estiver ativada, o cliente vê Sandbox mode: no real payment is taken. abaixo do método de pagamento. Reembolsos e capturas sempre usam o ambiente em que o pagamento foi feito, independentemente desta opção.
Credenciais de sandbox
Copie-as do Web Admin de sandbox da Datatrans (admin.sandbox.datatrans.com). A chave de assinatura fica lá, nas configurações de segurança.
Sandbox merchant ID: o Merchant ID da sua conta de sandbox.
Sandbox API password: a senha de API servidor a servidor da conta de sandbox.
Sandbox HMAC sign key: a chave hexadecimal usada para verificar o cabeçalho Datatrans-Signature dos webhooks. Sem ela, cada webhook é verificado novamente pela API de status da Datatrans.
Credenciais de produção
Copie-as do Web Admin de produção da Datatrans (admin.datatrans.com).
Production merchant ID: o Merchant ID da sua conta de produção.
Production API password: a senha de API servidor a servidor da conta de produção.
Production HMAC sign key: a chave hexadecimal usada para verificar o cabeçalho Datatrans-Signature dos webhooks de produção. Sem ela, cada webhook é verificado novamente pela API de status da Datatrans.
Senhas e chaves de assinatura salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente para alterá-lo. Uma chave de assinatura deve ser uma string hexadecimal, como emitida pela Datatrans. Qualquer outro valor não é salvo: a página mostra um erro e mantém o valor anterior, e as demais configurações são salvas.
Clear saved secrets: marque uma senha ou chave de assinatura e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
URL do webhook
A seção mostra a URL do webhook da sua loja. Com URLs amigáveis, ela tem esta forma: https://your-shop/module/wcp_datatrans_gateway/webhook, possivelmente com um código de idioma, como /en/. O módulo envia essa URL à Datatrans em cada transação, então você não precisa digitá-la em lugar nenhum. Você também pode digitá-la nas configurações de webhook do Web Admin da Datatrans para receber atualizações das capturas e cancelamentos feitos ali; copie-a exatamente como as configurações a mostram. Reembolsos feitos no Web Admin da Datatrans não são refletidos no pedido.
O webhook informa o estado da transação. O módulo age de acordo com estes estados:
Com uma chave de assinatura HMAC, cada webhook é verificado pelo seu cabeçalho Datatrans-Signature com a chave de assinatura do ambiente em que o pagamento foi feito. Webhooks sem assinatura válida são rejeitados. Sem a chave de assinatura, o módulo não confia no conteúdo do webhook e verifica cada um pela API de status da Datatrans. Sem o webhook, um pedido só é criado quando o cliente volta à loja depois de pagar.
Processamento do pagamento
Auto settle: captura (liquida) os pagamentos imediatamente. Se desativado, os pagamentos são apenas autorizados: o pedido vai para Datatrans payment on hold e você o captura depois com Capture Datatrans payment no bloco da Datatrans do pedido, ou o libera com Cancel Datatrans authorization. Padrão: ativado.
Order status after payment: o status do pedido depois que o pagamento é liquidado.
Pagamentos apenas autorizados e divergências de valor ou moeda sempre vão para Datatrans payment on hold.
Avançado
Logging: grava eventos de pagamento e chamadas de API em logs/datatrans_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros são sempre registrados, mesmo com esta opção desativada. Nenhuma chave, dado de cartão ou dado do cliente é gravado. Padrão: desativado.
Log: mostra o tamanho e as entradas mais recentes do log, com um botão para limpá-lo.
Delete data on uninstall: quando ativado, desinstalar o módulo remove as configurações e o log do módulo. Os registros de pagamento da Datatrans nos pedidos (transações, reembolsos) e o status do pedido sempre permanecem. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, Datatrans) e vê a nota You will be redirected to the Datatrans payment page to complete the payment securely. Após confirmar, o módulo cria uma transação na Datatrans para o total do carrinho na moeda do carrinho e envia o cliente à página de pagamento da Datatrans. A página abre em alemão, inglês, francês ou italiano se o idioma da loja for um desses. Lá o cliente paga com qualquer método ativado na sua conta da Datatrans. Neste ponto, ainda não existe pedido.
Depois de pagar, o cliente volta à sua loja. O pedido só é marcado como pago depois que a Datatrans confirma: pelo webhook ou por uma requisição no servidor à API de status da Datatrans quando o cliente retorna. O endereço de retorno contém a chave segura do carrinho, e o retorno em si nunca cria um pedido. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Your payment with Datatrans has been received. Em um pagamento apenas autorizado, a página mostra Your payment with Datatrans has been authorized. The amount will be charged when your order is processed. Se a Datatrans ainda não confirmou o pagamento, uma página de Payment confirmation mostra Your payment is being confirmed by Datatrans. You will receive an e-mail as soon as it is confirmed. Please do not pay again. com um botão Check again; o webhook cria o pedido assim que chegar.
Se o cliente cancelar na página da Datatrans, ele volta à finalização de compra com The payment was canceled. You can try again or choose another payment method. Se o pagamento falhou, a mensagem é The payment was not completed. Please try again or choose another payment method. O carrinho é mantido. Uma nova tentativa cria uma nova transação na Datatrans; um pagamento atrasado de uma tentativa anterior continua sendo reconhecido.
Se a Datatrans não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com The payment could not be started. Please try again or choose another payment method. O motivo técnico é gravado no log.
O webhook funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.
O módulo aceita pagamentos únicos na página de pagamento da Datatrans. Não há cartões salvos ou aliases, assinaturas, Lightbox ou Secure Fields no seu site, escolha dos métodos de pagamento nas configurações nem captura parcial de uma autorização.
Pedidos e reembolsos
Status do pedido
Ainda sem pedido: o cliente foi enviado à Datatrans e não pagou, o pagamento falhou ou foi cancelado, ou a Datatrans ainda não o confirmou. Existe apenas o carrinho.
Payment accepted, Delivered ou Datatrans payment on hold: o pagamento foi liquidado. O status segue Order status after payment. O pagamento é registrado com o ID da transação na Datatrans, e uma nota mostra o valor, o método de pagamento, o ambiente e como foi confirmado (webhook ou retorno).
Datatrans payment on hold após uma autorização: Auto settle está desativado e o pagamento é apenas autorizado. Capture-o ou cancele-o no bloco do pedido.
Datatrans payment on hold após o pagamento: a Datatrans informou um valor ou uma moeda diferente do total do carrinho (por exemplo, o carrinho foi alterado depois que o pagamento começou), ou o pagamento chegou depois que o pedido já tinha sido cancelado. A nota explica o motivo. Verifique a transação no Web Admin da Datatrans e então atenda o pedido ou reembolse o pagamento.
Canceled: a autorização foi liberada, no bloco do pedido ou no Web Admin da Datatrans.
Refunded: o pagamento foi reembolsado integralmente pelo módulo.
Se chegar um segundo pagamento para um carrinho que já está pago ou autorizado, o pedido não muda. Uma nota pede que você verifique e reembolse a duplicata na Datatrans. Uma transação falha ou cancelada nunca rebaixa um pedido pago.
Bloco Datatrans payment
A página do pedido mostra um bloco Datatrans payment com o ID da transação, o status na Datatrans, o método de pagamento, o valor, os valores pagos e reembolsados, um selo Sandbox para pagamentos de sandbox, o histórico de reembolsos e as Datatrans notes do pedido. As ações do bloco exigem a permissão para editar pedidos; o acesso às páginas de módulos não é necessário.
Captura e cancelamento
Para um pagamento apenas autorizado, o bloco mostra Capture Datatrans payment e Cancel Datatrans authorization. A captura liquida o pagamento pelo total atual do pedido, que não pode ser maior que o valor autorizado; depois o pedido passa para o status de Order status after payment. O cancelamento libera a autorização e coloca o pedido em Canceled. Ambas as ações vão para o ambiente do pagamento. Se a Datatrans recusar, o bloco mostra o erro e uma nota é adicionada.
Reembolsos
No bloco Datatrans payment, digite o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Datatrans. Confirme a pergunta Refund this amount through Datatrans? This cannot be undone. São aceitos reembolsos totais e parciais, até o valor que a Datatrans efetivamente cobrou menos os reembolsos anteriores. O reembolso é enviado ao ambiente do pagamento, por isso o Merchant ID e a senha de API desse ambiente precisam estar preenchidos. Um reembolso repetido não é creditado duas vezes. Se a Datatrans não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico e às notas, com o ID da transação de reembolso da Datatrans. Um reembolso total coloca o pedido em Refunded; um reembolso parcial não muda o status.
Em um pagamento apenas autorizado, nada foi cobrado ainda: só é possível "reembolsar" o valor total, o que cancela a autorização. Os reembolsos ficam disponíveis quando a Datatrans liquida o pagamento; uma autorização com valor divergente não pode ser reembolsada até ser liquidada.
O módulo não cria notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Datatrans. Reembolsos feitos no Web Admin da Datatrans não são registrados 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 Datatrans Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox Datatrans 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-datatrans 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 Datatrans 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
Datatrans does not appear at checkout: verifique se a licença está ativa, se Enable/Disable está ativado e se o ambiente atual tem o seu Merchant ID e a sua senha de API: os campos de sandbox no modo sandbox, os campos de produção nos demais casos. A página de configurações lista os campos que faltam. 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: a Datatrans não conseguiu alcançar a URL do webhook e o cliente não voltou à loja. Verifique se a loja está acessível pela internet e se nenhum firewall bloqueia requisições para a URL do webhook. Verifique se a chave de assinatura nas configurações pertence ao ambiente do pagamento. Consulte o campo Log na página do módulo.
Webhook answers Invalid signature: a chave de assinatura HMAC nas configurações não corresponde à do Web Admin da Datatrans, ou pertence ao outro ambiente. Copie a chave novamente.
Webhook answers Not configured or Verification failed: o webhook precisava ser verificado pela API de status da Datatrans, mas as credenciais desse ambiente estão ausentes, ou a Datatrans não respondeu. A Datatrans tenta o webhook novamente.
Webhook answers Busy, retry: o pedido estava sendo confirmado por outra requisição naquele mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). A Datatrans tenta o webhook novamente. O log mostra o motivo.
The webhook URL shows Method not allowed in the browser: isso é normal. A URL aceita apenas requisições da Datatrans.
The HMAC sign key is not saved: a chave precisa ser uma string hexadecimal. Copie-a novamente do Web Admin da Datatrans.
The customer sees Datatrans payments are not configured yet: o Merchant ID ou a senha de API do ambiente atual está ausente.
The customer sees The payment could not be started: consulte o campo Log. Um Merchant ID ou uma senha de API incorretos, ou credenciais do ambiente errado, são as causas mais comuns.
Order is Datatrans payment on hold after payment: leia as Datatrans notes no bloco do pedido (veja Status do pedido) e, então, atenda o pedido ou reembolse o pagamento.
Capture is refused: o total do pedido é maior que o valor autorizado. A Datatrans não pode liquidar mais do que foi autorizado.
Refund or capture fails with a message about missing credentials: o pagamento foi feito no outro ambiente, e o Merchant ID ou a senha de API dele não estão definidos. Digite-os e tente novamente.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Datatrans 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 on uninstall 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. As transações e reembolsos da Datatrans e o status de pedido Datatrans payment on hold são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados ou capturados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
Datatrans é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Datatrans.