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

¿Cómo migro de Coinbase Commerce a Crypto Merchant?

Tu integración con Commerce creaba cobros y recibía webhooks. Con Crypto Merchant creas una factura por cada pedido, envías al cliente a su página de pago y procesas webhooks firmados. Los pasos de abajo traducen cada tarea a nuestra API; la referencia de la API tiene todos los campos.

Qué reemplaza a qué

1. Crea una factura en lugar de un cobro

Crea una clave de API en el portal, en Desarrolladores (las claves de producción empiezan con cm_live_), y guárdala en tu servidor. Primero tu cuenta tiene que estar activa: hasta que se termine la configuración, la API responde 403 con el código merchant_not_live. Después, donde tu código creaba un cobro, crea una factura. El monto debe valer al menos 0.50 dólares estadounidenses.

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",
  …
}

La respuesta, con estado 201, es el objeto factura. Guarda su id con tu pedido. Su estado empieza como open.

2. Envía a los clientes a la URL de pago

Redirige al cliente a la checkout_url de la factura. Ahí elige una moneda y una red, recibe una dirección de depósito que se usa solo para esta factura y ve el monto exacto con un tipo de cambio fijado. Define redirect_url para que vuelva a tu sitio después de pagar. Si no se detecta ningún pago antes de expires_at, la factura vence.

Commerce funcionaba en Ethereum, Polygon y Base, y Crypto Merchant acepta USDC en las tres. Para omitir la elección de moneda, envía coin, por ejemplo, USDC.BASE: entonces pay_address y pay_amount vienen completos, así que puedes mostrar tú mismo los datos del pago.

// 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. Verifica la firma del webhook

Agrega la dirección HTTPS de tu endpoint en Desarrolladores. Cada endpoint recibe su propio secreto de firma, que empieza con whsec_. Cada evento es un POST con un encabezado CM-Signature: t= con una marca de tiempo Unix en segundos, y luego v1= con el HMAC-SHA256 en hexadecimal de la marca de tiempo, un punto y el cuerpo sin procesar, con el secreto de tu endpoint como clave.

Calcúlalo sobre el cuerpo sin procesar antes de analizar el JSON, compáralo en tiempo constante y rechaza las marcas de tiempo de más de cinco minutos. Responde con un estado 2xx en menos de 10 segundos; cualquier otra cosa se reintenta, hasta ocho veces a lo largo de unos dos días.

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. Asocia los estados de pago

Procesa los pedidos solo con invoice.paid, y asocia los demás estados a tu sistema de pedidos como se indica abajo. Una factura con pago incompleto todavía puede pasar a pagada si el cliente envía el resto a la misma dirección.

5. Gestiona webhooks duplicados y fuera de orden

Los eventos pueden llegar más de una vez, y no siempre en orden. Guarda el id de cada evento (que también se envía en el encabezado CM-Event-Id) con una clave única, en la misma transacción de base de datos que la actualización del pedido, y omite los eventos que ya guardaste. Haz que los cambios de estado vayan en un solo sentido, para que un invoice.confirming tardío nunca haga retroceder un pedido pagado. Antes de enviar algo valioso, obtén la factura desde la API para volver a comprobar su estado.

6. Concilia

Lista las facturas pagadas de 100 en 100, siguiendo starting_after mientras has_more sea true, y asocia cada una a un pedido por order_id o 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;
}

Tu saldo se acredita con el monto de la factura (o con el monto un poco menor que se recibió, si se aceptó un pago incompleto dentro de tu tolerancia), menos la comisión del 1 %, en la moneda del pago. Los pagos de más no se te acreditan: Crypto Merchant guarda el excedente para el cliente, que puede retirarlo desde la página de la factura. La página Reportes del portal da el bruto, las comisiones y el neto de cualquier período en CSV, y GET /balances muestra lo que tienes ahora.