Alternativa a Coinbase Commerce: Crypto Merchant vs Coinbase Commerce (2026)

Como migrar do Coinbase Commerce para o Crypto Merchant?

A sua integração com o Commerce criava cobranças e recebia webhooks. Com o Crypto Merchant, você cria uma fatura para cada pedido, envia o cliente para a página de checkout dela e trata webhooks assinados. As etapas abaixo mapeiam cada tarefa para a nossa API; a referência da API traz todos os campos.

O que substitui o quê

1. Crie uma fatura em vez de uma cobrança

Crie uma chave de API no portal, em Desenvolvedores (as chaves de produção começam com cm_live_), e mantenha-a no seu servidor. A sua conta precisa estar ativa primeiro: até que a configuração seja concluída, a API responde 403 com o código merchant_not_live. Depois, onde o seu código criava uma cobrança, crie uma fatura. O valor precisa ser de pelo menos 0.50 dólar americano.

curl https://cryptomerchant.online/api/v1/invoices \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.90",
    "currency": "USD",
    "order_id": "1042",
    "redirect_url": "https://yourstore.example/orders/1042",
    "metadata": { "cart_id": "c_8812" }
  }'

{
  "id": "inv_…",
  "object": "invoice",
  "status": "open",
  "amount": "49.9",
  "currency": "USD",
  "amount_usd": "49.9",
  "order_id": "1042",
  "metadata": { "cart_id": "c_8812" },
  "coin": null,
  "pay_address": null,
  "pay_amount": null,
  "checkout_url": "https://cryptomerchant.online/pay/i/inv_…",
  "redirect_url": "https://yourstore.example/orders/1042",
  "expires_at": "2026-10-30T10:30:00.000Z",
  …
}

A resposta, com status 201, é o objeto de fatura. Salve o id dela com o seu pedido. O status começa como open.

2. Envie os clientes para a URL de checkout

Redirecione o cliente para a checkout_url da fatura. Lá ele escolhe uma moeda e uma rede, recebe um endereço de depósito usado só para esta fatura e vê o valor exato com uma cotação garantida. Defina redirect_url para trazê-lo de volta ao seu site depois do pagamento. Se nenhum pagamento for detectado até expires_at, a fatura expira.

O Commerce funcionava na Ethereum, na Polygon e na Base, e o Crypto Merchant aceita USDC nas três. Para pular a escolha da moeda, envie coin, por exemplo USDC.BASE: aí pay_address e pay_amount já vêm preenchidos, e você pode exibir os dados do pagamento por conta própria.

// orders: your own data layer
app.post("/orders/:id/pay", async (req, res) => {
  const order = await orders.find(req.params.id);

  const r = await fetch("https://cryptomerchant.online/api/v1/invoices", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CM_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: order.total, // for example "49.90"
      currency: "USD",
      order_id: order.id,
      redirect_url: `https://yourstore.example/orders/${order.id}`,
    }),
  });
  if (!r.ok) {
    const { error } = await r.json();
    throw new Error(`${error.code}: ${error.message}`);
  }

  const invoice = await r.json();
  await orders.update(order.id, { invoiceId: invoice.id });
  res.redirect(303, invoice.checkout_url);
});

3. Verifique a assinatura do webhook

Adicione o endereço HTTPS do seu endpoint em Desenvolvedores. Cada endpoint recebe o próprio segredo de assinatura, que começa com whsec_. Todo evento é um POST com um header CM-Signature: t= um timestamp Unix em segundos, depois v1= o HMAC-SHA256 em hexadecimal do timestamp, um ponto e o corpo bruto, usando o segredo do seu endpoint como chave.

Calcule-o sobre o corpo bruto antes de interpretar o JSON, compare em tempo constante e rejeite timestamps com mais de cinco minutos. Responda com um status 2xx em até 10 segundos; qualquer outra resposta gera novas tentativas, até oito vezes ao longo de cerca de dois dias.

import crypto from "node:crypto";
import express from "express";

// CM-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(
    String(header ?? "").split(",").map((p) => p.trim().split("=")),
  );
  if (!parts.t || !parts.v1) return false;
  const expected = crypto
    .createHmac("sha256", secret) // your endpoint secret, whsec_…
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return false;
  return Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300; // 5 minutes
}

const app = express();

// db, tx.webhookEvents, tx.orders: your own data layer
app.post(
  "/webhooks/crypto-merchant",
  express.raw({ type: "application/json" }), // keep the raw body for the signature
  async (req, res) => {
    const raw = req.body.toString("utf8");
    if (!verify(raw, req.get("CM-Signature"), process.env.CM_WEBHOOK_SECRET)) {
      return res.sendStatus(400);
    }
    const event = JSON.parse(raw);
    const invoice = event.data;

    try {
      await db.transaction(async (tx) => {
        // A unique key on the event id: a repeated delivery is skipped.
        const isNew = await tx.webhookEvents.insertIfAbsent(event.id);
        if (!isNew) return;

        if (event.type === "invoice.paid") {
          await tx.orders.markPaid(invoice.order_id, invoice.id); // one-way: never moves back
        } else if (event.type === "invoice.expired" || event.type === "invoice.cancelled") {
          await tx.orders.cancelIfUnpaid(invoice.order_id);
        }
      });
    } catch {
      return res.sendStatus(500); // not 2xx: Crypto Merchant tries again later
    }
    res.sendStatus(200); // within 10 seconds
  },
);

4. Mapeie os status de pagamento

Atenda os pedidos apenas em invoice.paid e mapeie os outros status no seu sistema de pedidos como abaixo. Uma fatura paga a menos ainda pode ficar paga se o cliente enviar o restante para o mesmo endereço.

5. Trate webhooks duplicados e fora de ordem

Os eventos podem chegar mais de uma vez, e nem sempre em ordem. Armazene o id de cada evento (também enviado no header CM-Event-Id) com uma chave única, na mesma transação de banco de dados da atualização do pedido, e ignore os eventos que você já armazenou. Faça as mudanças de status em um só sentido, para que um invoice.confirming atrasado nunca faça um pedido pago voltar atrás. Antes de enviar algo de alto valor, consulte a fatura na API para confirmar o status.

6. Faça a conciliação

Liste as faturas pagas de 100 em 100, seguindo starting_after enquanto has_more for true, e vincule cada uma a um pedido por order_id ou metadata.

// Every paid invoice, newest first. Match each one to an order by order_id.
async function paidInvoices() {
  const all = [];
  let after = null;
  do {
    const url = new URL("https://cryptomerchant.online/api/v1/invoices");
    url.searchParams.set("status", "paid");
    url.searchParams.set("limit", "100");
    if (after) url.searchParams.set("starting_after", after);

    const r = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.CM_SECRET_KEY}` },
    });
    const page = await r.json();
    all.push(...page.data);
    after = page.has_more ? page.data[page.data.length - 1].id : null;
  } while (after);
  return all;
}

O seu saldo é creditado com o valor da fatura (ou com o valor um pouco menor recebido, se um pagamento a menos dentro da sua tolerância foi aceito), menos a taxa de 1%, na moeda do pagamento. Pagamentos a mais não são creditados a você: o Crypto Merchant guarda o excedente para o cliente, que pode sacá-lo na página da fatura. A página Relatórios do portal mostra o bruto, as taxas e o líquido de qualquer período em CSV, e GET /balances mostra o que você tem agora.