API REST nativa

A API nativa é a interface REST própria da blockwallets: cobranças em centavos de dólar, um ref idempotente por pedido, contas de depósito estáticas que cobrem todas as redes e webhooks assinados com HMAC-SHA256. Ela cria as mesmas cobranças na mesma página de pagamento hospedada que a API compatível com a Cryptomus, com as mesmas taxas e o mesmo saldo.

Gere as suas chaves você mesmo no painel, em “Desenvolvedores › Integração e chaves”: uma chave Live e uma Test com as respectivas chaves de assinatura de webhook. Cada uma é mostrada uma única vez; a lista só mostra o prefixo. Se a sua conta tem a verificação em duas etapas ativa, gerar ou rotacionar uma chave Live pede um código. Ainda não tem conta de lojista? Solicite acesso. Já usa a Cryptomus? Veja a API compatível com a Cryptomus (como escolher).

Chaves e requisições

URL base https://blockwallets.io. Requisições e respostas são em JSON. Toda requisição leva:

• Authorization: Bearer bw_live_… ou Bearer bw_test_…: o prefixo define o modo, então uma chave Test só enxerga cobranças Test e roda em testnets
• Content-Type: application/json nas requisições POST
• Guarde as chaves apenas no seu servidor, nunca numa página web ou app; nós armazenamos só o hash delas

Os erros retornam um status HTTP e {"error": {"code": "…", "message": "…"}}: 400 invalid_request (campo ausente ou malformado), 401 unauthorized (chave ausente, desconhecida ou desativada), 404 not_found, 409 conflict (a requisição conflita com o estado atual da cobrança), 422 currency_unsupported.

Endpoints

Adicione ?probe=1 à consulta de uma cobrança ou conta de depósito para verificar a blockchain na hora (no máximo uma vez a cada 10 segundos); caso contrário você recebe o último estado do nosso scanner, que verifica a cada minuto.

Criar uma cobrança POST /v1/invoices

Chame POST /v1/invoices quando o cliente finalizar a compra e redirecione-o para a pay_url da resposta.

curl -X POST https://blockwallets.io/v1/invoices \
  -H "Authorization: Bearer $BW_KEY" -H "Content-Type: application/json" \
  -d '{"ref":"order_1042","amount":4200,"title":"Order #1042",
       "return_url":"https://shop.example/cart","success_url":"https://shop.example/thanks?order=1042",
       "meta":{"user_id":42}}'

Toda URL deve estar em um dos domínios do seu site (painel → “Desenvolvedores › Integração e chaves”). A resposta é o objeto cobrança abaixo; network, address e pay_amount são preenchidos assim que uma rede é escolhida.

O objeto cobrança

Os ids começam com inv_. amount está em centavos de dólar; pay_amount e paid_amount são valores da moeda, em strings decimais, na rede escolhida.

{
  "id": "inv_01J8…",
  "ref": "order_1042",
  "mode": "live",
  "status": "pending",
  "amount": 4200,
  "currency": "USD",
  "title": "Order #1042",
  "meta": { "user_id": 42 },
  "network": null,
  "address": null,
  "pay_amount": null,
  "paid_amount": null,
  "payments": [],
  "pay_url": "https://blockwallets.io/pay/inv_01J8…",
  "return_url": "https://shop.example/cart",
  "success_url": "https://shop.example/thanks?order=1042",
  "created_at": "2026-11-03T08:00:00.000Z",
  "expires_at": "2026-11-03T09:00:00.000Z",
  "paid_at": null,
  "closed_at": null
}

Outros campos: pay_url (a página de pagamento hospedada), payments (cada transferência com txid, amount, confirmations e confirmed), expires_at, paid_at, closed_at; BTC, LTC, DOGE, BCH e moedas nativas também trazem rate (dólares por moeda, travado por 30 minutos), rate_locked_until e paid_cents (o que já chegou, em centavos de dólar).

Redes

