VibeFox dLocal 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.

Acesso à loja: sua loja deve estar acessível pela internet e usar HTTPS em produção, para que o dLocal Go possa enviar as notificações de pagamento.

Conta dLocal Go: você precisa da chave de API e do segredo de API do painel do dLocal Go, seção Payment integration: dashboard-sbx.dlocalgo.com para sandbox, dashboard.dlocalgo.com para produção. Sandbox e produção usam credenciais diferentes. A API corporativa dLocal Payments (credenciais X-Login / X-Trans-Key) é um produto diferente e não é suportada.

Países e moedas: o módulo não os limita. O dLocal Go decide quais métodos de pagamento são oferecidos para o país do cliente e a moeda do carrinho. Só se aplicam as restrições de pagamento do PrestaShop.

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 encontre VibeFox dLocal Payment depois 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. Escolha o Environment e cole a chave de API e o segredo de API desse ambiente (veja Configuração).

5. Ative Enable/Disable e clique em Save. Teste um pagamento em sandbox e depois mude o Environment para Production.

Ao ser instalado, o módulo cria o status de pedido dLocal 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 dLocal Payment > Configure. Cada seção tem o próprio botão Save, que salva a página inteira. O título da primeira seção mostra SANDBOX ou PRODUCTION. Até que a chave de API e o segredo do ambiente selecionado sejam informados, a página avisa que o método de pagamento fica oculto na finalização de compra, por exemplo Enter the sandbox API key and secret: until then the payment method is hidden at checkout. Quando o sandbox está selecionado e o método de pagamento está ativado, aparece Sandbox mode is active: payments are simulated, no money is charged.

dLocal Go

Enable/Disable: Enable dLocal Go 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: dLocal Go. Obrigatório.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay with local cards, bank transfer or cash via dLocal Go.

Credenciais de API

Copie a chave de API e o segredo de API do painel do dLocal Go, Payment integration: dashboard-sbx.dlocalgo.com (sandbox) ou dashboard.dlocalgo.com (produção). A seção traz links para os dois painéis.

Environment: quais credenciais e quais servidores do dLocal Go são usados para novos pagamentos.

Reembolsos e notificações de um pagamento sempre usam as credenciais do ambiente em que ele foi feito. Por isso, mantenha as credenciais do outro ambiente enquanto os pagamentos dele estiverem abertos ou puderem ser reembolsados.

Sandbox API Key: sua chave de API de sandbox do dLocal Go.

Sandbox API Secret: seu segredo de API de sandbox do dLocal Go.

Production API Key: sua chave de API de produção do dLocal Go.

Production API Secret: seu segredo de API de produção do dLocal Go.

Chaves e segredos salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo apenas se quiser alterá-lo.

Clear saved credentials: marque uma chave ou um segredo e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.

Pagamento

Default country: o dLocal Go mostra os métodos de pagamento do país do cliente, obtido do endereço de cobrança e, depois, do endereço de entrega. Este país é usado quando o carrinho não tem nenhum dos dois. Padrão: Uruguay.

Auto-complete orders: muda os pedidos pagos para Delivered em vez de Payment accepted. O status é definido de imediato, com uma única mudança de status. Padrão: desativado.

Notifications (IPN): as notificações informam sua loja de que um pagamento ou reembolso mudou. O módulo envia as URLs de notificação ao dLocal Go com cada pagamento e cada reembolso, então não é preciso configurar nada no painel do dLocal Go. Este campo mostra as duas URLs:

As notificações são verificadas com o seu segredo de API (HMAC-SHA256). Notificações sem assinatura válida são rejeitadas. Uma notificação deve ser assinada com as credenciais do ambiente em que o pagamento foi feito. Depois disso, o status, o valor e a moeda do pagamento são sempre lidos novamente na API do dLocal Go; o conteúdo da notificação não é considerado confiável. Sem notificações, o pedido só é criado quando o cliente volta para a loja.

Avançado

