Aceite pagamentos em cripto no seu site

Escolha como o comprador paga

Passo 1: crie um pedido no seu servidor

Nunca crie pedidos pelo navegador com uma chave secreta. Chame a API a partir do seu backend com o total do carrinho e a moeda que o comprador escolheu:

curl -X POST https://api.utopay.app/v1/crypto/payments \
  -H "Authorization: Bearer utopay_sk_live_..." \
  -H "content-type: application/json" \
  -d '{ "coin": "bep20/usdt", "amount": 49.90, "currency": "EUR",
        "description": "Order #1042",
        "success_url": "https://shop.example/thanks",
        "cancel_url": "https://shop.example/cart" }'

Com conta, a carteira de recebimento vem das configurações do projeto. Sem conta, use POST /v1/crypto/pay e informe payout_address. A lista de moedas e redes com os mínimos está em GET /v1/crypto/coins.

Passo 2: envie o comprador para pagar

• Redirecione para checkout_url: a página mostra o valor exato, a rede, o QR code e o status ao vivo, e depois devolve o comprador ao seu success_url.
• Ou mostre você mesmo crypto.address e crypto.amount_coin e consulte GET /v1/payments/:id enquanto o comprador está na página.

Passo 3: confirme o pagamento por webhook

Não confie só no redirecionamento. Marque o pedido como pago quando o seu endpoint receber um evento assinado payment.succeeded; trate payment.underpaid se chegou menos do que o pedido. Verifique o cabeçalho x-utopay-signature com o seu segredo whsec_…: há exemplos em Node.js, PHP e Python na documentação de webhooks.

<?php // PHP: verificar um webhook da UTOPAY
$raw = file_get_contents("php://input");
parse_str(str_replace(",", "&", $_SERVER["HTTP_X_UTOPAY_SIGNATURE"]), $sig);
$expected = hash_hmac("sha256", $sig["t"] . "." . $raw, getenv("UTOPAY_WHSEC"));
if (!hash_equals($expected, $sig["v1"] ?? "") || abs(time() - (int)$sig["t"]) > 300) {
  http_response_code(400); exit;
}
$event = json_decode($raw, true);
if ($event["event"] === "payment.succeeded") { /* marcar $event["data"]["id"] como pago */ }
http_response_code(200);

WordPress e WooCommerce

Existe um plugin pronto da UTOPAY para WooCommerce: veja os plugins. Sem o plugin, uma loja WooCommerce integra pela API: crie o pedido no hook woocommerce_checkout_order_processed, redirecione para checkout_url e conclua o pedido a partir do handler do webhook.

Shopify

A Shopify só mostra como gateway de pagamento os apps de pagamento aprovados. A configuração prática é um método de pagamento manual (por exemplo, «Pagar com cripto») mais uma página de pagamento da UTOPAY: quando o pedido é feito, seu app ou automação cria um pedido na UTOPAY com o total e envia ao comprador o checkout_url por e-mail. Depois, o webhook marca o pedido da Shopify como pago.

Checklist antes de lançar

• Teste o fluxo completo com chaves de teste (utopay_sk_test_…): pedidos de teste nunca tocam a blockchain.
• Confira se a carteira de recebimento suporta todas as redes que você oferece.
• Mostre o nome da rede ao lado do valor: transferências para a rede errada são o pedido de suporte mais comum.
• Guarde o id do pedido UTOPAY junto com o seu pedido e deduplique os webhooks por ele.
• Decida antes do lançamento o que fazer com pedidos underpaid.

Atualizado 11 de outubro de 2026 · Equipe UTOPAY