Passe o id como network. GET /v1/networks retorna as que estão abertas agora no seu modo; uma rede pode ser pausada, então prefira consultar a deixá-la fixa no código.

Contas de depósito (endereços estáticos) POST /v1/deposit-accounts

POST /v1/deposit-accounts com {"customer_ref": "user_42"} dá a esse cliente um endereço permanente em cada rede (todas as redes EVM compartilham um endereço). Tudo o que ele enviar é creditado em dólares americanos, com um webhook deposit.credited por transferência.

curl -X POST https://blockwallets.io/v1/deposit-accounts \
  -H "Authorization: Bearer $BW_KEY" -H "Content-Type: application/json" \
  -d '{"customer_ref":"user_42"}'

{
  "id": "dac_01J8…",
  "mode": "live",
  "customer_ref": "user_42",
  "deposit_url": "https://blockwallets.io/deposit/dac_01J8…",
  "min_amount": 100,
  "currency": "USD",
  "networks": [
    { "id": "USDT_TRC20", "chain": "tron", "token": "USDT", "address": "TXy4…8kQ2", "min_amount": 100, "confirmations": 1, … },
    { "id": "USDC_BASE", "chain": "base", "token": "USDC", "address": "0x5aE1…", "min_amount": 100, "confirmations": 20, … }
  ]
}

• customer_ref: 1–128 caracteres entre letras, dígitos e _ . : @ -; o mesmo valor sempre retorna a mesma conta. return_url opcional nos seus domínios
• A resposta traz deposit_url (uma página hospedada com os endereços, QR codes e depósitos recentes) e networks (id, address, min_amount e confirmations de cada uma)
• Os ids de depósito começam com dep_; amount é em centavos de dólar, amount_token é o valor da moeda, e as moedas cotadas trazem o rate usado

Transferências abaixo do mínimo (geralmente $1, BTC $5) são registradas como below_min e não são creditadas automaticamente; fale com a gente para creditá-las.

Webhooks

Enviamos um POST com JSON para a URL de webhook do painel (“Desenvolvedores › Integração e chaves”; Live e Test têm cada um a sua URL e o seu secret). O corpo é o evento:

POST /your/webhook
X-BW-Event: ev_01J8…
X-BW-Delivery: 1
X-BW-Signature: t=1793693052,v1=5f0c9b…

{"id":"ev_01J8…","type":"invoice.paid","created_at":"2026-11-03T08:04:12.000Z","invoice":{"id":"inv_01J8…","ref":"order_1042","status":"paid","amount":4200,…}}

• X-BW-Signature: t=<unix seconds>,v1=<hex>, onde v1 = HMAC-SHA256(webhook secret desse modo, t + . + corpo bruto)
• X-BW-Event: o id do evento (ev_…); desduplique por ele
• X-BW-Delivery: o número da tentativa, começando em 1

Verifique contra o corpo bruto antes de interpretá-lo, rejeite um t a mais de 300 segundos do seu relógio e compare em tempo constante. invoice / deposit no corpo é o mesmo objeto que uma consulta retorna.

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a string), header: X-BW-Signature
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return typeof parts.v1 === "string" && parts.v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Uma resposta 2xx conta como entregue; caso contrário tentamos de novo após 1 minuto, 5 minutos, 30 minutos, 2 horas, 12 horas, 24 horas e 24 horas (8 tentativas no total).

Eventos e reenvio

GET /v1/events?invoice_id=inv_… (ou deposit_id=dep_…) lista os webhooks de uma cobrança ou depósito com state, attempts, last_status e last_error. POST /v1/events/ev_…/redeliver o coloca de novo na fila na hora, por exemplo depois de você corrigir o seu endpoint. “Desenvolvedores › Log de webhooks” no painel mostra cada tentativa com requisição e resposta.

Modo de teste

As cobranças criadas com uma chave bw_test_ rodam em testnets e nunca tocam dinheiro real. A página de pagamento hospedada mostra um botão “Simular pagamento” (total / metade / a mais), para você acompanhar status e webhooks sem moedas de testnet.