Debug log: grava as requisições e notificações do dLocal Go em logs/dlocal_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Credenciais de API e dados pessoais não são registrados. Erros e avisos são sempre gravados; os demais registros apenas enquanto esta opção estiver ativada. Padrão: desativado.

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

Delete data on uninstall: quando ativado, desinstalar o módulo remove as configurações do gateway e o log. Os dados de pagamento dos pedidos (pagamentos e reembolsos do dLocal) e o status de pedido dLocal payment on hold são sempre mantidos, para que os pedidos existentes continuem funcionando. Padrão: desativado.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão dLocal Go). No modo sandbox, a finalização de compra mostra Sandbox mode: no real payment is made. abaixo do método de pagamento. Depois da confirmação, o módulo cria um pagamento no dLocal Go para o total do carrinho, na moeda do carrinho, com o país, o nome, o e-mail e o telefone do cliente, e envia o cliente para a página de pagamento do dLocal Go. Lá, o cliente paga com um método do seu país. O pagamento aparece na página do dLocal Go como Order # e o número do carrinho. Neste momento, ainda não existe pedido.

Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que o dLocal Go confirma: pela notificação assinada ou por uma requisição do servidor à API do dLocal Go quando o cliente volta. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Your payment with dLocal Go has been received. Se o pedido foi colocado em espera, a página mostra Your dLocal Go payment has been received and is being reviewed by the store. You will be informed when your order is confirmed. Se o dLocal Go ainda não confirmou o pagamento (por exemplo, um boleto em dinheiro ainda não pago, ou se o dLocal Go não pôde ser acessado), uma página Payment confirmation pede ao cliente que não pague de novo e oferece Check again e Back to checkout. O pedido é criado assim que o dLocal Go confirma o pagamento.

Se o cliente sair da página do dLocal Go sem pagar, ele volta à finalização de compra e vê The payment at dLocal Go was not completed. You can try again or choose another payment method. Se o pagamento foi recusado ou expirou, a mensagem é Your dLocal payment was not completed: it was declined or it expired. Please try again or choose another payment method. O carrinho é mantido. Cada nova tentativa cria um novo pagamento no dLocal Go; um link de pagamento mais antigo do mesmo carrinho ainda pode ser pago e cria o pedido.

Se o dLocal Go não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo dLocal could not start the payment: seguida do motivo informado pelo dLocal. Isso também acontece quando o país do cliente e a moeda do carrinho não estão habilitados na sua conta dLocal Go. Se o dLocal Go rejeitar as suas credenciais, o cliente vê This payment method is temporarily unavailable. Please choose another payment method or contact us. O motivo técnico é gravado no log.

As notificações funcionam enquanto a loja está em modo de manutenção e não são bloqueadas pela restrição de país da sua loja.

O módulo aceita apenas pagamentos avulsos na página do dLocal Go. Não há formulário de cartão no seu site, cartões salvos, assinaturas nem autorização e captura separadas.

Pedidos e reembolsos

Status do pedido

Ainda sem pedido: o cliente foi enviado ao dLocal Go e não pagou, ou o pagamento ainda está pendente no dLocal Go. Só existe o carrinho.

Payment accepted ou Delivered: o pagamento foi confirmado. O pedido fica como Pagamento aceito, ou como Entregue, com Auto-complete orders ativado. O pagamento é registrado com o ID do pagamento do dLocal como ID da transação, e uma nota mostra o ambiente e o ID do pagamento.

dLocal payment on hold: o dLocal Go informou um valor ou moeda diferente do total do carrinho (por exemplo, o carrinho foi alterado em outra aba depois que o pagamento começou), ou o pagamento chegou depois que o pedido havia sido cancelado. A nota explica o motivo. Compare com o painel do dLocal Go e então processe o pedido ou reembolse o pagamento.

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

Um pagamento recusado, expirado ou cancelado nunca altera um pedido existente. Se chegar um segundo pagamento para um pedido que já foi pago, o pedido não é alterado. Uma nota pede que você reembolse o pagamento duplicado no painel do dLocal Go.

Bloco de pagamento do dLocal Go

