VibeFox Redsys for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões anteriores do PHP.
Conta de comerciante Redsys: o seu banco (o adquirente que lhe forneceu o POS virtual da Redsys) fornece o código de comerciante (FUC), o número do terminal e o acesso ao painel administrativo da Redsys, onde é exibida a chave secreta SHA-256 de cada ambiente. A chave do ambiente de teste é diferente da real. A notificação online (HTTP) precisa estar ativa para o seu terminal. Pergunte ao seu banco se não tiver certeza.
Moeda da loja: uma das moedas suportadas pelo módulo (veja Configuration), e o seu terminal Redsys precisa estar habilitado pelo banco para ela. A maioria dos terminais aceita apenas EUR.
Loja acessível: a Redsys precisa conseguir acessar a sua loja pela internet, sem login nem bloqueio de firewall, para entregar as notificações de pagamento.
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 Redsys 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. Informe o seu código de comerciante, o terminal e a chave secreta de cada ambiente (veja Configuration).
5. Ative Enable/Disable e clique em Save. Teste um pagamento com Test Mode ligado e depois desligue o Test Mode para aceitar pagamentos reais.
Na instalação, o módulo cria o status de pedido Redsys payment on hold. O PrestaShop oferece o novo módulo de pagamento para os países ativos naquele momento, e para todas as moedas e grupos de clientes. Você pode alterar isso em Payment > Preferences; os países que você ativar depois devem ser marcados ali para o módulo.
Configuration
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Redsys 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 o código de comerciante está ausente ou não contém apenas dígitos, quando uma chave secreta não é uma chave SHA-256 válida da Redsys, quando a chave do modo atual está vazia (o método de pagamento fica oculto na finalização de compra) e quando a moeda da loja não é suportada. Enquanto o modo de teste está ligado, ela mostra Test mode is active: payments go to the Redsys test environment (SIS-T), no real money is charged. Se Title estiver vazio, a página mostra Enter a title for the payment method. e nada é salvo.
Redsys
Enable/Disable: Enable Redsys Gateway 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. Também é o nome do método de pagamento salvo no pedido. Padrão: Credit/Debit Card (Redsys). Obrigatório.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely with your credit or debit card via Redsys.
Conta Redsys
O seu banco fornece o código de comerciante, o terminal e o acesso ao painel administrativo da Redsys, onde é exibida a chave secreta SHA-256 de cada ambiente. A seção contém um link para o painel administrativo da Redsys.
Merchant Code (FUC): o seu código de comerciante Redsys, de até 9 dígitos. Tudo o que não for dígito é removido ao salvar.
Terminal Number: o número do terminal atribuído pelo seu banco, de até 3 dígitos. Padrão: 1. Um campo vazio é salvo como 1.
Secret Key (SHA-256) — live: a chave SHA-256 em Base64 do ambiente real (de produção), normalmente com 32 caracteres. Ela é usada quando o modo de teste está desligado.
Modo de teste (SIS-T)
O ambiente de teste da Redsys tem a sua própria chave secreta. A seção mostra os dados públicos de teste da Redsys: código de comerciante 999008881, terminal 1, chave sq7HjrUOBfKmC576ILgskD5srU870gJ7, cartão 4548 8100 0000 0003, validade 12/49, CVV 123. No modo de teste nenhum dinheiro real é cobrado.
Test Mode: pagamentos e reembolsos vão para o ambiente de teste da Redsys (SIS-T) e são assinados com a chave de teste. Padrão: ligado. Desligue para aceitar pagamentos reais. Enquanto estiver ligado, a finalização de compra mostra TEST MODE: Redsys test environment, no real money is charged. abaixo do método de pagamento.
Secret Key (SHA-256) — test: a chave SHA-256 em Base64 do ambiente de teste. Use a sua própria chave de teste ou a chave pública de teste indicada acima.
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 secrets: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Página de pagamento e pedidos
Commerce Name: o nome da loja exibido na página de pagamento da Redsys, com no máximo 25 caracteres. Padrão: o nome da sua loja, cortado em 25 caracteres.
Order Status After Payment: o status do pedido definido após um pagamento bem-sucedido.
Divergências de valor ou moeda, pagamentos de teste enquanto a loja está em modo real e pagamentos de tentativas canceladas sempre vão para Redsys payment on hold.
Notificações de pagamento
Notification URL: a Redsys informa cada pagamento a este endereço da sua loja. Ele é exibido nesta seção e tem a forma https://your-shop/module/wcp_redsys_gateway/notify com URLs amigáveis. O módulo o envia à Redsys em cada pagamento, então não há nada para copiar no painel da Redsys. A notificação online (HTTP) precisa estar ativa para o seu terminal. Pergunte ao seu banco se nenhum pedido for criado após um pagamento bem-sucedido. Notificações sem assinatura válida são rejeitadas. Sem a notificação, nenhum pedido é criado.
Avançado
Debug log: grava os detalhes de pagamentos, notificações e reembolsos em logs/rdsg_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros são sempre registrados, mesmo com esta opção desligada. Chaves, assinaturas e dados de cartão nunca são registrados. Padrão: desligado.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Delete Data: quando ligado, desinstalar o módulo remove as configurações do gateway e o log. Os registros de pagamento da Redsys dos pedidos (necessários para reembolsos) e o status de pedido Redsys payment on hold são sempre mantidos. Padrão: desligado.
Moedas suportadas
EUR, USD, GBP, JPY, CHF, CAD, AUD, NZD, NOK, SEK, DKK, PLN, CZK, HUF, BGN, RON, ILS, INR, MYR, SGD, THB, SAR, ZAR, RUB, BRL, MXN, ARS, CLP, COP, PEN, CNY, TWD. O método de pagamento fica oculto para carrinhos em outras moedas.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, Credit/Debit Card (Redsys)) e confirma o pedido. O cliente vê Redirecting to Redsys for payment. Please wait... e segue para a página de pagamento da Redsys do seu banco. Se o navegador não avançar sozinho, o cliente clica em Pay via Redsys, ou em Choose another payment method para voltar. Nesse ponto, ainda não existe pedido.
Na página da Redsys, o cliente paga com cartão com 3-D Secure, ou com Bizum ou outro método habilitado pelo seu banco para o terminal. A página usa o idioma do carrinho (espanhol, inglês, catalão, francês, alemão, italiano, português e outros), ou inglês para os demais idiomas. O valor é o total do carrinho na menor unidade da moeda do carrinho, por exemplo EUR 43,45 vira 4345, e JPY ou CLP sem decimais. O pagamento é descrito como Cart com o número do carrinho e o nome da sua loja.
Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que a Redsys confirma pela notificação assinada: é a notificação que cria o pedido, e o cliente vê a página padrão de confirmação de pedido com Your payment with Redsys has been received. Se o pedido foi para Redsys payment on hold, a página mostra Your payment with Redsys has been received and is being reviewed by the store. Se a notificação ainda não chegou, uma página Payment confirmation mostra Redsys is confirming your payment. If you completed the payment, your order will be created in a few moments — please do not pay again. com os botões Check again e Back to checkout.
Se o cliente cancelar ou o pagamento for recusado, a Redsys devolve o cliente à finalização de compra com The Redsys payment was not completed. You can try again or choose another payment method. O carrinho é mantido e o cliente pode pagar de novo. Cada nova tentativa recebe um novo número de pedido na Redsys, e um pagamento feito por qualquer uma delas, por exemplo por uma segunda aba do navegador, continua sendo reconhecido.
Se o pagamento não puder ser enviado à Redsys, o cliente permanece na finalização de compra com uma mensagem curta: Redsys payments are not configured correctly. Please choose another payment method or contact us., uma mensagem informando que a moeda não é aceita, ou The order total must be greater than zero.
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 aceita pagamentos únicos, autorizados e capturados na hora na página da Redsys. Não há formulário de cartão no seu próprio site (InSite ou iframe), nem cartões salvos, pagamentos com um clique ou tokenização, nem assinaturas ou pagamentos recorrentes, nem pré-autorização com captura posterior, nem links de pagamento para pedidos criados no back office.
Pedidos e reembolsos
Status do pedido
No order yet: o cliente foi enviado à Redsys e não pagou, o pagamento foi recusado ou cancelado, ou a notificação da Redsys ainda não chegou. Existe apenas o carrinho.
Payment accepted, Delivered or Redsys payment on hold: o pagamento foi confirmado. O status segue Order Status After Payment. O pagamento é registrado com o número do pedido na Redsys (Ds_Order) como ID da transação, e uma nota mostra o número do pedido na Redsys, o código de autorização e o código de resposta, com a marcação [TEST] para pagamentos de teste.
Redsys payment on hold after payment: a Redsys informou um valor ou uma moeda diferentes do total do carrinho (por exemplo, o carrinho foi alterado em outra aba depois que o pagamento começou), chegou um pagamento de teste enquanto a loja está em modo real (nenhum dinheiro real foi cobrado e nenhum pagamento é registrado), ou o cliente pagou depois de cancelar esse pagamento na página da Redsys. A nota explica o caso. Verifique o pagamento no painel administrativo da Redsys e depois processe o pedido ou reembolse o pagamento.
Refunded: o pagamento foi totalmente reembolsado pelo módulo.
Um pagamento recusado nunca altera um pedido existente. Para os códigos de resposta mais comuns, o log e as notas dão um motivo curto, como Insufficient funds, Card expired ou Cancelled by the customer. Se chegar um segundo pagamento diferente para um carrinho que já tem pedido, o pedido não é alterado. Uma nota pede que você reembolse o pagamento duplicado no painel administrativo da Redsys. Se a Redsys indicar que um pagamento ainda está em andamento, uma nota é adicionada e o pedido aguarda o resultado final.
Bloco de pagamento Redsys
A página do pedido mostra um bloco Redsys payment com o número do pedido na Redsys (Ds_Order), o código e a resposta de autorização, o ambiente (real ou teste), o valor pago e reembolsado, um selo Test mode para pagamentos de teste, uma indicação de revisão para pedidos em espera, o histórico de reembolsos, as Redsys notes do pedido e todos os números de pedido da Redsys emitidos para o carrinho.
Reembolsos
No bloco Redsys payment, informe o valor (o valor ainda não reembolsado vem preenchido), opcionalmente um motivo, e clique em Refund via Redsys. Confirme a pergunta Refund this amount through Redsys? This cannot be undone. Reembolsos totais e parciais são suportados. Você precisa do direito de editar pedidos; o acesso às páginas de módulos não é necessário. Os reembolsos são feitos no valor e na moeda que a Redsys cobrou, então, após uma divergência de valor ou moeda, você pode reembolsar até o que o cliente realmente pagou, não até o total do pedido. O reembolso é enviado pela API REST da Redsys ao ambiente em que o pagamento foi feito (teste ou real), assinado com a chave desse ambiente, e a assinatura da resposta é verificada. Se a Redsys não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o número do pedido na Redsys e o motivo. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status.
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 Redsys.
Reembolsos feitos no painel administrativo da Redsys não são registrados como reembolsos do módulo. Quando a Redsys envia uma notificação sobre eles, uma nota é adicionada ao pedido. O status do pedido não muda automaticamente.
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 Redsys Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox Redsys 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 ficam a linha Product: presta-payment-redsys 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 para o 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 for alterado, ou depois de 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 dela. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a Redsys não é exibida aos clientes na finalização de compra. Se mesmo assim um pagamento for iniciado, 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 para você também: você pode configurar o módulo antes de comprar uma chave, mas não pode 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: 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 precisam de 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
A Redsys não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, se o código de comerciante e o terminal estão preenchidos e se o modo atual tem uma chave válida: Secret Key (SHA-256) — test no modo de teste, Secret Key (SHA-256) — live no modo real. Verifique se a moeda do carrinho está na lista de moedas suportadas. A página de configurações mostra um aviso para cada um desses problemas. Em Payment > Preferences, verifique se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente.
O pagamento foi feito, mas nenhum pedido foi criado: a notificação da Redsys não chegou à sua loja. Peça ao seu banco para verificar se a notificação online (HTTP) está ativa para o seu terminal. Verifique se o endereço exibido em Notification URL é acessível pela internet, sem login nem bloqueio de firewall. Ligue o Debug log e veja o campo Log na página do módulo.
A notificação responde Forbidden: a assinatura não corresponde à chave secreta do ambiente em que o pagamento foi iniciado, ou o código de comerciante da notificação não é o seu. Verifique se as chaves secretas e o código de comerciante das configurações são os do seu terminal.
A notificação responde Order not found: a notificação estava corretamente assinada, mas nenhum carrinho desta loja usa esse número de pedido da Redsys.
A notificação responde Busy: o carrinho estava sendo processado por outra notificação ao mesmo tempo, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). A Redsys tenta a notificação novamente. O log mostra o motivo.
A notificação responde Bad request: a requisição não tinha parâmetros da Redsys ou estava com parâmetros corrompidos. Ela não veio da Redsys no formato esperado.
O pedido está em Redsys payment on hold após o pagamento: leia as notas do bloco Redsys payment (veja Status do pedido) e depois processe o pedido ou reembolse o pagamento.
Pagamentos de teste não confirmam pedidos em modo real: um pagamento de teste nunca paga um pedido enquanto o Test Mode estiver desligado. O pedido é colocado em espera com uma nota. Use o modo de teste com a chave de teste para pagamentos de teste.
O reembolso falha: leia o erro. Redsys refund: the merchant code or the TEST secret key is not configured. (ou LIVE) significa que falta a chave do ambiente do pagamento. Os códigos de erro da Redsys são explicados na mensagem, por exemplo SIS0057 (o valor excede o que resta do pagamento), SIS0056 (pagamento original não encontrado, outro ambiente ou terminal), SIS0042 (erro de assinatura, verifique a chave deste ambiente), SIS0026 (código de comerciante ou terminal desconhecido) e SIS0027 (moeda não configurada para o terminal). Se a Redsys não puder ser acessada, o reembolso não é feito. Tente novamente mais tarde.
Seu terminal aceita uma moeda que não está na lista: desenvolvedores podem alterar a lista de moedas com o hook actionRdsgCurrencyCodes. Adicione uma moeda somente se o seu banco a tiver habilitado para o terminal.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Redsys 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 estiver ligado, as configurações do gateway e o log são removidos. Se estiver desligado, todas as configurações são mantidas para uma reinstalação posterior. Os registros de pagamento e reembolso da Redsys e o status de pedido Redsys payment on hold são sempre mantidos, então pedidos pagos antes podem ser reembolsados mesmo após uma reinstalação. Os pedidos existentes mantêm as suas notas de pagamento e IDs de transação.
A Redsys é uma marca registrada de seu respectivo titular. Este módulo não é afiliado à Redsys nem endossado por ela.