VibeFox Worldline for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior.
Conta Worldline: uma conta de comerciante na Worldline Direct (antes Ingenico Direct). As contas de teste e de produção são separadas e têm credenciais diferentes. Para cada conta, você precisa do Merchant ID (seu PSPID), de um API Key ID com a sua Secret API Key e de uma chave de webhook com o seu secret. Tudo isso é criado no Merchant Portal da Worldline (veja «Configuration»).
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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_worldline_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Worldline (Ingenico) > Manage, ou clique em Settings abaixo do nome do plugin na página de plugins.
4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira as credenciais de teste, salve as configurações e clique em Test credentials.
6. Adicione a URL do webhook no Merchant Portal da conta de teste e insira a chave e o secret do webhook (veja «Configuration»).
7. Ative Enable/Disable e faça um pagamento de teste. Em seguida, insira as credenciais de produção, repita a configuração do webhook na sua conta de produção, clique em Live credentials e desmarque Test Mode.
Configuration
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Worldline (Ingenico). Na lista de métodos de pagamento, a Worldline aparece como precisando de configuração até que o modo atual tenha um Merchant ID, um API Key ID e uma Secret API Key. Na página de configurações, os campos de credenciais do modo que não está em uso ficam esmaecidos.
General
Enable/Disable: Enable Worldline Gateway 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. Padrão: Worldline.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely via Worldline.
Worldline Direct API
Obtenha as credenciais no Merchant Portal da Worldline, tanto da conta de teste quanto da conta de produção. Seu PSPID é o Merchant ID. Developer > Payment API cria o API Key ID e a Secret API Key, e Developer > Webhooks cria a chave e o secret do webhook. A seção tem links para os dois portais e para a documentação da Worldline.
Test Mode: Enable test mode (pre-production environment, no real money) alterna tanto o endpoint da API quanto as credenciais. O modo de teste usa o ambiente de pré-produção e as credenciais de teste; o modo ao vivo usa o ambiente de produção e as credenciais reais. Padrão: ativado. Desmarque para receber pagamentos reais. Enquanto o modo de teste estiver ativo, os clientes veem Test mode — no real money is charged. abaixo do método de pagamento.
Conta de teste (pré-produção)
Test Merchant ID (PSPID): o PSPID da sua conta de teste.
Test API Key ID: o API Key ID criado em Developer > Payment API da conta de teste.
Test Secret API Key: a Secret API Key que pertence a esse API Key ID.
Test Webhook Key ID: opcional. Quando preenchido, somente os webhooks enviados com esta chave são aceitos.
Test Webhook Secret: o secret do webhook da conta de teste. Ele é usado para verificar a assinatura de cada webhook.
Conta de produção (produção)
Live Merchant ID (PSPID): o PSPID da sua conta de produção.
Live API Key ID: o API Key ID criado em Developer > Payment API da conta de produção.
Live Secret API Key: a Secret API Key que pertence a esse API Key ID.
Live Webhook Key ID: opcional. Quando preenchido, somente os webhooks enviados com esta chave são aceitos.
Live Webhook Secret: o secret do webhook da conta de produção.
Verificar credenciais
Os botões Test credentials e Live credentials verificam as credenciais salvas de cada conta com uma chamada de teste à Worldline. Salve primeiro as alterações. A resposta aparece ao lado dos botões, por exemplo Test credentials: connection successful., API credentials are not configured. ou o erro retornado pela Worldline.
Webhooks
O webhook informa à sua loja sobre os pagamentos mesmo quando o cliente não volta à loja, por exemplo depois de fechar o navegador ou quando um pagamento é confirmado mais tarde. No Merchant Portal, abra Developer > Webhooks da conta de teste e adicione a URL do endpoint exibida nesta seção das configurações. Ela tem a seguinte forma: https://your-site/wc-api/wlg_worldline_webhook/. Copie a URL exatamente como as configurações a mostram: ela precisa responder sem redirecionamentos, então verifique os prefixos de idioma e os redirecionamentos forçados para www ou https. Depois, insira o ID e o secret da chave do webhook em Test Webhook Key ID e Test Webhook Secret. Faça o mesmo na conta de produção, com os campos de produção.
O plugin responde automaticamente à solicitação de verificação do endpoint da Worldline. Ele trata eventos de pagamento (mudanças de status de pagamento) e eventos de reembolso (mudanças de status de reembolso). Os demais eventos são aceitos e ignorados. Webhooks sem assinatura válida são rejeitados. Um webhook também é ignorado quando vem de um Merchant ID diferente do da conta cujo secret assinou o webhook. Sem o webhook, um pedido só é confirmado quando o cliente volta à loja após pagar.
Página de pagamento e pedidos
Payment page template: nome opcional de um modelo (variante) de página de pagamento hospedada enviado ao Merchant Portal, por exemplo SimplifiedCustomPaymentPage. Deixe em branco para usar a página de pagamento padrão da Worldline.
Order Status After Payment: o status do pedido assim que a Worldline confirma o pagamento capturado. O status é aplicado imediatamente, sem uma segunda alteração. Os pagamentos são sempre solicitados como venda direta (autorização e captura).
Logging: Enable debug logging grava todas as requisições à API e os webhooks em WooCommerce > Status > Logs, origem wcp_worldline_gateway. Erros e avisos são sempre registrados, mesmo com esta opção desativada. Chaves, dados de cartão e dados pessoais são mascarados. Padrão: desativado.
Delete Data: Delete the plugin settings and logs when the plugin is deleted. Desativar o plugin nunca apaga nada. Os dados de pagamento armazenados nos pedidos são mantidos, porque são necessários para os reembolsos. Padrão: desativado.
Ao atualizar a partir da versão 1.0, o antigo conjunto único de credenciais é transferido para os campos de teste ou de produção, de acordo com o modo que a loja estava usando.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, Worldline) e faz o pedido. O plugin cria uma página de pagamento hospedada da Worldline para o total do pedido, na moeda do pedido, e envia o cliente para a página de pagamento da Worldline. Lá, o cliente paga com cartão, carteira digital ou outro método de pagamento habilitado na sua conta Worldline. Nome de cobrança, endereço, e-mail e telefone são transmitidos à Worldline, e a página de pagamento abre no idioma da sua loja quando a Worldline oferece suporte a ele. Cada tentativa de pagamento recebe uma referência própria, formada pelo ID do pedido e por uma parte aleatória.
Depois de pagar, o cliente volta para a sua loja. O plugin confere o retorno com a tentativa salva e lê o status do pagamento na Worldline, no servidor. O pedido só é marcado como pago depois que a Worldline confirma: por essa verificação de status ou por um webhook assinado. Então o cliente vê a página de pedido recebido.
Se o pagamento não foi concluído, o cliente é levado à página Pay for order com uma mensagem:
Um cliente pode pagar novamente um pedido não pago pela página Pay for order. Se a tentativa anterior tiver sido paga nesse meio-tempo, o cliente vai direto para a página de pedido recebido e não é cobrado duas vezes. Se a página de pagamento anterior ainda estiver aberta para o mesmo valor e modo e tiver sido criada há menos de 30 minutos, o cliente é enviado de volta a ela.
Se a Worldline não conseguir iniciar o pagamento, o cliente vê Payment error: Could not create checkout session. Please try again. e pode escolher outro método de pagamento. O motivo é adicionado às notas do pedido e ao log. Se faltarem as credenciais do modo atual, o cliente vê This payment method is not available at the moment. Please choose another payment method.
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. É compatível com o WooCommerce High-Performance Order Storage (HPOS).
O plugin aceita pagamentos únicos como venda direta na página da Worldline. Não há cartões salvos ou tokenização, assinaturas, formulário de cartão incorporado, modo somente autorização com captura ou cancelamento pelo WooCommerce, cobrança adicional nem registro automático de webhooks.
Pedidos e reembolsos
Order statuses
Pending payment: o cliente foi enviado à Worldline e ainda não pagou, ou a Worldline ainda não confirmou o pagamento. Uma nota mostra o ID da página de pagamento hospedada, a referência e o modo (teste ou produção).
Processing or Completed: o pagamento foi capturado. O status segue Order Status After Payment. A nota do pedido mostra o valor, o ID do pagamento na Worldline e como ele foi confirmado (webhook assinado ou verificação de status). O ID da transação do pedido é o ID do pagamento na Worldline.
On hold, waiting for capture: a Worldline informa que o pagamento está autorizado ou que a captura foi solicitada, mas ainda não capturada. A nota do pedido explica isso. O pedido é marcado como pago automaticamente quando o webhook confirma a captura. Se a nota disser que o pagamento não está capturado, capture-o no Merchant Portal da Worldline.
On hold, held for manual review: o pagamento não corresponde ao pedido, por exemplo porque o valor ou a moeda são diferentes (o pedido foi editado depois que o pagamento começou) ou porque o pagamento pertence a outra tentativa. A nota mostra o valor pago, o total do pedido e a referência. Confira o pedido e atenda-o ou reembolse o pagamento.
Failed: a Worldline recusou ou cancelou o pagamento da última tentativa, ou o cliente não era elegível para o método de pagamento escolhido.
Cancelled: o pedido foi cancelado por você ou pelo tempo limite de reserva de estoque do WooCommerce. Se um pagamento chegar para um pedido cancelado ou reembolsado, o pedido não é reaberto. Uma nota pede que você reembolse ou cancele o pagamento no Merchant Portal da Worldline, ou que restaure o pedido manualmente. O cliente que retorna vê Your payment was received after this order had been cancelled. Please contact us — we will restore the order or refund the payment.
Se chegar um segundo pagamento para um pedido que já está pago, o pedido não é alterado novamente. Uma nota pede que você reembolse o segundo pagamento no Merchant Portal da Worldline.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Worldline (Ingenico). Reembolsos totais e parciais são suportados. O pagamento precisa estar capturado. O reembolso é sempre enviado ao ambiente do pagamento original (teste ou produção), com as credenciais dessa conta, por isso elas precisam estar configuradas. Um reembolso repetido após um tempo limite não é executado duas vezes. Se a Worldline recusar o reembolso, o WooCommerce exibe o erro e nenhum reembolso é registrado. Um reembolso aceito é adicionado às notas do pedido, com o ID e o status do reembolso na Worldline.
As mudanças de status dos reembolsos chegam da Worldline por webhook e são adicionadas às notas do pedido. Os reembolsos feitos no Merchant Portal não são registrados automaticamente como reembolsos do WooCommerce. Se necessário, crie um reembolso manual no WooCommerce sem usar Refund via Worldline (Ingenico).
Chave de licença
O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Worldline (Ingenico). 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 inserir 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 único domínio. Remover a chave de um site não libera a vaga de domínio. Libere-a na sua conta em vibefox.net.
Sem uma chave ativa, a Worldline 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. Gerentes da loja conectados 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 de plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática, em segundo plano.
Solução de problemas
A Worldline não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se o modo atual tem um Merchant ID, um API Key ID e uma Secret API Key: os campos de teste no modo de teste, os campos de produção no modo de produção. A lista de pagamentos marca o método como precisando de configuração quando eles estão faltando.
O pagamento foi aprovado, mas o pedido continua em Pending payment: o webhook não está funcionando. No Merchant Portal da conta que você usa (teste ou produção), verifique se o endpoint existe e se a URL dele é exatamente a exibida nas configurações, sem redirecionamentos. Confira se o secret do webhook dessa conta está no campo correspondente (Test Webhook Secret ou Live Webhook Secret) e se o Webhook Key ID está vazio ou corresponde à chave. O pedido também é confirmado quando o cliente volta à loja após pagar.
O webhook responde Webhook secret not configured: nenhum secret de webhook está definido. Insira o secret do webhook nas configurações. A Worldline repete o webhook.
O webhook responde Invalid signature: o secret do webhook pertence a outra conta ou outra chave, ou o Webhook Key ID não corresponde à chave que enviou o webhook.
O webhook responde Missing signature, Empty body ou Invalid JSON: a requisição não veio da Worldline no formato esperado, ou um proxy ou redirecionamento a alterou. Verifique se a URL responde sem redirecionamentos.
O webhook responde Ignored: o webhook veio de um Merchant ID diferente do configurado nas configurações desse modo. Confira Test Merchant ID (PSPID) ou Live Merchant ID (PSPID).
O webhook responde Retry later: o pedido estava sendo atualizado por outra requisição no mesmo momento. A Worldline repete o webhook.
Test credentials ou Live credentials exibe um erro: salve primeiro as configurações e depois verifique se o Merchant ID, o API Key ID e a Secret API Key vêm da mesma conta, e se os valores de teste estão nos campos de teste e os valores de produção nos campos de produção.
O cliente vê um erro ao fazer o pedido: abra as notas do pedido ou WooCommerce > Status > Logs, origem wcp_worldline_gateway. Os erros são registrados mesmo com o debug logging desativado. Para ver todos os detalhes das requisições, ative Logging e tente novamente.
Pagamentos de teste não confirmam um pedido real: teste e produção são mantidos separados. Um webhook assinado com o secret de teste nunca confirma uma tentativa de pagamento real, e vice-versa. Altere Test Mode para o modo que você quer usar e utilize as credenciais e o webhook dessa conta.
O pedido fica On hold após o pagamento: leia a nota do pedido. Ou a Worldline ainda não confirmou a captura (o webhook conclui o pedido), ou o valor ou a moeda pagos eram diferentes do pedido.
O reembolso falha com uma mensagem sobre o ambiente: o pagamento foi feito no ambiente de teste ou de produção, e as credenciais desse ambiente não estão preenchidas. Insira-as e tente novamente.
Desenvolvedores: o filtro wlg_hosted_checkout_data altera a requisição da página de pagamento hospedada, por exemplo para limitar os métodos de pagamento exibidos, e wlg_gateway_icon altera o ícone do método de pagamento.
O bloco de licença exibe um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso 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 no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.
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 e os logs só são removidos se Delete Data estava ativado. Caso contrário, permanecem para uma reinstalação posterior. Os dados de pagamento da Worldline armazenados nos pedidos são sempre mantidos, porque são necessários para os reembolsos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Worldline é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Worldline.