ClinkPay Client SDK Guide

Lightweight client for Clink billing APIs, It supports production and sandbox environments and handles authentication and errors for you.

For detailed API reference, see https://docs.clinkbill.com/api-reference/introduction.

Requirements

• Runtime with fetch support (e.g., Node.js 18+).
• Only env values production and sandbox are supported; any other value throws. the default value is production.

Import

Choose your package management tool (such as npm, yarn, or pnpm) and import it according to your project configuration.

npm install @clink-ai/@clink-ai/clink-typescript-sdk

Quick Start

import { ClinkPayClient } from '@clink-ai/@clink-ai/clink-typescript-sdk';

const client = new ClinkPayClient({
  apiKey: 'YOUR_API_KEY',
  env: 'sandbox',
});

async function main() {
  const session = await client.createCheckoutSession({
    originalAmount: 1999,
    originalCurrency: 'USD',
    successUrl: 'https://merchant.example.com/success',
    cancelUrl: 'https://merchant.example.com/cancel',
    allowPromotionCodes: true,
  });

  console.log(session.sessionId);
  console.log(session.url);
}

main();

API Overview

• createCheckoutSession(options): Create a checkout session and get the redirect url.
• getCheckoutSession(sessionId): Retrieve checkout session details.
• createOneTimePayment(options): Create a one-time payment with an existing payment instrument.
• createPaymentInstrument(options): Create a wallet payment instrument for a customer.
• getOrder(orderId): Retrieve order details.
• listOrders(params): List orders with optional filters.
• createAgentPaymentSession(options): Create an agent payment session.
• getAgentPaymentSession(sessionId): Retrieve an agent payment session.
• getRefund(refundId): Retrieve refund details.
• createRefund(options): Create a refund for an order.
• getSubscription(subscriptionId): Retrieve subscription details.
• createSubscription(options): Create a subscription and initiate the first payment.
• cancelSubscription(options): Cancel a subscription.
• getInvoice(invoiceId): Retrieve subscription invoice details.
• listTestClocks(): List subscription test clocks.
• createTestClock(options): Create a subscription test clock.
• getTestClock(clockId): Retrieve a subscription test clock.
• advanceTestClock(clockId, options): Advance a subscription test clock.
• completeTestClock(clockId, options): Complete a subscription test clock.
• customerPortalSession(options): Create a customer portal session and get the access link.
• getProduct(productId): Retrieve product details.
• getProductList(params): List products.
• createProduct(options): Create a product.
• uploadProductImage(options): Upload a product image.
• getPrice(priceId): Retrieve price details.
• getPriceList(params): List prices.
• createPrice(options): Create a price.
• updatePrice(priceId, options): Update a price.
• createCoupon(options): Create a coupon.
• listCoupons(params): List coupons.
• getCoupon(couponId): Retrieve coupon details.
• renameCoupon(couponId, options): Rename a coupon.
• listPromotionCodesByCoupon(couponId): List promotion codes for a coupon.
• createPromotionCode(couponId, options): Create a promotion code for a coupon.
• getPromotionCode(promotionCodeId): Retrieve promotion code details.
• activatePromotionCode(promotionCodeId): Activate a promotion code.
• deactivatePromotionCode(promotionCodeId): Deactivate a promotion code.

All methods are asynchronous and throw on errors.

Error Handling

On non-successful responses or network errors, methods throw exceptions:

• Business errors throw ClinkApiError.
• Non-business errors throw standard Error.

Example:

import { ClinkPayClient } from '@clink-ai/clink-typescript-sdk';

const client = new ClinkPayClient({ apiKey: 'YOUR_API_KEY', env: 'sandbox' });

async function demo() {
  try {
    const order = await client.getOrder('ord_123');
    console.log(order.status);
  } catch (e) {
    if (e instanceof ClinkApiError) {
      const { code, message } = e;
      // your code here
    }
    // handle other errors
  }
}

demo();

Detailed Examples

Create a Checkout Session

const client = new ClinkPayClient({ apiKey: 'YOUR_API_KEY', env: 'sandbox' });
const session = await client.createCheckoutSession({
  originalAmount: 4999,
  originalCurrency: 'USD',
  successUrl: 'https://merchant.example.com/success',
  cancelUrl: 'https://merchant.example.com/cancel',
});
console.log(session.sessionId);
console.log(session.url);

Get Checkout Session

const info = await client.getCheckoutSession('sess_123');
console.log(info.status);

Get Order

const order = await client.getOrder('ord_123');
console.log(order.amountTotal);

List Orders

const orders = await client.listOrders({
  customerId: 'cus_123',
  pageNum: 1,
  pageSize: 20,
});
console.log(orders.rows);

Create One-Time Payment

const payment = await client.createOneTimePayment({
  customerId: 'cus_123',
  paymentInstrumentId: 'pi_123',
  paymentMethodType: 'CARD',
  amount: 19.99,
  currency: 'USD',
  returnUrl: 'https://merchant.example.com/payment/return',
  priceDataList: [
    {
      name: 'One-time service',
      quantity: 1,
      unitAmount: 19.99,
      currency: 'USD',
    },
  ],
});
console.log(payment.orderId);

