Alternatif Coinbase Commerce: Crypto Merchant vs Coinbase Commerce (2026)

Bagaimana cara bermigrasi dari Coinbase Commerce ke Crypto Merchant?

Integrasi Commerce Anda membuat charge dan menerima webhook. Dengan Crypto Merchant, Anda membuat invoice untuk setiap pesanan, mengarahkan pelanggan ke halaman checkout-nya, dan menangani webhook bertanda tangan. Langkah-langkah di bawah memetakan setiap tugas ke API kami; Referensi API berisi semua field.

Apa yang menggantikan apa

1. Buat invoice, bukan charge

Buat kunci API di portal pada menu Developer (kunci live diawali dengan cm_live_) dan simpan di server Anda. Akun Anda harus sudah aktif terlebih dahulu: sampai penyiapan selesai, API menjawab 403 dengan kode merchant_not_live. Lalu, di setiap tempat kode Anda membuat charge, buat invoice. Nilai jumlahnya minimal harus 0.50 dolar AS.

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

Respons, dengan status 201, adalah objek invoice. Simpan id-nya bersama pesanan Anda. Statusnya dimulai sebagai open.

2. Arahkan pelanggan ke URL checkout

Arahkan pelanggan ke checkout_url invoice tersebut. Di sana mereka memilih koin dan jaringan, mendapatkan alamat deposit yang hanya digunakan untuk invoice ini, dan melihat jumlah tepat dengan kurs yang dikunci. Atur redirect_url untuk mengembalikan mereka ke situs Anda setelah membayar. Jika tidak ada pembayaran yang terdeteksi sebelum expires_at, invoice akan kedaluwarsa.

Commerce berjalan di Ethereum, Polygon, dan Base, dan Crypto Merchant menerima USDC di ketiganya. Untuk melewati pemilihan koin, kirim coin, misalnya USDC.BASE: pay_address dan pay_amount kemudian dikembalikan dalam keadaan terisi, sehingga Anda dapat menampilkan detail pembayaran sendiri.

// 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. Verifikasi tanda tangan webhook

Tambahkan alamat HTTPS endpoint Anda di menu Developer. Setiap endpoint mendapat secret penandatanganan sendiri, yang diawali dengan whsec_. Setiap event adalah POST dengan header CM-Signature: t= timestamp Unix dalam detik, lalu v1= HMAC-SHA256 dalam format hex dari timestamp, sebuah titik, dan body mentah, dengan secret endpoint Anda sebagai kunci.

Hitung tanda tangan dari body mentah sebelum mem-parsing JSON, bandingkan dengan perbandingan waktu-konstan, dan tolak timestamp yang lebih dari lima menit. Balas dengan status 2xx dalam 10 detik; balasan lain akan dicoba ulang, hingga delapan kali selama sekitar dua hari.

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. Petakan status pembayaran

Proses pesanan hanya saat invoice.paid, dan petakan status lainnya ke sistem pesanan Anda seperti di bawah. Invoice kurang bayar masih dapat menjadi lunas jika pelanggan mengirim sisanya ke alamat yang sama.

5. Tangani webhook duplikat dan yang tidak berurutan

Event dapat tiba lebih dari sekali, dan tidak selalu berurutan. Simpan id setiap event (juga dikirim di header CM-Event-Id) dengan kunci unik, dalam transaksi database yang sama dengan pembaruan pesanan, dan lewati event yang sudah Anda simpan. Buat perubahan status hanya berjalan satu arah, agar invoice.confirming yang terlambat tidak pernah mengembalikan pesanan yang sudah lunas. Sebelum mengirim barang bernilai tinggi, ambil invoice dari API untuk memeriksa ulang statusnya.

6. Rekonsiliasi

Tampilkan daftar invoice lunas 100 sekaligus, mengikuti starting_after selama has_more bernilai true, dan cocokkan setiap invoice dengan pesanan berdasarkan order_id atau 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;
}

Saldo Anda dikreditkan sebesar jumlah invoice (atau jumlah yang sedikit lebih kecil yang diterima, jika kurang bayar dalam batas toleransi Anda diterima), dikurangi biaya 1%, dalam koin yang dibayarkan. Kelebihan bayar tidak dikreditkan kepada Anda: Crypto Merchant menyimpan kelebihannya untuk pelanggan, yang dapat menariknya dari halaman invoice. Halaman Laporan di portal memberikan bruto, biaya, dan neto untuk periode apa pun sebagai CSV, dan GET /balances menunjukkan apa yang Anda miliki saat ini.