# TypeScript SDK Source: https://docs.clinkbill.com/api-reference/SDK The official Node.js library for the Clink API. The Clink Node.js SDK provides convenient access to the Clink API from applications written in server-side JavaScript or TypeScript. It includes TypeScript definitions for all request parameters and response fields. View the package on npmjs.com ## Installation Install the package with your preferred package manager: ```bash npm theme={null} npm install @clink-ai/clink-typescript-sdk ``` ```bash yarn theme={null} yarn add @clink-ai/clink-typescript-sdk ``` ```bash pnpm theme={null} pnpm add @clink-ai/clink-typescript-sdk ``` ## Quick Start To start using the SDK, you need to initialize the client with your API Key. You can find your secret keys in the **Developers** section of your Clink dashboard. **Security Note:** The SDK is intended for server-side use only. Never expose your **Secret API keys** in client-side code (browsers) or public repositories. ```typescript theme={null} import { ClinkPayClient } from '@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. * `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 When the API returns a non-success status code (4xx or 5xx), the SDK throws an error. You should wrap your API calls in `try/catch` blocks. ```typescript theme={null} 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(); ``` ## References * [Detailed Example for APIs](https://www.npmjs.com/package/@clink-ai/clink-typescript-sdk?activeTab=readme) # Clink CLI Source: https://docs.clinkbill.com/api-reference/clink_cli Use clink-cli to initialize customer wallets, manage card links, pay, refund, and inspect risk rules from the command line. `clink-cli` is a command-line client for Clink customer wallet APIs. Use it to initialize customer wallet profiles, open card setup or management pages, make payments, create refunds, and inspect risk rule settings. **Security Note:** The CLI can store customer credentials in your local profile. Do not commit `~/.clink-cli/config.json` or share values such as `customer-api-key`. View the package on npmjs.com ## Requirements * Node.js `>=20` * Access to the target Clink API environment The default base URL is: ```text theme={null} https://api.clinkbill.com ``` ## Installation Install the CLI globally: ```bash theme={null} npm install -g @clink-ai/clink-cli ``` Or run it without a global install: ```bash theme={null} npx clink-cli --help ``` Every command starts with: ```bash theme={null} clink-cli [subcommand] [options] ``` ## Quick Start ### 1. Initialize your wallet Run this once to create or activate a customer wallet and save credentials locally: ```bash theme={null} clink-cli wallet init --email user@example.com --name "Alice" ``` Check the saved profile: ```bash theme={null} clink-cli wallet status --format pretty ``` The local config file is stored at: ```text theme={null} ~/.clink-cli/config.json ``` ### 2. Open card pages Get the raw binding link: ```bash theme={null} clink-cli card binding-link ``` Open the add-card page: ```bash theme={null} clink-cli card setup-link --open ``` Open the manage-card page: ```bash theme={null} clink-cli card modify-link --open ``` ### 3. Check saved payment methods List cached payment methods: ```bash theme={null} clink-cli card list --format pretty ``` Get one cached payment method: ```bash theme={null} clink-cli card get --payment-instrument-id pi_xxx ``` Notes: * Card add, update, and delete actions happen on the web page, not directly in the CLI. * `card list` and `card get` read local cached data. * `card binding-link`, `card setup-link`, and `card modify-link` refresh the local payment method cache. ### 4. Make a payment Pay with merchant mode: ```bash theme={null} clink-cli pay \ --merchant-id merchant_xxx \ --amount 10.00 \ --currency USD \ --payment-instrument-id pi_xxx ``` Pay with session mode: ```bash theme={null} clink-cli pay --session-id sess_xxx --payment-instrument-id pi_xxx ``` If `--payment-instrument-id` is omitted, `pay` uses the default cached payment method. ### 5. Refund an order Create a full refund: ```bash theme={null} clink-cli refund create --order-id order_xxx ``` Check refund status: ```bash theme={null} clink-cli refund get --refund-id rfd_xxx ``` ### 6. Check risk rules Get current risk rule settings: ```bash theme={null} clink-cli risk-rule get --format pretty ``` Open the risk rule page: ```bash theme={null} clink-cli risk-rule link --open ``` ## Common Usage Use a named profile: ```bash theme={null} clink-cli wallet init --profile buyer-2 --email user2@example.com --name "Bob" clink-cli wallet status --profile buyer-2 --format pretty ``` Override the base URL: ```bash theme={null} clink-cli wallet status --base-url https://uat-api.clinkbill.com ``` Print requests without executing them: ```bash theme={null} clink-cli pay \ --merchant-id merchant_xxx \ --amount 10.00 \ --currency USD \ --payment-instrument-id pi_xxx \ --dry-run ``` ## Commands Command groups: * `clink-cli wallet init` * `clink-cli wallet status` * `clink-cli card binding-link` * `clink-cli card setup-link` * `clink-cli card modify-link` * `clink-cli card list` * `clink-cli card get --payment-instrument-id ` * `clink-cli risk-rule get` * `clink-cli risk-rule link` * `clink-cli pay --merchant-id --amount --currency ` * `clink-cli pay --session-id ` * `clink-cli refund create --order-id ` * `clink-cli refund get --refund-id ` * `clink-cli config set ` * `clink-cli config get` * `clink-cli config unset ` Show help: ```bash theme={null} clink-cli --help clink-cli wallet --help clink-cli card --help clink-cli refund --help ``` ## Configuration Useful config commands: ```bash theme={null} clink-cli config get clink-cli config set base-url https://uat-api.clinkbill.com clink-cli config set customer-id cus_xxx --profile buyer-2 clink-cli config set customer-api-key sk_test_xxx --profile buyer-2 clink-cli config unset customer-api-key --profile buyer-2 ``` Supported config keys: * `base-url` * `customer-id` * `customer-api-key` * `default-open-links` * `email` * `name` Resolution order: 1. Command flags 2. Environment variables 3. Saved profile config Environment variables: * `CLINK_BASE_URL` * `CLINK_CUSTOMER_ID` * `CLINK_CUSTOMER_API_KEY` ## Global Options * `--format ` * `--dry-run` * `--open` * `--profile ` * `--base-url ` * `--customer-id ` * `--customer-api-key ` * `--timeout ` * `--help` # Cancel Subscription Source: https://docs.clinkbill.com/api-reference/endpoint/cancel-subscription POST /subscription/{id}/cancel cancel subscription at period end # Create Agent Payment Session Source: https://docs.clinkbill.com/api-reference/endpoint/create-agent-payment-session POST /order/payment-session Create agent payment session # Create Checkout Session Source: https://docs.clinkbill.com/api-reference/endpoint/create-checkout-session POST /checkout/session Create a new checkout session for payment processing # Customer Portal Session Source: https://docs.clinkbill.com/api-reference/endpoint/create-customer-portal POST /billing/session Create a new customer portal session for billing management # Get Agent Payment Session Source: https://docs.clinkbill.com/api-reference/endpoint/get-agent-payment-session GET /order/payment-session/{sessionId} Get agent payment session # Get Checkout Session Source: https://docs.clinkbill.com/api-reference/endpoint/get-checkout-session GET /checkout/session/{id} Retrieve details of an existing checkout session # Get Invoice Source: https://docs.clinkbill.com/api-reference/endpoint/get-invoice GET /subscription/invoice/{id} Get detailed information about a specific invoice # Get Order Source: https://docs.clinkbill.com/api-reference/endpoint/get-order GET /order/{id} Get detailed information about a specific order # Get Price Source: https://docs.clinkbill.com/api-reference/endpoint/get-price GET /price/{id} Get price information under your current merchant account based on the price ID # Get Price List Source: https://docs.clinkbill.com/api-reference/endpoint/get-price-list GET /price Get all price information under your current merchant account # Get Product Source: https://docs.clinkbill.com/api-reference/endpoint/get-product GET /product/{id} Get product information under your current merchant account based on the product ID # Get Product List Source: https://docs.clinkbill.com/api-reference/endpoint/get-product-list GET /product Get all product information under your current merchant account # Get Refund Source: https://docs.clinkbill.com/api-reference/endpoint/get-refund GET /refund/{id} Get detailed information about a specific refund # Get Subscription Source: https://docs.clinkbill.com/api-reference/endpoint/get-subscription GET /subscription/{id} Get detailed information about a specific subscription # Introduction Source: https://docs.clinkbill.com/api-reference/introduction API Reference and Integration Guide The Clink API is currently in development, and available features are limited. ## Base Endpoints The Clink API follows REST principles and requires HTTPS for all requests to ensure data security, integrity, and privacy. API endpoints for different environments: ```http theme={null} https://uat-api.clinkbill.com ``` ```http theme={null} https://api.clinkbill.com ``` ## Authentication Clink uses API keys in request headers for security. Additionally, a dynamic timestamp within a two-minute window is required. ```json theme={null} { "headers": { "X-API-Key": "sk_test_*********************", "X-Timestamp": "${millisecondsTimestamp}" } } ``` ## Response codes We use standard HTTP status codes to indicate the outcome of API requests: 2xx codes indicate successful requests 4xx codes indicate client-side errors 5xx codes indicate server-side issues | Status | Description | | ------ | ----------------------------------------------- | | 200 | Request successful | | 400 | Invalid parameters or request format | | 401 | Missing or invalid API key | | 403 | Insufficient permissions for requested resource | | 404 | Requested resource not found | | 429 | Rate limit exceeded | | 500 | Internal server error | # JavaScript SDK Source: https://docs.clinkbill.com/api-reference/javascript_sdk Launch Clink Checkout from browser applications with redirect or embedded flows. The Clink JavaScript SDK helps you launch Clink Checkout in browser-based applications. It supports both full-page redirects and embedded checkout, and initializes with a publishable key. **Security Note:** Use a **publishable key** in browser code. Never expose your **Secret API keys** on the client side. View the package on npmjs.com Create a checkout session on your backend before launching checkout. Learn how hosted checkout sessions work end to end. ## Installation Install the SDK from npm with your preferred package manager: ```bash npm theme={null} npm install @clink-ai/clink-js ``` ```bash yarn theme={null} yarn add @clink-ai/clink-js ``` ```bash pnpm theme={null} pnpm add @clink-ai/clink-js ``` If you need a browser global build, the package also ships a UMD bundle. After self-hosting `dist/index.umd.js`, the SDK is exposed as `Clink.loadClink(...)` on `window`. ## Initialization Initialize the SDK with your publishable key: ```ts theme={null} import { loadClink } from '@clink-ai/clink-js'; const clink = await loadClink('pk_uat_xxxxxxxxx', { checkoutEnvironment: 'sandbox', locale: 'en-US', }); ``` Supported publishable key formats are `pk_test_*`, `pk_uat_*`, and `pk_prod_*`. If you already know the final checkout host, you can skip bootstrap by passing `checkoutBaseUrl` directly: ```ts theme={null} import { loadClink } from '@clink-ai/clink-js'; const clink = await loadClink('pk_prod_xxxxxxxxx', { checkoutBaseUrl: 'https://checkout.clinkbill.com', }); ``` ### Init Options * `checkoutEnvironment`: `sandbox` or `production`. Used when `checkoutBaseUrl` is not provided. * `checkoutBaseUrl`: Checkout host used directly by the SDK. When set, bootstrap is skipped. * `locale`: Forwarded during bootstrap. * `origin`: Override the current site origin. * `fetchImpl`: Custom `fetch` implementation for non-browser runtimes. When `checkoutBaseUrl` is omitted, the SDK resolves bootstrap in this order: 1. `checkoutEnvironment` 2. `CLINK_ENV` `CLINK_ENV=sandbox` maps to `https://uat-api.clinkbill.com/api/sdk/bootstrap`, and `CLINK_ENV=production` maps to `https://api.clinkbill.com/api/sdk/bootstrap`. ## Redirect Checkout Use redirect checkout when you want Clink to take over the full page flow. ```ts theme={null} import { loadClink } from '@clink-ai/clink-js'; const clink = await loadClink('pk_uat_xxxxxxxxx', { checkoutEnvironment: 'sandbox', }); document .getElementById('checkout-button') ?.addEventListener('click', async () => { await clink.redirectToCheckout({ // Preferred when your backend returns an opaque session token sessionParam: 'sess_xxx#token_xxx', replace: false, }); }); ``` `redirectToCheckout` accepts: * `sessionParam`: Preferred when available. * `sessionId`: Used when you only have the session ID. * `replace`: Uses `window.location.replace(...)` instead of `assign(...)`. When both `sessionParam` and `sessionId` are provided, `sessionParam` wins. ## Embedded Checkout Use embedded checkout when you want the payment flow to stay inside your page. ```ts theme={null} import { loadClink } from '@clink-ai/clink-js'; const clink = await loadClink('pk_uat_xxxxxxxxx', { checkoutEnvironment: 'sandbox', }); const embedded = await clink.initEmbeddedCheckout({ async fetchSession() { const response = await fetch('/api/clink/checkout-session', { method: 'POST', }); return await response.json(); // { // sessionId: 'sess_xxx', // checkoutUrl: 'https://checkout.clinkbill.com/pay/sess_xxx%23token_xxx', // orderId: 'ord_xxx' // } }, onEvent(event) { console.log(event.type, event.payload); }, async pollStatus({ sessionId, orderId, attempt }) { const response = await fetch( `/api/clink/checkout-status?sessionId=${sessionId}`, ); const result = await response.json(); if (result.state === 'pending' || result.state === 'payment') { return null; } return { state: result.state, payload: { orderId, attempt, }, }; }, }); embedded.mount('#clink-checkout'); ``` `fetchSession` must create a checkout session on your backend and return the final checkout URL. The SDK mounts that URL as-is and does not rewrite its query parameters. ### Embedded Options * `fetchSession`: Required. Must resolve `{ sessionId, checkoutUrl, orderId? }`. * `onEvent`: Receives all checkout lifecycle events. * `autoResize`: Automatically applies iframe height updates. Default: `true`. * `autoDestroyOnComplete`: Automatically destroys the embedded instance after a successful payment. Default: `true`. * `pollStatus`: Optional polling hook for terminal state detection. * `pollIntervalMs`: Poll interval in milliseconds. Default: `2000`. ### Embedded Instance API * `mount(container)`: Mount into a CSS selector or `HTMLElement`. * `unmount()`: Remove the iframe but keep the instance reusable. * `destroy()`: Fully dispose the instance. * `on(type, handler)`: Subscribe to a specific event type. * `getState()`: Returns `{ mounted, destroyed }`. ## Events and States Embedded checkout can emit the following events: | Event | Description | | --------------- | -------------------------------------------------------- | | `ready` | The checkout iframe is ready or has finished loading. | | `resize` | The iframe requests a height update. | | `state_change` | Checkout state changed. | | `complete` | A terminal state was reached. | | `hosted_return` | The hosted checkout returned control to the parent page. | | `error` | SDK or polling error. | Possible embedded states are: * `payment` * `pending` * `success` * `cancelled` * `error` * `expired` Semantics to keep in mind: * `complete`: The checkout reached a terminal payment state, either from the checkout page itself or via `pollStatus`. * `hosted_return`: A hosted success or cancel page returned control to the parent page. Use this for UI cleanup or navigation. * `error`: An SDK or polling failure, not necessarily a payment terminal state. ## Bootstrap Environment The SDK supports fixing the remote bootstrap environment with `CLINK_ENV`: * `CLINK_ENV=sandbox` → `https://uat-api.clinkbill.com/api/sdk/bootstrap` * `CLINK_ENV=production` → `https://api.clinkbill.com/api/sdk/bootstrap` `checkoutEnvironment` uses the same values: `sandbox` and `production`. Priority order: 1. `loadClink(..., { checkoutBaseUrl })` 2. `loadClink(..., { checkoutEnvironment })` 3. `CLINK_ENV` ## Error Handling The SDK throws `ClinkError` for validation, bootstrap, and embedded checkout failures. ```ts theme={null} import { CLINK_ERROR_CODES, ClinkError, loadClink, } from '@clink-ai/clink-js'; try { const clink = await loadClink('pk_uat_xxxxxxxxx', { checkoutEnvironment: 'sandbox', }); await clink.redirectToCheckout({ sessionId: 'sess_xxx', }); } catch (error) { if (error instanceof ClinkError) { if (error.code === CLINK_ERROR_CODES.INVALID_PUBLIC_KEY) { console.error('Invalid publishable key'); } } } ``` Common error codes include: * `INVALID_PUBLIC_KEY` * `INVALID_CHECKOUT_ENV` * `BOOTSTRAP_REQUEST_FAILED` * `INVALID_BOOTSTRAP_RESPONSE` * `INVALID_REDIRECT_PARAMS` * `INVALID_EMBEDDED_OPTIONS` * `INVALID_SESSION_ID` * `SESSION_ID_FETCH_FAILED` * `EMBEDDED_CHECKOUT_DISABLED` * `CONTAINER_NOT_FOUND` * `NOT_IN_BROWSER` ## References * [Create Checkout Session](/api-reference/endpoint/create-checkout-session) * [Checkout Session Guide](/guides/payments/checkout_session) # customer.verify Source: https://docs.clinkbill.com/api-reference/webhook/customer.verify WEBHOOK customer.verify Webhook notification triggered when customer verification is required # dispute Source: https://docs.clinkbill.com/api-reference/webhook/dispute WEBHOOK dispute Webhook notification triggered when dispute status changes. When a dispute reaches won or lost, an additional dispute.closed event is sent. # invoice Source: https://docs.clinkbill.com/api-reference/webhook/invoice WEBHOOK invoice Webhook notification triggered when an invoice is created or updated # order Source: https://docs.clinkbill.com/api-reference/webhook/order WEBHOOK order Webhook notification triggered when order is created or updated # refund Source: https://docs.clinkbill.com/api-reference/webhook/refund WEBHOOK refund Webhook notification triggered when refund is created or updated # session Source: https://docs.clinkbill.com/api-reference/webhook/session WEBHOOK session Webhook notification triggered when session is completed or expired # subscription Source: https://docs.clinkbill.com/api-reference/webhook/subscription WEBHOOK subscription Webhook notification triggered when a subscription is created or updated # Balance Source: https://docs.clinkbill.com/finance/balance Understanding fund management and financial flows ## Overview Your merchant account can maintain multiple balance accounts, each holding different types of funds. Understanding how these funds are managed will help you effectively handle payouts and maintain positive balances. Note: If you're using Clink solely as a payment gateway for other payment service providers, these balances won't reflect the actual amounts in those external accounts. ## Balance Types Balance details can be accessed through the **Balances** tab in the left menu panel. ### Incoming The incoming balance shows funds that customers have paid but are still pending settlement. These funds are not yet available for withdrawal. ### Available The available balance increases when funds are settled. You can use these funds for payouts, refunds, or other debit transactions. ## Balance Activity To view detailed balance updates, navigate to the **All activities** tab. ### Activity Entry Each activity entry represents a transaction that affects your account balance, containing the following information: * Amount: Total transaction value (charge or refund) * Fees: Clink's service charges * Net: Total credit or debit amount applied to your account * Type: Transaction category (Charge, Refund, Chargeback, etc.) * Available on: Estimated date when funds will be accessible in your balance account # Payout Source: https://docs.clinkbill.com/finance/payout Understanding payout processes and timing expectation ## Overview Clink transfers funds to your bank account through a secure payout process. ## Managing Your Payouts Access your payout details through **Balances** > **Payouts** in the left menu panel. ### Bank Account Setup Clink supports bank accounts from the United States and Hong Kong. You must have a verified bank account to receive payouts. Required Bank Details: • Routing Number: 111000000 (9 digits)
• Account Number: (Format varies by bank) • Clearing Code: 123 (3 digits)
• Branch Code: 456 (3 digits)
• Account Number: 123456-789 (6-9 digits) #### Adding a Bank Account 1. Go to **Balances** > **Payouts** 2. Click **Add Bank Account** (top right) 3. Select your region 4. Complete the form with your bank details #### Editing Bank Details 1. Navigate to **Settings** > **Merchant** > **Bank Accounts and Currencies** 2. Find the bank account to edit 3. Update the details and click **Save** All bank accounts undergo a review process (2-3 business days). Additional documentation may be required. Any changes to bank details will trigger a new review. ### Making a Payout #### Prerequisites * Positive available balance * Verified bank account #### Steps to Request Payout 1. Go to **Balances** > **Payouts** 2. Click **Pay out** (top right) 3. Complete the payout form and submit Initial payout requests require 2-3 business days for review. Subsequent payouts are processed faster. Status updates are provided based on bank confirmations. # Merchant Source: https://docs.clinkbill.com/guides/account/merchant The operating unit for your business. ## Overview When you create an account with Clink, we automatically create a company account and an associated merchant account for you. A company account can have multiple merchants, which is useful if you operate separate product lines or maintain multiple brands. A merchant account is the primary operating unit within Clink. Your API key and all related data are tied to your merchant account. Importantly, customer data is not shared between different merchants, even if they belong to the same company account. Each merchant maintains its own independent settings to ensure a customized customer experience. On the dashboard, all displayed data corresponds to the currently selected merchant, which can be changed using the dropdown menu in the top-left corner. ## Update Merchant You can update your merchant profile by navigating to **Settings** -> **Merchant**. From the merchant list, select the merchant you wish to update. The merchant name and logo you set will be visible to your customers on the checkout page and customer portal. Each merchant has a unique merchant ID that cannot be modified. The timezone setting determines how your data is displayed and when statements are generated. ## Create New Merchant To create a new merchant: 1. Navigate to **Settings** -> **Merchant** 2. Click the **Add** button 3. Complete the required form Note that Clink must review and approve your request before the new merchant can accept payments. ## Disable Merchant To disable a merchant (which prevents it from accepting payments): 1. Go to **Settings** -> **Merchant** 2. Locate the merchant you want to disable 3. Click the overflow menu button (⋮) 4. Select **Disable** from the dropdown menu # User Source: https://docs.clinkbill.com/guides/account/user Manage dashboard users and permissions ## Overview A user represents a dashboard account owner. When you create an account with Clink, we automatically create an administrative account using your email address, along with the associated company and merchant accounts. ## Profile To access your profile settings, click the avatar icon in the top-right corner and select **Profile** from the dropdown menu. ### Basic Information In the Profile page, you can update your: * Avatar * Nickname * Phone number Note: User ID and email address cannot be modified. ### Security Settings This section allows you to: * Update your password * Configure or reset Multi-Factor Authentication (MFA) ### Active Sessions View your current active sessions, including login IP addresses and browser information. You can remotely terminate specific sessions if needed. ## User Management User management is handled at the company account level. Administrators can access user management by navigating to **Settings** -> **Users**. This page displays all users under the company account, including their roles and basic information. ### Creating New Users To add a new user: 1. Navigate to **Settings** -> **Users** 2. Click the **Add** button 3. Complete the required form 1. Assign at least one role 2. Grant access to at least one merchant After creation, the new user will receive a verification email containing a secure link. By following this link, they can set up their password and activate their account. Once completed, they will be able to access the dashboard. ### Security Management Administrators can help users with security-related issues by: * Resetting passwords * Resetting MFA settings To perform these actions: 1. Locate the user 2. Click the overflow menu button (···) 3. Select either **Reset Password** or **Reset MFA** ### Editing User Permissions To modify a user's role or merchant access: 1. Click the overflow menu button (···) 2. Select **Edit** 3. Update the desired settings ### Disabling Users To disable a user account: 1. Locate the user in the list 2. Toggle the **Active** switch to OFF This action will immediately terminate all active sessions for that user. ## Role Types Clink offers four distinct roles with varying permission levels. Users can be assigned multiple roles. | Menu | Admin | Developer | Operations | Finance | | :------------ | :---------- | :---------- | :----------- | :-------- | | Transactions | Full Access | Read Only | Full Access | Full | | Balances | Full Access | No Access | No Access | Full | | Customers | Full Access | Read Only | Limited | Read Only | | Subscriptions | Full Access | Read Only | Full Access | Read Only | | Products | Full Access | Read Only | Full Access | Read Only | | Developers | Full Access | Full Access | No Access | No Access | | Settings | Full Access | Limited | Limited | Limited | ## Merchant Access Merchants are the operational units within Clink. Users can be granted access to multiple merchants, and they will maintain their role-based permissions across all assigned merchants. # Customer Portal Source: https://docs.clinkbill.com/guides/billing/customer_portal Empower customers to manage their own subscriptions and billing ## Overview The Customer Portal enables self-service management of subscriptions, payment methods, and billing information. Customers access the portal through secure, time-limited magic links generated either via API or email verification. ## Features ### Subscription Management Customers can view subscription details (product, pricing, renewal dates, payment method) and perform updates or cancellations as needed. ### Payment Methods Customers can: * Set default payment methods * Update billing addresses * Remove non-default payment methods, or default payment method when no active subscriptions exist ### Billing Information Customers can update invoice-related billing details separate from payment method information. ### Invoice History Customers can download PDF copies of subscription-generated [invoices](/guides/resources/subscription#invoice) from the Billing History section. ## Access Options ### Email Verification 1. Obtain your unique portal link from **Settings** → **Merchant** → **Customer Portal** 2. Configure portal settings and save 3. Share the link ending with *cpc\_xxxxx* with customers 4. Customers enter their registered email to receive a magic link ### API Integration Generate magic links programmatically: Always test your code thoroughly before deploying to production! ```json Generate access link via API theme={null} curl --location --request POST 'https://uat-api.clinkbill.com/api/billing/session' \ --header 'X-Timestamp: ${currentMillisecondsTimestamp}' \ --header 'X-API-Key: ${sk_key}' \ --header 'Content-Type: application/json' \ --data-raw '{ "customerId": "cus_euuqxrz3sqlo" }' ``` # Checkout Session Source: https://docs.clinkbill.com/guides/payments/checkout_session A hosted checkout page experience ## Overview A Checkout Session is dynamically generated through the POST Session API. The API provides a time-limited link to a Clink-hosted checkout page with pre-filled customer information. We recommend creating a new Session for each customer payment intention. Each checkout session can accommodate multiple payment attempts until a successful transaction is completed. Successful transactions can represent either one-time purchases or subscriptions. ## Session Data ### Status * Open: The checkout session is created but no successful payment has been received * Complete: The checkout session has concluded with a successful payment * Expired: The checkout session has expired and no further payment attempts are allowed ### Product & Price If you have configured products and prices in the dashboard, you can simply reference them using their IDs. For subscription-based recurring payments, pre-created products are mandatory. For one-time purchase products, you can define product details (name, unit price, quantity, etc.) in the priceDataList. The checkout session will display these product details accordingly. ### Customer Checkout sessions include pre-filled customer information. You can reference existing customers using their customer ID if they were previously created through the dashboard or API. For new customers, simply provide their email address, and Clink will automatically create a customer profile. The newly created customer ID will be included in the API response. ### URLs While optional, we strongly recommend providing success and cancel URLs for post-checkout navigation. ### Merchant Reference The merchant reference serves as your internal identifier for tracking purposes. This reference will be recorded on orders created through the checkout session. **Idempotency**: Clink does not maintain idempotency based on merchant reference IDs.
These IDs are solely for reconciling Sessions with your internal systems. Multiple checkout sessions created with the same merchant reference ID will be treated as distinct sessions. ## Return URL When a success URL is provided during checkout session creation, Clink will redirect customers to the specified address after successful payment. During redirection, Clink appends the session ID as a URL parameter, allowing you to retrieve session data via the Session#Get API. Example return URLs: * https\://your\_success\_url.com?sessionId=sess\_randoms
* https\://your\_success\_url.com?custom=xxxxxxxx\&sessionId=sess\_randoms ## Customer Experience Clink provides a streamlined solution with a standardized checkout experience. While customization options are limited, the interface maintains a clean, professional design. Merchant information and the cancel URL are accessible from the top left. Product and price information is displayed based on either dashboard configurations or API inputs. Available payment methods and currencies adapt automatically based on: * Purchase type (one-time or subscription) * Customer's geographical location ## Quick Start Examples Reference these code snippets to get started: Always test your code thoroughly before deploying to production! ```json One-time Purchase Without Product theme={null} curl --location --request POST 'https://uat-api.clinkbill.com/api/checkout/session' \ --header 'X-Timestamp: ${currentMillisecondsTimestamp}' \ --header 'X-API-Key: ${sk_key}' \ --header 'Content-Type: application/json' \ --data-raw '{ "customerEmail": "customer@example.com", "originalAmount": ${amount}, "originalCurrency": "USD", "priceDataList":[ { "name":"A one-time purchase", "quantity": 1, "unitAmount":${unitAmount}, "currency":"USD" } ] }' ``` ```json Purchase With Pre-created Product theme={null} curl --location --request POST 'https://uat-api.clinkbill.com/api/checkout/session' \ --header 'X-Timestamp: ${currentMillisecondsTimestamp}' \ --header 'X-API-Key: ${sk_key}' \ --header 'Content-Type: application/json' \ --data-raw '{ "customerEmail": "customer@example.com", "originalAmount": ${amount}, "originalCurrency": "USD", "priceId": "${price_id}", "productId": "${prd_id}" }' ``` # Currencies Source: https://docs.clinkbill.com/guides/payments/currencies Enable customers to pay in their local currency ## Overview [Checkout Session](/guides/payments/checkout_session) provides a unified hosted checkout experience with automatic local currency support. Clink handles all currency conversions and localizes prices without requiring additional configuration. Offering local currency support provides several advantages: * Higher conversion rates: Customers prefer to pay in familiar currencies * Access to local payment methods: Many local payment methods only support their native currency * Market-specific pricing: Implement competitive pricing strategies for different markets * Cost reduction: Avoid foreign exchange fees that some payment providers charge customers ## Customer Experience When customers access your checkout page from a location with a currency different from your defined price currencies, they'll see both their local currency and your default currency. Currency options are determined based on the customer's public IP address location. If the customer's local currency matches one of your defined price currencies, only that currency will be shown. currency_conversion ## Pre-defined Local Currency Prices Merchants can configure products with multiple local currencies to meet various business needs. Clink allows you to set multiple currencies for a single **price**. To configure this, visit the [Multi-currency Pricing](/guides/resources/product#multi-currency-pricing) section on the product page. multi_currency_price_example After configuration, simply use a **single Price ID** to create checkout sessions. Customers will automatically see your pre-defined price in their local currency, with no additional conversion needed. **Subscription**: To support local currencies in recurring payments, you must configure them in advance through price settings. Adaptive pricing is not available. **Settlement Currency**: For payments made in a pre-defined local currency different from your settlement currency, Clink automatically handles conversion during settlement.
 If a customer's local currency isn't included in your configuration, adaptive pricing will be used instead. ## Adaptive Pricing As mentioned in the [Customer Experience](#customer-experience) section, customers will see their local currency alongside your default price currency. For multi-currency price, only the primary currency will be shown. **Settlement Currency**: With adaptive pricing, orders settle in your primary price currency. Clink manages all customer-side currency conversions during payment processing.
 ### Restrictions Adaptive Pricing is not available for: * Subscription payments: Due to exchange rate fluctuations and the need for customer agreement on renewal amounts * Sessions where the customer's currency is already covered by pre-defined price currencies ## Supported Currencies Clink supports these major currencies: | | | | | :----------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------- | | United States Dollar (USD) | Euro (EUR) | Chinese Yuan (CNY) | | Canadian Dollar (CAD) | Japanese Yen (JPY) | Australian Dollar (AUD) | | Singapore Dollar (SGD) | Hong Kong Dollar (HKD) | South Korean Won (KRW) | | British Pound (BGP) | UAE Dirham (AED) | | # Link External Account Source: https://docs.clinkbill.com/guides/payments/link_psp Connect with your existing payment processors ## Overview Clink is fully **PCI DSS 4.0.1 compliant**, enabling secure connections with your existing payment service providers to process customer payments, renewals, and subscriptions. We support multiple external providers and multiple accounts per provider, with configurable routing rules to manage transaction flows according to your needs. ## Connection Management ### Add a Connection Prerequisites: * An active account with the target payment provider * Card payment method enabled with raw PAN payment capability * If required, contact us for an Attestation of Compliance (AoC) report Steps to add a connection: 1. Go to **Settings** -> **Merchant** (select the relevant merchant account if you have multiple) 2. Click **Linked Payment Services Providers**, then **New Connection** 3. Complete the connection form: 1. Select your provider from the dropdown list 2. Enter your API Key (we apply PCI requirements on API Key persistence) 3. Provide your Channel Merchant ID * For AirWallex: Use the Client ID associated with your API Key * For Stripe: Optional - use account name (without spaces) or account ID for reference 4. Enter the API endpoint URL * Some providers (e.g., Adyen) offer account-specific endpoints * Others (e.g., Stripe, AirWallex) use a common endpoint - refer to their developer guide 5. Set up webhook integration: * Copy the **Clink Generated Webhook URL** * Create a webhook endpoint in **your provider's dashboard** * Ensure payment-related events are selected 6. Copy the webhook signature from your provider and paste it into **Webhook Signature Key** 7. Click **Confirm** to save ### Edit Connection To modify an existing connection: 1. Navigate to **Settings** -> **Merchant** -> **Linked Payment Services Providers** 2. Find the connection you want to update 3. Click the **Edit** button on the right 4. Make your changes and click **Confirm** All changes take effect immediately.
 ### Delete Connection To remove an existing connection: 1. Navigate to **Settings** -> **Merchant** -> **Linked Payment Services Providers** 2. Locate the connection to delete 3. Click the **Delete** button on the right 4. Confirm by clicking **OK** Without an active connection, all customer payments and subscription renewals will fail. # Coupon Source: https://docs.clinkbill.com/guides/resources/coupon Create and manage discounts for bills, subscriptions, and customer accounts. Coupons in Clink allow you to offer discounts to your customers. These can be applied to individual bills, specific subscriptions, or an entire customer account. **Key Concept:** It is helpful to understand the two-layer structure: * **The Coupon (The Rule):** Defines *what* the discount is (e.g., "\$2.50 off") and its validity. * **The Promotion Code (The Key):** The specific string (e.g., `SUMMER2025`) a customer enters. A single Coupon can have multiple Promotion Codes. ## Creating a Coupon To set up a new discount rule, follow these steps: Go to **Products > Coupon** in the sidebar and click the **Add** button. Fill in the primary details for the discount rule. | Field | Description | | :------------------------ | :---------------------------------------------------------------------------------- | | **Name** | Internal name (e.g., "Black Friday"). This appears on customer receipts. | | **Type** | Choose **Percentage off** (%) or **Fixed amount off** (\$). | | **Applied to** | Select scope: **None** (Total invoice), **Product** (Specific items), or **Price**. | | **Subscription Duration** | **Once** (First invoice only) or **Repeating** (All future invoices). | At the bottom of the form, configure high-level restrictions: * **Exchange deadline:** The date range during which the coupon is valid. * **Limit total redemptions:** The total number of times this coupon can be used globally. * **Minimum amount requirement:** Specifies the minimum transaction amount required to redeem this coupon. Click **Add** to create the Coupon. *** ## Managing Promotion Codes Once a Coupon is created, you must generate codes so customers can redeem it. 1. Click on the **Name** of the coupon you just created in the list. 2. Scroll down to the **Promotion code** section. 3. Click the small button on the right side. ### Code Configuration When adding a promotional code, you can customize specific constraints: Enter a custom code (e.g., `WELCOME10`) or leave blank to auto-generate a random string. Check **Limited to specific customers** to restrict redemption to specific Customer IDs. Set how many times *this specific code* can be redeemed (distinct from the global coupon limit). Set an **Expires on** date specific to this code. *** ## Monitoring & Management ### The Coupon List Navigate to **Products > Coupon** for an overview. You can filter by discount type or duration. * **Terms:** Shows the rule (e.g., "\$2.5 off once"). * **Exchange:** Shows the current redemption count. ### Coupon Details Clicking into a specific Coupon provides a detailed dashboard. **Disabling Codes:** If a code is compromised, you can click the **Disable** button next to the specific code in the "Promotion code" table. This invalidates the code without deleting the parent Coupon. ### Editing & Deleting * **Rename:** You can rename a coupon at any time via the **Rename Coupon** button. * **Delete:** Clicking **Delete coupon** will remove the discount rule. Deleting a coupon will permanently disable all associated promotion codes immediately. # Customer Source: https://docs.clinkbill.com/guides/resources/customer Managing your customer base ## Overview Customers are a core resource within Clink, representing your real-world clients. Each customer profile contains essential information including personal details, billing information (including payment methods), and tax data. ## Customer Management A customer record is required for all purchases and subscriptions. When a customer doesn't exist in the system, Clink can automatically create one using the information you provide. ### Creating a Customer To create a customer through the dashboard: 1. Navigate to the **Customers** tab 2. Click the **Add** button 3. Complete the required profile information: 1. Customer name 2. Email address 4. Click **Save** to create the customer record ### Editing Customer Information To update customer details: 1. Go to the **Customers** tab 2. Find the customer using their customer ID or email address 3. Click to open their profile page 4. Click the **Edit** button in the top-right corner 5. Make your desired changes 6. Click **Confirm** to save the updates ### Deleting a Customer To delete a customer: 1. Open the customer's profile page 2. Click the **Delete** button in the top-right corner Note: Deleting a customer will: * Cancel all active subscriptions * Preserve historical payment records and invoices * Not affect past transaction data ## Customer Data ### Profile Information The customer profile includes: * Billing address (if not provided, the address used during checkout becomes the default) * Language preference (affects email communications and invoice language) ### Payment History View a comprehensive list of the customer's payment attempts. Click any record to view detailed [transaction](/guides/resources/order) information. ### Payment Methods Displays a list of the customer's active and valid payment methods. For PCI compliance, only limited payment method details are visible. ### Subscriptions Shows all customer subscriptions and associated invoice data. Click any subscription to view detailed [subscription](/guides/resources/subscription) information. # Order Source: https://docs.clinkbill.com/guides/resources/order Understanding payment transactions ## Overview An Order represents a payment transaction in the system. Orders are created for both customer-initiated payments and automated subscription renewals, regardless of whether the payment succeeds or fails. Every payment attempt generates an order record. ## Order Management ### Listing and Querying Orders can be viewed under the **Transactions** tab. By default, orders are listed chronologically based on their receipt time. You can filter orders using the following criteria: * Amount: The monetary value of the order * Currency: The payment currency used * Customer Email: The email address associated with the order * Card Last Four: The last four digits of the payment card (when applicable) * Created Date: The time period when orders were created * Status: The current order status (multiple status selections allowed) ### Order Details Clicking on any order from the list will display its detailed information, including: * Timeline: A chronological overview of the order's lifecycle * Payment Method: Comprehensive card information, including: * Last four digits * Card type, issuer, and issuing country * Billing address (when provided) * Additional card details * Processing Details: Critical transaction information, including: * Authorization code * CVV verification result * Address Verification Service (AVS) result * 3D Secure authentication result * Payment Breakdown: Detailed breakdown of the order amount * Product Information: List of products included in the order * Events & Logs: Chronological timeline of all events throughout the order lifecycle * Customer: Essential customer information related to the payment # Product & Price Source: https://docs.clinkbill.com/guides/resources/product Managing products and pricing structures ## Overview Products and Prices are core resources within Clink that define what you sell and how much you charge for it. These entities integrate seamlessly with subscriptions, invoices, and checkout sessions. ## Product Management Access your product list through the **Products** tab. ### Creating a Product To create a new product: product 1. Navigate to the **Products** tab and click **Add** 2. Enter the product name and upload a product image 3. Click **Add Price** to set pricing options: 1. Choose between *Recurring* or *One-off* price types 2. For recurring prices, select a *Billing Period* (Weekly, Monthly, or Yearly) 3. Optionally enable *Free Trial* and specify the trial duration 4. Set as *Default Price* if desired 5. Add additional pricing tiers as needed price 4. Select the appropriate *Tax Category* from the dropdown menu ### Editing Products To modify an existing product: 1. Go to the **Products** tab 2. Find the product you want to edit 3. Click the **Edit** button 4. Make your changes 5. Click **Confirm** to save ### Archiving Products When you archive a product, it becomes unavailable for new subscriptions while existing subscriptions remain active until canceled. To archive a product: 1. Navigate to the **Products** tab 2. Locate the target product 3. Click **Archive** and confirm in the popup window To restore an archived product, follow the same steps but click **Unarchive** instead. ## Price Management Products can have single or multiple pricing options, combining both recurring and one-off prices. For example: A starter plan could offer: * \$5.99 weekly * \$15.99 monthly * \$119.99 yearly * \$29.99 one-time purchase multi_price_example ### Multi-currency Pricing Multi-currency pricing allows you to set localized prices for different markets using a single price configuration (only one price ID). For example: * Default price: \$5.00 USD per week * European price: €3.00 EUR per week * Japanese price: ¥680 JPY per week multi_currency_price_example During settlement, Clink automatically converts customer payments from their local currency to your settlement currency, eliminating the need to manage multiple currencies. ### Automatic Currency Conversion For **One-off** prices without specific multi-currency settings, Clink automatically offers local currency options to international customers during checkout. ### Edit Price Price changes in Clink are managed through a snapshot system. While merchants cannot view or edit these snapshots directly, each price update creates a new snapshot. Here's how price changes affect your subscriptions or one-time sales: * New subscriptions and purchases will use the updated price * Existing subscriptions will continue with their original price until canceled * Price history is maintained automatically through snapshots To edit a price: 1. Navigate to the **Products** tab and locate your target product 2. Expand the price list using the arrow on the left, or click the **Edit** button 3. Find the price you want to update and click its overflow menu button (⋮) 4. Select **Edit** from the menu 5. Make your desired changes on the edit page 6. Click **Confirm** to save your changes # Refund Source: https://docs.clinkbill.com/guides/resources/refund Refund and Chargeback Policies ## Overview Merchants have complete control over their refund policies. However, Clink reserves the right to process refunds on merchants' behalf to mitigate chargeback risks. ## Refund As merchants best understand their business needs, they have the flexibility to implement their own refund policies. Refunds can be processed at any time through the Clink dashboard, and the refunded amount will be automatically deducted from the merchant's balance account. While Clink respects merchant-defined policies, we maintain the right to issue refunds on merchants' behalf when there are chargeback concerns. It's important to note that regardless of merchant or Clink actions, customers always retain the right to initiate chargebacks through their issuers. ### Issuing a Refund To issue a refund through the Clink dashboard: 1. Navigate to the **Transactions** tab in the menu panel 2. Locate the target order for refund 3. Click the **Refund** button in the top right corner 4. Complete the refund form: 1. The maximum refundable amount is automatically calculated based on the order's current status and previous refunds 2. Select one of the four refund reasons from the dropdown menu 3. Add a description if needed refund 5. Click the **Confirm** button The **Refund** button may be unavailable for the following reasons: * Payment was unsuccessful * Order has been fully refunded * Current refundable amount is zero * Payment method doesn't support refunds Refund requests will be rejected if you have insufficient funds in your balance. ## Chargeback A chargeback (also known as a dispute) occurs when customers request their card issuers to reverse a transaction. Common reasons include unauthorized charges and service dissatisfaction. When an issuer approves a chargeback request, the transaction amount is automatically withdrawn from the merchant's account, typically accompanied by a processing fee ranging from US\$15 to US\$20. Merchants can choose to either accept or challenge the chargeback. Clink's involvement in chargeback cases is limited by regulations. While we will assist merchants in collecting evidence for disputes when necessary, the final decision lies with the card issuer and card scheme. To maintain platform reputation and protect customer interests, Clink reserves the right to implement preventive measures, including account suspension, for merchants experiencing unusually high chargeback rates. For more detailed information about chargebacks, we recommend Stripe's comprehensive guide: [Chargebacks 101](https://stripe.com/resources/more/chargebacks-101) # Subscription Source: https://docs.clinkbill.com/guides/resources/subscription Understanding the recurring payment contract ## Overview A subscription is an agreement where a customer pays a recurring fee (e.g., weekly, monthly, annually) to access a product, service, or content. Key characteristics of subscriptions include: * Recurring Payments: Customers are billed regularly. * Continuous Access: Subscribers receive ongoing access to the product or service as long as payments are made. * Flexibility: Subscriptions may offer options to upgrade, downgrade, or cancel at any time, depending on the provider's terms. ## Subscription Data ### Status * Incomplete: The subscription was created, but the checkout session was not paid successfully. * Incomplete Expired: The subscription is incomplete and has been closed because the checkout session expired. * Active: The subscription is active with no outstanding bills. * Trialing: The subscription is in a free trial period. No payments have been attempted yet, but the customer has provided payment information. * Past Due: Payment attempts for renewal have failed, but the subscription remains active and will retry. * Canceled: The subscription has been terminated. ### [Product & Price](/guides/resources/product) The product represents the service that customer and merchant have agreed upon. The price contains information about the billing cycle and the payment amount to maintain the agreement. ### [Customer](/guides/resources/customer) A subscription contains a customer ID, representing the real-world client who agrees to pay periodically for the merchant service. The customer owns the payment instrument used for recurring payments. If a customer deletes the payment instrument associated with the subscription but has other payment instruments available, Clink will use the default payment instrument for renewal. ## Subscription Management ### Listing and Querying Subscriptions can be viewed under the **Subscriptions** tab. By default, subscriptions are listed chronologically based on their creation time. You can filter subscriptions using the following criteria: * Amount: The monetary value of the product * Currency: The currency used in the agreement * Customer ID: The customer ID associated with the subscription * Created Date: The time period when subscriptions were created * Status: The current subscription status ### Subscription Detail Clicking on any subscription from the list will display its detailed information, including: * Product & Price * Customer and the payment instrument * Invoices and the billing cycle coverage ### Cancel a Subscription To cancel a subscription: 1. Go to the **Subscriptions** tab 2. Locate the subscription using the search function and open the details page 3. Click on the **Action** button on the top right 4. Select **Cancel subscription** from the dropdown list 5. Select the reason for cancellation in the popup window 6. Click the **OK** button ### Downgrade or Upgrade a Subscription We do not support merchants downgrading or upgrading subscriptions on customers' behalf. To complete such requests, please guide customers to the customer portal for self-service. **Refund**: Canceling a subscription will not issue a prorated refund automatically.
