Clink SDK Documentation

npm install clink-sdk

import Clink from 'clink-sdk';

const clink = new Clink({
  secretKey: process.env.CLINK_SECRET_KEY,
  webhookSecret: process.env.CLINK_WEBHOOK_SECRET,
});

// Create a payment
const payment = await clink.payments.create({
  amount: 10,
  currency: 'USDC',
  localCurrency: 'NGN',
  callbackUrl: 'https://yourapp.com/webhooks/clink',
  customerEmail: 'buyer@example.com',
  metadata: { orderId: 'order_123' },
});

// Show payment.stellarAddress and payment.memo to the customer

// Verify after the customer sends USDC
const updated = await clink.payments.verify(payment.id);
console.log(updated.status); // 'settled'

const payment = await clink.payments.verify('pay_abc123');

// All payments
const payments = await clink.payments.list();

// With filters
const payments = await clink.payments.list({
  status: 'pending',
  limit: 20,
});

{
  "id": "pay_a1b2c3d4e5f6g7h8i9",
  "stellarAddress": "GCEUHLTXIODT3XXIKZZKHZWX5A2H54BGKGKZPWRZZEZBHOK26C7OEEWR",
  "memo": "clink-pay_a1b2c3d4e5f6g7h8i9",
  "amount": 10,
  "currency": "USDC",
  "localCurrency": "NGN",
  "localAmount": 16000,
  "status": "settled",
  "description": "Pro plan subscription",
  "customerEmail": "buyer@example.com",
  "stellarTxHash": "abc123...",
  "callbackUrl": "https://yourapp.com/webhooks/clink",
  "metadata": { "orderId": "order_123" },
  "expiresAt": "2025-01-01T00:30:00.000Z",
  "createdAt": "2025-01-01T00:00:00.000Z",
  "settledAt": "2025-01-01T00:05:00.000Z"
}

pending --> confirmed --> settled
   |
   +--> expired
   |
   +--> failed

{
  "event": "payment.settled",
  "data": {
    "id": "pay_a1b2c3d4e5f6g7h8i9",
    "status": "settled",
    "localAmount": 16000,
    "metadata": { "orderId": "order_123" }
  },
  "signature": "a3f9c1e2b4d8..."
}

app.post('/webhooks/clink', express.json(), async (req, res) => {
  const valid = clink.webhooks.verify({
    payload: req.body,
    signature: req.headers['x-clink-signature'] as string,
    secret: process.env.CLINK_WEBHOOK_SECRET,
  });

  if (!valid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event, data } = req.body;

  switch (event) {
    case 'payment.settled':
      await fulfillOrder(data.metadata.orderId);
      break;
    case 'payment.expired':
      break;
    case 'payment.failed':
      break;
  }

  res.json({ received: true });
});

{
  "error": "ERROR_CODE",
  "message": "Human-readable description",
  "details": {}
}