A página do pedido mostra um bloco dLocal Go payment com o ID do pagamento do dLocal, o ambiente (com um selo Sandbox para pagamentos de teste), o status do pagamento, o valor cobrado pelo dLocal Go e o valor reembolsado, o formulário de reembolso, o histórico de reembolsos e as dLocal Go notes do pedido.

Reembolsos

No bloco dLocal Go payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via dLocal Go. Confirme a pergunta Refund this amount through dLocal Go? This cannot be undone. São aceitos reembolsos totais e parciais. Você precisa ter 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 pelo dLocal Go. Por isso, 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 é enviado ao ambiente em que o pagamento foi feito, com as credenciais desse ambiente. Se o dLocal Go não aceitar 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 do reembolso, o status e o motivo. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status.

Depois, o dLocal Go informa o status final do reembolso pela notificação de reembolso, e ele é adicionado às notas. Se o dLocal Go rejeitar ou cancelar depois um reembolso que havia aceitado, a nota avisa que o dinheiro não foi devolvido ao cliente. Reembolse o cliente novamente ou por outro meio.

O módulo não cria notas de crédito. Os botões de reembolso padrão do PrestaShop na página do pedido não devolvem dinheiro pelo dLocal Go. Reembolsos feitos no painel do dLocal Go não são registrados como reembolsos no PrestaShop e normalmente não geram nenhuma nota. Atualize o pedido 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 dLocal Payment é o primeiro bloco de Modules > Module Manager > VibeFox dLocal Payment > 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-dlocal 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 dLocal Go não é exibido 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 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

O dLocal Go não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se a chave de API e o segredo de API do Environment selecionado estão preenchidos. 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.

O pagamento foi feito, mas nenhum pedido foi criado: o dLocal Go não conseguiu acessar a URL de notificação (firewall, autenticação básica, sem endereço público) e o cliente não voltou para a loja. Ative o Debug log, veja o campo Log e verifique o pagamento no painel do dLocal Go. Assim que uma notificação chegar ou o cliente clicar em Check again, o pedido é criado.

A notificação responde Missing signature ou Invalid signature: a chave de API e o segredo nas configurações não pertencem à conta que enviou a notificação. As notificações são verificadas com as credenciais do ambiente do pagamento, então pagamentos iniciados antes de você trocar o Environment continuam sendo confirmados, desde que as credenciais do ambiente deles permaneçam nas configurações.

A notificação responde Gateway not configured: as credenciais do ambiente do pagamento estão ausentes. Informe-as; o dLocal Go vai tentar a notificação novamente.

A notificação responde API verification failed: não foi possível acessar a API do dLocal Go para ler o pagamento. O dLocal Go vai tentar a notificação novamente.

A notificação responde Temporarily unavailable: o pedido estava sendo confirmado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). O dLocal Go vai tentar a notificação novamente. O motivo está no log.

A notificação responde Order not found: o pagamento não pertence a um carrinho desta loja, por exemplo porque foi criado por outro site com a mesma conta dLocal Go.

O cliente vê This payment method is temporarily unavailable: o dLocal Go rejeitou a chave de API ou o segredo. Verifique as credenciais do ambiente selecionado.

O cliente vê Payment gateway is not properly configured: as credenciais do ambiente selecionado estão ausentes.

O pedido está em dLocal payment on hold após o pagamento: leia as notas no bloco dLocal Go payment. O valor ou a moeda pagos eram diferentes do carrinho, ou o pagamento chegou depois que o pedido foi cancelado. Processe o pedido ou reembolse o pagamento.

O reembolso falha com uma mensagem sobre credenciais ausentes: o pagamento foi feito no outro ambiente, e as credenciais dele não estão preenchidas. Informe-as e tente novamente.

Para desenvolvedores, a documentação do módulo lista os hooks actionWcpDlocalPaymentData e actionWcpDlocalCurrencyDecimals.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox dLocal Payment 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 gateway e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os pagamentos e reembolsos do dLocal dos pedidos e o status de pedido dLocal payment on hold são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

O dLocal é marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pelo dLocal.