VibeFox Xendit for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e superior (testado na 4.1.0.3).

PHP: 8.0 ou superior.

Moeda da loja: IDR, PHP, VND, THB, MYR, USD ou SGD. Para outras moedas de finalização de compra, 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). Somente as chaves secretas e os tokens de verificação são usados. Não é necessária nenhuma chave pública, porque 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

O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote para o OpenCart 3 wcp_xendit_payment_gateway-oc3-(version).ocmod.zip e o pacote para o OpenCart 4 wcp_xendit_payment_gateway.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_xendit_payment_gateway-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, portanto Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Vá em Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Xendit Payment Gateway e clique em Install (o botão verde +). Seu usuário administrador precisa do direito de modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão do lápis) para abrir a página de configurações. Informe sua chave de licença VibeFox no campo License key do bloco de licença no topo da página e clique em Activate (veja Chave de licença).

4. Cole suas chaves secretas da Xendit, configure a URL do webhook no Xendit Dashboard 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, em seguida, desative Test Mode para aceitar pagamentos reais.

OpenCart 4

1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_xendit_payment_gateway.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão do nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Vá em Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Xendit Payment Gateway, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).

4. Informe a chave de licença, as chaves da Xendit e o webhook como nos passos 3 a 5 para o OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só a URL do webhook é diferente (veja Webhooks).

Uma instalação nova começa com o método de pagamento desativado e o modo de teste ativado.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Payments > VibeFox Xendit Payment Gateway > Edit. As seções são listadas à esquerda; o botão Save abaixo da lista salva a página inteira. Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Acima das configurações, uma caixa mostra o modo ativo: TEST MODE (as faturas são criadas com a chave secreta de teste; 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 página avisa quando a chave secreta do modo ativo está ausente ou tem prefixo incorreto (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 então rejeitadas, e os pedidos só são atualizados quando o cliente volta para a sua loja).

Ao salvar, Title não pode estar vazio (no máximo 128 caracteres), Sort Order precisa ser um número inteiro (números negativos são permitidos), Total precisa ser um número igual ou maior que 0, e a zona geográfica e os status de pedido precisam existir. Caso contrário, nada é salvo e a página indica o campo.

Xendit

Enable/Disable: Enable Xendit ativa ou desativa o método de pagamento. Padrão: off.

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 armazenado no pedido. Padrão: Xendit. Obrigatório, até 128 caracteres.

Description: o texto mostrado ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay with virtual accounts, e-wallets, QR codes, retail outlets or cards via Xendit.

Sort Order: a posição da Xendit entre os métodos de pagamento na finalização de compra. Deixe em branco ou informe um número inteiro.

Geo Zone: oferecer a Xendit somente para endereços de pagamento na zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones.

Total: o total da compra, na moeda padrão da loja, que um pedido precisa atingir antes que a Xendit seja oferecida. Deixe em branco para oferecer a Xendit para qualquer total.

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 (a seção traz o link), uma vez no modo de teste e outra 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 faturas com a chave secreta de teste, então nenhum dinheiro real é cobrado. Padrão: on. Desative para aceitar pagamentos reais com a chave secreta de produção. Enquanto estiver ativo, os clientes veem Test mode: no real money is charged. na etapa Confirm Order.

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

Chaves e tokens 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. Para remover um valor salvo, marque Clear the saved value abaixo do campo e clique em Save.

Webhooks

O webhook informa à sua loja que uma fatura foi paga. Em Xendit Dashboard > Settings > Developers > Webhooks (a seção traz o link), configure a URL mostrada em Webhook URL para Invoices > Invoice paid, no modo de teste e no modo de produção. Opcionalmente, configure-a também para Invoice expired. No OpenCart 3 a URL tem este formato: https://your-store/index.php?route=extension/payment/wcp_xendit_payment_gateway/webhook, no OpenCart 4: https://your-store/index.php?route=extension/wcp_xendit_payment_gateway/payment/wcp_xendit_payment_gateway.webhook. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart. Copie-a exatamente como as configurações a mostram. Ela precisa estar acessível pela internet.

Depois, copie o Webhook verification token de cada modo no Xendit Dashboard 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 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.

Pagamento

Invoice Description: a descrição exibida na fatura da Xendit. Você pode usar os marcadores {order_id} e {order_number} (ambos são o número do pedido no OpenCart) e {site_name} (o nome da loja). O HTML é removido e o texto é cortado em 255 caracteres. Padrão: Order #{order_id}.

Order Status After Payment: qual status um pagamento confirmado define, em uma única mudança de status.

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). O pedido só recebe um status depois que a Xendit confirma o pagamento pela API. Cada campo abaixo lista os seus status de pedido do OpenCart.

Paid Order Status: o status após um pagamento confirmado com Processing. Padrão: Processing.

Complete Order Status: o status após um pagamento confirmado com Completed. Padrão: Complete.

