VibeFox Redsys for WooCommerce — Ajuda
Requisitos
WordPress: 6.2 ou superior.
WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior.
Conta de comerciante Redsys: o seu banco (a adquirente que lhe deu o POS virtual da Redsys) fornece o código de comerciante (FUC), o número do terminal e o acesso ao painel de administração da Redsys, onde aparece a chave secreta SHA-256 de cada ambiente. A chave do ambiente de teste é diferente da do ambiente real. A notificação online (HTTP) precisa estar ativa para o seu terminal. Pergunte ao seu banco se tiver dúvidas.
Moeda da loja: uma das moedas suportadas pelo plugin (veja Configuração), e o seu banco deve ter habilitado o terminal Redsys para ela. A maioria dos terminais aceita somente EUR.
Site acessível: a Redsys precisa conseguir acessar o seu site pela internet, sem login nem bloqueio de firewall, para enviar 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 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_redsys_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Redsys > Manage, ou clique em Settings abaixo do nome do plugin na página de Plugins.
4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira o código de comerciante, o terminal e a chave secreta de cada ambiente (veja Configuração).
6. Ative Enable/Disable. Teste um pagamento com Test Mode ativado e depois desmarque Test Mode para aceitar pagamentos reais.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Redsys. Acima dos campos, a página avisa quando o código de comerciante está em branco ou não é composto só de números, 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 então oculto na finalização de compra) e quando a moeda da loja não é suportada. Com o modo de teste ativado, ela mostra Test mode is active: payments go to the Redsys test environment (SIS-T), no real money is charged. Depois de salvar, os avisos acompanham imediatamente as novas configurações. Na lista de métodos de pagamento, a Redsys aparece como precisando de configuração até que o código de comerciante, o terminal e a chave do modo atual estejam válidos.
Geral
Enable/Disable: Enable Redsys Gateway ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o nome do método de pagamento que os clientes veem na finalização de compra. Padrão: Credit/Debit Card (Redsys).
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 de administração da Redsys, onde aparece a chave secreta SHA-256 de cada ambiente. A seção tem um link para o painel de administração da Redsys.
Merchant Code (FUC): o seu código de comerciante Redsys, de até 9 dígitos. Qualquer caractere que não seja 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). É usada quando o modo de teste está desativado.
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. Nenhum dinheiro real é cobrado no modo de teste.
Test Mode: Enable test mode envia pagamentos e reembolsos para o ambiente de teste da Redsys (SIS-T) e os assina com a chave de teste. Padrão: ativado. Desmarque para aceitar pagamentos reais. Enquanto estiver ativado, 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.
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 do seu site, cortado em 25 caracteres.
Order Status After Payment: o status do pedido definido após um pagamento bem-sucedido. O status é definido uma única vez, então o cliente recebe um só e-mail.
Notificações de pagamento
A Redsys informa cada pagamento ao endereço de notificação da sua loja. Ele tem o formato https://your-site/wc-api/rdsg_redsys/ e é exibido nesta seção. O plugin 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 os pedidos continuam em Pagamento pendente após um pagamento bem-sucedido. Notificações sem assinatura válida são rejeitadas. Sem a notificação, um pedido não é marcado como pago.
Avançado
Debug log: Enable debug logging grava os detalhes de pagamentos, notificações e reembolsos em WooCommerce > Status > Logs, origem wcp_redsys_gateway. Erros são sempre registrados, mesmo com esta opção desativada. Chaves, assinaturas e dados de cartão nunca são registrados. Padrão: desativado.
Delete Data: Delete the gateway settings when the plugin is deleted. Quando ativado, excluir o plugin remove as configurações do gateway e os logs do plugin. Padrão: desativado.
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 as demais moedas. Na página Pay for order, vale a moeda do pedido.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão Credit/Debit Card (Redsys)) e faz o pedido. O pedido passa para Pagamento pendente e o cliente vê Redirecting to Redsys for payment. Please wait..., e depois segue para a página de pagamento da Redsys do seu banco. Se o navegador não continuar sozinho, o cliente clica em Pay via Redsys. 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 da sua loja (espanhol, inglês, catalão, francês, alemão, italiano, português e outros), ou inglês para os demais idiomas.
O valor é enviado nas unidades menores da moeda do pedido, por exemplo EUR 43,45 como 4345, e JPY ou CLP sem decimais. O pagamento é descrito como Order com o número do pedido e o nome do seu site. O estoque é reduzido quando o pagamento é confirmado, não antes.
Depois de pagar, o cliente volta à página de pedido recebido da sua loja. O pedido só é marcado como pago depois que a Redsys confirma por meio da notificação assinada. Até ela chegar, a página mostra Redsys is confirming your payment. If you completed the payment, your order will be updated in a few moments — please do not pay again.
Se o cliente cancelar ou o pagamento for recusado, a Redsys devolve o cliente à sua loja. Em um pedido do checkout, o pedido é cancelado da forma padrão do WooCommerce e o carrinho é mantido. Em um pedido que você criou no admin (um link de pagamento), o cliente volta para a página Pay for order com a mensagem The Redsys payment was not completed. You can try again or choose another payment method., e o pedido não é cancelado. A página de redirecionamento da sua loja também oferece Cancel order & restore cart ou, para pedidos criados no admin, Choose another payment method.
Um cliente pode pagar novamente um pedido não pago pela página Pay for order. Cada tentativa recebe um novo número de pedido da Redsys, e um pagamento feito em qualquer uma delas, por exemplo a partir de uma segunda aba do navegador, ainda é reconhecido.
Se o pedido não puder ser enviado à Redsys, o cliente vê uma mensagem curta e pode escolher outro método de pagamento: Redsys payments are not configured correctly. Please choose another payment method or contact us., uma mensagem de que a moeda não é aceita, ou The order total must be greater than zero.
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 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 e nem notificações SOAP.
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado à Redsys e ainda não pagou, ou a notificação da Redsys ainda não chegou. A nota do pedido diz Awaiting Redsys payment.
Processing, Completed or On Hold: o pagamento foi confirmado. O status segue Order Status After Payment. A nota do pedido mostra o número do pedido na Redsys (Ds_Order), o código de autorização e o código de resposta, marcado como [TEST] nos pagamentos de teste. O ID da transação do pedido é o número do pedido na Redsys.
On hold after payment: a Redsys informou um valor ou uma moeda diferentes do total do pedido, um pagamento de teste chegou enquanto a loja estava em produção (nenhum dinheiro real foi cobrado), ou o pagamento chegou depois que o pedido foi cancelado. A nota do pedido explica. Confira o pagamento no painel de administração da Redsys e depois envie o pedido ou reembolse o pagamento.
Failed: o pagamento foi recusado ou cancelado na Redsys. A nota do pedido mostra o código de resposta e, para os códigos mais comuns, um motivo curto como Insufficient funds, Card expired ou Cancelled by the customer. Somente um pedido que ainda aguarda pagamento passa para Falhou. Um pedido pago ou fechado nunca é alterado por uma tentativa recusada: a tentativa apenas é registrada em nota.
Cancelled: o cliente cancelou o pagamento, ou o pedido foi cancelado por você ou pelo tempo limite de reserva de estoque do WooCommerce.
Se chegar um segundo pagamento diferente para um pedido já pago ou reembolsado, o pedido não muda. Uma nota pede que você reembolse o pagamento duplicado no painel de administração da Redsys. Se a Redsys informar que um pagamento ainda está em andamento, uma nota é adicionada e o pedido aguarda o resultado final.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique no botão de reembolso pelo método de pagamento da Redsys (por padrão Refund via Credit/Debit Card (Redsys)). Reembolsos totais e parciais são suportados. O reembolso é enviado pela API REST da Redsys ao ambiente em que o pagamento foi feito (teste ou produção), assinado com a chave desse ambiente, e a assinatura da resposta é verificada. Se a Redsys não aceitar o reembolso, o WooCommerce mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o número do pedido na Redsys e o motivo.
Reembolsos feitos no painel de administração da Redsys não são registrados como reembolsos do WooCommerce. Quando a Redsys envia uma notificação sobre eles, uma nota é adicionada ao pedido. Se necessário, crie um reembolso manual no WooCommerce sem usar o botão de reembolso da Redsys.
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 > Redsys. 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 de domínio. Libere-a na sua conta vibefox.net.
Sem uma chave ativa, a Redsys não é exibida 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 logados 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. Os 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
A Redsys não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, 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 de produção. Verifique se a moeda da loja (na página Pay for order, a moeda do pedido) está na lista de moedas suportadas. A página de configurações mostra um aviso para cada um desses problemas.
O pagamento foi feito, mas o pedido continua em Pending payment: 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. Confira se o endereço exibido em Notificações de pagamento pode ser acessado pela internet sem login, sem página de manutenção e sem bloqueio de firewall. Ative o Debug log e veja WooCommerce > Status > Logs, origem wcp_redsys_gateway.
A notificação responde Forbidden: a assinatura não correspondeu à chave secreta do ambiente em que o pagamento foi iniciado, ou o código de comerciante na notificação não é o seu. Confira se as chaves secretas e o código de comerciante nas configurações são os do seu terminal.
A notificação responde Order not found: a notificação foi assinada corretamente, mas nenhum pedido desta loja usa esse número de pedido da Redsys.
A notificação responde Busy: o pedido estava sendo processado por outra notificação no mesmo momento. A Redsys tenta a notificação novamente.
A notificação responde Bad request: a requisição não tinha parâmetros da Redsys ou estava com dados corrompidos. Ela não veio da Redsys no formato esperado.
O pedido está On hold after payment: leia a nota do pedido. O valor ou a moeda pagos eram diferentes do pedido, um pagamento de teste chegou com a loja em produção, ou o pagamento chegou depois que o pedido foi cancelado. Envie o pedido ou reembolse o pagamento.
Pagamentos de teste não confirmam pedidos em produção: um pagamento de teste nunca paga um pedido enquanto o Test Mode estiver desativado. Em vez disso, 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 (o pagamento original não foi 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.
O seu terminal aceita uma moeda que não está na lista: desenvolvedores podem alterar a lista de moedas com o filtro rdsg_currency_codes. Adicione uma moeda somente se o seu banco a tiver habilitado para o terminal.
Após atualizar da versão 1.0: a chave que você usou no modo de teste agora está em Secret Key (SHA-256) — test. Insira a chave de produção antes de desmarcar Test Mode. Pedidos criados com a versão 1.0 continuam recebendo notificações e reembolsos.
O bloco de licença mostra um erro: siga a mensagem no bloco. Por exemplo, se a chave já estiver 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 do plugin são removidos somente se Delete Data estava ativado; caso contrário, ficam guardados para uma reinstalação futura. Os dados da Redsys armazenados nos pedidos são sempre mantidos, porque documentam os pagamentos e são necessários para os reembolsos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
Redsys é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela Redsys.