Java SDK

Getting Started

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

Prerequisites

  • Java 8+
  • KARD_CLIENT_ID and KARD_CLIENT_SECRET
  • Build tool: Maven or Gradle

Install the SDK

Gradle

Add the dependency in your build.gradle file:

1dependencies {
2    implementation 'com.getkard:kard-financial-sdk'
3}

Maven

Add the dependency in your pom.xml file:

1<dependency>
2    <groupId>com.getkard</groupId>
3    <artifactId>kard-financial-sdk</artifactId>
4    <version>1.5.1</version>
5</dependency>

Create a Client

Import and instantiate the KardApiClient using your credentials.

This SDK supports two authentication methods:

OAuth Client Credentials

1import com.kard.api.KardApiClient;
2
3KardApiClient client = KardApiClient
4    .withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
5    .build();

Bearer Token Authentication

1import com.kard.api.KardApiClient;
2
3KardApiClient client = KardApiClient.builder()
4    .token("your-access-token")
5    .url("https://api.getkard.com")
6    .build();

The client automatically handles authentication, retries, and timeouts.

Environments

This SDK allows you to configure different environments for API requests.

1import com.kard.api.KardApiClient;
2import com.kard.api.core.Environment;
3
4KardApiClient client = KardApiClient.builder()
5    .environment(Environment.Production)
6    .build();

Base URL

You can set a custom base URL when constructing the client.

1import com.kard.api.KardApiClient;
2
3KardApiClient client = KardApiClient.builder()
4    .url("https://example.com")
5    .build();

Make Your First API Calls

1. Creating a User:

1import com.kard.api.KardApiClient;
2import com.kard.api.resources.commons.types.EnrolledRewardsType;
3import com.kard.api.resources.users.types.CreateUsersObject;
4import com.kard.api.resources.users.types.UserRequestAttributes;
5import com.kard.api.resources.users.types.UserRequestData;
6import com.kard.api.resources.users.types.UserRequestDataUnion;
7import java.util.Arrays;
8
9KardApiClient client = KardApiClient
10    .withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
11    .build();
12
13client.users().create(
14    "organization-123",
15    CreateUsersObject.builder()
16        .data(Arrays.asList(
17            UserRequestDataUnion.user(
18                UserRequestData.builder()
19                    .id("1234567890")
20                    .attributes(
21                        UserRequestAttributes.builder()
22                            .zipCode("11238")
23                            .enrolledRewards(
24                                Arrays.asList(EnrolledRewardsType.CARDLINKED)
25                            )
26                            .build()
27                    )
28                    .build()
29            )
30        ))
31        .build()
32);

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:

1import com.kard.api.KardApiClient;
2import com.kard.api.resources.commons.types.EnrolledRewardsType;
3import com.kard.api.resources.users.types.CreateUsersObject;
4import com.kard.api.resources.users.types.UserRequestAttributes;
5import com.kard.api.resources.users.types.UserRequestData;
6import com.kard.api.resources.users.types.UserRequestDataUnion;
7import com.kard.hem.HEM;
8import java.util.Arrays;
9
10KardApiClient client = KardApiClient
11    .withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
12    .build();
13
14String hashedEmail = HEM.generateHEM("Jane.Doe+work@gmail.com");
15
16client.users().create(
17    "organization-123",
18    CreateUsersObject.builder()
19        .data(Arrays.asList(
20            UserRequestDataUnion.user(
21                UserRequestData.builder()
22                    .id("1234567890")
23                    .attributes(
24                        UserRequestAttributes.builder()
25                            .enrolledRewards(
26                                Arrays.asList(EnrolledRewardsType.CARDLINKED)
27                            )
28                            .hashedEmail(hashedEmail)
29                            .build()
30                    )
31                    .build()
32            )
33        ))
34        .build()
35);

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

2. Fetching Offers for User:

1import com.kard.api.KardApiClient;
2
3KardApiClient client = KardApiClient
4    .withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
5    .build();
6
7client.users().rewards().offers(
8    "organization-123",
9    "1234567890"
10);

