VibeFox dLocal for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo.
PHP: 8.0 ou superior. O plugin se recusa a ser ativado em uma versão mais antiga do PHP ou do WordPress.
Acesso ao site: o seu site precisa estar acessível pela internet e usar HTTPS em produção, para que o dLocal Go possa entregar as notificações de pagamento. Um firewall, o modo de manutenção ou a autenticação básica podem bloqueá-las.
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 teste (sandbox), dashboard.dlocalgo.com para produção. Teste e produção usam credenciais diferentes. A API corporativa dLocal Payments (credenciais X-Login / X-Trans-Key) é outro produto e não é compatível.
Países e moedas: o plugin 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 da loja.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_dlocal_payment para /wp-content/plugins/ por FTP.
2. Clique em Activate. O WooCommerce precisa estar ativo.
3. Abra as configurações: WooCommerce > Settings > Payments > dLocal Go > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Digite a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Escolha o Environment e cole a chave de API e o segredo de API desse ambiente (veja Configuração).
6. Ative Enable/Disable e salve. Teste um pagamento no ambiente de teste e depois mude Environment para Production.
Configuração
Todas as configurações ficam em uma página: WooCommerce > Settings > Payments > dLocal Go. O título da página mostra SANDBOX ou PRODUCTION. Enquanto a chave de API e o segredo do ambiente selecionado não forem informados, a página avisa que o método de pagamento está oculto na finalização de compra. Enquanto o ambiente de teste estiver selecionado e o gateway estiver ativado, ela mostra Sandbox mode is active: payments are simulated, no money is charged. Na lista de métodos de pagamento, o dLocal Go aparece como pendente de configuração até que as credenciais sejam definidas, e mostra Test mode no ambiente de teste.
Geral
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 os clientes veem na finalização de compra. Padrão: dLocal Go.
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 da API
Copie a chave de API e o segredo de API do painel do dLocal Go, Payment integration: dashboard-sbx.dlocalgo.com (teste) ou dashboard.dlocalgo.com (produção). Todos os campos de credenciais são campos de senha.
Environment: quais credenciais e quais servidores do dLocal Go são usados.
Sandbox API Key: a sua chave de API de teste do dLocal Go.
Sandbox API Secret: o seu segredo de API de teste do dLocal Go.
Production API Key: a sua chave de API de produção do dLocal Go.
Production API Secret: o seu segredo de API de produção do dLocal Go.
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 pedido não tem nenhum dos dois. Padrão: Uruguay.
Auto-complete orders: Set paid orders to "Completed" instead of "Processing". O status é definido de uma só vez, com um único conjunto de e-mails. Padrão: desativado.
Notificações (IPN)
As notificações informam a sua loja de que um pagamento ou um reembolso mudou. O plugin envia as URLs de notificação ao dLocal Go com cada pagamento e reembolso, então nada precisa ser configurado no painel do dLocal Go. Esta seção das configurações mostra as duas URLs:
As notificações são verificadas com o seu segredo de API (HMAC-SHA256). Notificações sem uma assinatura válida são rejeitadas. 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, um pedido só é atualizado quando o cliente volta à loja.
Avançado
Debug log: Log API requests and notifications grava detalhes em WooCommerce > Status > Logs, origem wcp_dlocal_payment, sem credenciais de API nem dados pessoais. Erros são sempre registrados. Padrão: desativado.
Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted (order payment data is kept). Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão dLocal Go) e faz o pedido. O plugin cria um pagamento dLocal Go no valor total do pedido, na moeda do pedido, 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 pedido. No modo de teste, a finalização de compra mostra Sandbox mode: no real payment is made. abaixo do método de pagamento.
Depois de pagar, o cliente volta para a página de pedido recebido da sua loja. O pedido só é marcado como pago depois que o dLocal Go o confirma: pela notificação assinada ou por uma solicitação do servidor à API do dLocal Go quando o cliente chega a essa página.
Se o cliente sair da página do dLocal Go sem pagar, ele volta à finalização de compra (ou à página Pay for order) 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. Se o pagamento acabar constando como pago, o cliente é enviado para a página de pedido recebido. Um link de pagamento mais antigo do mesmo pedido ainda pode ser pago depois de uma nova tentativa.
Se o dLocal Go não conseguir iniciar o pagamento, o cliente vê uma mensagem curta sem detalhes técnicos, por exemplo dLocal could not start the payment: seguida do motivo informado pela dLocal, e pode escolher outro método. Isso também acontece quando o país do cliente e a moeda da loja não estão habilitados na sua conta dLocal Go. O motivo técnico é 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 armazenamento de pedidos de alto desempenho (HPOS) do WooCommerce.
O plugin aceita apenas pagamentos avulsos na página do dLocal Go. Não há formulário de cartão no seu site, nem cartões salvos, nem assinaturas, nem autorização e captura separadas.
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado ao dLocal Go e ainda não pagou, ou o pagamento está pendente no dLocal Go (por exemplo, um boleto em dinheiro ainda não pago). Cada nova tentativa de pagamento é anotada no pedido com o ID do pagamento dLocal, o valor e o ambiente.
Processing or Completed: o pagamento foi confirmado. O pedido fica como Processando (o padrão do WooCommerce), ou Concluído com Auto-complete orders ativado. O ID da transação é o ID do pagamento dLocal.
On hold: o dLocal Go informou um valor ou uma moeda diferente do total do pedido, ou o pagamento chegou depois que o pedido foi cancelado. A nota do pedido explica o motivo. Compare com o painel do dLocal Go e atenda o pedido ou reembolse o pagamento.
Failed: a última tentativa de pagamento foi recusada ou expirou. O cliente pode tentar de novo.
Cancelled: o dLocal Go informou que a última tentativa de pagamento foi cancelada.
Somente a última tentativa de pagamento pode fazer um pedido não pago falhar ou ser cancelado. Um pedido pago nunca é reaberto por uma notificação antiga. Se chegar um segundo pagamento para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você reembolse o pagamento duplicado no painel do dLocal Go.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via dLocal Go. Reembolsos totais e parciais são aceitos para pedidos pagos pelo dLocal Go. 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 WooCommerce mostra o erro e nenhum reembolso é registrado. Um reembolso aceito é adicionado às notas do pedido com o ID e o status do reembolso.
Depois, o dLocal Go informa o status final do reembolso pela notificação de reembolso, e ele é adicionado às notas do pedido. Se o dLocal Go mais tarde rejeitar ou cancelar um reembolso que havia aceitado, a nota avisa que o dinheiro não foi devolvido ao cliente. Revise o reembolso do WooCommerce registrado para ele: exclua-o e reembolse de novo, ou reembolse o cliente de outra forma.
Reembolsos feitos no painel do dLocal Go não são registrados como reembolsos do WooCommerce e normalmente não adicionam nota ao pedido. Se necessário, crie um reembolso manual no WooCommerce sem Refund via dLocal Go.
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 > dLocal Go. 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 de novo, 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 vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio dele. 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. Gerentes da loja conectados continuam vendo o método de pagamento, marcado (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: pagamentos já iniciados continuam sendo confirmados, e os reembolsos 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
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 definidos. A página de configurações mostra um aviso quando eles faltam.
O pagamento foi aprovado, mas o pedido continua como Pagamento pendente: o dLocal Go não conseguiu acessar a URL de notificação (firewall, modo de manutenção, autenticação básica) e o cliente não voltou à página de pedido recebido. Verifique WooCommerce > Status > Logs, origem wcp_dlocal_payment, e o pagamento no painel do dLocal Go. Assim que chega uma notificação ou o cliente abre a página de pedido recebido, o pedido é atualizado.
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 dos dois ambientes, então pagamentos iniciados antes de você mudar Environment continuam sendo confirmados, desde que as credenciais do ambiente deles permaneçam nas configurações.
A notificação responde Gateway not configured: faltam as credenciais do ambiente selecionado. O dLocal Go tenta enviar 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 tenta enviar a notificação novamente.
A notificação responde Order not found: o pagamento não pertence a um pedido desta loja; por exemplo, 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 pedido fica como Aguardando após o pagamento: leia a nota do pedido. O valor ou a moeda pagos eram diferentes do pedido, ou o pagamento chegou depois que o pedido foi cancelado. Atenda 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 definidas. Informe-as e tente de novo.
O bloco de licença mostra um erro: siga a mensagem do bloco. Por exemplo, se a chave já está em uso em outro domínio, libere uma vaga na sua conta 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, a documentação do plugin lista os filtros dlocal_p_payment_data, dlocal_p_currency_decimals e dlocal_p_icon.
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ão removidos somente se Delete data on uninstall estava ativado. Caso contrário, eles permanecem para uma reinstalação posterior. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
dLocal é uma marca comercial de seu respectivo proprietário. Este plugin não é afiliado à dLocal nem endossado por ela.