VibeFox Satispay for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior com a extensão OpenSSL. Sem o OpenSSL, o plugin exibe um erro na área administrativa e o método de pagamento não é carregado.

Moeda: EUR. A Satispay cobra somente em euros, por isso o método de pagamento fica oculto quando a moeda da loja (ou, na página Pay for order, a moeda do pedido) não é EUR.

Conta Satispay: uma conta Satispay Business. Você não copia nenhuma chave de API: o plugin se conecta com um código de ativação de uso único que você gera no Satispay Business Dashboard (veja Configuração). Para testes, você precisa de uma conta sandbox da Satispay, solicitada em Satispay for developers.

Site público: seu site precisa estar acessível pela internet, para que a Satispay possa chamá-lo quando um pagamento mudar. Nada precisa ser configurado na Satispay para isso.

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_satispay_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate.

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

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

5. Escolha o ambiente: marque Sandbox Mode para testes e deixe desmarcado para pagamentos reais.

6. Cole um código de ativação desse ambiente em Activation Code e salve. O status da conexão passará a mostrar o Key ID.

7. Ative Enable/Disable e salve. Teste um pagamento no sandbox e, depois, desmarque Sandbox Mode e conecte o ambiente de produção com um código de ativação de produção.

Configuração

Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Satispay. A seção Satispay connection mostra o estado dos dois ambientes, por exemplo Live: Connected com o Key ID ou Sandbox: Not connected, e marca o ambiente em uso. Enquanto o ambiente em uso não estiver conectado, a página informa: O Satispay fica oculto na finalização de compra até que o ambiente em uso esteja conectado. Na lista de métodos de pagamento do WooCommerce, o Satispay aparece como pendente de configuração até que o ambiente em uso esteja conectado, e exibe um selo de modo de teste enquanto o Sandbox Mode estiver ativo.

Enable/Disable: Enable Satispay payment ativa ou desativa o método de pagamento. Padrão: desativado.

Checkout

O que os clientes veem na lista de métodos de pagamento.

Title: o nome do método de pagamento exibido na finalização de compra. Padrão: Satispay.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay with the Satispay app: scan the QR code or confirm the payment on your phone.

Satispay connection

Sandbox Mode: Use the Satispay sandbox (staging) environment. Pagamentos no sandbox não são cobrados. Padrão: desativado. Sandbox e produção têm chaves separadas: conecte cada ambiente com um código de ativação desse ambiente. Enquanto o sandbox estiver em uso, os clientes veem Modo sandbox: nenhum dinheiro real é cobrado. abaixo do método de pagamento.

Activation Code: para conectar o ambiente selecionado acima, cole um novo código de ativação de 6 caracteres e salve. Os códigos de produção são gerados no Satispay Business Dashboard, na seção Online shop. Os códigos de sandbox vêm com uma conta sandbox da Satispay. O código é usado uma única vez e não é armazenado. Deixe o campo vazio para manter a conexão atual.

Ao salvar com um código, o plugin cria um par de chaves RSA, envia a chave pública e o código para a Satispay e armazena no banco de dados do WordPress o Key ID e as chaves desse ambiente. Em caso de sucesso, a página mostra, por exemplo, Satispay Live connected. Key ID: seguido do ID. Se a Satispay recusar o código, a página exibe a mensagem da Satispay e pede que você verifique se o código é desse ambiente e se ainda não foi usado. Um código com caracteres diferentes de letras e números é recusado antes de qualquer envio. Salvar um novo código para um ambiente substitui a conexão anterior dele.

Payment notifications

Nada precisa ser configurado na Satispay. Cada pagamento tem sua própria URL de callback, que a Satispay chama quando o pagamento muda, e o plugin lê o pagamento novamente pela API da Satispay antes de alterar um pedido. A seção mostra um exemplo dessa URL. Ela tem este formato: https://your-site/wc-api/satispay_payment_callback/?action=callback&order_id={order}&payment_id={uuid}. A URL precisa estar acessível pela internet: sem modo de manutenção nem proteção por senha em /wc-api/.

Advanced

