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.

1 using KardFinancial;
2 
3 var 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.

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

The client automatically handles authentication, retries, and timeouts.

Environments

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

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

Make Your First API Calls

1. Creating a User:

1 using KardFinancial;
2 
3 var client = new KardClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
4 
5 await 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:

1 using KardFinancial;
2 using KardFinancial.Hem;
3 
4 var client = new KardClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
5 
6 var hashedEmail = Hem.GenerateHEM("Jane.Doe+work@gmail.com");
7 
8 await 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:

1 using KardFinancial;
2 using KardFinancial.Users;
3 
4 var client = new KardClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
5 
6 await 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:

1 using KardFinancial;
2 
3 var client = new KardClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
4 
5 await 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.

1 using KardFinancial;
2 
3 try
4 {
5     var response = await client.Users.CreateAsync(...);
6 }
7 catch (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:

1 var 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.

1 var 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.

1 var 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.

1 var 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().

1 using KardFinancial;
2 
3 var result = await client.Users.CreateAsync(...).WithRawResponse();
4 
5 var data = result.Data;
6 var statusCode = result.RawResponse.StatusCode;
7 var headers = result.RawResponse.Headers;
8 var url = result.RawResponse.Url;
9 
10 if (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.

1 using KardFinancial;
2 
3 // Using a built-in value
4 var cardNetwork = CardNetwork.Visa;
5 
6 // Using a custom value
7 var customCardNetwork = CardNetwork.FromCustom("custom-value");
8 
9 // Using in a switch statement
10 switch (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
21 string cardNetworkString = (string)CardNetwork.Visa;
22 CardNetwork cardNetworkFromString = (CardNetwork)"VISA";