VibeFox Midtrans for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 8.0 ou superior, instalado e ativo. Sem o WooCommerce o plugin não é ativado.
PHP: 8.0 ou superior.
Moeda da loja: rupia indonésia (IDR). Para outras moedas, o método de pagamento fica oculto na finalização de compra. Não há conversão de moeda.
Conta Midtrans: você precisa da Server Key em Midtrans Dashboard > Settings > Access Keys, no painel de sandbox e no painel de produção. Só a Server Key é usada. A Client Key não é necessária para o Snap Redirect. Os próprios métodos de pagamento (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 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_midtrans_payment_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Defina a moeda da loja como rupia indonésia (IDR).
4. Abra as configurações: WooCommerce > Settings > Payments > Midtrans > Manage, ou clique em Settings abaixo do nome do plugin na página de Plugins.
5. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
6. Insira as Server Keys e copie a URL de notificação de pagamento para o painel da Midtrans (veja Configuração).
7. Ative Enable/Disable. Teste em Sandbox e depois mude Environment para Production.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Midtrans. 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 da loja não é IDR, e mostra Sandbox mode: payments are simulated, no real money is charged. enquanto Sandbox estiver selecionado. Na lista de métodos de pagamento, a Midtrans aparece como precisando de configuração até que uma Server Key seja inserida, e mostra Test mode em Sandbox.
Geral
Enable/Disable: Enable Midtrans payments liga ou desliga o método de pagamento. Padrão: off.
Title: o título do método de pagamento exibido aos clientes na finalização de compra. Padrão: Midtrans.
Description: o texto exibido 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. é adicionada.
Credenciais de 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 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 pedidos mantêm o ambiente em que foram pagos, para reembolsos e notificações. Padrão: Sandbox.
Production Server Key: começa com Mid-server-. Mantenha em segredo.
Sandbox Server Key: começa com SB-Mid-server-.
URL de notificação de pagamento
A notificação informa à sua loja que um pagamento foi feito. A seção mostra a URL a ser usada. Ela tem este formato: https://your-site/wc-api/midtrans_p_callback/. Cole-a em Midtrans Dashboard > Settings > Payment > Notification URL, no painel de sandbox e no painel de produção que você usa. Se você abrir a URL em um navegador, aparece uma breve explicação, o que permite 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 corresponder ao ambiente do pedido. Notificações sem assinatura válida são rejeitadas. Em seguida, o status é consultado novamente na API de status da Midtrans. O plugin trata estes status de transação da Midtrans:
Sem a URL de notificação, um pedido só é confirmado quando o cliente volta à loja depois de pagar.
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. O status é definido em uma única etapa, sem e-mails duplicados ao cliente.
Payment page expiry (minutes): por quanto tempo o cliente pode pagar (página do Snap, conta virtual etc.). Deixe vazio ou 0 para o padrão da Midtrans.
Order ID prefix: adicionado ao número do pedido enviado à Midtrans, para que várias lojas possam compartilhar uma conta Midtrans. 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: Log API calls and notifications grava em WooCommerce > Status > Logs, origem wcp_midtrans_payment_gateway. Erros são sempre registrados. Chaves e dados do cliente nunca são registrados. Padrão: off.
Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (deactivation keeps everything). Order data is kept. Padrão: off.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão Midtrans) e faz o pedido. O plugin cria uma transação Midtrans Snap pelo total do pedido em rupias inteiras, com as linhas do pedido, frete, impostos e os dados de cobrança e entrega do cliente, e envia o cliente para a página de pagamento da Midtrans. Lá o cliente escolhe qualquer método ativado na sua conta Midtrans.
Depois de pagar, o cliente volta à página de pedido recebido da sua loja. O link de retorno nunca marca um pedido como pago: o plugin consulta a API de status da Midtrans, e o pedido só é marcado como pago depois que a Midtrans confirma. Enquanto o pagamento não estiver confirmado, 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. A página também mostra o método de pagamento usado.
Se o pagamento não foi concluído, o cliente é enviado à página Pay for order com The Midtrans payment was not completed. You can try again below. Se foi recusado ou expirou, a mensagem é Your Midtrans payment was declined or has expired. Please try again or choose another payment method. 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 expirada na Midtrans. Se o Snap anterior foi pago nesse meio tempo, o pedido é confirmado e nenhuma nova transação é criada.
Se a Midtrans não conseguir iniciar o pagamento, o cliente vê 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 errada) ou o motivo informado pela Midtrans. O motivo técnico é adicionado às notas do pedido.
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. É compatível com o WooCommerce High-Performance Order Storage (HPOS).
O plugin 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 WooCommerce Subscriptions. Pagamentos com cartão são capturados imediatamente, sem autorização e captura separadas.
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado à Midtrans e ainda não escolheu um método de pagamento.
On hold: o cliente escolheu um método com atraso e ainda não pagou, o pagamento com cartão está em análise antifraude (challenge), ou o valor ou a moeda pagos não conferem com o pedido. Em espera também é definido quando um pagamento chega para um pedido cancelado; o pedido não é reaberto automaticamente. A nota do pedido explica.
Processing, Completed or On hold after payment: o pagamento foi confirmado. O status segue Status after payment. A nota do pedido mostra o método de pagamento e os IDs da Midtrans. O ID da transação é o ID de transação da Midtrans e, na tela do pedido, leva à transação no painel da Midtrans do ambiente do pedido.
Failed: o pagamento falhou, ou um pagamento com cartão em challenge foi recusado.
Cancelled: a transação não paga venceu ou foi cancelada. O estoque é devolvido. Quando você cancela um pedido Midtrans não pago no WooCommerce (ou o temporizador de pedidos não pagos faz isso), a transação pendente na Midtrans, por exemplo uma conta virtual emitida, é expirada para que não possa mais ser paga.
Se um segundo pagamento chegar para um pedido já pago, o pedido não é alterado de novo. Uma nota pede que você reembolse o segundo pagamento no painel da Midtrans. Um pagamento para um pedido reembolsado apenas adiciona uma nota.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Midtrans (o botão mostra o seu Title). Reembolsos totais e parciais são suportados em rupias inteiras; um valor com decimais é recusado. O reembolso é enviado no ambiente em que o pedido foi pago, por isso 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 WooCommerce mostra o erro e nenhum reembolso é registrado; nesse caso, reembolse pelo painel da Midtrans. Um reembolso bem-sucedido é adicionado às notas do pedido.
Reembolsos feitos no painel da Midtrans chegam pela notificação e são registrados automaticamente como reembolsos do WooCommerce, com o motivo Refunded in the Midtrans dashboard.
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 > Midtrans. 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 vibefox.net.
Sem uma chave ativa, a Midtrans não aparece para os 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 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 de Plugins e nas páginas do WooCommerce. 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
Midtrans não aparece na finalização de compra: 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 da loja (ou a moeda do pedido na página Pay for order) é IDR. A página de configurações mostra um aviso para cada um desses problemas.
O pagamento foi feito, mas o pedido continua Pending payment: 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) e se ela está acessível: abra-a em um navegador, aparecerá uma breve explicação. Ative o Debug log para ver as notificações. O pedido também é confirmado quando o cliente volta à loja depois de pagar.
A notificação responde 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.
A notificação responde Server key not configured: nenhuma Server Key está configurada. Insira-a nas configurações; a Midtrans repete a notificação.
A notificação responde Order not found — ignored: o ID de pedido da Midtrans não pertence a um pedido desta loja, por exemplo, veio de outra loja na mesma conta Midtrans. Dê a cada loja um Order ID prefix diferente.
A notificação responde Environment mismatch — ignored: a notificação foi assinada com a chave de um ambiente diferente daquele em que o pedido foi pago.
A notificação responde Verification failed, please retry: a API de status da Midtrans não pôde ser acessada. A Midtrans repete a notificação.
O pedido está On hold: leia a nota do pedido. O cliente não concluiu um pagamento com atraso, o pagamento com cartão está em análise antifraude, ou o valor ou a moeda pagos não conferem com o pedido.
O cliente vê um erro ao fazer o pedido: abra as notas do pedido ou ative o Debug log e consulte WooCommerce > Status > Logs, origem wcp_midtrans_payment_gateway. Um pedido que não está em IDR mostra Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.
O reembolso falha: 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 WooCommerce. 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.
O bloco de licença mostra um erro: siga a mensagem exibida no 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 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 de 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 ficam para uma reinstalação posterior. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Midtrans é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Midtrans.