VibeFox Worldline 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 anteriores do PHP.

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 o respectivo Secret API Key e de uma chave de webhook com o respectivo secret. Todos são criados no Merchant Portal da Worldline (veja Configuração).

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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 Worldline Gateway na lista de módulos 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 as credenciais de teste, clique em Save e depois em Test credentials.

5. Adicione a URL do webhook no Merchant Portal da conta de teste e insira a chave e o secret do webhook (veja Configuração).

6. Ative Enable/Disable e faça um pagamento de teste. Depois insira as credenciais de produção, repita a configuração do webhook na sua conta de produção, clique em Live credentials e desative Test Mode.

Ao instalar, o módulo cria dois status de pedido: Awaiting Worldline capture e Worldline payment on hold. O PrestaShop ativa um novo módulo de pagamento para os países ativos naquele momento. Confira moedas, países e grupos de clientes em Payment > Preferences e marque ali os países que você adicionar depois.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Worldline Gateway > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa se as credenciais do modo atual (Merchant ID, API Key ID, Secret API Key) estiverem incompletas, porque nesse caso o método de pagamento fica oculto no checkout. Enquanto o modo de teste estiver ligado, a página mostra Test mode is on (pre-production environment): no real money is charged.

Worldline (Ingenico)

Enable/Disable: Enable Worldline Gateway liga ou desliga o método de pagamento. Padrão: desligado.

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: Worldline. Obrigatório.

Description: o texto exibido abaixo do método de pagamento no checkout. Padrão: Pay securely via Worldline.

Worldline Direct API

Obtenha as credenciais no Merchant Portal da Worldline da conta de teste e da conta de produção. Seu PSPID é o Merchant ID. Em Developer > Payment API são criados o API Key ID e o Secret API Key; em Developer > Webhooks, 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: troca ao mesmo tempo o endpoint da API e 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: ligado. Desligue para receber pagamentos reais. Enquanto o modo de teste estiver ligado, 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: o Secret API Key que pertence a esse API Key ID.

Test Webhook Key ID: opcional. Quando preenchido, só são aceitos webhooks enviados com esta chave.

Test Webhook Secret: o secret do webhook da conta de teste. Ele é usado para verificar a assinatura de cada webhook.

Conta de produção (ao vivo)

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: o Secret API Key que pertence a esse API Key ID.

Live Webhook Key ID: opcional. Quando preenchido, só são aceitos webhooks enviados com esta chave.

Live Webhook Secret: o secret do webhook da conta de produção.

Chaves secretas e secrets de webhook já salvos nunca são mostrados novamente. O campo fica vazio e exibe Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.

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

Check credentials: os botões Test credentials e Live credentials verificam as credenciais salvas de cada conta com uma chamada de teste à Worldline. Salve suas alterações primeiro. A resposta aparece no topo da página, por exemplo Test credentials: connection successful., API credentials are not configured. ou o erro retornado pela Worldline.

Webhooks

O webhook informa sua loja sobre 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 exibida em Endpoint URL nesta seção. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_worldline_gateway/webhook, possivelmente com um código de idioma como /en/. Copie a URL exatamente como as configurações a mostram: ela precisa responder sem redirecionamentos. Em seguida, 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 módulo responde automaticamente à requisição de verificação do endpoint da Worldline. Ele trata eventos de pagamento (mudanças de status dos pagamentos) e eventos de reembolso (mudanças de status dos reembolsos). Os demais eventos são aceitos e ignorados. Webhooks sem assinatura válida são rejeitados. Um evento precisa estar assinado com o secret da conta em que o pagamento foi feito, de modo que um webhook de teste nunca confirma um pagamento real. Um webhook também é ignorado quando vem de um Merchant ID diferente do da conta cujo secret o assinou. Sem o webhook, um pedido só é criado quando o cliente volta à loja depois de 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 padrão da Worldline.

Order Status After Payment: o status do pedido assim que a Worldline confirma o pagamento capturado. Os pagamentos são sempre solicitados como venda direta (autorização e captura).

Pagamentos autorizados aguardam em Awaiting Worldline capture. Divergências de valor ou moeda sempre vão para Worldline payment on hold.

Avançado

