VibeFox Datatrans for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo.
PHP: 8.0 ou superior.
HTTPS: seu site deve estar acessível pela internet via HTTPS, para que a Datatrans possa entregar os webhooks.
Conta da 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 vêm do Web Admin de sandbox da Datatrans (admin.sandbox.datatrans.com) e as de produção, do Web Admin de produção (admin.datatrans.com). Sandbox e produção são contas separadas da Datatrans, com Merchant IDs e chaves diferentes.
Moeda: a moeda da loja (ou a moeda do pedido do seu plugin multimoeda) deve estar ativada na sua conta de comerciante da Datatrans.
Chave de licença VibeFox: adquirida em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_datatrans_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate. O WooCommerce precisa estar ativo.
3. Abra as configurações: WooCommerce > Settings > Payments > Datatrans > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Digite sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Informe as credenciais de sandbox e, para pagamentos reais, as credenciais de produção (veja Configuração).
6. Ative Enable/Disable. Mantenha Sandbox mode ativado enquanto testa e depois desmarque-o para receber pagamentos reais.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Datatrans. Quando o gateway está ativado, mas falta o Merchant ID ou a senha de API do ambiente atual, a página exibe Datatrans is hidden at checkout until these settings are filled in: com a lista dos campos que faltam. Enquanto o modo sandbox estiver ativado, ela exibe Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged.
Webhook
A Webhook URL é exibida no topo das configurações. Ela tem este formato: https://your-site/wc-api/datatrans_payment_callback/. O plugin envia essa URL à Datatrans a cada transação, então você não precisa informá-la em nenhum lugar. Você também pode informá-la nas configurações de webhook do Web Admin da Datatrans para receber atualizações de capturas e cancelamentos feitos lá.
O webhook informa o estado da transação. O plugin age de acordo com estes estados:
Com uma chave de assinatura HMAC, cada webhook é verificado pelo cabeçalho Datatrans-Signature. Webhooks sem assinatura válida são rejeitados. Sem uma chave de assinatura, o plugin não confia no conteúdo do webhook e confere cada webhook na API de status da Datatrans. Sem o webhook, um pedido só é confirmado quando o cliente volta à loja depois de pagar.
Geral
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 os clientes veem na finalização de compra. Padrão: Datatrans.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely via Datatrans.
Sandbox mode: Use the Datatrans sandbox (test payments, no real money). Alterna tanto os hosts da API e da página de pagamento quanto as credenciais abaixo. Reembolsos e capturas sempre usam o ambiente em que o pagamento foi feito. Padrão: ativado. Desmarque para receber pagamentos reais.
Credenciais de sandbox
Copie-as do Web Admin de sandbox da Datatrans (admin.sandbox.datatrans.com). A chave de assinatura fica nas configurações de segurança de lá.
Sandbox merchant ID: o Merchant ID da sua conta de sandbox.
Sandbox API password: a senha de API servidor a servidor da sua conta de sandbox.
Sandbox HMAC sign key: a chave hexadecimal usada para verificar o cabeçalho Datatrans-Signature dos webhooks. Sem ela, cada webhook é conferido novamente na 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 sua 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 é conferido novamente na API de status da Datatrans.
Uma chave de assinatura deve ser uma cadeia hexadecimal, como emitida pela Datatrans. Qualquer outro valor não é salvo: a página exibe um erro e mantém o valor anterior. Se você atualizar da versão 1.0, o único conjunto de credenciais dessa versão é movido para os campos de sandbox quando o modo sandbox estava ativado; caso contrário, permanece nos campos de produção.
Processamento do pagamento
Auto settle: Capture (settle) payments immediately. Padrão: ativado. Se você o desativar, os pagamentos serão apenas autorizados: o pedido fica com o status Aguardando e você o captura depois com a ação do pedido Capture Datatrans payment, ou o libera com Cancel Datatrans authorization.
Order status after payment: o status do pedido definido quando o pagamento é liquidado. O status é definido imediatamente, sem uma segunda mudança de status.
Avançado
Logging: Log payment events and API calls grava detalhes em WooCommerce > Status > Logs, origem wcp_datatrans_gateway. Os erros são sempre registrados. Nenhuma chave, dado de cartão ou dado do cliente é gravado. Padrão: desativado.
Delete data on uninstall: Remove the plugin settings when the plugin is deleted. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, Datatrans) e faz o pedido. O plugin cria uma transação na Datatrans pelo total do pedido na moeda do pedido, com o ID do pedido como referência, e envia o cliente à página de pagamento da Datatrans. Lá, o cliente paga com qualquer método ativado na sua conta da Datatrans, por exemplo cartão, TWINT ou PostFinance. A página de pagamento abre em alemão, inglês, francês ou italiano quando o seu site usa um desses idiomas; caso contrário, a Datatrans escolhe o idioma.
Depois de pagar, o cliente volta à página de pedido recebido da sua loja. O pedido só é marcado como pago depois que a Datatrans o confirma: pelo webhook ou por uma solicitação no servidor à API de status da Datatrans quando o cliente retorna. O endereço de retorno traz a chave do pedido, e o retorno em si nunca marca um pedido como pago.
Se o cliente cancelar na página de pagamento, ele vai para a página Pay for order com a mensagem The payment was canceled. You can try again or choose another payment method. Após um pagamento com falha, a mensagem é The payment was not completed. Please try again or choose another payment method. O pedido continua podendo ser pago, e o cliente pode tentar novamente.
Se a Datatrans não conseguir iniciar o pagamento, o cliente vê The payment could not be started. Please try again or choose another payment method. O motivo é gravado no log.
O método de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. Ele é compatível com o High-Performance Order Storage (HPOS) do WooCommerce.
O plugin aceita apenas pagamentos únicos na página de pagamento da Datatrans. Não há cartões salvos ou aliases, assinaturas, integração do Lightbox ou do Secure Fields, escolha dos métodos de pagamento nas configurações nem captura parcial de uma autorização.
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado à Datatrans e ainda não pagou, cancelou na página de pagamento, ou a Datatrans ainda não confirmou o pagamento. Cada nova transação é anotada no pedido com seu ID e ambiente.
Processing, Completed or On Hold: o pagamento foi liquidado. O status segue Order status after payment. A nota do pedido mostra o valor, o método de pagamento, o ID da transação da Datatrans e o ambiente (sandbox ou produção). O ID da transação é salvo no pedido.
On hold, authorized: com Auto settle desativado, o pagamento foi autorizado, mas não capturado. Abra o pedido e escolha Capture Datatrans payment ou Cancel Datatrans authorization nas ações do pedido. A captura usa o total atual do pedido, que não pode ser maior que o valor autorizado. Se for, ou se a Datatrans rejeitar a captura ou o cancelamento, o motivo é adicionado às notas do pedido.
On hold after payment: a Datatrans informou um valor ou uma moeda diferente do total do pedido (por exemplo, o pedido foi editado depois que o pagamento começou), ou o pagamento chegou depois que o pedido havia sido cancelado. A nota do pedido explica. Verifique a transação no Web Admin da Datatrans e atenda o pedido ou reembolse o pagamento.
Failed: o pagamento falhou ou foi recusado. O cliente pode tentar novamente.
Cancelled: a autorização foi liberada, pela ação do pedido ou no Web Admin da Datatrans.
Um aviso tardio de falha ou cancelamento nunca altera um pedido pago. Se um segundo pagamento bem-sucedido chegar para um pedido que já está pago, o pedido não é alterado. Uma nota avisa sobre uma possível cobrança duplicada e pede que você a reembolse na Datatrans, se necessário.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Datatrans. Reembolsos totais e parciais são aceitos. O reembolso é enviado ao ambiente em que o pagamento foi feito, então as credenciais desse ambiente precisam estar definidas. Um reembolso repetido não é creditado duas vezes. Se a Datatrans não aceitar o reembolso, o WooCommerce mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o valor e o ID da transação de reembolso da Datatrans.
Para um pagamento apenas autorizado, o reembolso do valor total cancela a autorização. Um reembolso parcial não é possível até que o pagamento seja capturado.
Reembolsos feitos no Web Admin da Datatrans não são registrados no WooCommerce. Se necessário, crie um reembolso manual no WooCommerce sem Refund via Datatrans.
Chave de licença
O plugin funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Datatrans. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa e o seu domínio. Use Check now para verificar o status novamente, Change key para informar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta em vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do 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. Os gerentes da loja que estiverem logados continuam vendo o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados, e reembolsos e capturas funcionam.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática em segundo plano.
Solução de problemas
A Datatrans não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o Merchant ID e a senha de API do ambiente atual estão definidos: os campos de sandbox no modo sandbox, os de produção nos demais casos. A página de configurações lista os campos que faltam.
O pagamento foi concluído, mas o pedido continua em Pagamento pendente: a Datatrans não conseguiu acessar a URL do webhook e o cliente não voltou à loja. Verifique se o site está acessível pela internet via HTTPS e se nenhum plugin de segurança ou firewall bloqueia as solicitações para /wc-api/datatrans_payment_callback/. Verifique se a chave de assinatura nas configurações pertence ao ambiente do pagamento. Ative Logging e consulte WooCommerce > Status > Logs, origem wcp_datatrans_gateway.
O webhook responde 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.
O webhook responde Not configured ou Verification failed: o webhook precisava ser conferido na API de status da Datatrans, mas as credenciais desse ambiente estão ausentes, ou a Datatrans não respondeu. A Datatrans reenvia o webhook.
A chave de assinatura HMAC não é salva: a chave deve ser uma cadeia hexadecimal. Copie-a novamente do Web Admin da Datatrans.
O cliente vê The payment could not be started: o Merchant ID ou a senha de API está errado, pertence ao outro ambiente, ou a moeda não está ativada na sua conta da Datatrans. Ative Logging para ver o motivo.
O pedido fica Aguardando após o pagamento: leia a nota do pedido. O valor ou a moeda pagos diferiam do pedido, o pagamento chegou depois que o pedido foi cancelado, ou o pagamento está apenas autorizado e aguarda captura.
A captura não é possível: o total do pedido é maior que o valor autorizado. A captura usa o total atual do pedido, então reduza-o para o valor autorizado ou menos.
O reembolso falha com uma mensagem sobre credenciais: o pagamento foi feito no outro ambiente, e as credenciais dele não estão definidas. Informe-as e tente novamente. Para um pagamento autorizado, reembolse o valor total ou capture-o antes.
O bloco de licença mostra um erro: siga a mensagem do bloco. Por exemplo, se a chave já é usada em outro domínio, libere uma vaga na sua conta em vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave para o novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.
Para desenvolvedores, o readme menciona o filtro wcp_datatrans_gateway_init_request, por exemplo para limitar os métodos de pagamento exibidos na página da Datatrans.
Desinstalação
Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin são sempre removidos. As configurações do gateway só são removidas se Delete data on uninstall estava ativado. Caso contrário, elas permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
Datatrans é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado à Datatrans nem endossado por ela.