.NET SDK

Getting Started

C# Getting Started

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

Prerequisites

  • .NET Framework 4.6.2+ or .NET Standard 2.0+
  • KARD_CLIENT_ID and KARD_CLIENT_SECRET

Install the SDK

$dotnet add package KardFinancial

Create a Client

Import and instantiate the KardClient using your credentials.

1using KardFinancial;
2
3var client = new KardClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

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.

1using KardFinancial;
2
3var client = new KardClient();

The client automatically handles authentication, retries, and timeouts.

Environments

You can configure a custom base URL by setting BaseUrl on ClientOptions.

1using KardFinancial;
2
3var client = new KardClient(new ClientOptions
4{
5    BaseUrl = KardEnvironment.Production
6});

Make Your First API Calls

1. Creating a User:

1using KardFinancial;
2
3var client = new KardClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
4
5await client.Users.CreateAsync(
6    "organization-123",
7    new CreateUsersObject
8    {
9        Data = new List<UserRequestDataUnion>()
10        {
11            new UserRequestDataUnion(
12                new UserRequestDataUnion.User(
13                    new UserRequestData
14                    {
15                        Id = "1234567890",
16                        Attributes = new UserRequestAttributes
17                        {
18                            ZipCode = "11238",
19                            EnrolledRewards = new List<EnrolledRewardsType>()
20                            {
21                                EnrolledRewardsType.Cardlinked,
22                            },
23                            Email = "user@example.com",
24                            HashedEmail =
25                                "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1",
26                            PhoneNumber = "+14155552671",
27                            BirthYear = "1990",
28                            HistoricalTransactionsSent = true,
29                        },
30                    }
31                )
32            ),
33        },
34    }
35);

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

1using KardFinancial;
2using KardFinancial.Hem;
3
4var client = new KardClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
5
6var hashedEmail = Hem.GenerateHEM("Jane.Doe+work@gmail.com");
7
8await client.Users.CreateAsync(
9    "organization-123",
10    new CreateUsersObject
11    {
12        Data = new List<UserRequestDataUnion>()
13        {
14            new UserRequestDataUnion(
15                new UserRequestDataUnion.User(
16                    new UserRequestData
17                    {
18                        Id = "1234567890",
19                        Attributes = new UserRequestAttributes
20                        {
21                            EnrolledRewards = new List<EnrolledRewardsType>()
22                            {
23                                EnrolledRewardsType.Cardlinked,
24                            },
25                            HashedEmail = hashedEmail,
26                        },
27                    }
28                )
29            ),
30        },
31    }
32);

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

2. Fetching Offers for User with Extended API:

1using KardFinancial;
2using KardFinancial.Users;
3
4var client = new KardClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
5
6await client.Users.Rewards.OffersAsync(
7    "organization-123",
8    "1234567890",
9    new GetOffersByUserRequest
10    {
11        PageSize = 1,
12        FilterIsTargeted = true,
13        Sort = new List<OfferSortOptions> { OfferSortOptions.StartDateDesc },
14        SupportedComponents = new List<ComponentType>
15        {
16            ComponentType.ShortDescription,
17            ComponentType.LongDescription,
18            ComponentType.Cta,
19            ComponentType.Tags,
20            ComponentType.DetailTags,
21            ComponentType.BaseReward,
22        },
23    }
24);

3. Submitting Transaction for User:

