API compatível com a Coinbase Commerce

Os endpoints de charge, o cabeçalho X-CC-Api-Key, o objeto charge e os webhooks assinados com X-CC-Webhook-Signature seguem a documentação da Coinbase Commerce, então os SDKs oficiais funcionam depois de trocar uma linha. A Coinbase Commerce deixou de atender lojistas fora dos EUA e de Singapura em 2026-03-31. Vindo de outro lugar? Veja a visão geral da migração.

Por baixo é uma cobrança comum da blockwallets: os endereços de recebimento são seus, a página de pagamento é o nosso checkout hospedado, e um pagamento só vale depois de confirmado na blockchain e conferido com um segundo nó. A seguir: três passos, depois o que cada API suporta e como ela difere da original — parâmetros que não implementamos retornam erro em vez de serem ignorados em silêncio.

Três passos

1. Consiga uma conta de lojista (solicite na página inicial) e cadastre os seus domínios em “Domínios do site”, em “Desenvolvedores › Integração e chaves” no painel. As URLs de callback (ipn_callback_url) e de redirecionamento (success_url / cancel_url / redirect_url) precisam estar nesses domínios ou no domínio da sua URL de callback — uma chave vazada não consegue apontar webhooks para outro lugar.
2. Gere credenciais compatíveis no painel do lojista, em “Desenvolvedores › Integração e chaves”, um conjunto para live e outro para test: a NOWPayments recebe uma API key + IPN secret, a Coinbase Commerce uma API key + webhook shared secret. Elas são exibidas uma única vez; guardamos apenas hashes / texto cifrado.
3. Aponte o seu código para a URL base abaixo e use as novas chaves. Rode primeiro nas testnets com as credenciais de test e depois passe para live.

Coinbase Commerce

Todos os SDKs oficiais aceitam uma URL base — mude uma linha (atenção à / final):

// Node(coinbase-commerce-node)
const { Client } = require("coinbase-commerce-node");
- Client.init(process.env.COINBASE_COMMERCE_API_KEY);
+ Client.init(process.env.COINBASE_COMMERCE_API_KEY, "https://blockwallets.io/coinbase/");

# Python(coinbase-commerce)
- client = Client(api_key=API_KEY)
+ client = Client(api_key=API_KEY, base_api_uri="https://blockwallets.io/coinbase/")

// PHP(coinbase/coinbase-commerce)
- ApiClient::init($apiKey);
+ ApiClient::init($apiKey, 'https://blockwallets.io/coinbase/');

curl -X POST https://blockwallets.io/coinbase/charges \
  -H "X-CC-Api-Key: $COINBASE_COMMERCE_API_KEY" -H "X-CC-Version: 2018-03-22" \
  -H "content-type: application/json" \
  -d '{"name":"Order #12345","description":"Pro plan","pricing_type":"fixed_price",
       "local_price":{"amount":"100.00","currency":"USD"},
       "redirect_url":"https://shop.example/success","cancel_url":"https://shop.example/cancel",
       "metadata":{"order_id":"12345"}}'
# → 201 {"data": {"id": "…", "code": "7C7V5ECK", "hosted_url": "https://blockwallets.io/pay/inv_…", "timeline": [{"status": "NEW", …}], …}}

Endpoints suportados

Não disponíveis: /charges/:code/resolve (400 — trate cobranças pagas a menos no painel), /checkouts, /events, /invoices (404).

Webhooks

Os webhooks da Coinbase são no nível da conta, e os nossos também: vão para a URL de callback definida no seu painel (cobranças criadas com credenciais de test vão para a URL de callback de test). O corpo é o da Coinbase, {id, scheduled_for, attempt_number, event: {id, type, api_version, created_at, data}}, com a cobrança completa em data; X-CC-Webhook-Signature = HMAC-SHA256(shared secret, corpo bruto), então o Webhook.verifyEventBody dos SDKs funciona como está. Nas novas tentativas, event.id permanece o mesmo e attempt_number aumenta — deduplique por event.id.

import crypto from "node:crypto";

// Same as the SDK's Webhook.verifySigHeader: HMAC-SHA256(shared secret, raw body)
function verifyWebhook(rawBody, sig, sharedSecret) {
  const hmac = crypto.createHmac("sha256", sharedSecret).update(rawBody, "utf8").digest("hex");
  return crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(sig || ""));
}
// verifyWebhook(rawBody, req.headers["x-cc-webhook-signature"], process.env.COINBASE_WEBHOOK_SECRET)
// or with the official SDK:Webhook.verifyEventBody(rawBody, signature, sharedSecret)

Ao consultar você também verá NEW (aguardando pagamento) e PENDING (pagamento visto na blockchain, confirmando). Entregue o pedido em charge:confirmed: não enviamos charge:created, charge:pending, charge:delayed nem charge:resolved.

Diferenças em relação à Coinbase Commerce

• pricing_type precisa ser fixed_price; local_price.currency precisa ser USD (USDC / USDT a 1:1). no_price e outras moedas fiduciárias retornam 400.
• O endereço aparece quando o cliente escolhe moeda e rede no checkout: addresses contém apenas essa rede, pricing apenas local mais settlement depois da escolha; sem exchange_rates, checkout nem campos de marca.
• metadata é guardado e devolvido como está (até 4 KB).
• Reembolsos não aparecem na linha do tempo; veja-os no painel.

Modo de teste

Cobranças e pagamentos criados com credenciais de test rodam na testnet de cada rede e os webhooks deles são assinados com o IPN secret / shared secret de test — totalmente separados do live: uma chave de test não enxerga pagamentos live.

Todo o resto (checkout, confirmações, redes e mínimos, reembolsos) funciona como na documentação principal.