3. Submitting Transaction for User:

1import com.kard.api.KardApiClient;
2import com.kard.api.resources.transactions.types.*;
3import java.util.Arrays;
4
5KardApiClient client = KardApiClient
6    .withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
7    .build();
8
9client.transactions().create(
10    "organization-123",
11    CreateTransactionsObject.builder()
12        .data(Arrays.asList(
13            TransactionsDataUnion.transaction(
14                TransactionsData.builder()
15                    .id("12345610")
16                    .attributes(
17                        TransactionsAttributes.builder()
18                            .userId("1234567890")
19                            .amount(1000)
20                            .subtotal(800)
21                            .status("APPROVED")
22                            .currency("USD")
23                            .description("ADVANCEAUTO")
24                            .authorizationDate("2021-07-02T17:47:06Z")
25                            .paymentType("CARD")
26                            .direction("DEBIT")
27                            .merchant(
28                                Merchant.builder()
29                                    .id("12345678901234567")
30                                    .name("ADVANCEAUTO")
31                                    .addrStreet("125 Main St")
32                                    .addrCity("Philadelphia")
33                                    .addrState("PA")
34                                    .addrZipcode("19147")
35                                    .addrCountry("United States")
36                                    .latitude("37.9419429")
37                                    .longitude("-73.1446869")
38                                    .storeId("12345")
39                                    .build()
40                            )
41                            .cardBIN("123456")
42                            .cardLastFour("4321")
43                            .authorizationCode("123456")
44                            .retrievalReferenceNumber("100804333919")
45                            .systemTraceAuditNumber("333828")
46                            .acquirerReferenceNumber("1234567890123456789012345678")
47                            .transactionId("12345611")
48                            .build()
49                    )
50                    .build()
51            )
52        ))
53        .build()
54);

All SDK methods return typed responses and throw typed errors.

Handling Errors

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

1import com.kard.api.core.KardApiApiException;
2
3try {
4    client.users().create(...);
5} catch (KardApiApiException e) {
6    System.out.println("Status: " + e.statusCode());
7    System.out.println("Body: " + e.body());
8}

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.

1import com.kard.api.KardApiClient;
2
3KardApiClient client = KardApiClient.builder()
4    .maxRetries(1)
5    .build();

Set a Timeout

The SDK defaults to a 60 second timeout. Timeouts can be configured at the client or request level.

1import com.kard.api.KardApiClient;
2import com.kard.api.core.RequestOptions;
3
4// Client level
5KardApiClient client = KardApiClient.builder()
6    .timeout(30)
7    .build();
8
9// Request level
10client.users().create(
11    ...,
12    RequestOptions.builder()
13        .timeout(30)
14        .build()
15);

Add Custom Headers

Headers can be configured at the client or request level.

1import com.kard.api.KardApiClient;
2import com.kard.api.core.RequestOptions;
3
4// Client level
5KardApiClient client = KardApiClient.builder()
6    .addHeader("X-Custom-Header", "custom-value")
7    .build();
8
9// Request level
10client.users().create(
11    ...,
12    RequestOptions.builder()
13        .addHeader("X-Request-Header", "request-value")
14        .build()
15);

Access Raw HTTP Responses

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

1CreateHttpResponse response = client.users().withRawResponse().create(...);
2
3System.out.println(response.body());
4System.out.println(response.headers().get("X-My-Header"));

Custom HTTP Client

The SDK works with any OkHttpClient instance. By default, the SDK constructs one, but you can provide your own.

1import com.kard.api.KardApiClient;
2import okhttp3.OkHttpClient;
3
4OkHttpClient customClient = new OkHttpClient.Builder()
5    .connectTimeout(30, java.util.concurrent.TimeUnit.SECONDS)
6    .build();
7
8KardApiClient client = KardApiClient.builder()
9    .httpClient(customClient)
10    .build();