1using KardFinancial;
2
3var client = new KardClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
4
5await client.Transactions.CreateAsync(
6    "organization-123",
7    new TransactionsRequestBody
8    {
9        Data = new List<Transactions>
10        {
11            new Transactions(
12                new Transactions.Transaction(
13                    new TransactionsRequest
14                    {
15                        Id = "12345610",
16                        Attributes = new TransactionsAttributes
17                        {
18                            UserId = "1234567890",
19                            Amount = 1000,
20                            Subtotal = 800,
21                            Status = TransactionStatus.Approved,
22                            Currency = "USD",
23                            Description = "ADVANCEAUTO",
24                            AuthorizationDate = DateTime.Parse("2021-07-02T17:47:06Z"),
25                            PaymentType = TransactionPaymentType.Card,
26                            Direction = DirectionType.Debit,
27                            Merchant = new Merchant
28                            {
29                                Id = "12345678901234567",
30                                Name = "ADVANCEAUTO",
31                                AddrStreet = "125 Main St",
32                                AddrCity = "Philadelphia",
33                                AddrState = States.Pa,
34                                AddrZipcode = "19147",
35                                AddrCountry = "United States",
36                                Latitude = "37.9419429",
37                                Longitude = "-73.1446869",
38                                StoreId = "12345",
39                            },
40                            CardBin = "123456",
41                            CardLastFour = "4321",
42                            AuthorizationCode = "123456",
43                            RetrievalReferenceNumber = "100804333919",
44                            SystemTraceAuditNumber = "333828",
45                            AcquirerReferenceNumber = "1234567890123456789012345678",
46                            TransactionId = "12345611",
47                        },
48                    }
49                )
50            ),
51        },
52    }
53);

All SDK methods return typed responses and throw typed errors.

Handling Errors

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

1using KardFinancial;
2
3try
4{
5    var response = await client.Users.CreateAsync(...);
6}
7catch (KardApiException e)
8{
9    System.Console.WriteLine(e.Body);
10    System.Console.WriteLine(e.StatusCode);
11}

Common Configuration Options

Configure Retries

Retries are enabled by default (max 2 attempts) with exponential backoff. The SDK retries on status codes 408, 429, and 5xx. Configure with the MaxRetries request option:

1var response = await client.Users.CreateAsync(
2    ...,
3    new RequestOptions {
4        MaxRetries = 0
5    }
6);

Set a Timeout

The SDK defaults to a 30 second timeout. Override it with the Timeout request option.

1var response = await client.Users.CreateAsync(
2    ...,
3    new RequestOptions {
4        Timeout = TimeSpan.FromSeconds(3)
5    }
6);

Add Custom Headers

Use the AdditionalHeaders request option to send extra headers.

1var response = await client.Users.CreateAsync(
2    ...,
3    new RequestOptions {
4        AdditionalHeaders = new Dictionary<string, string?>
5        {
6            { "X-Custom-Header", "custom-value" }
7        }
8    }
9);

Add Query Parameters

Use the AdditionalQueryParameters request option to send extra query params.

1var response = await client.Users.CreateAsync(
2    ...,
3    new RequestOptions {
4        AdditionalQueryParameters = new Dictionary<string, string>
5        {
6            { "custom_param", "custom-value" }
7        }
8    }
9);

Access Raw HTTP Responses

To inspect status codes, headers, or the URL, use .WithRawResponse().

1using KardFinancial;
2
3var result = await client.Users.CreateAsync(...).WithRawResponse();
4
5var data = result.Data;
6var statusCode = result.RawResponse.StatusCode;
7var headers = result.RawResponse.Headers;
8var url = result.RawResponse.Url;
9
10if (headers.TryGetValue("X-Request-Id", out var requestId))
11{
12    System.Console.WriteLine($"Request ID: {requestId}");
13}

Forward Compatible Enums

This SDK uses forward-compatible enums that handle unknown values gracefully.

1using KardFinancial;
2
3// Using a built-in value
4var cardNetwork = CardNetwork.Visa;
5
6// Using a custom value
7var customCardNetwork = CardNetwork.FromCustom("custom-value");
8
9// Using in a switch statement
10switch (cardNetwork.Value)
11{
12    case CardNetwork.Values.Visa:
13        Console.WriteLine("Visa");
14        break;
15    default:
16        Console.WriteLine($"Unknown value: {cardNetwork.Value}");
17        break;
18}
19
20// Explicit casting
21string cardNetworkString = (string)CardNetwork.Visa;
22CardNetwork cardNetworkFromString = (CardNetwork)"VISA";