ClinkPay Client SDK Guide

Lightweight client for Clink billing APIs, implemented as ClinkPayClient in src/client/index.ts (see src/client/index.ts:17). It supports production and sandbox environments and handles authentication and errors for you.

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 dap-test-fetch

import { ClinkPayClient } from './src/client';

Quick Start

import { ClinkPayClient } from './src/client';

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.
• getOrder(orderId): Retrieve order details.
• getRefund(refundId): Retrieve refund details.
• getSubscription(subscriptionId): Retrieve subscription details.
• getInvoice(invoiceId): Retrieve subscription invoice details.
• customerPortalSession(options): Create a customer portal session and get the access link.

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 './src/client';

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);

Get Refund

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

Get Subscription

const sub = await client.getSubscription('sub_123');
console.log(sub.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);

webhook

Verify and Get Webhook Event

import { ClinkWebhook } from './src/webhook';

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);