VibeFox Xendit for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não é instalado em versões mais antigas do PHP.

Moeda da loja: IDR, PHP, VND, THB, MYR, USD ou SGD. Para outras moedas do carrinho, 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 escrita 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 (veja Configuração). Só as chaves secretas e os tokens de verificação são usados. Nenhuma chave pública é necessária, porque o cliente paga na página de fatura hospedada pela Xendit.

Chave de licença VibeFox: adquirida em vibefox.net. Uma chave funciona em um único domínio.

Instalação

1. No back office, acesse 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 depois VibeFox Xendit Payment Gateway na lista de módulos e clique em Configure.

3. Insira a 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. 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 (veja Configuração).

5. Ative Enable/Disable e clique em Save. Faça um pedido de teste no modo de teste e, depois, desative Test Mode para receber pagamentos reais.

Na instalação, o módulo cria o status de pedido Xendit 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 Xendit Payment Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, uma caixa 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). A caixa avisa 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 do webhook do modo ativo está vazio (as notificações da Xendit são rejeitadas, então os pedidos só são criados quando o cliente volta à sua loja).

Xendit

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

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

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 escrita 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: cria as faturas com a chave secreta de teste, então nenhum dinheiro real é cobrado. Padrão: ligado. Desligue para receber pagamentos reais com a chave secreta de produção. Enquanto estiver ligado, os clientes veem Test mode: no real money is charged. abaixo do método de pagamento.

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

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

Webhooks

O webhook informa à sua loja que uma fatura foi paga. Em Xendit Dashboard > Settings > Developers > Webhooks, defina a URL mostrada em Webhook URL desta seção para Invoices > Invoice paid, no modo de teste e no modo de produção. Opcionalmente, defina-a também para Invoice expired. Com URLs amigáveis, ela tem esta aparência: https://your-shop/module/wcp_xendit_payment_gateway/webhook, possivelmente com um código de idioma, como /en/. Copie-a exatamente como as configurações a mostram.

Em seguida, copie o Webhook verification token de cada modo, no 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 só 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ó é criado quando o cliente volta à loja depois de pagar.

Test Webhook Verification Token: o token de verificação do webhook do modo de teste da Xendit.

Live Webhook Verification Token: o token de verificação do webhook do modo de produção da Xendit.

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

Pagamento

Invoice Description: a descrição exibida na fatura da Xendit. Você pode usar os marcadores {order_id}, {order_number} e {site_name}. Como o pedido é criado depois do pagamento, {order_id} e {order_number} são o número do carrinho. 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.

Avançado

Debug Log: grava as requisições à API e os webhooks em logs/xendit_p_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 de API, tokens e dados dos clientes não são registrados. Padrão: desligado.

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

Delete Data on Uninstall: quando ligado, desinstalar o módulo remove as configurações do módulo e o log. Os dados dos pedidos (IDs das faturas dos pedidos) e o status Xendit payment on hold são sempre mantidos. Padrão: desligado.

Finalização de compra

O método de pagamento é exibido quando a moeda do carrinho é IDR, PHP, VND, THB, MYR, USD ou SGD. O cliente o escolhe na etapa de pagamento (por padrão Xendit) e confirma. O módulo cria uma fatura da Xendit pelo total do carrinho na moeda do carrinho e envia o cliente para a página da fatura da Xendit. Valores em IDR e VND são arredondados para números inteiros, porque a Xendit não aceita casas decimais para essas moedas. O e-mail 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. Nesse momento, ainda não existe pedido.

Depois de pagar, o cliente volta à sua loja. O pedido só é marcado como pago quando a Xendit confirma: pelo webhook ou por uma requisição do servidor à API da Xendit quando o cliente retorna. Só então o pedido é criado, e o cliente vê a página padrão de confirmação do pedido. Se a Xendit ainda não tiver confirmado o pagamento, aparece uma página Payment confirmation com a mensagem Your payment has not been confirmed by Xendit yet. Your order will be created as soon as Xendit confirms it — please do not pay again. e os botões Check again e Back to checkout. O webhook cria o pedido assim que chega.

Se a fatura falhar ou expirar, a Xendit devolve o cliente. O módulo verifica primeiro a fatura (ela pode ter sido paga em outra aba) e depois a expira, para que não possa mais ser paga. O cliente volta à finalização de compra com The Xendit payment was not completed. You can try again or choose another payment method. O carrinho é mantido.

Um cliente pode pagar o mesmo carrinho novamente. Se o total do carrinho, a moeda e o modo não tiverem mudado e a fatura aberta ainda for válida por pelo menos mais cinco minutos, 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 o mesmo carrinho. Se a fatura antiga já tiver sido paga, o pedido é criado em vez de um novo pagamento.

Se a Xendit não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo Xendit is temporarily unavailable. Please try again in a few minutes or choose another payment method., uma mensagem informando que a moeda não é aceita para a sua conta ou que o total do pedido está fora dos limites de valor da Xendit. O motivo técnico é gravado no log. Um carrinho com total zero não pode ser pago com a Xendit.

