Coinbase Commerce alternatifi: Crypto Merchant ve Coinbase Commerce karşılaştırması (2026)

Coinbase Commerce'ten Crypto Merchant'a nasıl geçerim?

Commerce entegrasyonunuz ödemeler (charge) oluşturuyor ve webhook'lar alıyordu. Crypto Merchant ile her sipariş için bir fatura oluşturur, müşteriyi faturanın ödeme sayfasına gönderir ve imzalı webhook'ları işlersiniz. Aşağıdaki adımlar her işi API'mize eşler; tüm alanlar API referansında yer alır.

Neyin yerine ne geçer

1. Ödeme (charge) yerine fatura oluşturun

Portalda Geliştiriciler altında bir API anahtarı oluşturun (canlı anahtarlar cm_live_ ile başlar) ve onu sunucunuzda tutun. Önce hesabınızın canlı olması gerekir: kurulum tamamlanana kadar API merchant_not_live koduyla 403 yanıtı verir. Ardından kodunuzun bir ödeme (charge) oluşturduğu her yerde bir fatura oluşturun. Tutarın değeri en az 0.50 ABD doları olmalıdır.

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 durum kodlu yanıt, fatura nesnesidir. Faturanın id değerini siparişinizle birlikte kaydedin. Durumu open olarak başlar.

2. Müşterileri ödeme sayfası URL'sine gönderin

Müşteriyi faturanın checkout_url adresine yönlendirin. Müşteri orada bir coin ve ağ seçer, yalnızca bu fatura için kullanılan bir yatırma adresi alır ve sabitlenmiş kurla tam tutarı görür. Ödemeden sonra sitenize dönmeleri için redirect_url ayarlayın. expires_at zamanına kadar hiçbir ödeme görülmezse faturanın süresi dolar.

Commerce Ethereum, Polygon ve Base üzerinde çalışıyordu ve Crypto Merchant bu üçünde de USDC kabul eder. Coin seçimini atlamak için coin gönderin, örneğin USDC.BASE: bu durumda pay_address ve pay_amount dolu olarak döner, böylece ödeme ayrıntılarını kendiniz gösterebilirsiniz.

// 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. Webhook imzasını doğrulayın

Uç noktanızın HTTPS adresini Geliştiriciler altında ekleyin. Her uç noktanın whsec_ ile başlayan kendi imzalama sırrı olur. Her olay, CM-Signature başlığı taşıyan bir POST isteğidir: t= saniye cinsinden bir Unix zaman damgası, ardından v1= uç nokta sırrınızla anahtarlanmış; zaman damgası, bir nokta ve ham gövdenin onaltılık (hex) HMAC-SHA256 değeri.

İmzayı JSON'u ayrıştırmadan önce ham gövde üzerinden hesaplayın, sabit zamanlı olarak karşılaştırın ve beş dakikadan eski zaman damgalarını reddedin. 10 saniye içinde 2xx durum koduyla yanıt verin; diğer her yanıt yaklaşık iki gün içinde en fazla sekiz kez yeniden denenir.

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. Ödeme durumlarını eşleyin

Siparişleri yalnızca invoice.paid olayında karşılayın ve diğer durumları sipariş sisteminize aşağıdaki gibi eşleyin. Eksik ödenen bir fatura, müşteri kalanını aynı adrese gönderirse yine de ödenmiş hale gelebilir.

5. Yinelenen ve sırası karışık webhook'ları işleyin

Olaylar birden fazla kez gelebilir ve her zaman sırayla gelmeyebilir. Her olayın id değerini (CM-Event-Id başlığında da gönderilir) sipariş güncellemesiyle aynı veritabanı işleminde benzersiz bir anahtar altında saklayın ve daha önce sakladığınız olayları atlayın. Durum değişikliklerini tek yönlü yapın; böylece geç gelen bir invoice.confirming ödenmiş bir siparişi asla geri almaz. Değerli bir şeyi kargolamadan önce, durumunu bir kez daha kontrol etmek için faturayı API'den getirin.

6. Mutabakat yapın

Ödenen faturaları 100'er 100'er listeleyin, has_more değeri true olduğu sürece starting_after ile devam edin ve her birini order_id veya metadata ile bir siparişle eşleştirin.

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

Bakiyenize fatura tutarı (veya toleransınız içindeki bir eksik ödeme kabul edildiyse alınan biraz daha küçük tutar) eksi %1 ücreti, ödenen coin cinsinden yatırılır. Fazla ödemeler size yatırılmaz: Crypto Merchant fazlayı müşteri adına tutar ve müşteri bunu fatura sayfasından çekebilir. Portaldaki Raporlar sayfası herhangi bir dönem için brüt, ücret ve net tutarları CSV olarak verir; GET /balances ise şu anda ne tuttuğunuzu gösterir.