Lựa chọn thay thế Coinbase Commerce: Crypto Merchant và Coinbase Commerce (2026)

Làm thế nào để chuyển từ Coinbase Commerce sang Crypto Merchant?

Tích hợp Commerce của bạn tạo các charge và nhận webhook. Với Crypto Merchant, bạn tạo một hóa đơn cho mỗi đơn hàng, đưa khách hàng đến trang thanh toán của hóa đơn, và xử lý webhook có chữ ký. Các bước dưới đây đối chiếu từng việc với API của chúng tôi; Tài liệu tham khảo API có mọi trường.

Cái gì thay thế cái gì

1. Tạo hóa đơn thay vì charge

Tạo khóa API trong cổng quản lý tại mục Nhà phát triển (khóa live bắt đầu bằng cm_live_) và giữ khóa trên máy chủ của bạn. Tài khoản của bạn phải được kích hoạt trước: cho đến khi thiết lập hoàn tất, API sẽ trả về 403 với mã merchant_not_live. Sau đó, ở mọi chỗ mã của bạn từng tạo charge, hãy tạo hóa đơn. Số tiền phải có giá trị ít nhất 0.50 đô la Mỹ.

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

Phản hồi, với trạng thái 201, là đối tượng hóa đơn. Lưu id của hóa đơn cùng đơn hàng. Trạng thái ban đầu là open.

2. Đưa khách hàng đến URL thanh toán

Chuyển hướng khách hàng đến checkout_url của hóa đơn. Tại đó họ chọn coin và mạng, nhận một địa chỉ nạp chỉ dùng cho hóa đơn này, và thấy số tiền chính xác theo tỷ giá đã khóa. Đặt redirect_url để đưa họ quay lại trang web của bạn sau khi thanh toán. Nếu không phát hiện khoản thanh toán nào trước expires_at, hóa đơn sẽ hết hạn.

Commerce chạy trên Ethereum, Polygon và Base, và Crypto Merchant chấp nhận USDC trên cả ba mạng. Để bỏ qua bước chọn coin, hãy truyền coin, ví dụ USDC.BASE: khi đó pay_address và pay_amount được trả về sẵn, để bạn có thể tự hiển thị thông tin thanh toán.

// 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. Xác minh chữ ký webhook

Thêm địa chỉ HTTPS của endpoint trong mục Nhà phát triển. Mỗi endpoint có khóa bí mật ký riêng, bắt đầu bằng whsec_. Mọi sự kiện đều là một POST với header CM-Signature: t= là dấu thời gian Unix tính bằng giây, sau đó v1= là HMAC-SHA256 dạng hex của dấu thời gian, một dấu chấm và body thô, dùng khóa bí mật của endpoint làm khóa.

Tính chữ ký trên body thô trước khi phân tích JSON, so sánh bằng phép so sánh thời gian hằng định (constant-time), và từ chối dấu thời gian cũ hơn năm phút. Trả lời bằng trạng thái 2xx trong vòng 10 giây; mọi phản hồi khác sẽ được thử lại, tối đa tám lần trong khoảng hai ngày.

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. Đối chiếu trạng thái thanh toán

Chỉ xử lý đơn hàng khi nhận invoice.paid, và đối chiếu các trạng thái khác với hệ thống đơn hàng của bạn như bên dưới. Một hóa đơn thanh toán thiếu vẫn có thể trở thành đã thanh toán nếu khách hàng gửi phần còn lại đến cùng địa chỉ.

5. Xử lý webhook trùng lặp và sai thứ tự

Sự kiện có thể đến nhiều lần, và không phải lúc nào cũng theo thứ tự. Lưu id của mỗi sự kiện (cũng được gửi trong header CM-Event-Id) dưới một khóa duy nhất, trong cùng giao dịch cơ sở dữ liệu với việc cập nhật đơn hàng, và bỏ qua các sự kiện bạn đã lưu. Chỉ cho phép thay đổi trạng thái theo một chiều, để một invoice.confirming đến muộn không bao giờ đưa đơn hàng đã thanh toán quay lại. Trước khi giao một món hàng giá trị, hãy lấy hóa đơn từ API để kiểm tra lại trạng thái.

6. Đối soát

Liệt kê các hóa đơn đã thanh toán, mỗi lần 100 hóa đơn, theo starting_after chừng nào has_more còn là true, và đối chiếu từng hóa đơn với một đơn hàng theo order_id hoặc 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;
}

Số dư của bạn được cộng số tiền của hóa đơn (hoặc số tiền nhận được thấp hơn một chút, nếu một khoản thiếu trong mức dung sai của bạn được chấp nhận), trừ đi phí 1%, bằng coin được thanh toán. Các khoản trả thừa không được cộng cho bạn: Crypto Merchant giữ phần thừa cho khách hàng, người có thể rút phần đó từ trang hóa đơn. Trang Báo cáo trong cổng quản lý cung cấp tổng doanh thu, phí và số tiền thực nhận cho bất kỳ khoảng thời gian nào dưới dạng CSV, và GET /balances cho biết số dư hiện tại của bạn.