Alternative à Coinbase Commerce : Crypto Merchant vs Coinbase Commerce (2026)

Comment migrer de Coinbase Commerce vers Crypto Merchant ?

Votre intégration Commerce créait des charges et recevait des webhooks. Avec Crypto Merchant, vous créez une facture pour chaque commande, envoyez le client vers sa page de paiement et traitez des webhooks signés. Les étapes ci-dessous font correspondre chaque tâche à notre API ; la Référence de l’API détaille tous les champs.

Ce qui remplace quoi

1. Créez une facture au lieu d’une charge

Créez une clé API dans le portail, sous Développeurs (les clés réelles commencent par cm_live_), et gardez-la sur votre serveur. Votre compte doit d’abord être activé : tant que la configuration n’est pas terminée, l’API répond 403 avec le code merchant_not_live. Ensuite, partout où votre code créait une charge, créez une facture. Le montant doit valoir au moins 0,50 dollar américain.

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 réponse, avec le statut 201, est l’objet facture. Enregistrez son id avec votre commande. Son statut est d’abord open.

2. Envoyez les clients vers l’URL de paiement

Redirigez le client vers le checkout_url de la facture. Il y choisit une crypto et un réseau, obtient une adresse de dépôt utilisée pour cette facture uniquement, et voit le montant exact à un taux bloqué. Définissez redirect_url pour le ramener sur votre site après le paiement. Si aucun paiement n’est détecté avant expires_at, la facture expire.

Commerce fonctionnait sur Ethereum, Polygon et Base, et Crypto Merchant accepte l’USDC sur les trois. Pour sauter le choix de la crypto, transmettez coin, par exemple USDC.BASE : pay_address et pay_amount sont alors renvoyés remplis, et vous pouvez afficher vous-même les détails du paiement.

// 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. Vérifiez la signature du webhook

Ajoutez l’adresse HTTPS de votre endpoint sous Développeurs. Chaque endpoint reçoit son propre secret de signature, qui commence par whsec_. Chaque événement est un POST avec un en-tête CM-Signature : t= un horodatage Unix en secondes, puis v1= le HMAC-SHA256 en hexadécimal de l’horodatage, d’un point et du corps brut, calculé avec le secret de votre endpoint.

Calculez-le sur le corps brut avant d’analyser le JSON, comparez-le en temps constant, et rejetez les horodatages de plus de cinq minutes. Répondez avec un statut 2xx en moins de 10 secondes ; toute autre réponse entraîne une nouvelle tentative, jusqu’à huit fois sur environ deux jours.

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. Faites correspondre les statuts de paiement

Ne traitez les commandes que sur invoice.paid, et faites correspondre les autres statuts à votre système de commandes comme ci-dessous. Une facture insuffisamment payée peut encore devenir payée si le client envoie le reste à la même adresse.

5. Gérez les webhooks en double et dans le désordre

Les événements peuvent arriver plusieurs fois, et pas toujours dans l’ordre. Enregistrez l’id de chaque événement (également envoyé dans l’en-tête CM-Event-Id) sous une clé unique, dans la même transaction de base de données que la mise à jour de la commande, et ignorez les événements déjà enregistrés. Rendez les changements de statut irréversibles, afin qu’un invoice.confirming tardif ne fasse jamais reculer une commande payée. Avant d’expédier un article de valeur, récupérez la facture via l’API pour revérifier son statut.

6. Rapprochez

Listez les factures payées 100 par 100, en suivant starting_after tant que has_more vaut true, et rapprochez chacune d’une commande grâce à 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;
}

Votre solde est crédité du montant de la facture (ou du montant légèrement inférieur reçu, si un paiement insuffisant dans la limite de votre tolérance a été accepté), moins les frais de 1 %, dans la crypto utilisée. Les paiements excédentaires ne vous sont pas crédités : Crypto Merchant conserve l’excédent pour le client, qui peut le retirer depuis la page de la facture. La page Rapports du portail fournit le brut, les frais et le net pour n’importe quelle période au format CSV, et GET /balances indique ce que vous détenez actuellement.