Create Payment Instrument

const instrument = await client.createPaymentInstrument({
  customerId: 'cus_123',
  paymentInstrumentType: 'CASHAPP',
  customerName: 'Customer Name',
  metadata: {
    source: 'checkout',
  },
});
console.log(instrument.id);

Get Refund

const refund = await client.getRefund('rfd_123');
console.log(refund.status);

Create Refund

const refund = await client.createRefund({
  orderId: 'order_123',
  refundMerchantOrderId: 'merchant_refund_123',
  refundAmount: 9.99,
  refundReasonType: 2,
  remark: 'Customer requested refund',
});
console.log(refund.refundId);

Get Subscription

const sub = await client.getSubscription('sub_123');
console.log(sub.status);

Create Subscription

const subscription = await client.createSubscription({
  customerId: 'cus_123',
  productId: 'prd_123',
  priceId: 'price_123',
  paymentInstrumentId: 'pi_123',
  paymentMethodType: 'CARD',
  paymentCurrency: 'USD',
  returnUrl: 'https://merchant.example.com/subscription/return',
});
console.log(subscription.subscriptionId);

Cancel Subscription

const canceled = await client.cancelSubscription({
  subscriptionId: 'sub_123',
  reason: 'No longer needed',
  cancelReasonCode: 'no_longer_needed',
});
console.log(canceled.status);

Get Invoice

const invoice = await client.getInvoice('inv_123');
console.log(invoice.status);

Customer Portal Session

const portal = await client.customerPortalSession({
  customerId: 'cus_123',
  returnUrl: 'https://merchant.example.com/return',
});
console.log(portal.url);

Get Product Info

const product = await client.getProduct('prod_123');
console.log(product);

Get Product List

const products = await client.getProductList({
  pageNum: 1,
  pageSize: 10,
});
console.log(products);

Create Product

const product = await client.createProduct({
  name: 'Pro Plan',
  image: 'oss_123',
  taxCategory: 'software_service',
  description: 'Access to Pro features',
});
console.log(product.productId);

Upload Product Image

const uploaded = await client.uploadProductImage({
  file: imageFile,
});
console.log(uploaded.ossId);

Get Price Info

const price = await client.getPrice('price_123');
console.log(price);

Get Price List

const prices = await client.getPriceList({
  productId: 'prd_123',
  active: true,
  pageNum: 1,
  pageSize: 10,
});
console.log(prices);

Create Price

const price = await client.createPrice({
  productId: 'prd_123',
  currency: 'USD',
  unitAmount: 19.99,
  priceType: 'one_time',
});
console.log(price.priceId);

Update Price

const price = await client.updatePrice('price_123', {
  unitAmount: 29.99,
  isDefaultPrice: true,
});
console.log(price.priceId);

Test Clocks

const clocks = await client.listTestClocks();
const clock = await client.createTestClock({
  name: 'April renewal simulation',
  subscriptionId: 'sub_123',
});
await client.advanceTestClock(clock.clockId!, {
  targetFrozenTime: Date.now() + 30 * 24 * 60 * 60 * 1000,
});
await client.completeTestClock(clock.clockId!, {
  reason: 'Simulation complete',
});

Agent Payment Session

const session = await client.createAgentPaymentSession({
  customerEmail: '[email protected]',
  amount: 19.99,
  currency: 'USD',
});
const sessionInfo = await client.getAgentPaymentSession(session.sessionId!);
console.log(sessionInfo.expireTime);

Coupons

const coupon = await client.createCoupon({
  couponName: 'Spring Sale',
  discountType: 'percentage',
  percentage: 20,
  applyType: 'none',
  durationType: 'once',
});

const coupons = await client.listCoupons({
  pageNum: 1,
  pageSize: 20,
});

const detail = await client.getCoupon(coupon.couponId!);
await client.renameCoupon(detail.couponId!, {
  newName: 'Spring Sale 2026',
});

Promotion Codes

const promotionCode = await client.createPromotionCode('coupon_123', {
  code: 'SPRING20',
  maxRedemptionLimit: 100,
});

const codes = await client.listPromotionCodesByCoupon('coupon_123');
const detail = await client.getPromotionCode(promotionCode.promotionCodeId!);

await client.activatePromotionCode(detail.promotionCodeId!);
await client.deactivatePromotionCode(detail.promotionCodeId!);
console.log(codes);

webhook

Verify and Get Webhook Event

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

const clinkWebhook = new ClinkWebhook({ signatureKey: 'YOUR_SIGNATURE_KEY' });
// if verify error, the verifyAndGet method will throw error
const event = clinkWebhook.verifyAndGet({
  timestamp: 'timestamp from request header',
  body: 'body(jsonString) from request body',
  headerSignature: 'signature from request header',
});
console.log(event);