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

# Getting Started

Welcome to the Kard API Getting Started guide. This resource will walk you through recommended integration patterns
and recommended user experiences to quickly jump start your rewards program through Kard. Whether you are making your
first API call, testing parts of your integration or preparing for your pre-production credentials call, this guide
will help you get started. We also offer **[official SDKs](/2024-10-01/sdks)** to help you integrate quickly.

If you use [Marqeta](https://www.marqeta.com/payment-solutions/digital-banking) to process your transactions than you
can see [additional details](/2024-10-01/api/getting-started#marqeta-integrations) below to help you set up your integration.

## Postman Collection and OpenAPI Spec

Download our Postman collection below and import it directly into Postman. It mirrors the folder structure of these docs, so there's nothing extra to configure on import.

Prefer your own tooling? Download the OpenAPI spec for the same endpoints to generate clients, mock servers, or import into any OpenAPI-compatible tool.

## Authenticating with the API

Kard uses OAuth 2.0 credentials for authentication.  Read [here](/2024-10-01/api/authentication) to learn more about how to connect.

# Recommended Integration Patterns

## Historical Transactions and User Management

User management is handled through Kard's User endpoints: enroll users with [Create Users](/2024-10-01/api/users/create) and maintain them with [Update User](/2024-10-01/api/users/update). Onboarding a user has two parts: enrolling them and sending their historical transactions, and the `historicalTransactionsSent` flag on the user links the two.

The flag tells Kard whether a user's prior transaction history has been provided, so targeted offers and related attribution can account for that past activity. **Until a user's historical transactions have been sent and the user's historical transactions flag has been set to `true` (`historicalTransactionsSent: true`), the user is not evaluated for targeted offers.**

For new integrations, a few rules govern the flag:

* Once set to `true`, it cannot be set back to `false`.
* If omitted at user creation, it defaults to `false`. The user is held out of targeted offers until you send their history and set the flag to `true`.
* If a user has no historical transactions to send, set it to `true` and skip the upload step entirely.

Historical transactions themselves are uploaded in bulk — see the [Historical Transaction Uploads](/2024-10-01/api/integration-guides/historical-transaction-uploads) guide for more details on how to upload. The two flows can be sequenced in one of two ways:

**Option 1: Send history first, then enroll**

1. Upload the user's historical transactions.
2. Create the user with `historicalTransactionsSent: true` → the user is evaluated for targeted offers.

**Option 2: Enroll first, then send history**

1. Create the user with `historicalTransactionsSent: false` (or omit it — it defaults to `false`).
2. Upload the user's historical transactions.
3. Update the user, setting `historicalTransactionsSent: true` → the user is now evaluated for targeted offers.

> **Note**
>
> **Already integrated before July 1, 2026?** Your default is set to `true` — users created without the `historicalTransactionsSent` flag are treated as having history sent and are evaluated for targeted offers, exactly as before. No change to your existing flow.

***Code Recipe:***

Creating a User:

* `POST /v2/issuers/{organizationId}/users`
* *required:* `id`, `enrolledRewards`

```json
{
    "data": [
        {
            "type": "user",
            "id": "438103",
            "attributes": {
                "zipCode": "30047",
                "enrolledRewards": ["CARDLINKED"],
                "historicalTransactionsSent": false
            }
        }
    ]
}
```

Updating a User:

* `PUT /v2/issuers/{organizationId}/users/{userId}`

```json
{
    "data": {
        "type": "user",
        "id": "438103",
        "attributes": {
            "zipCode": "30048",
            "enrolledRewards": ["CARDLINKED"],
            "historicalTransactionsSent": true
        }
    }
}
```

### Hashed Email (HEM)

When creating users, you can include a **Hashed Email (HEM)** to enhance offer targeting, attribution accuracy, and cross-platform user matching while preserving user privacy. A HEM is a SHA-256 hash of a normalized email address, following [UID2/LiveRamp industry standards](https://unifiedid.com/docs/getting-started/gs-normalization-encoding).

Our **[official SDKs](/2024-10-01/sdks)** include a built-in `generateHEM` utility that handles normalization and hashing. We strongly recommend using the SDK function rather than implementing your own hashing to ensure consistent results.

***Code Recipe:***

Creating a User with a Hashed Email:

#### TypeScript

```typescript
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("{organizationId}", {
    data: [{
        type: "user",
        id: "438103",
        attributes: {
            enrolledRewards: ["CARDLINKED"],
            hashedEmail: hashedEmail,
            historicalTransactionsSent: true,
        }
    }]
});
```

See the [TypeScript SDK docs](/sdks/type-script-sdk/getting-started) for more details.

#### Python

```python
from kard import KardApi
from kard.hem import generate_hem
from kard.users import UserRequestAttributes, UserRequestDataUnion_User

client = KardApi(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

hashed_email = generate_hem("Jane.Doe+work@gmail.com")

client.users.create(
    organization_id="{organizationId}",
    data=[
        UserRequestDataUnion_User(
            id="438103",
            attributes=UserRequestAttributes(
                enrolled_rewards=["CARDLINKED"],
                hashed_email=hashed_email,
                historical_transactions_sent=True,
            ),
        )
    ],
)
```

See the [Python SDK docs](/sdks/python-sdk/getting-started) for more details.

#### Java

```java
import com.kard.api.KardApiClient;
import com.kard.api.resources.commons.types.EnrolledRewardsType;
import com.kard.api.resources.users.types.CreateUsersObject;
import com.kard.api.resources.users.types.UserRequestAttributes;
import com.kard.api.resources.users.types.UserRequestData;
import com.kard.api.resources.users.types.UserRequestDataUnion;
import com.kard.hem.HEM;
import java.util.Arrays;

KardApiClient client = KardApiClient
    .withCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
    .build();

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

client.users().create(
    "{organizationId}",
    CreateUsersObject.builder()
        .data(Arrays.asList(
            UserRequestDataUnion.user(
                UserRequestData.builder()
                    .id("438103")
                    .attributes(
                        UserRequestAttributes.builder()
                            .enrolledRewards(Arrays.asList(EnrolledRewardsType.CARDLINKED))
                            .hashedEmail(hashedEmail)
                            .historicalTransactionsSent(true)
                            .build()
                    )
                    .build()
            )
        ))
        .build()
);
```

See the [Java SDK docs](/sdks/java-sdk/getting-started) for more details.

#### Go

```go
package example

import (
    context "context"

    kard "github.com/KardFinancial/kard-go-sdk"
    client "github.com/KardFinancial/kard-go-sdk/client"
    hem "github.com/KardFinancial/kard-go-sdk/hem"
    option "github.com/KardFinancial/kard-go-sdk/option"
)

func createUser() {
    c := client.NewClient(
        option.WithClientCredentials("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET"),
    )

    hashedEmail, err := hem.GenerateHEM("Jane.Doe+work@gmail.com")
    if err != nil {
        return
    }

    c.Users.Create(
        context.TODO(),
        "{organizationId}",
        &kard.CreateUsersObject{
            Data: []*kard.UserRequestDataUnion{
                {
                    User: &kard.UserRequestData{
                        Id: "438103",
                        Attributes: &kard.UserRequestAttributes{
                            EnrolledRewards: []kard.EnrolledRewardsType{
                                kard.EnrolledRewardsTypeCardlinked,
                            },
                            HashedEmail:                kard.String(hashedEmail),
                            HistoricalTransactionsSent: kard.Bool(true),
                        },
                    },
                },
            },
        },
    )
}
```

See the [Go SDK docs](/sdks/go-sdk/getting-started) for more details.

#### .NET

```csharp
using KardFinancial;
using KardFinancial.Hem;

var client = new KardClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

var hashedEmail = Hem.GenerateHEM("Jane.Doe+work@gmail.com");

await client.Users.CreateAsync(
    "{organizationId}",
    new CreateUsersObject
    {
        Data = new List<UserRequestDataUnion>()
        {
            new UserRequestDataUnion(
                new UserRequestDataUnion.User(
                    new UserRequestData
                    {
                        Id = "438103",
                        Attributes = new UserRequestAttributes
                        {
                            EnrolledRewards = new List<EnrolledRewardsType>()
                            {
                                EnrolledRewardsType.Cardlinked,
                            },
                            HashedEmail = hashedEmail,
                            HistoricalTransactionsSent = true,
                        },
                    }
                )
            ),
        },
    }
);
```

See the [.NET SDK docs](/sdks/net-sdk/getting-started) for more details.

The `generateHEM` function normalizes the email before hashing — it removes whitespace, lowercases the address, and for Gmail/Googlemail addresses, removes dots and `+` suffixes from the local part. This means `Jane.Doe+work@gmail.com` and `janedoe@gmail.com` produce the same hash.

> **Tip**
>
> Always use the SDK's `generateHEM` function rather than implementing your own hashing. The SDK handles email normalization according to industry standards, ensuring consistent hash output across all platforms.

## Transaction CLO Matching

There are three common patterns for transmitting transactions.

* **The Dual Message pattern** - one authorized transaction followed by a settled transaction.
* **The Single Message pattern** - one single settled transaction
* **The Multiple Message pattern** - one authorized transaction, and then multiple settled transactions.  Example: one purchase is authorized, but multiple products are shipped from different distributors that settle their portion of the bill separately.

#### Dual Message Pattern

The most common pattern used to transmit transactionsis the Dual Message system, also known as a Signature
transactions. Using this system, a transaction is submitted in 2 events. The first, originating event is a
temporary transaction state followed by a second event that is a final, clearing transaction state.  You may
handle transactions in other ways.  If so, please see the other options that we support below.

In order to accurately match incoming transactions, specific fields must be provided which can be found
[here](/2024-10-01/api/transactions/create).

To properly ingest a matched transaction earned reward notification webhook, check out the section on
[HMAC Signature Verification](/2024-10-01/api/integration-guides/notifications#webhook-authentication).

The following describes the Dual Message system, also known as a Signature transactions. Using this system,
a transaction is submitted in 2 events. The first, originating event is a temporary transaction state followed
by a second event that is a final, clearing transaction state.

1. Temporary Transaction Event: APPROVED
2. Final Transaction Event: SETTLED, REVERSED, DECLINED, RETURNED\*
   \*special case where the originating, temporary transaction ID is not readily identifiable

***Code Recipe: Cleared, Signature Transaction***

**Temporary transaction event:**

* status: APPROVED
* authorizationDate timestamp

```json
{
    "data": [
        {
            "type": "transaction",
            "id": "sandbox-web-313",
            "attributes": {
                "userId": "438103",
                "amount": 10000,
                "direction": "DEBIT",
                "status": "APPROVED",
                "currency": "USD",
                "description": "Hilltop BBQ",
                "mcc": "1234",
                "authorizationDate": "2022-10-29T17:48:06.135Z",
                "merchant": {
                    "id": "542814140150267",
                    "name": "Hilltop BBQ",
                    "addrCity": "Atlanta",
                    "addrState": "GA",
                    "addrZipcode": "30033",
                    "addrCountry": "United States",
                    "addrStreet": "123 Peachtree St",
                },
                "cardBIN": "123456",
                "cardLastFour": "4321",
                "authorizationCode": "123456",
                "retrievalReferenceNumber": "100804333919",
                "systemTraceAuditNumber": "333828",
                "acquirerReferenceNumber": "1234567890123456789012345678"
            }
        }
    ]
}
```

**Final transaction event:**

* status: SETTLED
* authorizationDate timestamp
* settledDate timestamp
* identical transactionId as the originating APPROVED event

```json
{
    "data": [
        {
            "type": "transaction",
            "id": "sandbox-web-313",
            "attributes": {
                "referringPartnerUserId": "438103",
                "cardBIN": "123456",
                "cardLastFour": "4321",
                "mcc": "1234",
                "merchantId": "123456789101213",
                "amount": 10000,
                "direction": "DEBIT",
                "currency": "USD",
                "description": "Hilltop BBQ",
                "merchant": {
                    "id": "542814140150267",
                    "name": "Hilltop BBQ",
                    "addrCity": "Atlanta",
                    "addrState": "GA",
                    "addrStreet": "123 Peachtree St",
                },
                "status": "SETTLED",
                "authorizationDate": "2022-10-29T17:48:06.135Z",
                "settledDate": "2022-10-30T17:48:06.135Z",
                "authorizationCode": "123456",
                "retrievalReferenceNumber": "100804333919",
                "systemTraceAuditNumber": "333828",
                "acquirerReferenceNumber": "1234567980123456789012345687",
                "isDeposit": false
            }
        }
    ]
}
```

***Code Recipe: Reversed, Signature Transaction***

*Sending Reversal infomration enables the platform's Transaction Monitoring, where Kard conducts internal fraud
detection to identify suspicious behavior through abnormal transaction amounts and high volume transactions or
returns per user on a daily basis. We then notify Issuers of any potential fraud to be investigated if it is
found.*

**Temporary transaction event:**

* status: APPROVED
* authorizationDate timestamp

```json
{
    "data": [
        {
            "type": "transaction",
            "id": "sandbox-web-313",
            "attributes": {
                "referringPartnerUserId": "438103",
                "cardBIN": "123456",
                "cardLastFour": "4321",
                "amount": 10000,
                "direction": "DEBIT",
                "mcc": "1234",
                "currency": "USD",
                "description": "Hilltop BBQ",
                "merchant": {
                    "id": "542814140150267",
                    "name": "Hilltop BBQ",
                    "addrCity": "Atlanta",
                    "addrState": "GA",
                    "addrStreet": "123 Peachtree St",
                },
                "status": "APPROVED",
                "authorizationDate": "2022-10-29T17:48:06.135Z",
                "authorizationCode": "123456",
                "retrievalReferenceNumber": "100804333919",
                "systemTraceAuditNumber": "333828",
                "acquirerReferenceNumber": "1234567980123456789012345687",
                "isDeposit": false
            }
        }
    ]
}
```

**Final transaction event:**

* status: REVERSED
* transactionDate timestamp
* identical transactionId as the originating APPROVED event

```json
{
    "data": [
        {
            "type": "transaction",
            "id": "sandbox-web-313",
            "attributes": {
                "referringPartnerUserId": "438103",
                "cardBIN": "123456",
                "cardLastFour": "4321",
                "amount": 10000,
                "direction": "DEBIT",
                "mcc": "1234",
                "currency": "USD",
                "description": "Hilltop BBQ",
                "merchant": {
                    "id": "542814140150267",
                    "name": "Hilltop BBQ",
                    "addrCity": "Atlanta",
                    "addrState": "GA",
                    "addrStreet": "123 Peachtree St",
                },
                "status": "REVERSED",
                "transactionDate": "2022-10-30T17:48:06.135Z"
            }
        }
    ]
}
```

#### Single Message Pattern

The Single Message system is also known as a PIN debit transaction. In these transactions, the user is required
to enter a PIN. The PIN is validated in real-time by the bank, so a transaction submitted as a single message will be
a final transaction event and the authorization and settlement dates are effectively the same.

In order to accurately match incoming transactions, specific fields must be provided which can be found
[here](/2024-10-01/api/transactions/create).

To properly ingest a matched transaction earned reward notification webhook, check out the section on
[HMAC Signature Verification](/2024-10-01/api/integration-guides/notifications#webhook-authentication).

***Code Recipe: Clearing, PIN debit Transaction***

* status: SETTLED
* authorizationDate timestamp
* settledDate timestamp

```json
{
    "data": [
        {
            "type": "transaction",
            "id": "sandbox-web-313",
            "attributes": {
                "referringPartnerUserId": "438103",
                "cardBIN": "123456",
                "cardLastFour": "4321",
                "amount": 10000,
                "direction": "DEBIT",
                "mcc": "1234",
                "currency": "USD",
                "description": "Hilltop BBQ",
                "merchant": {
                    "id": "542814140150267",
                    "name": "Hilltop BBQ",
                    "addrCity": "Atlanta",
                    "addrState": "GA",
                    "addrStreet": "123 Peachtree St",
                },
                "status": "SETTLED",
                "authorizationDate": "2022-10-29T17:48:06.135Z",
                "settledDate": "2022-10-30T17:48:06.135Z",
                "authorizationCode": "123456",
                "retrievalReferenceNumber": "100804333919",
                "systemTraceAuditNumber": "333828",
                "acquirerReferenceNumber": "1234567980123456789012345687",
                "isDeposit": false
            }
        }
    ]
}
```

#### Multiple Message Pattern

This pattern is one where a single authorization is followed by multiple settlement events. This pattern
is generally seen when a single transaction represents multiple objects.

For example, imagine using an e-commerce site and checking out a cart with multiple items. If these items
are shipped individually, there may be multiple, subsequent settlement events.

In order to accurately match incoming transactions, specific fields must be provided which can be found
[here](/2024-10-01/api/transactions/create).

To properly ingest a matched transaction earned reward notification webhook, check out the section on
[HMAC Signature Verification](/2024-10-01/api/integration-guides/notifications#webhook-authentication).

***Code Recipe: Single Auth, Multiple Settlements Transaction***

* identical referringPartnerUserId for all events
* identical transactionId for all events
* different settledDate timestamps for each SETTLED event

**Temporary transaction event: (1 of 1)**

* status: APPROVED
* authorizationDate timestamp ("2022-10-29T17:48:06.135Z")
* \$100 transaction amount

```json
{
    "data": [
        {
            "type": "transaction",
            "id": "sandbox-web-323",
            "attributes": {
                "referringPartnerUserId": "438103",
                "cardBIN": "123456",
                "cardLastFour": "4321",
                "amount": 10000,
                "direction": "DEBIT",
                "mcc": "1234",
                "currency": "USD",
                "description": "Hilltop BBQ",
                "merchant": {
                    "id": "542814140150267",
                    "name": "Hilltop BBQ",
                    "addrCity": "Atlanta",
                    "addrState": "GA",
                    "addrStreet": "123 Peachtree St",
                },
                "status": "APPROVED",
                "authorizationDate": "2022-10-29T17:48:06.135Z"
            }
        }
    ]
}
```

**Final transaction event: (1 of 2)**

* status: SETTLED
* authorization timestamp ("2022-10-***30***&#x54;17:48:06.135Z")
* settledDate timestamp ("2022-10-***30***&#x54;18:48:06.135Z")
* \$75 transaction amount

```json
{
    "data": [
        {
            "type": "transaction",
            "id": "sandbox-web-323",
            "attributes": {
                "referringPartnerUserId": "438103",
                "cardBIN": "123456",
                "cardLastFour": "4321",
                "amount": 7500,
                "direction": "DEBIT",
                "mcc": "1234",
                "currency": "USD",
                "description": "Hilltop BBQ",
                "merchant": {
                    "id": "542814140150267",
                    "name": "Hilltop BBQ",
                    "addrCity": "Atlanta",
                    "addrState": "GA",
                    "addrStreet": "123 Peachtree St",
                },
                "status": "SETTLED",
                "authorizationDate": "2022-10-30T17:48:06.135Z",
                "settledDate": "2022-10-30T18:48:06.135Z"
            }
        }
    ]
}
```

**Final transaction event: (2 of 2)**

* status: SETTLED
* authorizationDate timestamp ("2022-10-***30***&#x54;17:48:06.135Z")
* settledDate timestamp ("2022-10-***31***&#x54;18:48:06.135Z")
* \$25 transaction amount

```json
{
    "data": [
        {
            "type": "transaction",
            "id": "sandbox-web-323",
            "attributes": {
                "referringPartnerUserId": "438103",
                "cardBIN": "123456",
                "cardLastFour": "4321",
                "amount": 2500,
                "direction": "DEBIT",
                "mcc": "1234",
                "currency": "USD",
                "description": "Hilltop BBQ",
                "merchant": {
                    "id": "542814140150267",
                    "name": "Hilltop BBQ",
                    "addrCity": "Atlanta",
                    "addrState": "GA",
                    "addrStreet": "123 Peachtree St",
                },
                "status": "SETTLED",
                "authorizationDate": "2022-10-30T17:48:06.135Z"
                "settledDate": "2022-10-31T18:48:06.135Z"
            }
        }
    ]
}
```

## Transaction Reconciliation

There are two standard reconciliation reports that Kard issues: Daily files and end of month (EOM) files. Both of these
files can be retrieved using the [GET Files](/2024-10-01/api/files/get-metadata) endpoint.

### Daily Reconciliation File

At the end of each day, a daily reconciliation file of transactions is automatically generated and available via the
endpoint. This file will be ideal for your team to compare against received earned reward approved and settled
notification webhooks and will act as a ledger until the EOM file is generated.

* The file is generated at 4:30 am EST. This is midnight UTC, so it’ll shift by an hour when we enter Daylight Savings Time.
* file naming convention: `cardlinked-reconciliation-YYMMDD`
* file format: `.json`

#### Code recipe

* `GET` [Files](/2024-10-01/api/files/get-metadata) Endpoint
* `organizationId` path param: the organization id given to you by the Kard Team.
* `fileType` query param: `dailyReconciliationFile`

```javascript
var axios = require('axios');

var config = {
    method: 'get',
    url: 'https://test-rewards-api.getkard.com/v2/issuers/{organizationId}/files?fileType=dailyReconciliationFile',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'redacted_token'
    }
};

axios(config)
.then(function (response) {
    console.log(JSON.stringify(response.data));
})
.catch(function (error) {
    console.log(error);
});
```

Use the `attributes.downloadUrl` field in the [returned response](/2024-10-01/api/files/get-metadata) to access your daily
reconciliation files.

### EOM Reconciliation File

On the 15th (or following business day in case the 15th should fall on a weekend or a holiday) each month, a monthly
reconciliation file will be available via the endpoint. The EOM reconciliation report contains only `SETTLED`
transactions that occurred in the previous month both `PAID_IN_FULL` and `PENDING`, as well as all `PENDING`
transactions from all previous months that still have yet to be paid, and `PAID_IN_FULL` transactions from previous
months that are being paid out that month.

* file naming convention: `cardlinked-reconciliation-YYMM`
* file format: `.csv`

#### Code recipe

* `GET` [Files](/2024-10-01/api/files/get-metadata) Endpoint
* `organizationId` path param: the organization id given to you by the Kard Team.
* `fileType` query param: `monthlyReconciliationFile`

```javascript
var axios = require('axios');

var config = {
    method: 'get',
    url: 'https://test-rewards-api.getkard.com/v2/issuers/{organizationId}/files?fileType=monthlyReconciliationFile',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'redacted_token'
    }
};

axios(config)
.then(function (response) {
    console.log(JSON.stringify(response.data));
})
.catch(function (error) {
    console.log(error);
});
```

Use the `attributes.downloadUrl` field in the [returned response](/2024-10-01/api/files/get-metadata) to access your monthly
reconciliation files.

### Payouts

* Merchants: Merchant terms are generally Net 30 across our merchant partners, but payment can be up to Net 90.
* Issuers: the product supports the 2 following options for payouts to end users.
  * Immediate
    * Issuers may opt to disburse payments to their end-users immediately, or shortly after a transaction occurs. By selecting this option, the issuer agrees to front the payment amounts to the end-users. Kard will reimburse the issuer for these payments once Kard receives the corresponding commissions from the Merchants.
  * Withheld
    * Alternatively, issuers may choose to withhold payments to their end-users until such time as they have received the corresponding commission payments from Kard. This option allows issuers to avoid fronting the payment amounts.

# Testing The User Experiences

#### A. Discover a New Customer CLO

* `GET` [Get Offers By User](/2024-10-01/api/rewards/offers) Endpoint
* `organizationId` path param: the organization id given to you by the Kard Team.
* `userId` path param: `sandbox-{issuerName}-new-customer`

```javascript
var axios = require('axios');

var config = {
    method: 'get',
    url: 'https://test-rewards-api.getkard.com/v2/issuers/{organizationId}/users/sandbox-{issuerName}-new-customer/offers',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'redacted_token'
    }
};

axios(config)
.then(function (response) {
    console.log(JSON.stringify(response.data));
})
.catch(function (error) {
    console.log(error);
});
```

#### B. Discover a Lapsed Customer CLO

* `GET` [Get Offers By User](/2024-10-01/api/rewards/offers) Endpoint
* `organizationId` path param: the organization id given to you by the Kard Team.
* `userId` path param: `sandbox-{issuerName}-lapsed-customer`

```javascript
var axios = require('axios');

var config = {
    method: 'get',
    url: 'https://test-rewards-api.getkard.com/v2/issuers/{organizationId}/users/sandbox-{issuerName}-lapsed-customer/offers',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'redacted_token'
    }
};

axios(config)
.then(function (response) {
    console.log(JSON.stringify(response.data));
})
.catch(function (error) {
    console.log(error);
});
```

#### C. Discover CLOs Near You (Map View)

* `GET` [Get Locations By User](/2024-10-01/api/rewards/locations) Endpoint
* `organizationId` path param: the organization id given to you by the Kard Team.
* `userId` path param: `sandbox-{issuerName}-new-customer`
* query params:
  * `longitude=-73.9930148`
  * `latitude=40.74201480000001`

```javascript
var axios = require('axios');

var config = {
    method: 'get',
    url: 'https://test-rewards-api.getkard.com/v2/issuers/{organizationId}/users/sandbox-{issuerName}-new-customer/locations?longitude=-73.9930148&latitude=40.74201480000001',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'redacted_token'
    }
};

axios(config)
.then(function (response) {
    console.log(JSON.stringify(response.data));
})
.catch(function (error) {
    console.log(error);
});
```

#### D. Trigger Earned Reward Notification

The following steps provide a demo experience from the perspective of the `sandbox-{issuerName}-new-customer`
user.

1. Discover Eligible New Customer Offers

* `GET` **[Get Offers By User](/2024-10-01/api/rewards/offers)** Endpoint

```json
{
    "data": [
        {
            "type": "standardOffer",
            "attributes": {
                "assets": [
                    {
                        "type": "LOGO_IMAGE",
                        "url": "http://assets.getkard.com/logo/img?attribution-tokens",
                        "alt": "BaaS Pro Shops Logo Image"
                    },
                    {
                        "type": "BANNER_IMAGE",
                        "url": "http://assets.getkard.com/banner/img?attribution-tokens",
                        "alt": "BaaS Pro Shops Banner Image"
                    }
                ],
                "expirationDate": "2025-03-01T05:00:00Z",
                "isTargeted": true,
                "name": "BaaS Pro Shops",
                "purchaseChannel": [
                    "INSTORE"
                ],
                "startDate": "2023-03-01T05:00:00Z",
                "terms": "This offer is only valid for first-time customers.",
                "userReward": {
                    "type": "FLAT",
                    "value": 20
                },
                "description": "From state-of-the-art smartphones and laptops to smart home devices and audio gear, we bring you top brands at unbeatable prices. Our knowledgeable team is dedicated to helping you find the perfect product to enhance your digital lifestyle. Shop with us and experience fast delivery, expert advice, and the best in modern technology!",
                "websiteUrl": "https://www.kardbaasproshops.com"
            },
            "id": "654d3fce9587960008944c61",
            "relationships": {
                "category": {
                    "data": [
                        {
                            "type": "category",
                            "id": "65920081b524d126068de24a"
                        }
                    ]
                }
            }
        }
    ],
    "links": {
        "self": "/v2/issuers/{organizationId}/users/{userId}/offers?page[size]=1?sort=-startDate",
        "prev": null,
        "next": "/v2/issuers/{organizationId}/users/{userId}/offers?page[after]=NDMyNzQyODI3OTQw&page[size]=1?&sort=-startDate"
    },
    "included": [
        {
            "type": "category",
            "id": "65920081b524d126068de24a",
            "attributes": {
                "name": "Food & Beverage"
            }
        }
    ]
}
```

2. Submit Eligible Approved Transaction

* `POST` **[Incoming Transactions](/2024-10-01/api/transactions/create)** Endpoint
* Map Rewards offer `attributes.name` to Incoming Transaction `description`

```json
{
    "data": [
        {
            "type": "transaction",
            "id": "sandbox-web-313",
            "attributes": {
                "userId": "sandbox-{issuerName}-new-customer",
                "cardBIN": "123456",
                "cardLastFour": "4321",
                "amount": 10000,
                "direction": "DEBIT",
                "mcc": "1234",
                "currency": "USD",
                "description": "BaaS Pro Shops",
                "status": "APPROVED",
                "authorizationDate": "2023-03-29T17:48:06.135Z",
                "authorizationCode": "123456",
                "retrievalReferenceNumber": "100804333919",
                "systemTraceAuditNumber": "333828",
                "acquirerReferenceNumber": "1234567980123456789012345687"
            }
        }
    ]
}
```

3. Ingest Earned Reward Approved Notification Webhook

* `POST` **[Notifications Webhook](/2024-10-01/api/notifications/notification-webhook)**
* Authenticate webhook using [HMAC Signature Verification](/2024-10-01/api/integration-guides/notifications#webhook-authentication)
  ```json
  {
      "data": {
          "type": "earnedRewardApproved",
          "attributes": {
              "attributionUrl": "www.attribution.com/token",
              "message": "Congrats! You have earned a pending reward on your purchase at BaaS Pro Shops!",
              "name": "BaaS Pro Shops",
              "surveyUrl": "www.survey.com"
          },
          "id": "d80a6f28-1b24-4d65-9e42-e1cf3379bc98",
          "relationships": {
              "user": {
                  "data": {
                      "type": "user",
                      "id": "sandbox-{issuerName}-new-customer"
                  }
              }
          }
      }
  }
  ```
* Delight your user with a notification!
  * Use attributes.message to serve the push notification:

    ![pending reward notification](/_fern-img/c7653a0e62e1bee8f87303c2f2ac20e5a26ebe13d17c3fe0af8c765e61e7b99d.webp)

4. Submit Eligible Settled Transaction

* `POST` **[Incoming Transactions](/2024-10-01/api/transactions/create)** Endpoint
* Map Rewards offer `attributes.name` to Incoming Transaction `description`
  ```json
  {
      "data": [
          {
              "type": "transaction",
              "id": "sandbox-web-319",
              "attributes": {
                  "userId": "sandbox-{issuerName}-new-customer",
                  "cardBIN": "123456",
                  "cardLastFour": "4321",
                  "amount": 10000,
                  "direction": "DEBIT",
                  "mcc": "1234",
                  "currency": "USD",
                  "description": "BaaS Pro Shops",
                  "status": "SETTLED",
                  "authorizationDate": "2023-03-29T17:48:06.135Z",
                  "settledDate": "2023-03-30T17:48:06.135Z",
                  "authorizationCode": "123456",
                  "retrievalReferenceNumber": "100804333919",
                  "systemTraceAuditNumber": "333828",
                  "acquirerReferenceNumber": "1234567980123456789012345687"
              }
          }
      ]
  }
  ```

5. Ingest Earned Reward Settled Notification Webhook

* `POST` **[Notifications Webhook](/2024-10-01/api/notifications/notification-webhook)**
* Authenticate webhook using **[HMAC Signature Verification](/2024-10-01/api/integration-guides/notifications#webhook-authentication)**
  ```json
  {
  "data": {
      "type": "earnedRewardSettled",
      "attributes": {
      "attributionUrl": "www.attribution.com/token",
      "commissionEarned": {
          "type": "cents",
          "value": 2000
      },
      "message": "Congrats! You have earned a $20.00 reward on your purchase at BaaS Pro Shops!",
      "name": "BaaS Pro Shops",
      "surveyUrl": "www.survey.com"
      },
      "id": "d80a6f28-1b24-4d65-9e42-e1cf3379bc98",
      "relationships": {
      "user": {
          "data": {
          "type": "user",
          "id": "sandbox-{issuerName}-new-customer"
          }
      }
      }
  }
  }
  ```
* Delight your user with a rewards confirmation notification!
  * Use `attributes.message` to serve the push notification:

    ![earned reward notification](/_fern-img/3a349f3554ee2ba6dfc44977e890d75a4b09ed1c795430259164222495de5759.webp)

#### E. Track User Attributions

For issuers using event tracking via images on the eligibility endpoints:

1. To test that attribution is flowing to Kard, please load the asset urls from the endpoint or webhook you would
   like to test. We recommend sending both the **`IMPRESSION`** event and the **`VIEW`** event and medium, while
   testing in sandbox. Once you are finished with testing, please provide the **`eventCode`**, **`medium`** and
   the id of the resource related to the asset url, to your AM/solutions architect so that the team can validate.
2. If an invalid query **`eventCode`** or **`medium`** is supplied the image will return a 400 error with a
   description of the issue. It is important to note in production image delivery is prioritized so errors will
   not be returned in production.

For issuers using event tracking via attribution API endpoint:

1. To test that attribution is flowing to Kard, please send requests to the endpoint defined above in your sandbox
   environment. We recommend sending both the **`IMPRESSION`** event and the **`VIEW`** event and medium, while
   testing in sandbox. Once you receive a response code, please notify your AM and solutions architect to verify
   that events were correctly posted to Kard. Please provide the **`eventCode`**, **`medium`** and **`typeID`**
   so that the team can validate.

During the pre-production call, you will be asked to show the end-to-end user flow, and asked to simulate both
an **`IMPRESSION`** event and **`VIEW`** event by navigating your UX experience. For more information see
[Attributions](/2024-10-01/api/attributions).

# User Acceptance Test Cases

#### As a user, I should be able to successfully:

* Enroll in the rewards program.
* Unenroll from the rewards program.
* Add a card to my profile.
* View a list of eligible ONLINE rewards.
  * Submit attribution data points for impressions and views
* View a list of eligible INSTORE rewards.
  * Submit attribution data points for impressions and views
* View a list of eligible rewards near me.
  * Submit attribution data points for impressions and views
* View Offer Details.
  * Submit attribution data points for impressions and views
* Submit a Clearing, Dual Message Transaction.
  * Submit an APPROVED(aka AUTH) event to the Incoming Transactions Endpoint
  * Submit a SETTLED (aka CLEARED) event to the Incoming Transactions Endpoint
* Submit a Declined, Dual Message Transaction.
  * Submit an APPROVED(aka AUTH) event to the Incoming Transactions Endpoint
  * Submit a DECLINED event to the Incoming Transactions Endpoint
* Submit a Reversed, Dual Message Transaction.
  * Submit an APPROVED(aka AUTH) event to the Incoming Transactions Endpoint
  * Submit a REVERSED (aka CLEARED) event to the Incoming Transactions Endpoint
* Submit a Single Message, PIN-debit Transaction.
  * Submit a SETTLED (aka CLEARED) event to the Incoming Transactions Endpoint
* Submit a Refund Transaction.
  * Submit a RETURNED event to the Incoming Transactions Endpoint
* Receive an Earned Reward Approved Webhook push notification
  * Submit attribution data points for impressions and views
* Receive an Earned Reward Settled Webhook push notification
  * Submit attribution data points for impressions and views

#### As a rewards program manager, I should be able to successfully:

* Consume recon files.
  * Daily
  * Monthly
* Create an Audit Request.
* Get an Audit Request Status.

# Marqeta Integrations

Marqeta has it's own user and transaction management systems.  If you are using these to power your platform you can
integrate those flows directly with Kard rather than writing custom integrations.

Some key differences in terminology are outlined below, and you can find out more [here](https://www.getkard.com/docs/marqeta-kard-integration).

#### Transactions

Transaction Status Mapping

Kard currently receives the following transaction event types from Marqeta:

| Marqeta                | Kard     |
| ---------------------- | -------- |
| authorization          | Approved |
| authorization.clearing | Settled  |
| pindebit               | Settled  |

Note: The data mapping for the transaction events below also apply to Kard’s Earned Rewards Webhook.

| Marqeta Field                                                                                                          | Kard Field                         |
| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| token                                                                                                                  | transactionId                      |
| user.metadata.user\_id                                                                                                 | referringPartnerUserId             |
| Note: Optional. Only needed if the user is created with a different referringPartnerUserId than Marqeta's user\_token. |                                    |
| user\_token                                                                                                            | referringPartnerUserId             |
| Note: Used when `user.metadata.user_id` is not set.                                                                    |                                    |
| user\_transaction\_time                                                                                                | transactionDate, authorizationDate |
| Note: Depending on status of transaction                                                                               |                                    |
| settlement\_date                                                                                                       | settledDate                        |
| amount                                                                                                                 | amount                             |
| state                                                                                                                  | status                             |
| preceding\_related\_transaction\_token                                                                                 | transactionId                      |
| Note: valid for transactions after the first transaction event                                                         |                                    |
| card\_acceptor.mcc                                                                                                     | mcc                                |
| card\_acceptor.name                                                                                                    | merchantName                       |
| card\_acceptor.street\_address                                                                                         | merchantAddrStreet                 |
| card\_acceptor.city                                                                                                    | merchantAddrCity                   |
| card\_acceptor.state                                                                                                   | merchantAddrState                  |
| card\_acceptor.zip                                                                                                     | merchantAddrZipcode                |
| card.last\_four                                                                                                        | cardLastFour                       |
| card.pan                                                                                                               | cardBIN                            |
| Note: Kard receives a masked PAN, only showing BIN and Last 4                                                          |                                    |
| currency\_code                                                                                                         | currency                           |
| card\_acceptor.mid                                                                                                     | merchantId                         |
| card\_acceptor.name                                                                                                    | description                        |
| network\_reference\_id                                                                                                 | transactionId                      |
| Note: This is relevant for specific integrations. Consult your Kard Account Manager with questions                     |                                    |

#### FIPS

FIPS State Abbreviation mappings
FIPS codes are numbers which uniquely identify geographic areas

| FIPS State Code | State                |
| --------------- | -------------------- |
| 01              | ALABAMA              |
| 02              | ALASKA               |
| 04              | ARIZONA              |
| 05              | ARKANSAS             |
| 06              | CALIFORNIA           |
| 08              | COLORADO             |
| 09              | CONNECTICUT          |
| 10              | DELAWARE             |
| 11              | DISTRICT OF COLUMBIA |
| 12              | FLORIDA              |
| 13              | GEORGIA              |
| 15              | HAWAII               |
| 16              | IDAHO                |
| 17              | ILLINOIS             |
| 18              | INDIANA              |
| 19              | IOWA                 |
| 20              | KANSAS               |
| 21              | KENTUCKY             |
| 22              | LOUISIANA            |
| 23              | MAINE                |
| 24              | MARYLAND             |
| 25              | MASSACHUSETTS        |
| 26              | MICHIGAN             |
| 27              | MINNESOTA            |
| 28              | MISSISSIPPI          |
| 29              | MISSOURI             |
| 30              | MONTANA              |
| 31              | NEBRASKA             |
| 32              | NEVADA               |
| 33              | NEW HAMPSHIRE        |
| 34              | NEW JERSEY           |
| 35              | NEW MEXICO           |
| 36              | NEW YORK             |
| 37              | NORTH CAROLINA       |
| 38              | NORTH DAKOTA         |
| 39              | OHIO                 |
| 40              | OKLAHOMA             |
| 41              | OREGON               |
| 42              | PENNSYLVANIA         |
| 44              | RHODE ISLAND         |
| 45              | SOUTH CAROLINA       |
| 46              | SOUTH DAKOTA         |
| 47              | TENNESSEE            |
| 48              | TEXAS                |
| 49              | UTAH                 |
| 50              | VERMONT              |
| 51              | VIRGINIA             |
| 53              | WASHINGTON           |
| 54              | WEST VIRGINIA        |
| 55              | WISCONSIN            |
| 56              | WYOMING              |