On Hold (Review) Status: uma fatura foi paga com valor ou moeda diferentes do pedido (o carrinho foi alterado depois que a fatura foi criada, ou houve pagamento parcial). Uma nota explica o motivo. Padrão: Pending, porque o OpenCart não tem o status On hold. Você pode criar seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

Avançado

Debug Log: grava as requisições à API e os webhooks em xendit_p_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web e, ao atingir 5 MB, é movido para xendit_p_debug.old.log.php. 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: off.

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

Delete Data on Uninstall: quando ativado, desinstalar a extensão remove as configurações do gateway e o registro. Os dados de pedidos (os IDs das faturas dos pedidos) são sempre mantidos. Padrão: off.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. Chaves secretas e tokens não são exportados.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. As chaves secretas e os tokens salvos são mantidos.

Finalização de compra

O método de pagamento é exibido quando a moeda da finalização de compra é IDR, PHP, VND, THB, MYR, USD ou SGD. O cliente o escolhe na etapa Payment Method (por padrão, Xendit). Na etapa Confirm Order, o cliente vê a sua descrição. O OpenCart cria o pedido nessa etapa, ainda sem status. Quando o cliente clica em Confirm Order, a extensão cria uma fatura Xendit pelo total do pedido na moeda do pedido e envia o cliente para a página de fatura da Xendit. Os valores em IDR e VND são arredondados para números inteiros, porque a Xendit não aceita decimais para essas moedas. O e-mail do cliente é enviado à 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 varejo ou um cartão. No OpenCart 4 o cliente escolhe o método de pagamento com o botão Choose do bloco do método de pagamento, na janela Payment method options, e clica em Confirm Order na parte de baixo da página de finalização de compra.

Depois do pagamento, o cliente volta para a sua loja. O pedido só é marcado como pago depois que a Xendit o confirma: pelo webhook ou por uma requisição do servidor à API da Xendit quando o cliente retorna. Em seguida, o pedido recebe seu status da forma padrão do OpenCart, com os e-mails de pedido habituais e a atualização do estoque, e o cliente vê a página de sucesso do pedido do OpenCart. Se a Xendit ainda não tiver confirmado o pagamento, uma página Payment confirmation mostra Your payment has not been confirmed by Xendit yet. Your order will be confirmed as soon as Xendit confirms it — please do not pay again. com os botões Check again e Back to checkout. O webhook define o status do pedido assim que chega.

Se a fatura falhar ou expirar, a Xendit devolve o cliente. A extensão primeiro verifica 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.

O OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida. O OpenCart 4 mantém um único pedido para a finalização da compra e o atualiza, então, após uma fatura com falha ou expirada, o próximo Confirm Order cria uma nova fatura para o mesmo pedido. Se outro pedido do mesmo carrinho já estiver pago, o cliente vai direto para a página de sucesso e não é cobrado duas vezes. Se o total do pedido, a moeda e o modo não tiverem mudado e a fatura aberta deste pedido 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 haja duas faturas abertas para o mesmo carrinho. Se a fatura antiga já tiver sido paga, esse pagamento é confirmado em vez de criar um novo.

No OpenCart 4, se o pedido da finalização de compra foi fechado pela loja nesse meio-tempo (por exemplo, cancelado ou reembolsado), ou já está pago mas o carrinho mudou desde então, inclusive com uma nova quantidade, o cliente volta à finalização de compra com Your previous order is already closed or paid. Please confirm the order again: the cart will be paid with a new order., e o próximo Confirm Order paga um novo pedido. No OpenCart 4, essa mensagem, a mensagem sobre o pagamento não concluído e We could not match this payment to an order. If you were charged, please contact us. são exibidas acima da página de finalização de compra.

Se a Xendit não conseguir iniciar o pagamento, o cliente permanece na etapa Confirm Order com uma breve mensagem acima do botão, 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 pedido com total zero não pode ser pago com a Xendit.

O webhook e o retorno do cliente também funcionam enquanto a loja está em modo de manutenção: o OpenCart 3 deixa passar as requisições das extensões de pagamento, e no OpenCart 4 a extensão adiciona uma ação de inicialização para elas.

O pagamento sempre acontece na página da Xendit. A extensão não oferece reembolsos pelo painel administrativo, 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 xenPlatform.

Pedidos

Status do pedido

Nenhum status (pedido ausente): o cliente foi enviado para a Xendit e não pagou, ou a Xendit ainda não confirmou o pagamento. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders.

Paid Order Status ou Complete Order Status (padrão Processing ou Complete): o pagamento foi confirmado. O status segue Order Status After Payment. Uma nota mostra o ID da fatura, o valor pago, o canal de pagamento e o modo.

On Hold (Review) Status (padrão Pending): a fatura paga não correspondeu ao total ou à moeda do pedido, ou foi pago menos que o total (por exemplo, o carrinho foi alterado depois que a fatura foi criada). A nota explica. Verifique o pagamento no Xendit Dashboard e, depois, atenda o pedido ou reembolse o pagamento. Se outra fatura do mesmo pedido for paga depois com o valor correto, o pedido passa para o status de pago.

