VibeFox Transbank for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e versões posteriores (testado na versão 4.1.0.3).

PHP: 8.0 ou superior.

Moeda: peso chileno (CLP). Adicione-a em System > Localisation > Currencies se a sua loja não a tiver, com 0 casas decimais: o Webpay Plus cobra apenas pesos inteiros. Para pedidos em outra moeda, o método de pagamento não é exibido.

Conta Transbank: para pagamentos reais, você precisa de um comércio Webpay Plus padrão (captura imediata) com o 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, do Oneclick e de captura posterior não são suportados.

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 das duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3 wcp_transbank_gateway-oc3-(version).ocmod.zip e o pacote do OpenCart 4 wcp_transbank_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, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_transbank_gateway-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, então Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você também pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Acesse Extensions > Extensions e escolha o tipo Payments. Localize VibeFox Transbank 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. Cole sua chave de licença VibeFox em License key, no bloco de licença no topo da página, e clique em Activate (veja Chave de licença).

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

5. Para entrar em produção, informe o seu Production Commerce Code e a sua Production API Key Secret, desative Integration (test) mode e clique em Save.

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_transbank_gateway.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir 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. Acesse Extensions > Extensions e escolha o tipo Payments. Localize VibeFox Transbank 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 e as configurações como nas etapas 3 a 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só a URL de retorno é diferente (veja URL de retorno).

Não é preciso configurar nenhuma URL de retorno ou webhook na Transbank. A extensão envia a sua URL de retorno em cada transação. Uma nova instalação começa com o método de pagamento desativado e o modo de integração ativado.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Payments > VibeFox Transbank Gateway > Edit. As seções são listadas à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, a página avisa quando a produção está selecionada, mas o Commerce Code ou a API Key de produção está ausente ou é inválido (nesse caso o Webpay fica oculto no checkout), quando a moeda padrão da loja não é CLP (o método de pagamento fica oculto para outras moedas) e quando o CLP tem casas decimais (os totais são arredondados para pesos inteiros). Enquanto o modo de integração estiver ativado, a página informa que os pagamentos vão para o ambiente de integração da Transbank com o código de comércio público de teste e que nenhum dinheiro real é cobrado. Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title não pode ficar vazio nem ter mais de 128 caracteres, Sort Order precisa ser um número inteiro (valores negativos são permitidos), Total precisa ser um número igual ou maior que 0 e os status de pedido precisam existir; caso contrário, nada é salvo e a página exibe o erro.

Transbank Webpay Plus

Enable / Disable: Enable Transbank Webpay Plus payments 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 da compra. É também o nome do método de pagamento armazenado no pedido. Padrão: Webpay Plus. Obrigatório, no máximo 128 caracteres.

Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay with credit, debit or prepaid card via Webpay.

Sort Order: a posição do Webpay entre os métodos de pagamento na finalização da compra. Deixe em branco ou informe um número inteiro (valores negativos são permitidos).

Geo Zone: oferece o Webpay 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 o Webpay seja oferecido. Deixe em branco para oferecer o Webpay para qualquer total.

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: os pagamentos vão para o ambiente de integração da Transbank com o seu código de comércio de teste público (597055555532), usado automaticamente. As credenciais de produção abaixo não são usadas e nenhum dinheiro real é cobrado. Padrão: on. Desative para entrar em produção. Enquanto estiver ativo, os clientes veem TEST MODE — ambiente de integração. Sem cobranças reais. na etapa Confirm Order.

Production Commerce Code: o 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, informe-o como está; o prefixo 5970 é adicionado ao salvar. Espaços e outros caracteres são removidos. Os códigos de comércio públicos de teste da Transbank não funcionam em produção: com qualquer um deles o Webpay continua oculto no checkout.

Production API Key Secret: o Tbk-Api-Key-Secret do seu comércio de produção. Mantenha-o em segredo. Os espaços são removidos ao salvar. Uma chave salva nunca mais é exibida: o campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-la. Para remover a chave salva, marque Clear saved API key e clique em Save.

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.

URL de retorno

