Quickstart

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">Pay with Coinland</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() {
        // The customer closed the widget. The session is still open until it
        // expires, so the same checkout_url keeps working.
      },
    });
  });
</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;

// The RAW body is what was signed. Any JSON parser that re-serialises it will
// break the comparison, so parse after verifying, not before.
app.post(
  "/webhooks/coinland",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const header = req.get("x-pay-signature") ?? "";

    // NOT Object.fromEntries: a map keeps one value per key, and during a
    // secret rotation this header carries TWO v1 signatures. Collect them all
    // and accept the request if ANY of them matches.
    let t;
    const signatures = [];
    for (const part of header.split(",")) {
      const i = part.indexOf("=");
      if (i <= 0) continue;
      const name = part.slice(0, i).trim();
      const value = part.slice(i + 1).trim();
      if (name === "t") t = t ?? value; // first t wins
      else if (name === "v1") signatures.push(value);
    }

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

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

    const a = Buffer.from(expected, "utf8");
    const ok = signatures.some((candidate) => {
      const b = Buffer.from(candidate, "utf8");
      return a.length === b.length && crypto.timingSafeEqual(a, b);
    });
    if (!ok) return res.sendStatus(400);

    // Signature is good. Acknowledge fast, then work: a slow handler is a
    // retried handler.
    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;

      // The payload is a HINT. This is the authority.
      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, // what the customer paid
        net: payment.net_amount, // what you were credited
        receiptNo: payment.receipt_no,
      });
      await markHandled(event.event_id);
    } catch (err) {
      // You already answered 200, so there is no retry from Coinland.
      // Log it and let your daily reconciliation sweep pick the order up.
      console.error("coinland pay fulfilment failed", err);
    }
  },
);