O que o plugin faz
- UTOPAY — cartões e PayPal: cartões, Apple Pay, Google Pay, PayPal, Revolut, transferências bancárias. O comprador paga na página da UTOPAY e volta para a página de «Obrigado».
- UTOPAY — cripto: o comprador escolhe uma moeda (USDT e USDC na BNB Chain, Ethereum, Polygon, Arbitrum, Base…; ETH, BNB) no próprio checkout e recebe um endereço com o valor exato.
- O pedido só é marcado como pago depois que o plugin relê o pagamento pela API e o valor e a moeda coincidem.
- Um pedido em cripto pago a menos vai para On hold com uma nota: o dinheiro já está na sua carteira e você decide o que fazer.
- Pagamentos não realizados expiram em 24 horas; o WooCommerce cancela o pedido pelo seu próprio temporizador de reserva de estoque.
Instalação
- Baixe o ZIP acima. Não descompacte.
- Admin do WordPress → Plugins → Add New → Upload Plugin → escolha o arquivo → Install Now → Activate.
- No painel da UTOPAY abra Integration → API keys e crie uma chave secreta de teste
utopay_sk_test_…. - WooCommerce → Settings → Payments → UTOPAY — cards & PayPal → cole a chave → marque Enable → Save. A chave é verificada ao salvar.
- Para cripto: no painel adicione suas carteiras em Project settings → Funds & payouts, seção Crypto wallets (um endereço EVM serve para todas as redes EVM); depois ative UTOPAY — crypto e escolha as moedas.
Configurações
| Campo | O que faz |
|---|---|
| Secret key | utopay_sk_test_… para o sandbox, utopay_sk_live_… para pagamentos reais. Compartilhada pelos dois métodos. |
| Title / Description | O que o comprador vê no checkout. |
| Payment method on the UTOPAY side | Vazio: o comprador escolhe. Ou envie todos direto para um método (Stripe, PayPal, Revolut…); se não estiver disponível, aparece o seletor de métodos. |
| Coins | Só no método cripto: moedas oferecidas no checkout. Ative só as redes para as quais você tem carteira no painel. |
| Debug log | Grava requisições e notificações em WooCommerce → Status → Logs, origem utopay. |
Pagamento de teste
- Com a chave de teste, faça um pedido e escolha um método da UTOPAY.
- O sandbox da UTOPAY abre. Clique no botão verde ✅ para simular um pagamento.
- Em um segundo e meio você volta para a página de «Obrigado»; o pedido fica Processing com a nota «UTOPAY payment ord_test_… received (test)».
- Repita com o botão vermelho ❌: o pedido fica Failed.
- Troque a chave por
utopay_sk_live_…. Pronto.
Como os pedidos são confirmados
Cada pagamento é criado com sua própria URL de notificação: https://seu-site/?wc-api=utopay&order_id=…&key=…. A UTOPAY envia para lá cada mudança de status, assinada com HMAC-SHA256 (a chave é derivada da sua chave secreta). Se o seu site não responder 2xx, a UTOPAY tenta de novo após 30 s, 2 min, 15 min, 1 h e 6 h.
O plugin não confia no corpo da notificação: consulta o pagamento na API e conclui o pedido só se o pagamento pertencer a ele e o valor e a moeda coincidirem. Quando o comprador volta para a página de «Obrigado», a mesma verificação roda de novo — assim até um site local ou protegido confirma os pedidos.
Solução de problemas
- Os métodos não aparecem no checkout: a moeda da loja não é suportada ou a chave está vazia. Suportadas: USD EUR GBP CAD AUD NZD CHF SEK NOK DKK PLN CZK HUF TRY UAH INR JPY SGD HKD AED MYR THB PHP IDR BRL MXN COP ZAR NGN.
- «Payment could not be started: amount is below the minimum»: o total do pedido está abaixo do mínimo do método ou da moeda escolhidos; o comprador pode escolher outro.
- O pedido continua em «Pending payment»: o site precisa estar acessível pela internet sem autenticação HTTP, e plugins de segurança não podem bloquear requisições POST para
/?wc-api=utopay. Ative o Debug log e procure linhascallback. - «no evm wallet…»: a moeda está ativada no plugin, mas não há carteira para a rede dela no painel.
Histórico de versões
- 1.0.2 — núcleo comum da UTOPAY atualizado, sem mudança de comportamento.
- 1.0.1 — suporte a domínio de API white-label (constante UTOPAY_API_BASE); moedas padrão em redes EVM.
- 1.0.0 — primeira versão: cartões e PayPal, cripto, checkout de blocos, HPOS, tradução para o russo.
SHA-256: 8a3900be6f724ca8c467fa538aeaedb9c81a6789dd59840313767688e1ffcf1b
Atualizado · Equipe de integrações da UTOPAY