O webhook funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição por país da sua loja.

O pagamento sempre acontece na página da Xendit. O módulo não tem reembolsos pelo back office, 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 nem subcontas do xenPlatform.

Pedidos

Status do pedido

Ainda sem pedido: o cliente foi enviado à Xendit e não pagou, ou a Xendit ainda não confirmou o pagamento. Existe apenas o carrinho.

Payment accepted or Delivered: o pagamento foi confirmado. O status segue Order Status After Payment. O pagamento é registrado com o ID da fatura da Xendit como ID da transação, e uma nota mostra o ID da fatura, o valor pago, o canal de pagamento e o modo.

Xendit payment on hold: a fatura paga não correspondia ao total ou à moeda do carrinho, ou foi pago menos que o total (por exemplo, o carrinho foi alterado depois que a fatura foi criada). A nota explica o caso. Verifique o pagamento no Painel de Controle da Xendit e depois atenda o pedido ou reembolse o pagamento. Se outra fatura do mesmo carrinho for paga depois, com o valor correto, o pagamento é registrado e o pedido passa para o status de pago.

Se uma fatura for paga para um pedido que já foi cancelado ou reembolsado, o status do pedido não muda. Uma nota pede que você reembolse o pagamento no Painel de Controle da Xendit ou restaure o pedido manualmente. Se uma segunda fatura for paga para um pedido que já está pago, o pedido não muda e uma nota pede que você reembolse o pagamento duplicado no Painel de Controle da Xendit.

Bloco Xendit payment

A página do pedido mostra um bloco Xendit payment com o ID da fatura, o modo (com um selo Test mode para pagamentos de teste), o status do pagamento, uma lista de todas as faturas do pedido (data, fatura, ID externo, valor e valor pago, status, canal de pagamento) e as Payment notes do pedido.

Reembolsos

Os reembolsos não são enviados à Xendit a partir da loja. Reembolse o pagamento no Painel de Controle da Xendit (procure pelo ID da fatura exibido no bloco Xendit payment) e registre o reembolso no pedido manualmente. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Xendit.

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 Xendit Payment Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox Xendit Payment Gateway > Configure, acima das configurações. Insira 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 aparecem a linha Product: presta-payment-xendit e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente funcionários com a permissão Configure para o 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 de 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 sua vaga de domínio. Libere a vaga na sua conta 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 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 pode 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.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem 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 e, 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 Xendit não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, 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 do carrinho é IDR, PHP, VND, THB, MYR, USD ou SGD. A página de configurações mostra um aviso quando a chave está ausente ou errada. 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 webhook não está funcionando. No Painel de Controle da Xendit do modo que você usa (teste ou produção), verifique se a URL mostrada em Webhook URL 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 é criado quando o cliente volta à loja depois de pagar.

O webhook responde Webhook verification token is not configured: nenhum token de verificação está definido. Cole o token nas configurações.

O webhook responde Unauthorized: o token enviado pela Xendit não corresponde a nenhum token das configurações. Copie novamente o token do modo correto.

O webhook responde Token does not match the mode of this invoice: a fatura foi criada no outro modo. Uma notificação de teste nunca confirma um pagamento real, e vice-versa. Configure o webhook e o token no modo em que o carrinho foi pago.

O webhook responde 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. Ignored: unknown order e Ignored: unknown invoice significam que o carrinho ou a fatura não são conhecidos por esta loja.

O webhook responde 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, o carrinho estava sendo atualizado por outra requisição no mesmo momento, ou não foi possível criar o pedido (por exemplo, porque o módulo está desativado). A Xendit repete o webhook. Verifique se as duas chaves secretas estão definidas, caso pagamentos tenham sido iniciados nos dois modos, e ative Debug Log para ver o motivo.

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

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 rejeitou a requisição, por exemplo porque a chave secreta está errada ou não tem permissão de escrita para Money-in (faturas). Veja o campo Log na página do módulo. 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 carrinho foi paga, mas o pedido ainda não pôde ser confirmado. Verifique o pagamento no Painel de Controle da Xendit e no log.

O cliente vê We could not match this payment to an order: o link de retorno da Xendit não pertence a um carrinho desta loja, ou nenhuma fatura do carrinho pôde ser associada. Verifique o pagamento no Painel de Controle da Xendit e no log.

O pedido está em Xendit payment on hold após o pagamento: leia as notas no bloco Xendit payment. O valor ou a moeda pagos foram diferentes do carrinho. Atenda o pedido ou reembolse o pagamento no Painel de Controle da Xendit.

Para desenvolvedores, o módulo oferece os hooks actionWcpXenditInvoiceRequest, actionWcpXenditSupportedCurrencies e actionWcpXenditCurrencyDecimals para alterar a requisição de fatura, a lista de moedas e o número de casas decimais por moeda.

Desinstalação

Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Xendit Payment 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 on Uninstall 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 futura reinstalação. Os dados das faturas da Xendit dos pedidos e o status Xendit payment on hold são sempre mantidos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

Xendit é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Xendit.