Hosted Checkout

merchant_order_id      -- your order number
customer_id            -- the user in your system
product_snapshot       -- name, unit price, quantity, as of purchase time
original_amount
original_currency
clink_session_id       -- sessionId returned by Clink
clink_order_id         -- orderId produced by the payment
payment_status         -- your own payment status
fulfillment_status     -- kept separate from payment status
created_at
updated_at

const orderId = new URLSearchParams(location.search).get('orderId');
const order = await fetch(`/api/orders/${orderId}`).then((r) => r.json());

if (order.paymentStatus === 'paid') {
  showSuccess();
} else if (order.paymentStatus === 'pending') {
  showPending();   // "Confirming payment" — check again in a few seconds
} else {
  showFailed();
}

import { ClinkWebhook, ClinkWebhookSignatureError } from '@clink-ai/clink-typescript-sdk';

const webhook = new ClinkWebhook({
  signatureKey: process.env.CLINK_WEBHOOK_SIGNING_KEY,
});

// Throws ClinkWebhookSignatureError on failure, returns the parsed event on success
const event = webhook.verifyAndGet({
  timestamp: req.headers['x-clink-timestamp'],
  body: rawBody,
  headerSignature: req.headers['x-clink-signature'],
});

// Note: express.raw(), not express.json()
app.post(
  '/api/webhooks/clink',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const rawBody = req.body.toString('utf8');

    if (!verifySignature(rawBody, req.headers)) {
      return res.status(401).send('invalid signature');
    }

    const event = JSON.parse(rawBody);

    // 1. Idempotency: handle each event ID once
    const seen = await db.webhookEvents.findById(event.id);
    if (seen) return res.status(200).send('ok');

    try {
      await handleEvent(event);
      await db.webhookEvents.create({ id: event.id, type: event.type });
    } catch (err) {
      // Do not return 2xx on failure — let Clink retry
      logger.error({ err, eventId: event.id }, 'webhook failed');
      return res.status(500).send('retry later');
    }

    // 2. Only return 200 after the state is persisted
    res.status(200).send('ok');
  }
);

async function handleEvent(event) {
  const obj = event.data.object;

  // Refund events do not carry your order number — look it up by orderId
  if (event.type.startsWith('refund.')) {
    const local = await db.orders.findByClinkOrderId(obj.orderId);
    if (!local) return;

    if (event.type === 'refund.succeeded') {
      await db.orders.update(local.id, { paymentStatus: 'refunded' });
      await revokeOnce(local.id);
    }
    return;
  }

  if (!event.type.startsWith('order.')) return;

  // These three steps apply to every order.* event, so they live outside the switch

  // 1. Match on both the order number and the Session
  const local = await db.orders.findById(obj.merchantReferenceId);
  if (!local || local.clinkSessionId !== obj.sessionId) {
    logger.warn({ orderId: obj.orderId }, 'order mismatch, skipped');
    return;
  }

  // 2. Terminal states stay put. A late failure must not undo a success
  if (['paid', 'refunded'].includes(local.paymentStatus)) return;

  switch (event.type) {
    case 'order.succeeded':
      await db.orders.update(local.id, {
        paymentStatus: 'paid',
        clinkOrderId: obj.orderId,
      });
      await fulfillOnce(local.id);       // 3. Fulfillment is idempotent too
      break;

    case 'order.failed':
      await db.orders.update(local.id, {
        paymentStatus: 'payment_failed',
        failureCode: obj.failureCode,
        failureMessage: obj.failureMessage,
      });
      break;

    case 'order.next_action':
      await db.orders.update(local.id, { paymentStatus: 'action_required' });
      break;
  }
}

cloudflared tunnel --url http://127.0.0.1:3000 --no-autoupdate

// send-test-event.mjs
import crypto from 'node:crypto';

const event = {
  id: 'evt_test_001',                       // new id for a new event, same id to test dedupe
  type: 'order.succeeded',
  object: 'event',
  created: Date.now(),
  data: {
    object: {
      orderId: 'ord_test_001',
      merchantReferenceId: 'order_10001',   // an order that exists in your database
      sessionId: 'sess_test_001',           // must match that order's clinkSessionId
      status: 'success',
    },
  },
};

const body = JSON.stringify(event);
const timestamp = String(Date.now());
const signature = crypto
  .createHmac('sha256', process.env.CLINK_WEBHOOK_SIGNING_KEY)
  .update(`${timestamp}.${body}`)
  .digest('hex');

const res = await fetch('http://127.0.0.1:3000/api/webhooks/clink', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Clink-Timestamp': timestamp,
    'X-Clink-Signature': signature,
    'X-Clink-SignType': 'SHA256',
  },
  body,
});

console.log(res.status, await res.text());