VibeFox Midtrans for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões antigas do PHP.
Moeda: rupia indonésia (IDR). A Midtrans cobra somente em IDR, então o método de pagamento só é oferecido quando a moeda do carrinho é IDR. Não há conversão de moeda. Adicione a moeda IDR em International > Localization se a sua loja não a tiver.
Conta Midtrans: você precisa da Server Key em Midtrans Dashboard > Settings > Access Keys, tanto no painel de sandbox quanto no painel de produção. Somente a Server Key é usada. A Client Key não é necessária para o Snap Redirect. Os métodos de pagamento em si (GoPay, QRIS, contas virtuais e outros) são ativados na sua conta Midtrans.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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 depois VibeFox Midtrans 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. Insira as Server Keys e copie a URL de notificação de pagamento para o painel da Midtrans (veja Configuração).
5. Ative Enable/Disable e clique em Save. Teste em Sandbox e depois mude Environment para Production.
Ao instalar, o módulo cria dois status de pedido: Awaiting Midtrans payment e Midtrans 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. O módulo deve continuar permitido para a moeda IDR.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa quando a Server Key do ambiente selecionado está ausente (o método de pagamento fica oculto na finalização de compra) e quando a moeda padrão da loja não é IDR, e mostra Sandbox mode: payments are simulated, no real money is charged. enquanto Sandbox estiver selecionado.
Midtrans
Enable/Disable: Enable Midtrans payments liga ou desliga o método de pagamento. Padrão: desativado.
Title: o título do método de pagamento mostrado aos clientes na finalização de compra. É também o nome do método de pagamento salvo no pedido. Padrão: Midtrans. Obrigatório.
Description: o texto mostrado abaixo do método de pagamento na finalização de compra. Padrão: Pay securely via Midtrans — GoPay, QRIS, ShopeePay, cards, bank transfer and more. Em Sandbox, a linha SANDBOX MODE: no real money is charged. é acrescentada.
Credenciais da API
Copie a Server Key em Midtrans Dashboard > Settings > Access Keys. A seção tem links para o painel de produção e para o painel de sandbox.
Environment: qual ambiente da Midtrans os novos pagamentos usam. Ao trocar, são usados a chave e a API do ambiente selecionado. Os pagamentos mantêm o ambiente em que foram feitos, para reembolsos e notificações. Padrão: Sandbox.
Production Server Key: começa com Mid-server-. Mantenha-a em segredo.
Sandbox Server Key: começa com SB-Mid-server-.
As chaves salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-la.
Clear saved keys: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
URL de notificação de pagamento
A notificação informa à sua loja que um pagamento foi feito. O campo Notification URL mostra a URL a ser usada. Com URLs amigáveis, ela tem a forma https://your-shop/module/wcp_midtrans_payment_gateway/webhook, possivelmente com um código de idioma como /en/. Copie a URL exatamente como as configurações a mostram e cole-a em Midtrans Dashboard > Settings > Payment > Notification URL, no painel de sandbox e no painel de produção que você usa. Se abrir a URL em um navegador, aparece uma breve explicação, para que você possa verificar se ela está acessível. O botão Test notification URL no painel da Midtrans também recebe resposta.
Cada notificação deve trazer uma assinatura válida feita com uma das suas Server Keys, e o ambiente da chave deve coincidir com o ambiente do pagamento. Notificações sem assinatura válida são rejeitadas. Então o status é consultado novamente na API de status da Midtrans. O módulo trata estes status de transação da Midtrans:
Sem a URL de notificação, um pedido só é criado quando o cliente volta à loja depois de pagar, e um pagamento com atraso feito depois não é percebido até que o cliente retorne.
Configurações de pagamento
A Midtrans cobra somente em IDR, e os valores são enviados em rupias inteiras. Se as linhas do pedido não somarem o total arredondado, uma linha Rounding adjustment é enviada à Midtrans.
Status after payment: o status do pedido após um pagamento confirmado.
Payment page expiry (minutes): por quanto tempo o cliente pode pagar (página do Snap, conta virtual etc.). Deixe vazio ou use 0 para o padrão da Midtrans. Um valor que não seja um número inteiro de minutos é recusado com um erro ao salvar.
Order ID prefix: acrescentado ao número enviado à Midtrans, para que várias lojas possam compartilhar uma conta Midtrans. O número é o ID do carrinho com um carimbo de tempo, por exemplo WC-123-1700000000. Somente letras, dígitos e - _ . ~, até 20 caracteres; outros caracteres são removidos ao salvar. Notificações de outras lojas são ignoradas. Padrão: WC-.
Avançado
Debug log: grava as chamadas à API e as notificações em logs/midtrans_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros são sempre registrados. Chaves e dados do cliente nunca são registrados. Padrão: desativado.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: quando ativado, desinstalar o módulo remove as suas configurações e o log. Pedidos, suas referências de pagamento da Midtrans e reembolsos e os status de pedido do módulo sempre permanecem, para que pedidos antigos possam ser reembolsados depois de uma reinstalação. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Midtrans) e confirma. O módulo cria uma transação Midtrans Snap para o total do carrinho em rupias inteiras, com as linhas do pedido, o frete, os descontos, o embrulho para presente, os impostos e os dados de cobrança e entrega do cliente, e envia o cliente à página de pagamento da Midtrans. Lá o cliente escolhe qualquer método ativado na sua conta Midtrans. Ainda não existe nenhum pedido neste ponto.
Depois de pagar, o cliente volta à sua loja. O link de retorno nunca marca um pedido como pago: o pedido só é marcado como pago depois que a Midtrans confirma, pela notificação assinada ou por uma consulta à API de status da Midtrans quando o cliente volta. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido com o método de pagamento usado. Para um pagamento com atraso, a página mostra We are waiting for Midtrans to confirm your payment. If you chose a bank transfer, virtual account or convenience store, please complete the payment using the instructions from Midtrans. You will receive an e-mail once the payment is confirmed. Para um pedido encerrado sem pagamento, mostra Your Midtrans payment was not completed. Please contact us about this order. Se a Midtrans não puder ser acessada quando o cliente voltar, uma página Payment confirmation mostra We are confirming your payment with Midtrans. The order will be updated automatically — please do not pay again. com um botão Check again.
Se o cliente saiu da página do Snap sem pagar, ele volta à finalização de compra com The Midtrans payment was not completed. You can try again below. Se o pagamento foi recusado ou venceu, a mensagem é Your Midtrans payment was declined or has expired. Please try again or choose another payment method. O carrinho é mantido. Quando o cliente paga de novo, um Snap não usado ou pendente do mesmo valor é reaproveitado. Se o valor mudou, a transação pendente é primeiro vencida na Midtrans. Se o Snap anterior foi pago nesse meio tempo, o pedido é criado e nenhuma nova transação é feita. Se o pedido já existe e foi encerrado sem pagamento, a mensagem é Your Midtrans payment was declined or has expired. Please place a new order or contact us.
Se a Midtrans não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma mensagem curta: Could not connect to Midtrans. Please try again in a moment., Midtrans payments are temporarily unavailable. Please choose another payment method or contact us. (por exemplo, com uma Server Key incorreta) ou o motivo informado pela Midtrans. O motivo técnico é gravado no log. Um carrinho que não está em IDR exibe Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.
A notificação funciona enquanto a loja está em modo de manutenção e não é bloqueada pela restrição de países da sua loja.
O módulo usa somente o Snap Redirect. Não há pop-up do Snap, nem formulário de cartão no seu site, nem cartões salvos ou pagamentos com um clique, nem configurações de parcelamento ou promoções (configure os métodos de pagamento no painel da Midtrans), nem assinaturas. Pagamentos com cartão são capturados imediatamente, sem autorização e captura separadas.
Pedidos e reembolsos
Status do pedido
No order yet: o cliente foi enviado à Midtrans e não pagou, ou a Midtrans ainda não confirmou o pagamento. Existe apenas o carrinho.
Awaiting Midtrans payment: o cliente escolheu um método com atraso (conta virtual, loja de conveniência) ou começou um pagamento com cartão que não foi concluído. O pedido passa a pago quando a Midtrans informa o pagamento.
Payment accepted, Delivered ou Midtrans payment on hold: o pagamento foi confirmado. O status segue Status after payment. O pagamento é registrado com o ID da transação na Midtrans, e uma nota mostra o método de pagamento e o ID do pedido na Midtrans.
Midtrans payment on hold: também é definido quando um pagamento com cartão está em análise antifraude (challenge, sem pagamento registrado ainda), quando o valor ou a moeda pagos não correspondem ao pedido (o pedido não é marcado como pago) ou quando chega um pagamento para um pedido cancelado (o pedido não é reaberto automaticamente). A nota explica. Verifique o pedido e depois atenda-o ou reembolse o pagamento.
Canceled: a transação não paga venceu ou foi cancelada. Quando você cancela manualmente um pedido Midtrans não pago, a sua transação pendente na Midtrans, por exemplo uma conta virtual emitida, é vencida para que não possa mais ser paga.
Payment error: o pagamento falhou, ou um pagamento com cartão em análise foi negado.
Refunded: o pagamento foi reembolsado integralmente.
Se chegar um segundo pagamento para um pedido que já está pago, o pedido não muda. Uma nota pede que você reembolse o segundo pagamento no painel da Midtrans. Um pagamento para um pedido reembolsado apenas acrescenta uma nota.
Bloco de pagamento Midtrans
A página do pedido mostra um bloco Midtrans payment com o ID do pedido na Midtrans, o ID da transação (com link para a transação no painel da Midtrans do ambiente do pagamento), o método de pagamento, o status, o valor pago e reembolsado, um selo Sandbox para pagamentos de sandbox, o histórico de reembolsos e as Midtrans notes do pedido.
Reembolsos
No bloco Midtrans payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Midtrans. Confirme a pergunta Refund this amount through Midtrans? This cannot be undone. Reembolsos totais e parciais são aceitos em rupias inteiras; um valor com decimais é recusado. Você precisa ter permissão para editar pedidos. É possível reembolsar até o valor que a Midtrans realmente cobrou, mesmo que o pedido tenha sido editado depois. O reembolso é enviado no ambiente em que o pagamento foi feito, então a Server Key desse ambiente precisa estar configurada. A Midtrans só permite reembolsos pela API para alguns métodos de pagamento e estados de transação (por exemplo, pagamentos com cartão liquidados, GoPay, QRIS ou ShopeePay). Se a Midtrans não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado; nesse caso, reembolse pelo painel da Midtrans. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status. Os reembolsos estão disponíveis depois que a Midtrans informa que o pagamento foi liquidado.
O módulo não cria notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Midtrans.
Reembolsos feitos no painel da Midtrans chegam pela notificação e são adicionados automaticamente ao histórico de reembolsos, com o motivo Refunded in the Midtrans dashboard. Quando o pagamento inteiro é reembolsado lá, o pedido passa para Refunded.
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 Midtrans Payment Gateway é o primeiro bloco de Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure, acima das configurações. Insira a chave em License key e clique em Activate. Depois, 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-midtrans 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 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 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, a Midtrans 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á logado no back office, então o método de pagamento fica oculto também 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: os 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 exigem uma 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
Midtrans does not appear at checkout: verifique se a licença está ativa, se Enable/Disable está ligado e se o Environment selecionado tem a sua Server Key. Verifique se a moeda do carrinho é IDR. Em Payment > Preferences, verifique se o módulo está permitido para IDR, para o país do cliente e para o grupo do cliente. A página de configurações mostra um aviso quando a chave está ausente ou quando a moeda da loja não é IDR.
The payment went through, but no order was created: a notificação não está funcionando. Verifique se a URL de notificação de pagamento está configurada no painel da Midtrans do ambiente que você usa (sandbox ou produção), se ela é exatamente a URL mostrada em Notification URL e se está acessível: abra-a em um navegador, deve aparecer uma breve explicação. Ative o Debug log para ver as notificações. O pedido também é criado quando o cliente volta à loja depois de pagar.
Notification answers Invalid signature: a notificação não foi assinada com a sua Server Key de Sandbox ou de Production. Verifique se as chaves nas configurações pertencem à mesma conta Midtrans do painel que envia as notificações.
Notification answers Server key not configured: nenhuma Server Key está definida. Digite-a nas configurações; a Midtrans repete a notificação.
Notification answers Order not found — ignored: o ID do pedido na Midtrans não foi emitido por esta loja, por exemplo por outra loja na mesma conta Midtrans. Dê a cada loja um Order ID prefix diferente.
Notification answers Environment mismatch — ignored: a notificação foi assinada com a chave do outro ambiente, diferente daquele em que o pagamento foi feito.
Notification answers Verification failed, please retry: a API de status da Midtrans não pôde ser acessada. A Midtrans repete a notificação.
Notification answers Busy, please retry: o carrinho estava sendo atualizado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). A Midtrans repete a notificação. Veja o log para o motivo.
The order is Midtrans payment on hold: leia as Midtrans notes no bloco. O pagamento com cartão está em análise antifraude, o valor ou a moeda pagos não coincidem com o pedido, ou o pagamento chegou depois que o pedido foi cancelado.
The customer sees an error when choosing Midtrans: veja o campo Log na página do módulo; erros são sempre registrados. Uma Server Key incorreta mostra a mensagem de que os pagamentos Midtrans estão temporariamente indisponíveis.
Refund fails: o método de pagamento ou o estado da transação não permite reembolsos pela API; reembolse pelo painel da Midtrans, e o reembolso será registrado automaticamente no pedido. Se a mensagem disser que nenhuma Server Key está configurada para o ambiente em que o pedido foi pago, insira essa chave e tente novamente.
Desenvolvedores podem alterar os dados enviados à Midtrans com o hook actionWcpMidtransSnapPayload; o ID do pedido e o valor não podem ser alterados.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Midtrans 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 ativado, as configurações do módulo e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. As referências de pagamento da Midtrans e os reembolsos dos pedidos, bem como os status de pedido Awaiting Midtrans payment e Midtrans payment on hold, são sempre mantidos, para que pedidos pagos antes possam ser reembolsados depois de uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Midtrans é uma marca registrada do respectivo titular. Este módulo não é afiliado nem endossado pela Midtrans.