> This page is for version 2024-10-01 (default).
> For other versions, use one of these documentation indexes:
> - 2024-10-01 (default): https://docs.getkard.com/2024-10-01/llms.txt
> - Legacy: https://docs.getkard.com/legacy/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getkard.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getkard.com/_mcp/server.

# Getting Started

This guide walks you through installing the [**Kard TypeScript SDK**](https://github.com/KardFinancial/kard-node-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
```bash
npm install --save @kard-financial/sdk
```

## Create a Client
Import and instantiate the `KardApiClient` using your credentials.
```tsx
import { KardApiClient } from "@kard-financial/sdk";

const client = new KardApiClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});
```
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.
```tsx
import { KardApiClient } from "@kard-financial/sdk";

const client = new KardApiClient();
```

The client automatically handles **authentication, retries, and timeouts.**

## Make Your First API Calls
**1.** [Creating a User](https://docs.getkard.com/api/users/create):

```tsx
import { KardApiClient } from "@kard-financial/sdk";

const client = new KardApiClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

await client.users.create("organization-123", {
    data: [{
            type: "user",
            id: "1234567890",
            attributes: {
                zipCode: "11238",
                enrolledRewards: ["CARDLINKED"]
            }
        }]
});
```

To enhance offer targeting and attribution, you can include a **hashed email (HEM)** when creating users. The SDK includes a built-in `generateHEM` utility that normalizes and hashes email addresses:

```tsx
import { KardApiClient } from "@kard-financial/sdk";
import { generateHEM } from "@kard-financial/sdk/helpers/hem";

const client = new KardApiClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

const hashedEmail = generateHEM("Jane.Doe+work@gmail.com");

await client.users.create("organization-123", {
    data: [{
        type: "user",
        id: "1234567890",
        attributes: {
            enrolledRewards: ["CARDLINKED"],
            hashedEmail: hashedEmail,
        }
    }]
});
```

The function normalizes the email before hashing (removes whitespace, lowercases, and handles Gmail-specific rules like dot and `+` suffix removal). It throws a `TypeError` for invalid inputs.

**2.** [Fetching Offers for User with Extended API](https://docs.getkard.com/api/rewards/offers):

```tsx
import { KardApiClient } from "@kard-financial/sdk";

const client = new KardApiClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

await client.users.rewards.offers("organization-123", "user-123", {
    "page[size]": 1,
    "filter[isTargeted]": true,
    sort: "-startDate",
    supportedComponents: [
        "shortDescription",
        "longDescription",
        "cta",
        "tags",
        "detailTags",
        "baseReward"
    ],
});
```
**3.** [Submitting Transaction for User](https://docs.getkard.com/api/transactions/create):
```tsx
import { KardApiClient } from "@kard-financial/sdk";

const client = new KardApiClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

await client.transactions.create("organization-123", {
    data: [{
            type: "transaction",
            id: "12345610",
            attributes: {
                userId: "1234567890",
                amount: 1000,
                status: "APPROVED",
                currency: "USD",
                description: "ADVANCEAUTO",
                cardBIN: "123456",
                cardLastFour: "4321",
                direction: "DEBIT",
                paymentType: "CARD",
                transactionId: "12345611",
                subtotal: 800,
                description2: "ADVANCEAUTO",
                mcc: "1234",
                authorizationDate: "2021-07-02T17:47:06Z",
                merchant: {
                    name: "ADVANCEAUTO",
                    id: "12345678901234567",
                    addrStreet: "125 Main St",
                    addrCity: "Philadelphia",
                    addrState: "PA",
                    addrZipcode: "19147",
                    addrCountry: "United States",
                    latitude: "37.9419429",
                    longitude: "-73.1446869",
                    storeId: "12345"
                },
                authorizationCode: "123456",
                retrievalReferenceNumber: "100804333919",
                systemTraceAuditNumber: "333828",
                acquirerReferenceNumber: "1234567890123456789012345678",
                processorMids: {
                    processor: "VISA",
                    mids: {
                        vmid: "12345678901",
                        vsid: "12345678"
                    }
                }
            }
        }]
});
```
All SDK methods return **typed responses and throw typed errors.**

## Type Safety
The SDK exports all request and response types for full TypeScript support.
```tsx
import { KardApi } from "@kard-financial/sdk";

const request: KardApi.GetTokenRequest = {
    ...
};
```

## Handling Errors
If an API request fails (4xx or 5xx), the SDK throws a `KardApiError`.
```tsx
import { KardApiError } from "@kard-financial/sdk";

try {
  await client.users.create(...);
} catch (err) {
  if (err instanceof KardApiError) {
    console.error("Status:", err.statusCode);
    console.error("Message:", err.message);
    console.error("Body:", err.body);
  }
}
```

## Common Configuration Options
### Add Custom Headers
```tsx
const response = await client.users.create(..., {
    headers: {
        'X-Custom-Header': 'custom value'
    }
});
```
### Add Query Parameters
```tsx
const response = await client.users.create(..., {
    queryParams: {
        'customQueryParamKey': 'custom query param value'
    }
});
```
### Configure Retries
Retries are enabled by default (max 2 attempts).
```tsx
const response = await client.users.create(..., {
    maxRetries: 0 
});
```
### Set a Timeout
```tsx
const response = await client.users.create(..., {
    timeoutInSeconds: 30 
});
```
### Abort a Request
```tsx
const controller = new AbortController();
const response = await client.users.create(..., {
    abortSignal: controller.signal
});
controller.abort();
```

## Access Raw HTTP Responses
To inspect headers or status codes, use `withRawResponse()`:
```tsx
const { data, rawResponse } = await client.users.create(...).withRawResponse();
console.log(data);
console.log(rawResponse.headers['X-My-Header']);
```

## Enable Logging
Logging is disabled by default. Enable it during development to debug requests.
```tsx
import { KardApiClient, logging } from "@kard-financial/sdk";

const client = new KardApiClient({
    ...
    logging: {
        level: logging.LogLevel.Debug, 
        logger: new logging.ConsoleLogger(), 
        silent: false,
    }
});
```

## Customize Fetch Client
The SDK provides a way for you to customize the underlying HTTP client / Fetch function.
```tsx
import { KardApiClient } from "@kard-financial/sdk";

const client = new KardApiClient({
    ...
    fetcher:
});
```
```