Return from Webpay: o endereço para onde a Transbank envia o cliente de volta, mostrado para referência. No OpenCart 3 ele tem esta aparência: https://your-store/index.php?route=extension/payment/wcp_transbank_gateway/back, no OpenCart 4: https://your-store/index.php?route=extension/wcp_transbank_gateway/payment/wcp_transbank_gateway.back. Nada precisa ser configurado na Transbank: a extensão envia esta URL em cada transação (a Transbank não tem webhook: o pagamento é confirmado quando o cliente volta). Ela precisa estar acessível pela internet; o modo de manutenção não a bloqueia (no OpenCart 4, a extensão adiciona para isso uma ação de inicialização).

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). O pedido só recebe um status depois que a loja confirma a transação com a Transbank (commit), quando o cliente volta do Webpay. Cada campo abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: o status definido após um pagamento Webpay aprovado e verificado. Padrão: Processing.

Transbank Payment On Hold Status: a Transbank autorizou um pagamento que não corresponde ao pedido (valor, buy order, session id): o pedido fica retido para revisão manual, e uma nota explica o motivo. Padrão: Pending, pois o OpenCart não tem o status On hold. Você pode criar o seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

Refunded Status: definido quando o pagamento é totalmente reembolsado pela página do pedido. Padrão: Refunded.

Avançado

Debug log: registra as requisições à API e as respostas em wc_tbk_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web. Erros são sempre registrados, mesmo quando esta opção está desativada. Dados de cartões, chaves de API ou tokens completos não são registrados. Padrão: off.

Log: mostra o tamanho e as últimas entradas 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 e pagamentos são sempre mantidos. Padrão: off.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. A API Key Secret não é exportada.

Import: cole o JSON exportado anteriormente e clique em Import para restaurar as configurações. A chave de API salva é mantida.

Finalização da compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Webpay Plus). Na etapa Confirm Order, o cliente vê a sua descrição e a nota You will be redirected to Webpay (Transbank) to complete the payment. O OpenCart cria o pedido nesta etapa, ainda sem status. Quando o cliente clica em Confirm Order, a extensão cria uma transação na Transbank para o total do pedido em pesos inteiros (um total com decimais é arredondado para o peso mais próximo) e o cliente vai direto para o formulário do Webpay, onde paga com cartão de crédito, débito ou pré-pago. 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 inferior da página de finalização da compra.

Quando o cliente volta, a extensão 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 pedido recebe o seu status da forma padrão do OpenCart, com os e-mails habituais de pedido e a atualização do estoque, e o cliente vê a página de sucesso do pedido do OpenCart com Your Webpay payment has been received. Para um pedido em análise, a página mostra Your Webpay payment was received and is being reviewed by the store.

Se a chamada de confirmação falhar, por exemplo por um timeout, a extensão pergunta à Transbank o status da transação. Se o status ainda não puder ser conhecido, o pedido permanece sem status e o cliente volta à finalização da compra com 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 outra requisição estiver confirmando o mesmo carrinho naquele momento, ou se a Transbank aprovou o pagamento mas o status do pedido ainda não pôde ser definido, o cliente vê uma página Payment confirmation com Your Webpay payment is being confirmed. Please do not pay again — check again in a moment. e os botões Check again e Back to checkout. O status é então definido a partir da resposta armazenada, sem uma segunda confirmação.

Se o cliente cancelar no Webpay, ou se o formulário do Webpay expirar ou informar um erro, nada é cobrado. O cliente volta à finalização da compra 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 exibe Your Webpay payment was rejected and nothing was charged. Please try again or choose another payment method. O carrinho é mantido, e cada nova tentativa é uma nova transação do Webpay. No OpenCart 4, essas mensagens são exibidas acima da página de finalização da compra.

O OpenCart 3 cria um novo pedido toda vez que a etapa Confirm Order é exibida. O OpenCart 4 mantém um único pedido para a finalização da compra e o atualiza; por isso, depois de um pagamento cancelado ou recusado, o cliente paga o mesmo pedido com uma nova transação do Webpay. Se o pedido mudou depois que o pagamento começou (a moeda ou o total não correspondem mais à transação), a transação não é confirmada, portanto a Transbank não a cobra, e o cliente vê Your order changed after the Webpay payment was started. The payment was not confirmed, so it was not charged — please pay again. Se o pedido já tiver um status, ou se outro pedido do mesmo carrinho já estiver pago, um retorno tardio também não é confirmado: o cliente vai para a página de sucesso do pedido pago, ou 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.

