VibeFox Transbank 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: peso chileno (CLP). O Webpay Plus cobra apenas pesos inteiros, então defina Number of decimals como 0 em WooCommerce > Settings > General. Em lojas com outra moeda, o método de pagamento não é exibido.

Conta na Transbank: para pagamentos reais, você precisa de um comércio Webpay Plus padrão (captura imediata) com o respectivo Commerce Code de produção e a API Key Secret. A Transbank fornece o Commerce Code quando sua afiliação é aprovada, e a API Key Secret após o processo de validação da integração (consulte a documentação para desenvolvedores da Transbank). Para testes, não são necessárias credenciais. Os códigos de comércio do Webpay Plus Mall, Oneclick e de captura adiada não são suportados.

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

Instalação

1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_transbank_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Defina a moeda da loja como peso chileno e Number of decimals como 0 em WooCommerce > Settings > General.

4. Abra as configurações: WooCommerce > Settings > Payments > Transbank Webpay Plus > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.

5. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

6. Ative Enable / Disable e teste um pagamento com Integration (test) mode ativado, usando os cartões de teste da documentação para desenvolvedores da Transbank.

7. Para entrar em produção, insira seu Production Commerce Code e sua Production API Key Secret, desmarque Integration (test) mode e salve.

Não é preciso configurar URL de retorno nem webhook na Transbank. O plugin envia sua URL de retorno em cada transação.

Configuração

Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Transbank Webpay Plus. Acima dos campos, a página avisa quando a produção está selecionada, mas o Production Commerce Code ou a API Key está ausente ou inválido (o Webpay fica então oculto na finalização de compra), quando a moeda da loja não é CLP (o método de pagamento fica oculto) e quando os preços em CLP têm casas decimais (os totais são arredondados para pesos inteiros). Enquanto o modo de integração estiver ativo, a página mostra Integration (test) environment: nenhum dinheiro real é cobrado. Após salvar, os avisos já seguem as novas configurações. Na lista de métodos de pagamento, o gateway aparece como precisando de configuração quando a produção está selecionada sem credenciais válidas.

Geral

Enable / Disable: Enable Transbank Webpay Plus payments 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. Padrão: Webpay Plus.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay with credit, debit or prepaid card via Webpay.

Ambiente e credenciais

O texto da seção traz um link para a documentação para desenvolvedores da Transbank e explica quando a Transbank fornece as credenciais de produção.

Integration (test) mode: Use the Transbank integration environment. Os pagamentos vão para o ambiente de integração da Transbank com o código de comércio de teste público dela (597055555532), preenchido automaticamente. As credenciais de produção abaixo não são usadas e nenhum dinheiro real é cobrado. Padrão: ligado. Desmarque para entrar em produção.

Production Commerce Code: seu código de comércio de produção (Tbk-Api-Key-Id): 12 dígitos, começando com 5970. Se o seu tiver 8 dígitos, insira-o como está; o plugin adiciona o prefixo 5970 ao salvar. Espaços e outros caracteres são removidos. Os códigos de comércio de teste públicos da Transbank não são aceitos em produção.

Production API Key Secret: o Tbk-Api-Key-Secret do seu comércio de produção. Mantenha em sigilo. Os espaços são removidos ao salvar.

Avançado

Debug log: Log API requests and returns (errors are always logged). Os detalhes são gravados em WooCommerce > Status > Logs, origem wcp_transbank_gateway; o campo tem um link view logs. Erros e avisos são registrados mesmo quando esta opção está desligada. Nenhum dado de cartão, chave de API ou token completo é registrado. Padrão: desligado.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted (order data is kept). Padrão: desligado.

Teste e produção

