Альтернатива Coinbase Commerce: Crypto Merchant и Coinbase Commerce (2026)

Как перейти с Coinbase Commerce на Crypto Merchant?

Ваша интеграция с Commerce создавала платежи (charges) и получала вебхуки. С Crypto Merchant вы создаёте счёт для каждого заказа, направляете клиента на его страницу оплаты и обрабатываете подписанные вебхуки. Шаги ниже показывают, как каждая задача решается через наш API; в справочнике API описано каждое поле.

Что чем заменяется

1. Создавайте счёт вместо платежа (charge)

Создайте API-ключ в личном кабинете в разделе Разработчикам (рабочие ключи начинаются с cm_live_) и храните его на своём сервере. Сначала аккаунт должен быть активирован: пока не завершена настройка, API отвечает 403 с кодом merchant_not_live. Затем везде, где ваш код создавал платёж (charge), создавайте счёт. Сумма должна быть не меньше 0.50 доллара США.

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

Ответ со статусом 201 — это объект счёта. Сохраните его id вместе с заказом. Его статус изначально open.

2. Направляйте клиентов на URL страницы оплаты

Перенаправьте клиента на checkout_url счёта. Там он выбирает монету и сеть, получает адрес для оплаты, используемый только для этого счёта, и видит точную сумму по зафиксированному курсу. Укажите redirect_url, чтобы вернуть его на ваш сайт после оплаты. Если до expires_at платёж не замечен, срок счёта истекает.

Commerce работал в сетях Ethereum, Polygon и Base, и Crypto Merchant принимает USDC во всех трёх. Чтобы пропустить выбор монеты, передайте coin, например USDC.BASE: тогда pay_address и pay_amount вернутся заполненными, и вы сможете показать платёжные данные сами.

// 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. Проверяйте подпись вебхука

Добавьте HTTPS-адрес своего эндпоинта в разделе Разработчикам. Каждый эндпоинт получает собственный секрет подписи, начинающийся с whsec_. Каждое событие — это POST с заголовком CM-Signature: t= — метка времени Unix в секундах, затем v1= — HMAC-SHA256 в шестнадцатеричном виде от метки времени, точки и необработанного тела запроса, с секретом вашего эндпоинта в качестве ключа.

Вычисляйте её по необработанному телу до разбора JSON, сравнивайте за постоянное время и отклоняйте метки времени старше пяти минут. Отвечайте статусом 2xx в течение 10 секунд; при любом другом ответе событие отправляется повторно, до восьми раз в течение примерно двух дней.

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. Сопоставьте статусы платежей

Выполняйте заказы только по invoice.paid, а остальные статусы сопоставьте с вашей системой заказов, как показано ниже. Недоплаченный счёт ещё может стать оплаченным, если клиент отправит остаток на тот же адрес.

5. Обрабатывайте повторные вебхуки и вебхуки не по порядку

События могут приходить больше одного раза и не всегда по порядку. Сохраняйте id каждого события (он также передаётся в заголовке CM-Event-Id) под уникальным ключом в той же транзакции базы данных, что и обновление заказа, и пропускайте уже сохранённые события. Делайте изменения статуса однонаправленными, чтобы запоздавшее invoice.confirming никогда не вернуло оплаченный заказ назад. Прежде чем отправлять что-то ценное, запросите счёт через API, чтобы перепроверить его статус.

6. Сверка

Получайте список оплаченных счетов по 100 штук, следуя по starting_after, пока has_more равно true, и сопоставляйте каждый счёт с заказом по order_id или 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;
}

На ваш баланс зачисляется сумма счёта (или немного меньшая полученная сумма, если была принята недоплата в пределах вашего допуска) за вычетом комиссии 1 %, в монете оплаты. Переплаты вам не зачисляются: Crypto Merchant хранит излишек для клиента, который может вывести его со страницы счёта. Страница Отчёты в личном кабинете показывает валовую сумму, комиссии и чистую сумму за любой период в виде CSV, а GET /balances показывает, что у вас есть сейчас.