No OpenCart 4, se o pedido da finalização da compra recebeu um status sem um pagamento do Webpay ou foi fechado pela loja nesse meio tempo, o próximo Confirm Order envia o cliente de volta à finalização da compra com a mesma mensagem, e o carrinho é pago com um novo pedido. Se o pedido da finalização da compra já estiver pago, mas o carrinho tiver mudado desde então, inclusive com uma nova quantidade, o cliente é enviado de volta à finalização da compra e o novo carrinho é pago com um novo pedido.

Se o Webpay não conseguir iniciar o pagamento, o cliente permanece na etapa Confirm Order com uma mensagem curta, por exemplo Could not connect to Webpay. Please try again in a moment. ou Webpay could not start the payment. Please try again or choose another payment method. O motivo técnico é gravado no log.

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 voltar, a transação não é confirmada e o pedido permanece sem status; de acordo com a Transbank, transações não confirmadas não são liquidadas. A extensão não tem Webpay Plus Mall, cartões salvos do Oneclick, assinaturas, captura posterior nem conversão de moeda.

Pedidos e reembolsos

Status de pedido

Sem status (pedido ausente): o cliente foi enviado ao Webpay e não pagou, cancelou, deixou o formulário expirar, o cartão foi recusado ou o pagamento ainda não pôde ser confirmado. Em Sales > Orders, esses pedidos só aparecem com o filtro Order Status definido como Missing Orders.

Order Status After Payment (padrão Processing): a Transbank aprovou o pagamento. Uma nota 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.

Transbank Payment On Hold Status (padrão Pending): a Transbank autorizou um pagamento que não corresponde ao pedido (valor, buy order ou sessão). A nota lista as diferenças. Verifique o portal da Transbank e atenda o pedido ou reembolse o pagamento.

Refunded Status (padrão Refunded): o pagamento foi totalmente reembolsado pela extensão.

Se o Webpay devolver um pagamento de um pedido que já tem status, ou de um carrinho que outro pedido já pagou, o pagamento não é confirmado e uma nota pede que você verifique o portal da Transbank caso o cliente relate uma cobrança. Cancelamentos, formulários expirados, erros de formulário e cartões recusados também são anotados. As notas são entradas do History do pedido, que o cliente não vê.

Aba VibeFox Transbank Gateway

Em Sales > Orders, abra um pedido pago com Webpay. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Transbank Gateway mostra o Buy order e o seu ambiente (um rótulo Integration para pagamentos de teste), o Status do pagamento, o Authorization code, o Card / payment type com o número de parcelas, Charged / refunded, o formulário de reembolso, o histórico de reembolsos, as Webpay attempts of the order e as Transbank notes. A aba é exibida para usuários que têm acesso à extensão.

Reembolsos

Na aba, informe o Amount em CLP (o valor ainda não reembolsado é preenchido), opcionalmente um Reason (optional), e clique em Refund via Transbank. Confirme a pergunta Refund this amount via Transbank? Reembolsos totais e parciais são suportados em pesos inteiros. Você precisa do direito de modificar a extensão (definido em System > Users > User Groups). Um valor parcial com decimais é recusado com Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. O último resto de um total com decimais é arredondado como a cobrança. Os reembolsos vão até o valor que a Transbank cobrou. O reembolso segue para o ambiente em que o pagamento foi feito, então, para um pagamento de produção, as credenciais de produção precisam estar configuradas.

A Transbank responde com um estorno (REVERSED) ou uma anulação (NULLIFIED). Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o valor, o tipo, o código de autorização e o saldo restante na Transbank. Um reembolso total define o Refunded Status sem notificar o cliente e sem devolver produtos ao estoque, como uma alteração manual de status. Um reembolso parcial não altera o status. Se a Transbank não aceitar o reembolso, a aba mostra o erro e nenhum reembolso é registrado.

