VibeFox Transbank for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.

Moeda: peso chileno (CLP). O Webpay Plus cobra apenas pesos inteiros, então defina a precisão da moeda CLP como 0 em International > Localization > Currencies. Para carrinhos em 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 Commerce Code de produção e a API Key Secret. A Transbank fornece o Commerce Code quando a sua afiliação é aprovada e a API Key Secret depois do processo de validação da integração (consulte a documentação para desenvolvedores da Transbank). Para testes, não são necessárias credenciais. 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 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 o VibeFox Transbank Gateway na lista de módulos e clique em Configure.

3. Informe 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. Ative Enable / Disable e clique em Save. Teste um pagamento com Integration (test) mode ativado, usando os cartões de teste da documentação para desenvolvedores da Transbank.

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

Não é necessário configurar nenhuma URL de retorno ou webhook na Transbank. O módulo envia a sua URL de retorno em cada transação.

Na instalação, o módulo cria o status de pedido Transbank payment on hold. O PrestaShop ativa o novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences; a moeda CLP deve continuar permitida para o módulo.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Transbank 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 produção está selecionada, mas o Commerce Code ou a API Key de produção está ausente ou inválida (o Webpay fica oculto na finalização de compra); 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 mostra que os pagamentos vão para o ambiente de integração da Transbank, com o código de comércio de teste público, e que nenhum dinheiro real é cobrado.

Transbank Webpay Plus

Enable / Disable: Enable Transbank Webpay Plus payments ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o nome do método de pagamento que o cliente vê na finalização de compra. Ele também é o nome do método de pagamento salvo no pedido. Padrão: Webpay Plus. Obrigatório: se você salvar com o título vazio, aparece Enter a title for the payment method.

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: 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), preenchido automaticamente. As credenciais de produção abaixo não são usadas e nenhum dinheiro real é cobrado. Padrão: ativado. Desative para ir para produção. Enquanto estiver ativo, os clientes veem TEST MODE: ambiente de integração. Nenhuma cobrança real. acima da descrição do método de pagamento.

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 módulo 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-o em sigilo. Os espaços são removidos ao salvar. Uma chave salva nunca é exibida novamente: o campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo somente se quiser alterá-la.

Clear saved API key: marque Production API Key Secret e clique em Save para remover a chave salva. Um campo vazio mantém o valor salvo.

URL de retorno

Return from Webpay: o endereço para onde a Transbank envia o cliente de volta, exibido apenas como referência. Nada precisa ser configurado na Transbank: o módulo envia esta URL em cada transação. Ela precisa estar acessível aos clientes; o modo de manutenção não a bloqueia.

Avançado

Debug log: registra as requisições à API e os retornos em logs/wc_tbk_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados, mesmo com esta opção desativada. Nenhum dado de cartão, chave de API ou token completo é registrado. 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 configurações do gateway e o log. Os dados dos pedidos são mantidos. Padrão: desativado.

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

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Webpay Plus, com o logotipo do Webpay) e confirma. O módulo cria uma transação na Transbank pelo total do carrinho 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. Nesse ponto, ainda não existe pedido.

Quando o cliente retorna, o módulo 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 estar aprovada, e o valor, o buy order e a sessão precisam corresponder ao que a loja enviou para esta tentativa. Só então o pedido é criado, e o cliente vê a página padrão de confirmação do pedido com Your Webpay payment has been received. Para um pedido em espera, a página mostra Your Webpay payment was received and is being reviewed by the shop.

Se a chamada de confirmação falhar, por exemplo por tempo esgotado, o módulo pede à Transbank o status da transação. Se o status continuar desconhecido, nenhum pedido é criado 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 outra requisição estiver confirmando o mesmo carrinho naquele momento, ou se a Transbank aprovou o pagamento mas o pedido ainda não pôde ser criado, 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 um botão Check again. Então o pedido é criado a partir da resposta salva, sem uma segunda confirmação.

Se o cliente cancelar no Webpay, ou o formulário do Webpay expirar ou informar um erro, nada é cobrado. O cliente volta à finalização de 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 mostra 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.

Se o carrinho mudou depois que o pagamento começou (por exemplo, em outra aba, ou um cupom do carrinho deixou de ser válido e o PrestaShop o removeu), a transação não é confirmada, então a Transbank não a cobra. O cliente vê Your cart changed after the Webpay payment was started. The payment was not confirmed, so it was not charged — please pay again. Se o carrinho já tiver um pedido (pago por outra tentativa ou outro método de pagamento), um retorno atrasado também não é confirmado, e 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 esse pedido não estiver pago.