Integration (test) mode define para onde vão os novos pagamentos. Cada pagamento guarda o seu ambiente: a confirmação e os reembolsos de um pagamento sempre vão para o ambiente (integração ou produção) e com as credenciais com que foi criado, mesmo que você troque o modo depois.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Webpay Plus) e faz o pedido. No modo de integração, a finalização de compra exibe TEST MODE: Integration environment. Sem cobranças reais. O plugin cria uma transação na Transbank pelo total do pedido em pesos inteiros (um total com casas decimais é arredondado para o peso mais próximo) e envia o cliente a uma página curta Redirecting to Webpay. Please wait..., que o encaminha ao formulário do Webpay. Sem JavaScript, o cliente clica em Proceed to Webpay. No Webpay, o cliente paga com cartão de crédito, débito ou pré-pago.

Quando o cliente retorna, o plugin confirma (commit) a transação com a Transbank de servidor para servidor. O pedido só é marcado como pago depois que a Transbank confirma: a resposta precisa ser aprovada, e o valor, o buy order e a sessão precisam corresponder ao que a loja enviou para esta tentativa. Em seguida, o cliente vê a página de pedido recebido. Se a chamada de confirmação falhar, por exemplo por tempo esgotado, o plugin pede à Transbank o status da transação. Se o status continuar desconhecido, o pedido não é alterado e o cliente vê We could not confirm your Webpay payment with Transbank. Please try again in a moment; if your card was charged, contact us before paying again.

Se o cliente cancelar no Webpay, o formulário do Webpay expirar ou apresentar um erro, nada é cobrado. O pedido continua aguardando pagamento e o cliente volta para a página Pay for order com uma mensagem, por exemplo You cancelled the Webpay payment. Nothing was charged — you can try again or choose another payment method. Um cartão recusado mostra Your Webpay payment was rejected and nothing was charged. Please try again or choose another payment method. O cliente pode pagar novamente na mesma página. Cada nova tentativa é uma nova transação do Webpay.

Cada tentativa do Webpay é confirmada no máximo uma vez. Recarregar a página de retorno, usar o botão voltar do navegador ou um segundo retorno ao mesmo tempo nunca confirmam duas vezes nem alteram o pedido. Se um pedido não precisar mais de pagamento (já pago por outra tentativa, cancelado ou reembolsado), um retorno tardio não é confirmado, e a Transbank não o cobra. O cliente vê This order can no longer be paid (it was cancelled or already paid). Your Webpay payment was not confirmed, so it was not charged.

Se o Webpay não conseguir iniciar o pagamento, o cliente vê uma mensagem curta, por exemplo Could not connect to Webpay. Please try again in a moment. ou Webpay payments are not available at the moment. Please choose another payment method. O motivo técnico vai para o log.

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

A Transbank não tem webhook de pagamento: o resultado é processado quando o cliente volta do Webpay. Se o cliente fechar o navegador no Webpay e nunca retornar, a transação não é confirmada e o pedido continua pendente; segundo a Transbank, transações não confirmadas não são liquidadas. O plugin não oferece Webpay Plus Mall, cartões salvos Oneclick, assinaturas, captura adiada nem conversão de moeda.

Pedidos e reembolsos

Status do pedido

Pending payment: o cliente foi enviado ao Webpay e ainda não pagou, cancelou, deixou o formulário expirar, ou o pagamento ainda não pôde ser confirmado. Uma nota registra cada tentativa encerrada com o seu buy order.

Processing or Completed: a Transbank aprovou o pagamento. O status é definido pelo WooCommerce: Processando, ou Concluído para pedidos com apenas produtos virtuais para download. A nota do pedido mostra o código de autorização, os últimos quatro dígitos do cartão, o buy order, o valor, o tipo de pagamento e o número de parcelas. O ID da transação é o token do Webpay.

On hold: a Transbank autorizou um pagamento que não corresponde ao pedido (valor, buy order ou ID da sessão), por exemplo porque o pedido foi editado depois que o pagamento começou. A nota lista as diferenças. Verifique o portal da Transbank e reembolse ou conclua o pedido.

Failed: o pagamento foi recusado. Nada foi cobrado. A nota mostra o código e o status da resposta.

Se o Webpay devolver um pagamento de um pedido que já está pago, cancelado ou reembolsado, o pagamento não é confirmado e uma nota pede que você verifique o portal da Transbank caso o cliente informe uma cobrança. Os pedidos existentes não são afetados por tentativas posteriores.

