VibeFox Xendit for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior.
Moeda da loja: IDR, PHP, VND, THB, MYR, USD ou SGD. Para outras moedas, o método de pagamento não é exibido. Quais canais de pagamento e moedas estão realmente disponíveis depende da sua conta Xendit.
Conta Xendit: você precisa de uma chave secreta de API com permissão de gravação para Money-in (faturas) para o modo de teste e outra para o modo de produção, além do token de verificação de webhook de cada modo (consulte Configuração). Somente as chaves secretas e os tokens de verificação são usados. Não é necessária chave pública, pois o cliente paga na página de fatura hospedada pela Xendit.
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_xendit_payment_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Xendit > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Cole as suas chaves secretas da Xendit, defina a URL do webhook no Painel de Controle da Xendit e cole os tokens de verificação (consulte Configuração).
6. Ative Enable/Disable. Faça um pedido de teste no modo de teste e depois desmarque Test Mode para receber pagamentos reais.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Xendit. Acima dos campos, um aviso mostra o modo ativo: TEST MODE (as faturas são criadas com a chave secreta de teste e nenhum dinheiro real é cobrado) ou LIVE MODE (as faturas são criadas com a chave secreta de produção e os clientes são cobrados). O aviso alerta quando a chave secreta do modo ativo está ausente ou tem o prefixo errado (nesse caso o método de pagamento fica oculto na finalização de compra), e quando o token de verificação de webhook do modo ativo está vazio (as notificações da Xendit são rejeitadas, então os pedidos só são atualizados quando o cliente volta à sua loja). Na lista de métodos de pagamento, a Xendit aparece como precisando de configuração até que o modo ativo tenha uma chave secreta válida.
Geral
Enable/Disable: Enable Xendit 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: Xendit.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay with virtual accounts, e-wallets, QR codes, retail outlets or cards via Xendit.
Chaves de API
Crie uma chave secreta de API com permissão de gravação para Money-in (faturas) em Xendit Dashboard > Settings > Developers > API keys, uma vez no modo de teste e uma vez no modo de produção. A chave define onde a fatura é criada. Ao salvar, uma chave que não começa com o prefixo do seu campo não é salva, e a página mostra, por exemplo, Test secret key was not saved: it must start with xnd_development_. As demais configurações são salvas.
Test Mode: Enable test mode cria as faturas com a chave secreta de teste, então nenhum dinheiro real é cobrado. Padrão: ativado. Desmarque para aceitar pagamentos reais com a chave secreta de produção.
Test Secret Key: a chave secreta do modo de teste da Xendit. Começa com xnd_development_.
Live Secret Key: a chave secreta do modo de produção da Xendit. Começa com xnd_production_.
Webhooks
O webhook avisa a sua loja de que uma fatura foi paga. Em Xendit Dashboard > Settings > Developers > Webhooks, defina a URL exibida nesta seção das configurações para Invoices > Invoice paid, no modo de teste e no modo de produção. Opcionalmente, defina-a também para Invoice expired. A URL tem este formato: https://your-site/wc-api/xendit_p_callback/. Copie-a exatamente como as configurações a mostram.
Em seguida, copie o Webhook verification token de cada modo do Painel de Controle da Xendit para o campo correspondente. A Xendit o envia no cabeçalho x-callback-token. Notificações sem o token do modo em que a fatura foi criada são rejeitadas. O token apenas comprova que a notificação vem da Xendit: o status, o valor e a moeda da fatura são sempre consultados novamente na API da Xendit com a chave secreta desse modo. Sem o webhook, um pedido só é confirmado quando o cliente volta à loja após pagar.
Test Webhook Verification Token: o token de verificação de webhook do modo de teste da Xendit.
Live Webhook Verification Token: o token de verificação de webhook do modo de produção da Xendit.
Pagamento
Invoice Description: a descrição exibida na fatura da Xendit. Você pode usar os marcadores {order_id}, {order_number} e {site_name}. O HTML é removido e o texto é cortado em 255 caracteres. Padrão: Order #{order_id}.
Order Status After Payment: o status do pedido definido depois que a Xendit confirma o pagamento. O status é definido de imediato, em uma única mudança de status.
Avançado
Debug Log: Log API requests and webhooks grava requisições, webhooks e mudanças de status em WooCommerce > Status > Logs, origem wcp_xendit_payment_gateway. Erros e avisos são sempre registrados, mesmo quando esta opção está desativada. Chaves de API, tokens e dados de clientes não são registrados. Padrão: desativado.
Delete Data on Uninstall: Delete the plugin settings and logs when the plugin is deleted. Desativar o plugin nunca apaga nada. Os dados dos pedidos (IDs das faturas nos pedidos) são sempre mantidos. Padrão: desativado.
Finalização de compra
O método de pagamento é exibido quando a moeda da loja é IDR, PHP, VND, THB, MYR, USD ou SGD. Na página Pay for order, vale a moeda do pedido. O cliente escolhe o método de pagamento (por padrão Xendit) e faz o pedido. O plugin cria uma fatura da Xendit pelo total do pedido na moeda do pedido e envia o cliente para a página de fatura da Xendit. Valores em IDR e VND são arredondados para números inteiros, porque a Xendit não aceita casas decimais nessas moedas. O e-mail de cobrança do cliente é repassado à Xendit. Na página da fatura, o cliente paga com um dos canais de pagamento ativados na sua conta Xendit para essa moeda, por exemplo uma conta virtual, uma carteira eletrônica, um código QR, um ponto de venda ou um cartão.
Depois de pagar, o cliente volta à página de pedido recebido da sua loja. O pedido só é marcado como pago depois que a Xendit confirma: pelo webhook, ou por uma requisição do servidor à API da Xendit quando o cliente chega a essa página. Até lá, o pedido permanece como Pagamento pendente.
Se a fatura falhar ou expirar, a Xendit devolve o cliente. Um pedido feito na finalização de compra é então cancelado da forma padrão do WooCommerce, e a fatura dele é expirada. Um pedido pago pela página Pay for order (por exemplo, um pedido que você criou para o cliente) volta à sua página de pagamento com a mensagem The Xendit payment was not completed. You can try again or choose another payment method. e continua pagável.
Um cliente pode pagar novamente um pedido não pago. Se o total do pedido, a moeda e o modo não tiverem mudado e a fatura aberta ainda estiver válida, o cliente é enviado para a mesma fatura. Caso contrário, a fatura antiga é expirada primeiro e uma nova é criada, de modo que nunca há duas faturas abertas para um mesmo pedido. Se a fatura antiga já tiver sido paga, o pedido passa a Concluído em vez de haver um novo pagamento.
Se a Xendit não conseguir iniciar o pagamento, o cliente vê uma mensagem curta e pode escolher outro método de pagamento, por exemplo Xendit is temporarily unavailable. Please try again in a few minutes or choose another payment method., uma mensagem de que a moeda não é aceita para a sua conta ou de que o total do pedido está fora dos limites de valor da Xendit. O motivo técnico é gravado no log. Um pedido com total zero não pode ser pago com a Xendit.
O método de pagamento funciona na finalização de compra clássica, no bloco de Finalizar compra e na página Pay for order. No modo de teste, o bloco de Finalizar compra mostra Test mode: no real money is charged. abaixo do método de pagamento. É compatível com o WooCommerce High-Performance Order Storage (HPOS).
O pagamento sempre acontece na página da Xendit. O plugin não oferece reembolsos pelo WooCommerce, cartões salvos, assinaturas ou pagamentos recorrentes, campos de cartão ou carteira eletrônica na finalização de compra, autorização e captura separadas, subcontas do xenPlatform, expiração de fatura personalizada nem taxas de pagamento.
Pedidos
Status do pedido
Pending payment: a fatura foi criada e o cliente ainda não pagou, ou a Xendit ainda não confirmou o pagamento. A nota do pedido mostra o ID da fatura, o valor, a moeda e o modo.
Processing or Completed: o pagamento foi confirmado. O status segue Order Status After Payment. A nota do pedido mostra o ID da fatura, o valor pago, o canal de pagamento e o modo. O ID da transação é o ID da fatura da Xendit.
On hold: a fatura paga não correspondia ao total ou à moeda do pedido, ou foi pago menos que o total (por exemplo, o pedido foi editado depois que a fatura foi criada). A nota do pedido explica isso, inclusive quando o pedido já estava em espera. Confira o pagamento no Painel de Controle da Xendit e depois processe o pedido ou reembolse o pagamento.
Failed: a fatura atual expirou sem pagamento. O cliente pode pagar o pedido novamente.
Cancelled: o cliente voltou de uma fatura falha ou expirada, ou o pedido foi cancelado por você ou pelo tempo limite do WooCommerce para pedidos não pagos. A fatura aberta é expirada, então não pode mais ser paga. Se a Xendit não aceitar isso, uma nota pede que você expire a fatura no Painel de Controle da Xendit.
Se uma fatura for paga para um pedido que já está pago, cancelado ou reembolsado, o pedido não é alterado. Uma nota pede que você reembolse o pagamento no Painel de Controle da Xendit ou restaure o pedido manualmente.
Reembolsos
Os reembolsos não são enviados à Xendit pelo WooCommerce. Reembolse o pagamento no Painel de Controle da Xendit (a nota do pedido e o ID da transação contêm o ID da fatura) e registre o reembolso no WooCommerce manualmente.
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 > Xendit. 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 na 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 na vibefox.net.
Sem uma chave ativa, a Xendit não é exibida aos clientes na finalização de compra. Se um pagamento for iniciado mesmo assim, o cliente verá This payment method is not available. Please choose another one. Os gerentes da loja conectados ainda veem 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: pagamentos já iniciados continuam sendo confirmados.
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 Xendit não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se o modo ativo tem uma chave secreta com o prefixo correto (Test Secret Key com xnd_development_ no modo de teste, Live Secret Key com xnd_production_ no modo de produção) e se a moeda da loja é IDR, PHP, VND, THB, MYR, USD ou SGD. O aviso das configurações mostra um alerta quando a chave está ausente ou errada.
O pagamento foi feito, mas o pedido continua como Pagamento pendente: o webhook não está funcionando. No Painel de Controle da Xendit do modo que você usa (teste ou produção), verifique se a URL exibida nas configurações está definida para Invoice paid e se o token de verificação desse modo está salvo no campo correspondente. O Painel de Controle da Xendit mostra a resposta da sua loja para cada webhook. O pedido também é confirmado quando o cliente volta à página de pedido recebido.
Resposta do webhook «Webhook verification token is not configured»: nenhum dos dois tokens de verificação está definido. Cole o token nas configurações.
Resposta do webhook «Unauthorized»: o token enviado pela Xendit não corresponde a nenhum token das configurações. Copie novamente o token do modo correto.
Resposta do webhook «Token does not match the mode of this invoice»: a fatura foi criada no outro modo. Uma notificação de teste nunca confirma um pedido de produção, e vice-versa. Configure o webhook e o token no modo em que o pedido foi pago.
Resposta do webhook «Ignored: not an invoice of this store»: a fatura não foi criada por esta loja, por exemplo por outra integração na mesma conta Xendit. O botão Test do Painel de Controle da Xendit também recebe essa resposta, o que confirma que a URL e o token funcionam.
Resposta do webhook «Temporary error»: não foi possível acessar a API da Xendit para verificar a fatura, a chave secreta do modo da fatura está ausente, ou o pedido estava sendo atualizado por outra requisição no mesmo momento. A Xendit repete o webhook. Verifique se as duas chaves secretas estão definidas, caso você tenha pedidos dos dois modos.
Uma chave não é salva: o valor não começa com o prefixo do seu campo. Chaves de teste começam com xnd_development_, chaves de produção com xnd_production_.
O cliente vê «This payment method is temporarily unavailable»: a Xendit recusou a requisição, por exemplo porque a chave secreta está errada ou não tem permissão de gravação para Money-in (faturas). Ative o Debug Log se necessário e consulte WooCommerce > Status > Logs, origem wcp_xendit_payment_gateway. Uma mensagem sobre os dados de cobrança significa que a Xendit não aceitou os dados da requisição, por exemplo o e-mail.
O cliente vê «A payment for this order was already received by Xendit and is being reviewed»: uma fatura anterior deste pedido foi paga, mas não correspondia ao pedido, então o pedido está em espera. Confira o pagamento no Painel de Controle da Xendit.
O pedido está On hold após o pagamento: leia a nota do pedido. O valor ou a moeda pagos eram diferentes do pedido. Processe o pedido ou reembolse o pagamento no Painel de Controle da Xendit.
O bloco de licença mostra um erro: siga a mensagem do bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta na 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, as demais opções do plugin, os dados temporários e os seus logs (arquivos de log, inclusive os rotacionados, entradas de log no banco de dados e a pasta de logs da versão 1.0) são removidos somente se Delete Data on Uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento, IDs de fatura e IDs de transação.
Xendit é marca comercial de seu respectivo proprietário. Este plugin não é afiliado à Xendit nem endossado por ela.