Se o Webpay não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com 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 é gravado no log.

O retorno do Webpay funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.

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 nenhum pedido é criado; segundo a Transbank, transações não confirmadas não são liquidadas. O módulo não oferece Webpay Plus Mall, cartões salvos Oneclick, assinaturas, captura adiada ou conversão de moeda.

Pedidos e reembolsos

Status do pedido

No order yet: 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. Existe apenas o carrinho.

Payment accepted: a Transbank aprovou o pagamento. O pagamento é registrado com o token do Webpay como ID da transação, e 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: a Transbank autorizou um pagamento que não corresponde ao pedido (valor, buy order ou sessão), ou um cupom do carrinho deixou de ser válido depois que a Transbank aprovou o pagamento e o PrestaShop o removeu. O pagamento é registrado com o valor cobrado pela Transbank, e a nota lista as diferenças. Confira o portal da Transbank e conclua o pedido ou reembolse o pagamento.

Refunded: o pagamento foi totalmente reembolsado pelo módulo.

Se o Webpay devolver um pagamento de um carrinho que já tem um pedido, o pagamento não é confirmado e uma nota nesse pedido pede que você confira o portal da Transbank caso o cliente informe uma cobrança. Pedidos existentes não são afetados por tentativas posteriores.

Bloco Transbank Webpay Plus

A página do pedido mostra um bloco Transbank Webpay Plus com o buy order e o seu ambiente, o status do pagamento, o código de autorização, o cartão e o tipo de pagamento com o número de parcelas, o valor cobrado e reembolsado, um selo Integration para pagamentos de teste, o histórico de reembolsos, as Webpay attempts of the cart e as Transbank notes do pedido.

Reembolsos

No bloco Transbank Webpay Plus, informe o valor em CLP (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, 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 da permissão para editar pedidos; o acesso às páginas de Módulos não é necessário. Um valor parcial com casas decimais é recusado com Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. O resto final de um total de pedido com casas decimais é arredondado como a cobrança. Os reembolsos são possíveis até o valor cobrado pela Transbank, então, após uma divergência, você pode reembolsar o que o cliente realmente pagou. O reembolso vai 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 uma reversão (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 pedido como Refunded. Um reembolso parcial não altera o status. Se a Transbank não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado.

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 Transbank. Os reembolsos feitos no portal da Transbank não são importados para o PrestaShop.

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 Transbank Gateway é o primeiro bloco em Modules > Module Manager > VibeFox Transbank Gateway > Configure, 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 estão a linha Product: presta-payment-transbank e o link Manage licenses and domains in your account, que abre a sua conta na 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 único 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 do domínio. Libere a vaga na sua conta 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. A vitrine do PrestaShop não sabe que você está conectado ao back office, então a forma de pagamento também fica oculta para você: é possível 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 quando o cliente volta do Webpay, e os reembolsos pela página do pedido funcionam.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem 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 informada, 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

Webpay Plus não aparece na finalização de compra: verifique se a licença está ativa, se o Enable / Disable está ativado, se a moeda do carrinho é CLP e, com o modo de integração desativado, 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. Em Payment > Preferences, verifique se o módulo está permitido para CLP, para o país do cliente e para o grupo do cliente.

O pagamento foi feito, mas nenhum pedido foi criado: a Transbank não tem webhook, então o pedido só é criado 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. Nenhum pedido foi criado 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 cart changed after the Webpay payment was started: o total do carrinho era diferente da transação, por exemplo por uma mudança em outra aba ou um cupom expirado. Nada foi cobrado; o cliente paga o novo total.

O cliente vê um erro ao escolher o Webpay Plus: ative o Debug log e veja o campo Log na página do módulo. 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 alcançada. Transbank Webpay only supports payments in CLP (Chilean Peso) significa que o carrinho está em outra moeda.

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

O pedido está como Transbank payment on hold após o pagamento: leia as notas no bloco Transbank Webpay Plus (veja Status do pedido) e depois conclua 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. Confira 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

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Transbank Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se o Delete data on uninstall estiver ativado, as configurações do gateway e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação futura. As tentativas de Webpay e os reembolsos dos pedidos, assim como o status de pedido Transbank payment on hold, são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados após uma reinstalação. 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 proprietários. Este módulo não é afiliado nem endossado pela Transbank.