Debug log: Log API calls and payment events grava em WooCommerce > Status > Logs, origem wcp_satispay_gateway, sem chaves nem dados de clientes. Os erros são sempre registrados, mesmo com esta opção desativada. Padrão: desativado.

Delete data on uninstall: Remove the settings and Satispay keys when the plugin is deleted. Os dados de pagamento salvos nos pedidos são mantidos. Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Satispay) e clica em Pay with Satispay. O plugin cria um pagamento Satispay pelo total do pedido em euros, com o número do pedido como referência, e envia o cliente à página de pagamento da Satispay. Em um computador, o cliente escaneia o QR code com o aplicativo Satispay. Em um celular, o cliente confirma o pagamento no aplicativo.

Após o pagamento, o cliente volta à sua loja. O pedido só é marcado como pago depois que a Satispay confirma: o plugin lê o pagamento pela API da Satispay, verifica se ele foi criado para este pedido e compara o status, o valor (em centavos) e a moeda com o pedido. Isso acontece tanto quando a Satispay chama a URL de callback quanto quando o cliente retorna, o que ocorrer primeiro. Se o pagamento ainda não tiver sido confirmado, a página de pedido recebido exibe: A Satispay ainda não confirmou o seu pagamento. O pedido será atualizado automaticamente assim que a confirmação chegar.

Se o cliente sair da página da Satispay sem pagar, o plugin cancela o pagamento na Satispay, para que a página abandonada não possa mais ser paga. O cliente volta à finalização de compra (ou à página Pay for order) com a mensagem Seu pagamento Satispay foi cancelado e nada foi cobrado. Você pode tentar novamente ou escolher outro método de pagamento. A mesma mensagem aparece quando o cliente recusa o pagamento no aplicativo.

Um cliente pode pagar novamente um pedido não pago, por exemplo pela página Pay for order. Antes de criar um novo pagamento Satispay, o anterior é verificado: um pagamento pendente é cancelado na Satispay e, se já tiver sido pago, o pedido é marcado como pago com ele e nenhuma segunda cobrança é criada.

Se o pagamento não puder ser iniciado, o cliente vê uma mensagem curta e pode escolher outro método de pagamento: O Satispay não está disponível no momento. Escolha outro método de pagamento. quando a loja não está conectada ou a Satispay recusa as chaves, ou Não foi possível criar o pagamento Satispay. Tente novamente ou escolha outro método de pagamento. para outros erros. O motivo é gravado no 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).

O plugin aceita somente pagamentos únicos em euros. Não há assinaturas, métodos de pagamento salvos, pré-autorizações nem vale-refeição. Não existe verificação programada de pagamentos pendentes: se nem o callback da Satispay nem o retorno do cliente chegarem ao seu site, o pedido permanece como Pagamento pendente, e o pagamento fica visível no Satispay Dashboard.

Pedidos e reembolsos

Order statuses

Pending payment: o cliente foi enviado à Satispay e ainda não pagou, ou a Satispay ainda não confirmou o pagamento. A nota do pedido mostra o ID do pagamento Satispay, o valor e o ambiente (Live ou Sandbox).

Processing or Completed: o pagamento foi confirmado. O pedido segue a regra padrão do WooCommerce: Processando, ou Concluído para pedidos com apenas produtos virtuais para download. A nota do pedido mostra o pagamento Satispay, o valor e como ele foi verificado (callback, redirecionamento ou finalização de compra). O ID da transação é o ID do pagamento Satispay.

On hold: a Satispay informou um valor ou uma moeda diferentes do total do pedido, ou o pagamento foi aceito depois que o pedido já havia sido cancelado. A nota do pedido explica isso, e o pagamento é salvo como ID da transação, para que possa ser reembolsado. Verifique o pagamento no Satispay Dashboard e, em seguida, conclua o pedido ou reembolse o pagamento.

Cancelled: o último pagamento Satispay do pedido foi cancelado ou expirou, por exemplo porque o cliente saiu da página da Satispay. Um pagamento anterior que expira não cancela um pedido com um pagamento mais recente em andamento. Pedidos criados por você na área administrativa (links de pagamento) não são cancelados: eles permanecem como Pagamento pendente com uma nota, para que o cliente ainda possa pagá-los.

