O que a extensão faz
- No checkout o comprador escolhe Cartão, Apple Pay, Google Pay, PayPal ou Cripto com seletor de moeda, clica em Confirmar e paga na página da UTOPAY.
- O pedido recebe o status de pago (padrão Processing) só depois que o pagamento é relido pela API e o valor e a moeda coincidem.
- Se o comprador voltar antes de o pagamento ser confirmado (a cripto ainda está na rede), o pedido fica visível com o status de espera (padrão Pending) e passa a pago depois.
- Cripto paga a menos e valores divergentes ficam no status de espera com uma nota no histórico do pedido.
- O método fica oculto quando a moeda do pedido não é suportada ou o carrinho tem produtos de assinatura (4.x).
Instalação
- Baixe a versão para o seu OpenCart e descompacte: dentro estão utopay.ocmod.zip e README.txt.
- OpenCart 3.0 e 4.x: Extensions → Installer → Upload → escolha
utopay.ocmod.zip(na 4.x clique também em Install ao lado). Não renomeie o arquivo: o OpenCart 4 tira dele o código da extensão. - OpenCart 2.3: descompacte
utopay.ocmod.zipe envie por FTP o conteúdo da pastauploadpara a raiz da loja — o instalador da 2.3 precisa de configurações de FTP. - Extensions → Extensions → Payments → UTOPAY → Install → Edit.
- No painel da UTOPAY abra Integration → API keys, crie uma chave de teste
utopay_sk_test_…e cole. A chave é verificada ao salvar. - Para cripto adicione sua carteira EVM no painel (Project settings → Funds & payouts) e liste as moedas.
Configurações
| Campo | O que faz |
|---|---|
| Secret key | utopay_sk_test_… para o sandbox, utopay_sk_live_… para pagamentos reais. |
| Payment options | Cartão / PayPal e cripto, só cartão ou só cripto. |
| Crypto coins | Tickers separados por vírgula, ex. bep20/usdt,erc20/usdt,polygon/usdc. |
| Card method | Vazio: o comprador escolhe; ou direto para Stripe, PayPal, Revolut… |
| Paid order status | Definido quando o pagamento é confirmado. Padrão Processing. |
| Awaiting / check status | Definido quando o comprador voltou antes da confirmação ou pagou cripto a menos. Padrão Pending. |
| Geo zone, status, sort order | Como em qualquer método de pagamento do OpenCart. |
Pagamento de teste
- Com a chave de teste faça um pedido, escolha UTOPAY e clique em Confirm order.
- No sandbox da UTOPAY clique no botão verde ✅.
- Você chega à página de pedido concluído; o pedido está em Processing com a nota «UTOPAY: payment ord_test_… received (test)».
- Troque a chave por
utopay_sk_live_….
Como os pedidos são confirmados
Cada pagamento leva sua própria URL de notificação com o número do pedido, o valor e a moeda, assinada com a sua chave secreta. A UTOPAY assina cada evento (HMAC-SHA256) e tenta de novo por seis horas se a loja não responder 2xx.
A extensão confere as duas assinaturas, relê o pagamento pela API e altera o pedido só quando ele está pago exatamente com o valor e a moeda solicitados. Um pedido pago nunca volta atrás.
Solução de problemas
- UTOPAY não aparece no checkout: a moeda do pedido não é suportada, a chave está vazia, o método está desativado ou a zona geográfica não confere.
- «amount is below the minimum»: o total está abaixo do mínimo do método ou da moeda; o comprador pode escolher outro.
- O pedido não aparece no admin: o comprador saiu sem pagar; o OpenCart guarda esses pedidos como «missing orders» (filtre por Missing Orders).
- O pedido continua Pending: a loja precisa estar acessível pela internet; procure linhas
UTOPAYem System → Maintenance → Error Logs.
Histórico de versões
- 1.0.0 — primeira versão: OpenCart 2.3 – 3.0 e 4.0 – 4.1, cartões e PayPal, cripto, tradução para o russo.
SHA-256 (2.3 – 3.0): 75fda725c1a514f5723ea19caf8f3fae64dc7c0576b1d3eb17a43d54cc439191
SHA-256 (4.x): bc1e1f62e1da1ca9e5bb1f7c83b59e34804508d2cebc3aa46b5125856c4b65b9
Atualizado · Equipe de integrações da UTOPAY