Logging: grava todas as requisições à API e os webhooks em logs/wlg_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados, mesmo com esta opção desligada. Chaves, dados de cartão e dados pessoais são mascarados. Padrão: desligado.

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

Delete Data: quando ligado, desinstalar o módulo remove as configurações do módulo e o log. As transações e os reembolsos da Worldline e os status de pedido do módulo sempre permanecem, pois os pedidos existentes precisam deles para os reembolsos. Padrão: desligado.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, Worldline) e confirma. O módulo cria uma página de pagamento hospedada da Worldline para o total do carrinho na moeda do carrinho 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 repassados à Worldline, e a página de pagamento abre no idioma do cliente quando a Worldline oferece suporte a ele. Cada tentativa de pagamento recebe uma referência própria, formada pelo ID do carrinho e por uma parte aleatória. Nesse momento, ainda não existe pedido.

Depois de pagar, o cliente volta à sua loja. O módulo 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 pedido é criado, e o cliente vê a página padrão de confirmação do pedido com Your payment with Worldline has been received. Se o pagamento estiver autorizado, mas ainda não capturado, a página mostra Your payment is authorized. The order is confirmed as soon as Worldline confirms the capture. Se o pagamento de um pedido assim falhar depois, a página mostra Your Worldline payment was not completed. Please contact us about this order.

Se o pagamento não foi concluído, nenhum pedido é criado, o carrinho é mantido e o cliente volta à finalização de compra com uma mensagem:

Se o status ainda não puder ser verificado, uma página Payment confirmation mostra We could not confirm your payment yet. If you completed the payment, please do not pay again — you will receive a confirmation as soon as Worldline confirms it. com os botões Check again e Back to checkout. O webhook cria o pedido assim que chegar.

Quando o cliente paga o mesmo carrinho de novo, o módulo verifica primeiro a tentativa anterior. Se ela tiver sido paga nesse meio-tempo, o cliente vai direto à confirmação do pedido 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 puder iniciar o pagamento, o cliente permanece na finalização de compra com Payment error: Could not create checkout session. Please try again. O motivo é gravado no log. Se as credenciais do modo atual estiverem ausentes, o cliente vê This payment method is not available at the moment. Please choose another payment method.

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 como venda direta na página da Worldline. Não há cartões salvos nem tokenização, assinaturas, formulário de cartão incorporado, modo somente autorização com captura ou cancelamento pelo PrestaShop, cobrança adicional nem registro automático de webhooks.

Pedidos e reembolsos

Status do pedido

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

Payment accepted or Delivered: o pagamento foi capturado. O status segue Order Status After Payment. O pagamento é registrado com o ID de pagamento da Worldline como ID da transação, e uma nota mostra o valor, o ID do pagamento e como ele foi confirmado (webhook assinado ou verificação de status).

Awaiting Worldline capture: a Worldline informa que o pagamento está autorizado ou que a captura foi solicitada, mas ainda não capturada. Nenhum pagamento foi registrado ainda. O pedido passa ao status pago quando o webhook confirma a captura. Se a nota disser que o pagamento não está capturado, capture-o no Merchant Portal da Worldline.

