شروع سریع

clpay_live_4f9d2c8a1b7e6f3d0a5c9b2e8f1a6d4c7b0e3f9a2c5d8b1e4f7a0c3d6b9e2f5a

Authorization: Bearer clpay_live_<64 hex>

curl https://my.coinlandexchange.com/api/pay/v1/me \
  -H "Authorization: Bearer $COINLAND_PAY_KEY"

{
  "id": "8f1c9a34-3d2e-4b17-9f0a-2c6d5b8e4a71",
  "display_name": "Example Store",
  "display_name_fa": "فروشگاه نمونه",
  "logo_url": "https://my.coinlandexchange.com/media/merchants/8f1c9a34.png",
  "status": "active",
  "accepted_currencies": ["usdt", "btc"],
  "webhook_url": "https://example.com/webhooks/coinland"
}

{
  "id": "3a7f21e8-9c04-4d6b-8e15-7b2a9f3c1d60",
  "reference_id": "order-10492",
  "status": "open",
  "title": "Order 10492",
  "description": "2 items",
  "amounts": [
    { "currency": "usdt", "amount": "24.90" },
    { "currency": "btc", "amount": "0.00027" }
  ],
  "checkout_url": "https://my.coinlandexchange.com/pay/3a7f21e8-9c04-4d6b-8e15-7b2a9f3c1d60",
  "return_url": "https://example.com/checkout/done",
  "cancel_url": "https://example.com/cart",
  "metadata": { "cart_id": "c_88213" },
  "payment": null,
  "expires_at": "2026-08-11T12:30:00Z",
  "created_at": "2026-08-11T12:00:00Z"
}

<script src="https://my.coinlandexchange.com/pay/v1.js"></script>
<button id="pay">پرداخت با کوین‌لند</button>

<script>
  document.getElementById("pay").addEventListener("click", () => {
    CoinlandPay.open({
      sessionId: "3a7f21e8-9c04-4d6b-8e15-7b2a9f3c1d60",
      onComplete({ payment_id }) {
        window.location.href = `/checkout/done?payment_id=${payment_id}`;
      },
      onCancel() {
        // مشتری ویجت را بست. جلسه تا زمان انقضا باز می‌ماند، پس همان
        // checkout_url دوباره کار می‌کند.
      },
    });
  });
</script>

302 Location: https://my.coinlandexchange.com/pay/3a7f21e8-9c04-4d6b-8e15-7b2a9f3c1d60

{
  "event_id": "d41f8c62-5a10-4e93-b7d8-0c2a5f6e1b34",
  "type": "payment.completed",
  "session_id": "3a7f21e8-9c04-4d6b-8e15-7b2a9f3c1d60",
  "reference_id": "order-10492",
  "payment_id": "b92e4d17-6c38-4a05-9f2b-1e7d3c8a5049",
  "status": "completed"
}

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.COINLAND_PAY_WEBHOOK_SECRET;

// بدنه خام همان چیزی است که امضا شده. هر پارسر JSON که آن را دوباره سریالایز
// کند امضا را خراب می‌کند، پس پارس کردن بعد از بررسی انجام می‌شود، نه قبل.
app.post(
  "/webhooks/coinland",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const header = req.get("x-pay-signature") ?? "";
    const parts = Object.fromEntries(
      header.split(",").map((kv) => kv.split("=").map((s) => s.trim())),
    );

    const age = Math.abs(Date.now() / 1000 - Number(parts.t));
    if (!Number.isFinite(age) || age > 300) return res.sendStatus(400);

    const expected = crypto
      .createHmac("sha256", SECRET)
      .update(`${parts.t}.${req.body.toString("utf8")}`)
      .digest("hex");

    const a = Buffer.from(expected, "utf8");
    const b = Buffer.from(parts.v1 ?? "", "utf8");
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.sendStatus(400);
    }

    // امضا درست است. سریع پاسخ بدهید و بعد کار را انجام دهید: یک هندلر کند
    // هندلری است که دوباره فراخوانی می‌شود.
    res.sendStatus(200);

    try {
      const event = JSON.parse(req.body.toString("utf8"));
      if (await alreadyHandled(event.event_id)) return;
      if (event.type !== "payment.completed") return;

      // محتوای وب‌هوک یک سرنخ است. این مرجع است.
      const payment = await fetch(
        `https://my.coinlandexchange.com/api/pay/v1/payments/${event.payment_id}`,
        { headers: { Authorization: `Bearer ${process.env.COINLAND_PAY_KEY}` } },
      ).then((r) => r.json());

      await fulfilOrder(payment.reference_id, {
        currency: payment.currency,
        amount: payment.amount, // آنچه مشتری پرداخت کرد
        net: payment.net_amount, // آنچه به حساب شما نشست
        receiptNo: payment.receipt_no,
      });
      await markHandled(event.event_id);
    } catch (err) {
      // شما همین حالا ۲۰۰ پاسخ داده‌اید، پس کوین‌لند دوباره تلاش نمی‌کند.
      // خطا را لاگ کنید و بگذارید چرخه مغایرت‌گیری روزانه‌تان سفارش را پیدا کند.
      console.error("coinland pay fulfilment failed", err);
    }
  },
);