Reembolsos

O botão de reembolso só é oferecido para pedidos pagos pelo Webpay. Abra o pedido, clique em Refund, informe o valor e clique em Refund via Webpay Plus (o botão usa o título do método de pagamento). Reembolsos totais e parciais são aceitos em pesos inteiros. Um valor parcial com casas decimais é recusado com Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. O último resto de um total de pedido com casas decimais é arredondado da mesma forma que a cobrança. O reembolso vai para o ambiente em que o pagamento foi feito, então em produção as credenciais de produção precisam estar configuradas.

A Transbank responde com uma reversão (REVERSED) ou uma anulação (NULLIFIED). Um reembolso bem-sucedido é adicionado às notas do pedido com o valor, o tipo, o código de autorização e o saldo restante na Transbank. Se a Transbank não aceitar o reembolso, o WooCommerce mostra o erro e nenhum reembolso é registrado. Os reembolsos feitos no portal da Transbank não são importados para o WooCommerce.

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 > Transbank Webpay Plus. 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 único domínio. Remover a chave de um site não libera a vaga de domínio. Libere a vaga na sua conta na vibefox.net.

Sem uma chave ativa, o Webpay Plus não é exibido 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. 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: os 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

O Webpay Plus não aparece na finalização de compra: verifique se a licença está ativa, se Enable / Disable está ligado, se a moeda da loja é CLP (na página Pay for order, a moeda do pedido) e, com o modo de integração desligado, se um Production Commerce Code válido (12 dígitos, começando com 5970) e uma Production API Key Secret estão salvos. A página de configurações mostra um aviso para cada condição ausente.

O pagamento foi feito, mas o pedido continua em Pending payment: a Transbank não tem webhook, então o pedido só é confirmado quando o cliente volta do Webpay. Se o cliente fechou o navegador no Webpay, a transação não foi confirmada e, segundo a Transbank, não é liquidada. Verifique as notas do pedido, o log e a transação no portal da Transbank.

O cliente vê We could not confirm your Webpay payment with Transbank: a chamada de confirmação falhou e não foi possível verificar o status. O pedido não foi alterado e uma nota foi adicionada. O cliente pode tentar novamente em instantes. Se o portal da Transbank mostrar a transação como autorizada, confirme-a lá antes de enviar o pedido.

O cliente vê um erro ao fazer o pedido: ative o Debug log e consulte WooCommerce > Status > Logs, origem wcp_transbank_gateway. A mensagem Webpay payments are not available at the moment geralmente indica credenciais de produção incorretas. Could not connect to Webpay significa que a Transbank não pôde ser alcançada. Um pedido em moeda diferente de CLP não pode ser pago com o Webpay.

Totais e reembolsos diferem em alguns pesos: os preços em CLP têm casas decimais. O Webpay cobra pesos inteiros, então os totais são arredondados. Defina Number of decimals como 0.

O reembolso falha com The production Commerce Code / API Key are missing: o pagamento foi feito em produção e as credenciais de produção não estão salvas. Insira-as e tente novamente.

O reembolso falha com Transbank refused the refund ou Transbank did not approve the refund: a Transbank não aceitou; a mensagem mostra o motivo ou o tipo e o código de resposta devolvido. Nada foi reembolsado. Verifique a transação no portal da Transbank.

O bloco de licença mostra um erro: siga a mensagem exibida no 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 alcançado, 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, as demais opções e os dados temporários do plugin, bem como os seus logs (arquivos de log, incluindo os rotacionados, e entradas de log no banco de dados), só são removidos se Delete data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação futura. Os dados da Transbank armazenados nos pedidos são sempre mantidos, pois são necessários para a contabilidade e os reembolsos. Os pedidos existentes mantêm as suas notas de pagamento e os IDs de transação.

Transbank e Webpay são marcas registradas de seus respectivos titulares. Este plugin não é afiliado à Transbank nem endossado por ela.