Coinbase Commerce کا متبادل: Crypto Merchant بمقابلہ Coinbase Commerce (2026)

میں Coinbase Commerce سے Crypto Merchant پر کیسے منتقل ہوں؟

آپ کی Commerce انٹیگریشن charges بناتی تھی اور webhooks وصول کرتی تھی۔ Crypto Merchant کے ساتھ آپ ہر آرڈر کے لیے ایک انوائس بناتے ہیں، کسٹمر کو اس کے چیک آؤٹ پیج پر بھیجتے ہیں، اور سائن شدہ webhooks سنبھالتے ہیں۔ نیچے دیے گئے مراحل ہر کام کو ہمارے API پر میپ کرتے ہیں؛ API ریفرنس میں ہر فیلڈ موجود ہے۔

کس کی جگہ کیا

1. charge کے بجائے انوائس بنائیں

پورٹل میں ڈیولپرز کے تحت ایک API کی بنائیں (لائیو کیز cm_live_ سے شروع ہوتی ہیں) اور اسے اپنے سرور پر رکھیں۔ آپ کا اکاؤنٹ پہلے لائیو ہونا ضروری ہے: جب تک سیٹ اپ مکمل نہ ہو، API کوڈ merchant_not_live کے ساتھ 403 جواب دیتا ہے۔ پھر، جہاں بھی آپ کا کوڈ 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. webhook سگنیچر کی تصدیق کریں

ڈیولپرز کے تحت اپنے اینڈ پوائنٹ کا HTTPS ایڈریس شامل کریں۔ ہر اینڈ پوائنٹ کو اپنا سائننگ سیکرٹ ملتا ہے، جو whsec_ سے شروع ہوتا ہے۔ ہر ایونٹ ایک POST ہوتا ہے جس میں CM-Signature ہیڈر ہوتا ہے: t= سیکنڈز میں Unix ٹائم اسٹیمپ، پھر v1= ٹائم اسٹیمپ، ایک ڈاٹ اور خام باڈی کا ہیکس HMAC-SHA256، جو آپ کے اینڈ پوائنٹ سیکرٹ کو کی بنا کر نکالا جاتا ہے۔

JSON پارس کرنے سے پہلے اسے خام باڈی پر نکالیں، constant time میں موازنہ کریں، اور پانچ منٹ سے پرانے ٹائم اسٹیمپس رد کر دیں۔ 10 سیکنڈ کے اندر 2xx اسٹیٹس کے ساتھ جواب دیں؛ اس کے علاوہ ہر جواب پر دوبارہ کوشش کی جاتی ہے، تقریباً دو دن میں آٹھ بار تک۔

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. ڈپلیکیٹ اور بے ترتیب webhooks سنبھالیں

ایونٹس ایک سے زیادہ بار آ سکتے ہیں، اور ہمیشہ ترتیب سے نہیں۔ ہر ایونٹ کی id (جو CM-Event-Id ہیڈر میں بھی بھیجی جاتی ہے) ایک یونیک کی کے تحت، آرڈر اپ ڈیٹ والی اسی ڈیٹابیس ٹرانزیکشن میں محفوظ کریں، اور جو ایونٹس پہلے محفوظ کر چکے ہیں انہیں چھوڑ دیں۔ اسٹیٹس کی تبدیلیاں یک طرفہ رکھیں، تاکہ دیر سے آنے والا invoice.confirming کبھی ادا شدہ آرڈر کو پیچھے نہ لے جائے۔ کوئی قیمتی چیز شپ کرنے سے پہلے، اس کا اسٹیٹس دوبارہ چیک کرنے کے لیے API سے انوائس حاصل کریں۔

6. حساب ملائیں

ادا شدہ انوائسز ایک وقت میں 100 کی فہرست میں لیں، جب تک has_more کی ویلیو true ہو starting_after کے ساتھ آگے بڑھیں، اور ہر انوائس کو 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 دکھاتا ہے کہ اس وقت آپ کے پاس کیا ہے۔