Devoluções de produtos em Sales > Returns não devolvem dinheiro pela Transbank. Reembolsos feitos no portal da Transbank não são importados para o OpenCart.

Chave de licença

A extensão funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença License — VibeFox Transbank Gateway é o primeiro bloco em Extensions > Extensions > Payments > VibeFox Transbank Gateway > Edit, acima das configurações. Cole 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 estão a linha Product: opencart-payment-transbank e o link Manage licenses and domains in your account, que abre a sua conta em 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 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 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, a extensão continua funcionando com o último status conhecido.

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

Sem uma chave ativa, o Webpay Plus não é exibido aos clientes na finalização da compra. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. Um usuário administrador conectado ao administrativo 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 vê o login do administrativo, então, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois de abrir a página Edit uma vez, um lembrete aparece no Dashboard do administrativo. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados quando o cliente volta do Webpay, e os reembolsos pela página do pedido funcionam.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem a renovação. O status é verificado novamente de forma automática quando você abre o Dashboard ou a página Edit do administrativo: uma vez por dia nos primeiros 14 dias após a chave ser informada e, depois, uma vez por semana. Nenhum cron job é necessário. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

O Webpay Plus não aparece na finalização da compra: verifique se a licença está ativa, se Enable / Disable está ativado, se o cliente paga em CLP e se, com o modo de integração desativado, estão salvos um Production Commerce Code válido (12 dígitos, começando com 5970) e uma Production API Key Secret. 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. A página de configurações mostra um aviso para credenciais ausentes e para uma moeda da loja diferente de CLP.

O pagamento foi feito, mas o pedido continua sem status: a Transbank não tem webhook, então o pedido só recebe o status 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. Ative o Debug log, veja o campo Log e confira 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 o motivo está no log. O cliente pode tentar novamente em instantes. Se o portal da Transbank mostrar a transação como autorizada, entre em contato com o cliente antes que ele pague de novo.

O cliente vê Your order changed after the Webpay payment was started: o total ou a moeda do pedido não correspondiam à transação. Nada foi cobrado; o cliente paga novamente.

O cliente vê um erro após Confirm Order: ative o Debug log e veja o campo Log na página da extensão. Webpay payments are not available at the moment normalmente indica credenciais de produção incorretas. Could not connect to Webpay significa que a Transbank não pôde ser acessada. Transbank Webpay only supports payments in CLP (Chilean Peso) significa que o pedido está em outra moeda. This payment method is not available. Please reload the checkout page. significa que a sessão de finalização não corresponde mais ao pedido: o cliente recarrega a finalização da compra.

Totais e reembolsos diferem em alguns pesos: a moeda CLP tem casas decimais. O Webpay cobra pesos inteiros, então os totais são arredondados. Defina as casas decimais do CLP como 0 em System > Localisation > Currencies.

O pedido está em status de revisão após o pagamento: leia as notas na aba VibeFox Transbank Gateway (veja Status de pedido) e, em seguida, atenda o pedido ou reembolse o pagamento.

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. Informe-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 que ela devolveu. Nada foi reembolsado. Verifique a transação no portal da Transbank.

O reembolso falha com Another request is processing this order: o pedido estava sendo reembolsado ou confirmado no mesmo momento. Tente novamente em instantes.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Transbank 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 Orders, que voltam aos valores padrão em uma nova instalação. O evento do OpenCart da extensão também é removido (no OpenCart 4, os seus eventos e a sua ação de inicialização, que deixa o retorno do Webpay passar no modo de manutenção). Se Delete data on uninstall estiver ativado, as demais configurações do gateway (título, descrição, modo de integração, credenciais, chave do log de depuração) e o registro são removidos. Se estiver desativado, elas são mantidas para uma nova instalação. As tentativas e os reembolsos do Webpay dos pedidos são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados após uma nova instalação. Os pedidos existentes mantêm as suas notas de pagamento.

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

Transbank e Webpay são marcas registradas de seus respectivos titulares. Esta extensão não é afiliada nem endossada pela Transbank.