Coinbase Commerce-Alternative: Crypto Merchant vs. Coinbase Commerce (2026)

Wie migriere ich von Coinbase Commerce zu Crypto Merchant?

Ihre Commerce-Integration hat Charges erstellt und Webhooks empfangen. Mit Crypto Merchant erstellen Sie für jede Bestellung eine Rechnung, leiten den Kunden auf deren Bezahlseite und verarbeiten signierte Webhooks. Die Schritte unten ordnen jede Aufgabe unserer API zu; die API-Referenz enthält jedes Feld.

Was ersetzt was

1. Eine Rechnung statt einer Charge erstellen

Erstellen Sie im Portal unter Entwickler einen API-Schlüssel (Live-Schlüssel beginnen mit cm_live_) und bewahren Sie ihn auf Ihrem Server auf. Ihr Konto muss zuerst live sein: Bis die Einrichtung abgeschlossen ist, antwortet die API mit 403 und dem Code merchant_not_live. Erstellen Sie dann überall dort, wo Ihr Code eine Charge erstellt hat, eine Rechnung. Der Betrag muss mindestens 0,50 US-Dollar wert sein.

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

Die Antwort mit Status 201 ist das Rechnungsobjekt. Speichern Sie seine id mit Ihrer Bestellung. Sein Status ist zu Beginn open.

2. Kunden auf die Checkout-URL leiten

Leiten Sie den Kunden auf die checkout_url der Rechnung. Dort wählt er einen Coin und ein Netzwerk, erhält eine Einzahlungsadresse, die nur für diese Rechnung verwendet wird, und sieht den genauen Betrag zu einem fixierten Kurs. Setzen Sie redirect_url, um ihn nach dem Bezahlen auf Ihre Website zurückzubringen. Wird bis expires_at keine Zahlung erkannt, läuft die Rechnung ab.

Commerce lief auf Ethereum, Polygon und Base, und Crypto Merchant akzeptiert USDC auf allen dreien. Um die Coin-Auswahl zu überspringen, übergeben Sie coin, zum Beispiel USDC.BASE: pay_address und pay_amount kommen dann ausgefüllt zurück, sodass Sie die Zahlungsdetails selbst anzeigen können.

// 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. Die Webhook-Signatur prüfen

Fügen Sie unter Entwickler die HTTPS-Adresse Ihres Endpunkts hinzu. Jeder Endpunkt erhält sein eigenes Signaturgeheimnis, das mit whsec_ beginnt. Jedes Ereignis ist ein POST mit einem CM-Signature-Header: t= ein Unix-Zeitstempel in Sekunden, dann v1= der hexadezimale HMAC-SHA256 aus dem Zeitstempel, einem Punkt und dem unveränderten Body, berechnet mit Ihrem Endpunkt-Geheimnis.

Berechnen Sie ihn über den unveränderten Body, bevor Sie das JSON parsen, vergleichen Sie ihn in konstanter Zeit und lehnen Sie Zeitstempel ab, die älter als fünf Minuten sind. Antworten Sie innerhalb von 10 Sekunden mit einem 2xx-Status; alles andere wird wiederholt, bis zu achtmal über etwa zwei Tage.

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. Zahlungsstatus zuordnen

Liefern Sie Bestellungen nur bei invoice.paid aus und ordnen Sie die anderen Status wie unten beschrieben Ihrem Bestellsystem zu. Eine unterbezahlte Rechnung kann noch bezahlt werden, wenn der Kunde den Rest an dieselbe Adresse sendet.

5. Doppelte Webhooks und Webhooks in falscher Reihenfolge verarbeiten

Ereignisse können mehr als einmal und nicht immer in der richtigen Reihenfolge eintreffen. Speichern Sie die id jedes Ereignisses (auch im CM-Event-Id-Header gesendet) unter einem eindeutigen Schlüssel, in derselben Datenbanktransaktion wie die Aktualisierung der Bestellung, und überspringen Sie bereits gespeicherte Ereignisse. Lassen Sie Statusänderungen nur in eine Richtung zu, damit ein verspätetes invoice.confirming eine bezahlte Bestellung nie zurücksetzt. Bevor Sie etwas Wertvolles versenden, rufen Sie die Rechnung über die API ab, um ihren Status doppelt zu prüfen.

6. Abgleichen

Listen Sie bezahlte Rechnungen jeweils zu 100 auf, folgen Sie starting_after, solange has_more true ist, und ordnen Sie jede über order_id oder metadata einer Bestellung zu.

// 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;
}

Ihrem Guthaben wird der Rechnungsbetrag gutgeschrieben (oder der etwas kleinere eingegangene Betrag, wenn eine Unterzahlung innerhalb Ihrer Toleranz akzeptiert wurde), abzüglich der Gebühr von 1 %, im bezahlten Coin. Überzahlungen werden Ihnen nicht gutgeschrieben: Crypto Merchant hält den Mehrbetrag für den Kunden, der ihn auf der Rechnungsseite abheben kann. Die Seite Berichte im Portal liefert Brutto, Gebühren und Netto für jeden Zeitraum als CSV, und GET /balances zeigt, was Sie aktuell halten.