TypeScript SDK

Getting Started

This guide walks you through installing the Kard TypeScript SDK, authenticating with the Kard API, and making your first request.

Prerequisites

  • Node.js 18+ or a supported runtime
  • KARD_CLIENT_ID and KARD_CLIENT_SECRET
  • Package manager: npm, yarn, or pnpm

Supported runtimes: Node.js 18+, Vercel, Cloudflare Workers, Deno v1.25+, Bun 1.0+, React Native

Install the SDK

$npm install --save @kard-financial/sdk

Create a Client

Import and instantiate the KardApiClient using your credentials.

1import { KardApiClient } from "@kard-financial/sdk";
2
3const client = new KardApiClient({
4  clientId: "YOUR_CLIENT_ID",
5  clientSecret: "YOUR_CLIENT_SECRET",
6});

You can also configure the SDK using environment variables.

If KARD_CLIENT_ID and KARD_CLIENT_SECRET are set in your runtime environment, the SDK will automatically use them, so you can initialize the client without passing credentials explicitly.

1import { KardApiClient } from "@kard-financial/sdk";
2
3const client = new KardApiClient();

The client automatically handles authentication, retries, and timeouts.

Make Your First API Calls

1. Creating a User:

1import { KardApiClient } from "@kard-financial/sdk";
2
3const client = new KardApiClient({
4  clientId: "YOUR_CLIENT_ID",
5  clientSecret: "YOUR_CLIENT_SECRET",
6});
7
8await client.users.create("organization-123", {
9    data: [{
10            type: "user",
11            id: "1234567890",
12            attributes: {
13                zipCode: "11238",
14                enrolledRewards: ["CARDLINKED"]
15            }
16        }]
17});

2. Fetching Offers for User:

1import { KardApiClient } from "@kard-financial/sdk";
2
3const client = new KardApiClient({
4  clientId: "YOUR_CLIENT_ID",
5  clientSecret: "YOUR_CLIENT_SECRET",
6});
7
8await client.users.rewards.offers("organization-123", "user-123", {
9    "page[size]": 1,
10    "filter[isTargeted]": true,
11    sort: "-startDate"
12});

3. Submitting Transaction for User:

1import { KardApiClient } from "@kard-financial/sdk";
2
3const client = new KardApiClient({
4  clientId: "YOUR_CLIENT_ID",
5  clientSecret: "YOUR_CLIENT_SECRET",
6});
7
8await client.transactions.create("organization-123", {
9    data: [{
10            type: "transaction",
11            id: "12345610",
12            attributes: {
13                userId: "1234567890",
14                amount: 1000,
15                status: "APPROVED",
16                currency: "USD",
17                description: "ADVANCEAUTO",
18                cardBIN: "123456",
19                cardLastFour: "4321",
20                direction: "DEBIT",
21                paymentType: "CARD",
22                transactionId: "12345611",
23                subtotal: 800,
24                description2: "ADVANCEAUTO",
25                mcc: "1234",
26                authorizationDate: "2021-07-02T17:47:06Z",
27                merchant: {
28                    name: "ADVANCEAUTO",
29                    id: "12345678901234567",
30                    addrStreet: "125 Main St",
31                    addrCity: "Philadelphia",
32                    addrState: "PA",
33                    addrZipcode: "19147",
34                    addrCountry: "United States",
35                    latitude: "37.9419429",
36                    longitude: "-73.1446869",
37                    storeId: "12345"
38                },
39                authorizationCode: "123456",
40                retrievalReferenceNumber: "100804333919",
41                systemTraceAuditNumber: "333828",
42                acquirerReferenceNumber: "1234567890123456789012345678",
43                processorMids: {
44                    processor: "VISA",
45                    mids: {
46                        vmid: "12345678901",
47                        vsid: "12345678"
48                    }
49                }
50            }
51        }]
52});

All SDK methods return typed responses and throw typed errors.

Type Safety

The SDK exports all request and response types for full TypeScript support.

1import { KardApi } from "@kard-financial/sdk";
2
3const request: KardApi.GetTokenRequest = {
4    ...
5};

Handling Errors

If an API request fails (4xx or 5xx), the SDK throws a KardApiError.

1import { KardApiError } from "@kard-financial/sdk";
2
3try {
4  await client.users.create(...);
5} catch (err) {
6  if (err instanceof KardApiError) {
7    console.error("Status:", err.statusCode);
8    console.error("Message:", err.message);
9    console.error("Body:", err.body);
10  }
11}

Common Configuration Options

Add Custom Headers

1const response = await client.users.create(..., {
2    headers: {
3        'X-Custom-Header': 'custom value'
4    }
5});

Add Query Parameters

1const response = await client.users.create(..., {
2    queryParams: {
3        'customQueryParamKey': 'custom query param value'
4    }
5});

Configure Retries

Retries are enabled by default (max 2 attempts).

1const response = await client.users.create(..., {
2    maxRetries: 0 
3});

Set a Timeout

1const response = await client.users.create(..., {
2    timeoutInSeconds: 30 
3});

Abort a Request

1const controller = new AbortController();
2const response = await client.users.create(..., {
3    abortSignal: controller.signal
4});
5controller.abort();

Access Raw HTTP Responses

To inspect headers or status codes, use withRawResponse():

1const { data, rawResponse } = await client.users.create(...).withRawResponse();
2console.log(data);
3console.log(rawResponse.headers['X-My-Header']);

Enable Logging

Logging is disabled by default. Enable it during development to debug requests.

1import { KardApiClient, logging } from "@kard-financial/sdk";
2
3const client = new KardApiClient({
4    ...
5    logging: {
6        level: logging.LogLevel.Debug, 
7        logger: new logging.ConsoleLogger(), 
8        silent: false,
9    }
10});

Customize Fetch Client

The SDK provides a way for you to customize the underlying HTTP client / Fetch function.

1import { KardApiClient } from "@kard-financial/sdk";
2
3const client = new KardApiClient({
4    ...
5    fetcher:
6});