Se um segundo pagamento for aceito para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você reembolse o pagamento duplicado pelo Satispay Dashboard. Uma confirmação repetida nunca reabre um pedido cancelado ou reembolsado.

Refunds

Abra o pedido, clique em Refund, informe o valor e clique em Refund via Satispay. Reembolsos totais e parciais são suportados para pedidos pagos com Satispay. O reembolso é enviado ao ambiente em que o pagamento foi feito (produção ou sandbox), por isso esse ambiente precisa continuar conectado. Um reembolso só é considerado concluído quando a Satispay o aceita: um reembolso bem-sucedido é adicionado às notas do pedido com o ID do reembolso na Satispay e o motivo. Se a Satispay não aceitar o reembolso, o WooCommerce exibe o erro e nenhum reembolso é registrado.

Reembolsos feitos no Satispay Dashboard não são convertidos em reembolsos do WooCommerce. Se necessário, crie um reembolso manual no WooCommerce sem usar Refund via Satispay.

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 > Satispay. 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 informar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre 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 na vibefox.net.

Sem uma chave ativa, a Satispay não aparece para os clientes na finalização de compra. Se um pagamento for iniciado mesmo assim, o cliente vê Este método de pagamento não está disponível. Escolha outro. Gerentes da loja que estiverem logados continuam vendo 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

A Satispay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, se o ambiente em uso está conectado (a seção Satispay connection mostra Connected para ele) e se a moeda é EUR.

O pagamento foi feito, mas o pedido continua como Pending payment: o pedido é atualizado quando a Satispay chama o seu site ou quando o cliente retorna. Verifique se o seu site está acessível pela internet, sem modo de manutenção nem proteção por senha em /wc-api/, e consulte WooCommerce > Status > Logs, origem wcp_satispay_gateway. O pagamento fica visível no Satispay Dashboard.

O callback responde Payment status unavailable, retry later ou Not configured: o plugin não conseguiu ler o pagamento na Satispay, ou o ambiente do pedido não está conectado. O pedido não é alterado. Verifique o status da conexão e o log.

O callback responde Busy, retry later: o pedido estava sendo atualizado por outra requisição no mesmo instante. Este callback não altera o pedido. Ele será atualizado pelo próximo callback ou quando o cliente retornar.

O callback responde Unknown payment ou Missing or invalid payment_id: o pagamento não foi criado para este pedido, ou a requisição não é um callback da Satispay. O pedido não é alterado.

A ativação falha: os códigos de ativação só podem ser usados uma vez. Verifique se o código pertence ao ambiente selecionado em Sandbox Mode (código de produção para produção, código de sandbox para o sandbox), gere um novo código e salve novamente. Se a página informar que não foi possível gerar um par de chaves RSA, peça à sua hospedagem para ativar a extensão PHP OpenSSL.

A Satispay sumiu da finalização de compra após trocar de sandbox para produção: sandbox e produção usam chaves diferentes. Cole um código de ativação de produção com Sandbox Mode desmarcado e salve.

O pedido está On hold e a nota não corresponde ao pedido: a Satispay informou um valor ou uma moeda diferentes do total do pedido, por exemplo porque o pedido foi editado depois que o pagamento começou. Verifique o pagamento no Satispay Dashboard e, em seguida, conclua o pedido ou reembolse o pagamento.

O reembolso falha porque o ambiente não está mais conectado: o pagamento foi feito em produção ou no sandbox, e esse ambiente não tem mais chaves. Conecte-o novamente com um código de ativação ou reembolse o pagamento pelo Satispay Dashboard.

O reembolso falha com Satispay did not accept the refund: a Satispay devolveu um status diferente de accepted. O WooCommerce não registrou o reembolso. Verifique no Satispay Dashboard.

O bloco de licença exibe um erro: siga a mensagem do 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 estiver inacessível, 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 da licença deste plugin são sempre removidos. As configurações do gateway, as chaves Satispay dos dois ambientes e os logs do plugin são removidos somente se Delete data on uninstall estiver ativado. Caso contrário, permanecem para uma eventual reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

Satispay é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Satispay.