Se uma fatura for paga para um pedido com outro status, por exemplo cancelado ou reembolsado, o status do pedido não é alterado. Uma nota pede que você reembolse o pagamento no Xendit Dashboard ou restaure o pedido manualmente. Se uma segunda fatura for paga para um pedido que já está pago, ou para outro pedido de um carrinho já pago, o pedido não é alterado e uma nota no pedido pago pede que você reembolse o pagamento duplicado no Xendit Dashboard.

As notas são entradas do History do pedido que o cliente não vê. Elas começam com a palavra Xendit.

Aba VibeFox Xendit Payment Gateway

Em Sales > Orders, abra um pedido pago com a Xendit. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Xendit Payment Gateway mostra a Xendit invoice, o Mode (com o rótulo Test para pagamentos de teste), o Status do pagamento, a tabela Invoices of this order and its cart (data, pedido, ID da fatura, ID externo, modo, valor, valor pago, status, canal de pagamento) e as Payment notes do pedido. A aba é exibida para usuários que têm acesso à extensão.

Reembolsos

Os reembolsos não são enviados à Xendit a partir da loja. Reembolse o pagamento no Xendit Dashboard (pesquise o ID da fatura exibido na aba) e depois altere o status do pedido no OpenCart. As devoluções de produtos em Sales > Returns não devolvem dinheiro pela Xendit.

Chave de licença

A extensão 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 Extensions > Extensions > Payments > VibeFox Xendit Payment Gateway > Edit, acima das configurações. Informe 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 ficam a linha Product: opencart-payment-xendit e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel administrativo (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 com uma data. Depois que o endereço da loja mudar, ou depois que você liberar um lugar de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o endereço da loja da configuração do OpenCart. Remover a chave da loja não libera o seu lugar de domínio. Libere o lugar na sua conta vibefox.net.

Sem uma chave ativa, a Xendit não é exibida aos clientes na finalização de compra. Se mesmo assim um pagamento for iniciado, o cliente vê This payment method is not available. Please choose another one. Um usuário administrador que esteja conectado ao painel no mesmo navegador ainda vê o método de pagamento na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa prévia não está disponível: a loja não enxerga o login do administrador, por isso, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois que você abrir a página Edit uma vez, aparece um lembrete no Dashboard do painel. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática quando você abre o Dashboard do painel administrativo ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário nenhum cron job. A desinstalação da extensão 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á 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 finalização de compra é IDR, PHP, VND, THB, MYR, USD ou SGD. A página de configurações exibe um aviso quando a chave está ausente ou errada. Verifique também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.

O pagamento foi feito, mas o pedido continua sem status: o webhook não está funcionando. No Xendit Dashboard do modo que você usa (teste ou produção), verifique se a URL exibida em Webhook URL está configurada para Invoice paid e se o token de verificação desse modo está salvo no campo correspondente. O Xendit Dashboard mostra a resposta da sua loja para cada webhook. O pedido também recebe seu status quando o cliente volta para a loja depois de pagar.

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

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

Webhook answers 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 pedido foi pago.

Webhook answers 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 Xendit Dashboard 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 pedido ou a fatura não são conhecidos por esta loja.

Webhook answers 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 carrinho estava sendo atualizado por outra requisição ao mesmo tempo. A Xendit repete o webhook. Verifique se as duas chaves secretas estão definidas se pagamentos foram 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 da extensão. 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 Xendit Dashboard 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 pedido desta loja, ou a fatura não pôde ser associada a ele. Verifique o pagamento no Xendit Dashboard e no log.

O pedido está no status de análise após o pagamento: leia as notas na aba VibeFox Xendit Payment Gateway. O valor ou a moeda pagos eram diferentes do pedido. Atenda o pedido ou reembolse o pagamento no Xendit Dashboard.

Para desenvolvedores: a extensão dispara os eventos do OpenCart xendit_p_invoice_request, xendit_p_supported_currencies e xendit_p_currency_decimals para alterar a requisição da fatura, a lista de moedas e o número de casas decimais por moeda.

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Xendit Payment Gateway. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as próprias configurações da extensão: Enable/Disable, Sort Order, Geo Zone, Total e os status de pedido da seção Payment, que voltam aos padrões em uma reinstalação. No OpenCart 4, também são removidos o evento da extensão e a sua ação de inicialização, que deixa passar o webhook e o retorno do cliente no modo de manutenção. Se Delete Data on Uninstall estiver ativado, as demais configurações do gateway (título, descrição, modo de teste, chaves, tokens, descrição da fatura, status do pedido após o pagamento, registro de logs) e o log são removidos. Se estiver desativado, elas são mantidas para uma reinstalação posterior. Os dados das faturas Xendit dos pedidos são sempre mantidos. Os pedidos existentes mantêm as suas notas de pagamento.

No OpenCart 4, para remover também os arquivos da extensão, vá em Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Xendit Payment Gateway na lista de extensões instaladas, depois em Delete (o botão vermelho com lixeira) para remover o pacote enviado.

Xendit é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela Xendit.