Worldline payment on hold: o pagamento não corresponde ao carrinho, por exemplo porque o valor ou a moeda são diferentes (o carrinho foi alterado 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. Verifique o pedido e atenda-o, ou reembolse o pagamento.

Payment error: a Worldline recusou ou cancelou o pagamento de um pedido que aguardava a captura.

Refunded: o pagamento foi totalmente reembolsado pelo módulo.

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 restaure o pedido manualmente. O cliente que volta 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 já pago, o pedido não é alterado. Uma nota pede que você reembolse o segundo pagamento no Merchant Portal da Worldline.

Bloco de pagamento Worldline

A página do pedido mostra um bloco Worldline payment com o ID do pagamento, a referência do comerciante, a página de pagamento hospedada, o status da tentativa, o valor cobrado e o valor reembolsado, um selo Test environment para pagamentos de teste, o histórico de reembolsos e as Payment notes do pedido.

Reembolsos

No bloco Worldline payment, informe o valor (o valor ainda não reembolsado vem preenchido), opcionalmente um motivo, e clique em Refund via Worldline. Confirme a pergunta Refund this amount through Worldline? This cannot be undone. Reembolsos totais e parciais são suportados. O pagamento precisa estar capturado. Você precisa da permissão para editar pedidos; o acesso às páginas de módulos não é necessário. Os reembolsos são feitos no valor e na moeda cobrados pela Worldline, então, após uma divergência de valor ou moeda, você pode reembolsar até o que o cliente realmente pagou, e não o total do pedido. O reembolso é sempre enviado ao ambiente do pagamento original (teste ou produção) com as credenciais dessa conta, por isso elas precisam estar preenchidas. Um reembolso repetido após um tempo limite não é executado duas vezes, e apenas um reembolso por pedido é processado por vez. Se a Worldline recusar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso aceito é adicionado ao histórico de reembolsos e às notas, com o ID e o status do reembolso na Worldline. Um reembolso total define o pedido como Refunded. Um reembolso parcial não altera o status.

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

As mudanças de status dos reembolsos vindas da Worldline chegam por webhook, atualizam o histórico de reembolsos e são adicionadas às notas. Reembolsos feitos no Merchant Portal não alteram o status do pedido nem criam notas de crédito. Atualize-os manualmente, se necessário.

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 Worldline Gateway é o primeiro bloco de Modules > Module Manager > VibeFox Worldline 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-payment-worldline e o link Manage licenses and domains in your account, que abre sua conta vibefox.net. Somente 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, 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. 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 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 renovação. O status é verificado novamente automaticamente enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser informada, 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

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 Merchant ID, API Key ID e Secret API Key: os campos de teste no modo de teste, os campos de produção no modo de produção. A página de configurações mostra um aviso quando eles estão faltando. Em Payment > Preferences, confira se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente.

O pagamento foi feito, mas nenhum pedido foi criado: o webhook não está funcionando. No Merchant Portal da conta que você usa (teste ou produção), confira se o endpoint existe e se a URL é exatamente a exibida em Endpoint URL, sem redirecionamentos. Confira se o secret do webhook dessa conta está no campo correspondente (Test Webhook Secret ou Live Webhook Secret) e se o campo de ID da chave do webhook está vazio ou corresponde à chave. O pedido também é criado quando o cliente volta à loja depois de pagar.

Se o webhook responder Webhook secret not configured: nenhum secret de webhook está definido. Insira o secret do webhook nas configurações. A Worldline tenta o webhook novamente.

Se o webhook responder Invalid signature: o secret do webhook pertence a outra conta ou outra chave, ou o ID da chave do webhook não corresponde à chave que enviou o webhook. Confira se os secrets de teste e de produção não foram trocados.

Se o webhook responder 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. Confira se a URL responde sem redirecionamentos.

Se o webhook responder Ignored: o webhook veio de um Merchant ID diferente do que está nas configurações desse modo. Confira Test Merchant ID (PSPID) ou Live Merchant ID (PSPID).

Se o webhook responder Retry later: 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 Worldline tenta o webhook novamente. Veja o campo Log para o motivo.

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

Se Test credentials ou Live credentials mostrar um erro: salve as configurações primeiro e depois confira se Merchant ID, API Key ID e Secret API Key vêm da mesma conta e se os valores de teste estão nos campos de teste e os de produção nos campos de produção.

O cliente vê um erro ao escolher a Worldline: veja o campo Log na página do módulo. Os erros são registrados mesmo com Logging desligado. Para ver todos os detalhes das requisições, ligue Logging e tente novamente.

Pagamentos de teste não confirmam um pagamento real: teste e produção são separados. Altere Test Mode para o modo que você quer usar e use as credenciais e o webhook dessa conta.

O pedido está em Worldline payment on hold ou Awaiting Worldline capture após o pagamento: leia as notas no bloco Worldline payment (veja Status 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 carrinho.

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 hook actionWlgHostedCheckoutData altera a requisição da página de pagamento hospedada antes de ela ser enviada, por exemplo para limitar os métodos de pagamento exibidos.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Worldline 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 ligado, as configurações do módulo e o log são removidos. Se estiver desligado, todas as configurações são mantidas para uma reinstalação futura. As transações e os reembolsos da Worldline e os status de pedido Awaiting Worldline capture e Worldline payment on hold são sempre mantidos, para que pedidos pagos antes ainda possam ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

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