For example, if your service is usage-based metering, you will need to calculate the refund amount. If a refund is required upon cancellation, please submit a [refund](/guides/resources/refund) request. ## Invoice An invoice is generated on every billing cycle for the subscription. Customers can download invoices for expense purposes, proof of payments, etc. ### Status * Open: The initial status of an invoice, indicating it is waiting for payment. * Paid: The bill amount has been received. * Void: The invoice is closed but unpaid. ### Invoice Management Invoices are generated automatically when the service is initially subscribed to or when renewal is triggered. We do not currently support manual invoice creation. Invoices are strongly tied to subscriptions. To view the list of invoices, navigate to the subscription details page and scroll down. # Introduction Source: https://docs.clinkbill.com/index Clink aims to provide a simplified but solid subscription and payment solution. ## Get Started If you are interested, please [contact us](https://www.clinkbill.com/contact). If you already have an account, enjoy. Create your first payment session. Learn about integration details. ## Guides and Resources Learn more about the concepts. How to manage your dashboard account. Learn API and webhook details. Explanation of basic concepts. Understand your balance and get paid. # Integration Source: https://docs.clinkbill.com/integration Learn how to connect with Clink from Test to Production environments. **Prerequisite**: Please ensure you have an account in our test environment and thoroughly debug before deploying to production.
Our test environment uses a different domain and API key. Do not use real data in the test environment. ## Dashboard Our dashboard manages daily operations for your account. The following resources can be managed through the dashboard: The business operating unit. A dashboard account owner. The selling unit and pricing configuration. Understand account balances and fees. ## API Keys We provide secure and easy-to-use APIs. API integration is authenticated using a secret key generated through the dashboard. ### Initialize API Key Navigate to the **Developers** tab. Click **Initialize Key**, and be sure to copy and securely store the secret key, as it will only be displayed once. key ### Key Types * Secret Key: Used to authenticate requests with Clink. By default, this key can perform any API request without restrictions. * Test environment key format: sk\_test\_\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* * Prod environment key format: sk\_prod\_\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* * Publishable Key: Used in client-side code with embedded payment forms. Clink is currently working on supporting this use case. * Test environment key format: pk\_test\_\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* * Prod environment key format: pk\_prod\_\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* ### Key Rotation Rolling a key revokes it and automatically generates a replacement key. You can set the old key to expire immediately or schedule it to expire after a specified time. To roll an API key: * Open the API keys page. * Click the overflow button (⋮) in the row of the key you want to roll, then select **Roll Key**. * Select an expiration date from the **Expiration** dropdown. * Click **Roll Key**. * **Copy the new key value** displayed in the dialog. * Save the key value, as you won't be able to retrieve it later. ### Delete a Secret Key Deleting a key immediately prevents it from making API calls. You **cannot** delete the standard key if it is the last valid key remaining. To delete an API key: * Open the API keys page. * Roll the key you want to delete. * Update your code to use the new key. * Click the overflow button (⋮) on the old key, then select delete. ### Restrict Secret Key with IP Addresses Only secret keys can be restricted to specific IP addresses. You can limit API requests to one or more IP addresses or to an IP range using [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing). * Open the API keys page. * Click the overflow button (⋮) in the row of the key you want to restrict, then select **Manage IP Restrictions**. * Toggle *Restrict usage to a set of IP addresses*. * Click the **Add** button. * Enter a single IP address or CIDR range. * Clink the **Save** button. ## Webhooks Webhooks enable applications to provide real-time information to other applications. They deliver data immediately as events occur, ensuring you receive information instantly. Create an event destination to receive events at an HTTPS webhook endpoint. Once you register a webhook endpoint, Clink will push real-time event data to your application's webhook endpoint when events occur. ### Registration To register a webhook endpoint, go to the **Developers** tab and select the Webhooks tab: * Click the Add button. * Enter your **HTTPS** endpoint. * Select the event types you want to monitor. We recommend monitoring all events. For details about event types and their associated data, please refer to [Webhook Reference](/api-reference/webhook) ### Verify Signature Clink uses HMAC SHA-256 to generate a signature for each event. The signature key becomes available after webhook endpoint registration. To generate your signature: * Extract the timestamp and signature from the header: * Timestamp is available in the **X-Clink-Timestamp** field * Clink-generated signature is available in the **X-Clink-Signature** field * Prepare the payload string by concatenating: * The timestamp (as a string) * The character **.** * The event body (JSON payload) * Generate your signature by computing an HMAC with the SHA256 hash function. * Compare the signatures and process the event only if they match. ### Event Delivery Clink attempts to deliver events to your destination up to 10 times with exponential backoff. All retries complete within approximately one day. Please note that we do not guarantee events will be delivered in the order they were generated. Ensure your application does not depend on receiving events in a specific order. ### Best Practices Credit to Stripe for their detailed guide: [Best practices for using webhooks](https://docs.stripe.com/webhooks#best-practices) # Quickstart Source: https://docs.clinkbill.com/quickstart Create your first checkout session in minutes. ## Log in into your account If you have been invited, you should receive an email from us about account verification. invitation Follow the instructions to set your password, and then log in use your email address. Upon first login, you will need an authenticator app for TOTP registration. We recommend the **Microsoft/Google Authenticator** app. ## Generate API key Go to the **Developers** tab. Click on **Initialize Key**, and make sure you copy the SK as it will only appear once. key ## Create first product (Optional) Go to the **Products** tab. The name, icon, prices are required to create a product. We will display this information to your customers. product price ## Create a checkout session Follow the API reference to create a checkout session! Please test your code before hitting production! ```json without a Product theme={null} curl --location --request POST 'https://uat-api.clinkbill.com/api/checkout/session' \ --header 'X-Timestamp: ${currentMillisecondsTimestamp}' \ --header 'X-API-Key: ${sk_key}' \ --header 'Content-Type: application/json' \ --data-raw '{ "customerEmail": "customer@example.com", "originalAmount": ${amount}, "originalCurrency": "USD", "priceDataList":[ { "name":"A One-time purchase", "quantity": 1, "unitAmount":${unitAmount}, "currency":"USD" } ] }' ``` ```json with a Product created theme={null} curl --location --request POST 'https://uat-api.clinkbill.com/api/checkout/session' \ --header 'X-Timestamp: ${currentMillisecondsTimestamp}' \ --header 'X-API-Key: ${sk_key}' \ --header 'Content-Type: application/json' \ --data-raw '{ "customerEmail": "customer@example.com", "originalAmount": ${amount}, "originalCurrency": "USD", "priceId": "${price_id}", "productId": "${prd_id}" }' ```