Getting Started | Kard API

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.

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.

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:

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:

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:

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:

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.

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.

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

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

Add Query Parameters

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

Configure Retries

Retries are enabled by default (max 2 attempts).

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

Set a Timeout

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

Abort a Request

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():

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.

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.

import { KardApiClient } from "@kard-financial/sdk";
const client = new KardApiClient({
    ...
    fetcher:
});