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.

Note, this guide will use the most up to date API definitions. Incoming Transactions API, Rewards APIs and notifications webhooks will reference the 2024-10-01 version and the remaining APIs will reference the legacy definitions.

If you use Marqeta to process your transactions than you can see additional details below to help you set up your integration.

Authenticating with the API

Kard uses OAuth 2.0 credentials for authentication. Read here to learn more about how to connect.

Use our Postman API to test your connection

Postman Collection Coming Soon!

Recommended Integration Patterns

User Management

Kard supports two different patterns for getting users into your system. The card issuer pattern where you add users who you have provisioned a card to, and the aggregator pattern where you collect multiple cards not issued by you. If you use both patterns than you will be given two different environments. One for your self-issued cards, and one for your aggregated cards.

If your application supports cards issued by your program manager transactions will originate from known cardBINs and networks so a user can be created with or without card-level information. If creating without the cardInfo object, the user can later be updated.

Code Recipe:

Creating a User:

  • required: userName OR email, referringPartnerUserId, zipCode
1{
2    "email": "testuser@test-TEST.com",
3    "userName": "testUser",
4    "referringPartnerUserId": "438103",
5    "zipCode": "30047",
6}

Add cardInfo to User:

  • cardInfo[“issuer”]: Program Name as known to Kard, rather than the underlying Card Issuer
  • required: referringPartnerUserId, cardInfo
1{
2    "referringPartnerUserId": "438103",
3    "cardInfo": {
4        "last4": "4321",
5        "bin": "123456",
6        "issuer": "TEST",
7        "network": "VISA"
8    }
9}

Targeted Offers

Each sandbox environment is configured with the following user personas:

  • sandbox-{issuerName}-new-customer: this user has no record of prior transactions at the merchant.
  • sandbox-{issuerName}-lapsed-customer: this user has prior transaction history at the merchant, but none within the last 6 months.

These personas demonstrate targeting functionality in terms of offer discovery (the user is viewing a personalized offer) and transaction matching (the user transaction matches to the personalized offer). The {issuerName} variable is provided in the sandbox environment.json.

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.

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.

To properly ingest a matched transaction earned reward notification webhook, check out the section on HMAC Signature Verification.

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
1{
2    "data": [
3        {
4            "type": "transaction",
5            "id": "sandbox-web-313",
6            "attributes": {
7                "userId": "438103",
8                "amount": 10000,
9                "direction": "DEBIT",
10                "status": "APPROVED",
11                "currency": "USD",
12                "description": "Hilltop BBQ",
13                "mcc": "1234",
14                "authorizationDate": "2022-10-29T17:48:06.135Z",
15                "merchant": {
16                    "id": "542814140150267",
17                    "name": "Hilltop BBQ",
18                    "addrCity": "Atlanta",
19                    "addrState": "GA",
20                    "addrZipcode": "30033",
21                    "addrCountry": "United States",
22                    "addrStreet": "123 Peachtree St",
23                },
24                "cardBIN": "123456",
25                "cardLastFour": "4321",
26                "authorizationCode": "123456",
27                "retrievalReferenceNumber": "100804333919",
28                "systemTraceAuditNumber": "333828",
29                "acquirerReferenceNumber": "1234567890123456789012345678"
30            }
31        }
32    ]
33}

Final transaction event:

  • status: SETTLED
  • authorizationDate timestamp
  • settledDate timestamp
  • identical transactionId as the originating APPROVED event
1{
2    "data": [
3        {
4            "type": "transaction",
5            "id": "sandbox-web-313",
6            "attributes": {
7                "referringPartnerUserId": "438103",
8                "cardBIN": "123456",
9                "cardLastFour": "4321",
10                "mcc": "1234",
11                "merchantId": "123456789101213",
12                "amount": 10000,
13                "direction": "DEBIT",
14                "currency": "USD",
15                "description": "Hilltop BBQ",
16                "merchant": {
17                    "id": "542814140150267",
18                    "name": "Hilltop BBQ",
19                    "addrCity": "Atlanta",
20                    "addrState": "GA",
21                    "addrStreet": "123 Peachtree St",
22                },
23                "status": "SETTLED",
24                "authorizationDate": "2022-10-29T17:48:06.135Z",
25                "settledDate": "2022-10-30T17:48:06.135Z",
26                "authorizationCode": "123456",
27                "retrievalReferenceNumber": "100804333919",
28                "systemTraceAuditNumber": "333828",
29                "acquirerReferenceNumber": "1234567980123456789012345687",
30                "isDeposit": false
31            }
32        }
33    ]
34}

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
1{
2    "data": [
3        {
4            "type": "transaction",
5            "id": "sandbox-web-313",
6            "attributes": {
7                "referringPartnerUserId": "438103",
8                "cardBIN": "123456",
9                "cardLastFour": "4321",
10                "amount": 10000,
11                "direction": "DEBIT",
12                "mcc": "1234",
13                "currency": "USD",
14                "description": "Hilltop BBQ",
15                "merchant": {
16                    "id": "542814140150267",
17                    "name": "Hilltop BBQ",
18                    "addrCity": "Atlanta",
19                    "addrState": "GA",
20                    "addrStreet": "123 Peachtree St",
21                },
22                "status": "APPROVED",
23                "authorizationDate": "2022-10-29T17:48:06.135Z",
24                "authorizationCode": "123456",
25                "retrievalReferenceNumber": "100804333919",
26                "systemTraceAuditNumber": "333828",
27                "acquirerReferenceNumber": "1234567980123456789012345687",
28                "isDeposit": false
29            }
30        }
31    ]
32}

Final transaction event:

  • status: REVERSED
  • transactionDate timestamp
  • identical transactionId as the originating APPROVED event
1{
2    "data": [
3        {
4            "type": "transaction",
5            "id": "sandbox-web-313",
6            "attributes": {
7                "referringPartnerUserId": "438103",
8                "cardBIN": "123456",
9                "cardLastFour": "4321",
10                "amount": 10000,
11                "direction": "DEBIT",
12                "mcc": "1234",
13                "currency": "USD",
14                "description": "Hilltop BBQ",
15                "merchant": {
16                    "id": "542814140150267",
17                    "name": "Hilltop BBQ",
18                    "addrCity": "Atlanta",
19                    "addrState": "GA",
20                    "addrStreet": "123 Peachtree St",
21                },
22                "status": "REVERSED",
23                "transactionDate": "2022-10-30T17:48:06.135Z"
24            }
25        }
26    ]
27}

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.

To properly ingest a matched transaction earned reward notification webhook, check out the section on HMAC Signature Verification.

Code Recipe: Clearing, PIN debit Transaction

  • status: SETTLED
  • authorizationDate timestamp
  • settledDate timestamp
1{
2    "data": [
3        {
4            "type": "transaction",
5            "id": "sandbox-web-313",
6            "attributes": {
7                "referringPartnerUserId": "438103",
8                "cardBIN": "123456",
9                "cardLastFour": "4321",
10                "amount": 10000,
11                "direction": "DEBIT",
12                "mcc": "1234",
13                "currency": "USD",
14                "description": "Hilltop BBQ",
15                "merchant": {
16                    "id": "542814140150267",
17                    "name": "Hilltop BBQ",
18                    "addrCity": "Atlanta",
19                    "addrState": "GA",
20                    "addrStreet": "123 Peachtree St",
21                },
22                "status": "SETTLED",
23                "authorizationDate": "2022-10-29T17:48:06.135Z",
24                "settledDate": "2022-10-30T17:48:06.135Z",
25                "authorizationCode": "123456",
26                "retrievalReferenceNumber": "100804333919",
27                "systemTraceAuditNumber": "333828",
28                "acquirerReferenceNumber": "1234567980123456789012345687",
29                "isDeposit": false
30            }
31        }
32    ]
33}

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.

To properly ingest a matched transaction earned reward notification webhook, check out the section on HMAC Signature Verification.

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
1{
2    "data": [
3        {
4            "type": "transaction",
5            "id": "sandbox-web-323",
6            "attributes": {
7                "referringPartnerUserId": "438103",
8                "cardBIN": "123456",
9                "cardLastFour": "4321",
10                "amount": 10000,
11                "direction": "DEBIT",
12                "mcc": "1234",
13                "currency": "USD",
14                "description": "Hilltop BBQ",
15                "merchant": {
16                    "id": "542814140150267",
17                    "name": "Hilltop BBQ",
18                    "addrCity": "Atlanta",
19                    "addrState": "GA",
20                    "addrStreet": "123 Peachtree St",
21                },
22                "status": "APPROVED",
23                "authorizationDate": "2022-10-29T17:48:06.135Z"
24            }
25        }
26    ]
27}

Final transaction event: (1 of 2)

  • status: SETTLED
  • authorization timestamp (“2022-10-30T17:48:06.135Z”)
  • settledDate timestamp (“2022-10-30T18:48:06.135Z”)
  • $75 transaction amount
1{
2    "data": [
3        {
4            "type": "transaction",
5            "id": "sandbox-web-323",
6            "attributes": {
7                "referringPartnerUserId": "438103",
8                "cardBIN": "123456",
9                "cardLastFour": "4321",
10                "amount": 7500,
11                "direction": "DEBIT",
12                "mcc": "1234",
13                "currency": "USD",
14                "description": "Hilltop BBQ",
15                "merchant": {
16                    "id": "542814140150267",
17                    "name": "Hilltop BBQ",
18                    "addrCity": "Atlanta",
19                    "addrState": "GA",
20                    "addrStreet": "123 Peachtree St",
21                },
22                "status": "SETTLED",
23                "authorizationDate": "2022-10-30T17:48:06.135Z",
24                "settledDate": "2022-10-30T18:48:06.135Z"
25            }
26        }
27    ]
28}

Final transaction event: (2 of 2)

  • status: SETTLED
  • authorizationDate timestamp (“2022-10-30T17:48:06.135Z”)
  • settledDate timestamp (“2022-10-31T18:48:06.135Z”)
  • $25 transaction amount
1{
2    "data": [
3        {
4            "type": "transaction",
5            "id": "sandbox-web-323",
6            "attributes": {
7                "referringPartnerUserId": "438103",
8                "cardBIN": "123456",
9                "cardLastFour": "4321",
10                "amount": 2500,
11                "direction": "DEBIT",
12                "mcc": "1234",
13                "currency": "USD",
14                "description": "Hilltop BBQ",
15                "merchant": {
16                    "id": "542814140150267",
17                    "name": "Hilltop BBQ",
18                    "addrCity": "Atlanta",
19                    "addrState": "GA",
20                    "addrStreet": "123 Peachtree St",
21                },
22                "status": "SETTLED",
23                "authorizationDate": "2022-10-30T17:48:06.135Z"
24                "settledDate": "2022-10-31T18:48:06.135Z"
25            }
26        }
27    ]
28}

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 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
  • GET Files Endpoint
  • organizationId path param: the organization id given to you by the Kard Team.
  • fileType query param: dailyReconciliationFile
1var axios = require('axios');
2
3var config = {
4    method: 'get',
5    url: 'https://test-rewards-api.getkard.com/issuers/{organizationId}/files?fileType=dailyReconciliationFile',
6    headers: { 
7        'Content-Type': 'application/json', 
8        'Authorization': 'redacted_token'
9    }
10};
11
12axios(config)
13.then(function (response) {
14    console.log(JSON.stringify(response.data));
15})
16.catch(function (error) {
17    console.log(error);
18});

Use the attributes.downloadUrl field in the returned response 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
  • GET Files Endpoint
  • organizationId path param: the organization id given to you by the Kard Team.
  • fileType query param: monthlyReconciliationFile
1var axios = require('axios');
2
3var config = {
4    method: 'get',
5    url: 'https://test-rewards-api.getkard.com/issuers/{organizationId}/files?fileType=monthlyReconciliationFile',
6    headers: { 
7        'Content-Type': 'application/json', 
8        'Authorization': 'redacted_token'
9    }
10};
11
12axios(config)
13.then(function (response) {
14    console.log(JSON.stringify(response.data));
15})
16.catch(function (error) {
17    console.log(error);
18});

Use the attributes.downloadUrl field in the returned response 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

  • GET Get Offers By User Endpoint
  • organizationId path param: the organization id given to you by the Kard Team.
  • userId path param: sandbox-{issuerName}-new-customer
1var axios = require('axios');
2
3var config = {
4    method: 'get',
5    url: 'https://test-rewards-api.getkard.com/v2/issuers/{organizationId}/users/sandbox-{issuerName}-new-customer/offers',
6    headers: { 
7        'Content-Type': 'application/json', 
8        'Authorization': 'redacted_token'
9    }
10};
11
12axios(config)
13.then(function (response) {
14    console.log(JSON.stringify(response.data));
15})
16.catch(function (error) {
17    console.log(error);
18});
  • GET Get Offers By User Endpoint
  • organizationId path param: the organization id given to you by the Kard Team.
  • userId path param: sandbox-{issuerName}-lapsed-customer
1var axios = require('axios');
2
3var config = {
4    method: 'get',
5    url: 'https://test-rewards-api.getkard.com/v2/issuers/{organizationId}/users/sandbox-{issuerName}-lapsed-customer/offers',
6    headers: { 
7        'Content-Type': 'application/json', 
8        'Authorization': 'redacted_token'
9    }
10};
11
12axios(config)
13.then(function (response) {
14    console.log(JSON.stringify(response.data));
15})
16.catch(function (error) {
17    console.log(error);
18});
  • GET Get Locations By User 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
1var axios = require('axios');
2
3var config = {
4    method: 'get',
5    url: 'https://test-rewards-api.getkard.com/v2/issuers/{organizationId}/users/sandbox-{issuerName}-new-customer/locations?longitude=-73.9930148&latitude=40.74201480000001',
6    headers: { 
7        'Content-Type': 'application/json', 
8        'Authorization': 'redacted_token'
9    }
10};
11
12axios(config)
13.then(function (response) {
14    console.log(JSON.stringify(response.data));
15})
16.catch(function (error) {
17    console.log(error);
18});

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

  1. Discover Eligible New Customer Offers
1{
2    "data": [
3        {
4            "type": "purchaseCountOffer",
5            "attributes": {
6                "assets": [
7                    {
8                        "type": "LOGO_IMAGE",
9                        "url": "http://assets.getkard.com/logo/img?attribution-tokens",
10                        "alt": "BaaS Pro Shops Logo Image"
11                    },
12                    {
13                        "type": "BANNER_IMAGE",
14                        "url": "http://assets.getkard.com/banner/img?attribution-tokens",
15                        "alt": "BaaS Pro Shops Banner Image"
16                    }
17                ],
18                "expirationDate": "2025-03-01T05:00:00Z",
19                "isTargeted": true,
20                "name": "BaaS Pro Shops",
21                "purchaseChannel": [
22                    "INSTORE"
23                ],
24                "startDate": "2023-03-01T05:00:00Z",
25                "terms": "This offer is only valid for first-time customers.",
26                "userReward": {
27                    "type": "FLAT",
28                    "value": 20
29                },
30                "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!",
31                "websiteUrl": "https://www.kardbaasproshops.com"
32            },
33            "id": "654d3fce9587960008944c61",
34            "relationships": {
35                "category": {
36                    "data": [
37                        {
38                            "type": "category",
39                            "id": "65920081b524d126068de24a"
40                        }
41                    ]
42                }
43            }
44        }
45    ],
46    "links": {
47        "self": "/v2/issuers/{organizationId}/users/{userId}/offers?page[size]=1?sort=-startDate",
48        "prev": null,
49        "next": "/v2/issuers/{organizationId}/users/{userId}/offers?page[after]=NDMyNzQyODI3OTQw&page[size]=1?&sort=-startDate"
50    },
51    "included": [
52        {
53            "type": "category",
54            "id": "65920081b524d126068de24a",
55            "attributes": {
56                "name": "Food & Beverage"
57            }
58        }
59    ]
60}
  1. Submit Eligible Approved Transaction
  • POST Incoming Transactions Endpoint
  • Map Rewards offer attributes.name to Incoming Transaction description
1{
2    "data": [
3        {
4            "type": "transaction",
5            "id": "sandbox-web-313",
6            "attributes": {
7                "userId": "sandbox-{issuerName}-new-customer",
8                "cardBIN": "123456",
9                "cardLastFour": "4321",
10                "amount": 10000,
11                "direction": "DEBIT",
12                "mcc": "1234",
13                "currency": "USD",
14                "description": "BaaS Pro Shops",
15                "status": "APPROVED",
16                "authorizationDate": "2023-03-29T17:48:06.135Z",
17                "authorizationCode": "123456",
18                "retrievalReferenceNumber": "100804333919",
19                "systemTraceAuditNumber": "333828",
20                "acquirerReferenceNumber": "1234567980123456789012345687"
21            }
22        }
23    ]
24}
  1. Ingest Earned Reward Approved Notification Webhook
  • POST Notifications Webhook
  • Authenticate webhook using HMAC Signature Verification 
    1{
    2    "data": {
    3        "type": "earnedRewardApproved",
    4        "attributes": {
    5            "attributionUrl": "www.attribution.com/token",
    6            "message": "Congrats! You have earned a pending reward on your purchase at BaaS Pro Shops!",
    7            "name": "BaaS Pro Shops",
    8            "surveyUrl": "www.survey.com"
    9        },
    10        "id": "d80a6f28-1b24-4d65-9e42-e1cf3379bc98",
    11        "relationships": {
    12            "user": {
    13                "data": {
    14                    "type": "user",
    15                    "id": "sandbox-{issuerName}-new-customer"
    16                }
    17            }
    18        }
    19    }
    20}
  • Delight your user with a notification!
    • Use attributes.message to serve the push notification:
      pending reward notification
  1. Submit Eligible Settled Transaction
  • POST Incoming Transactions Endpoint
  • Map Rewards offer attributes.name to Incoming Transaction description 
    1{
    2    "data": [
    3        {
    4            "type": "transaction",
    5            "id": "sandbox-web-319",
    6            "attributes": {
    7                "userId": "sandbox-{issuerName}-new-customer",
    8                "cardBIN": "123456",
    9                "cardLastFour": "4321",
    10                "amount": 10000,
    11                "direction": "DEBIT",
    12                "mcc": "1234",
    13                "currency": "USD",
    14                "description": "BaaS Pro Shops",
    15                "status": "SETTLED",
    16                "authorizationDate": "2023-03-29T17:48:06.135Z",
    17                "settledDate": "2023-03-30T17:48:06.135Z",
    18                "authorizationCode": "123456",
    19                "retrievalReferenceNumber": "100804333919",
    20                "systemTraceAuditNumber": "333828",
    21                "acquirerReferenceNumber": "1234567980123456789012345687"
    22            }
    23        }
    24    ]
    25}
  1. Ingest Earned Reward Settled Notification Webhook
  • POST Notifications Webhook
  • Authenticate webhook using HMAC Signature Verification 
    1{
    2"data": {
    3    "type": "earnedRewardSettled",
    4    "attributes": {
    5    "attributionUrl": "www.attribution.com/token",
    6    "commissionEarned": {
    7        "type": "cents",
    8        "value": 2000
    9    },
    10    "message": "Congrats! You have earned a $20.00 reward on your purchase at BaaS Pro Shops!",
    11    "name": "BaaS Pro Shops",
    12    "surveyUrl": "www.survey.com"
    13    },
    14    "id": "d80a6f28-1b24-4d65-9e42-e1cf3379bc98",
    15    "relationships": {
    16    "user": {
    17        "data": {
    18        "type": "user",
    19        "id": "sandbox-{issuerName}-new-customer"
    20        }
    21    }
    22    }
    23}
    24}
  • Delight your user with a rewards confirmation notification!
    • Use attributes.message to serve the push notification:
      earned reward notification

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.

User Acceptance Test Cases

  • 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
  • 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.

Transaction Status Mapping

Kard currently receives the following transaction event types from Marqeta:

MarqetaKard
authorizationApproved
authorization.clearingSettled
pindebitSettled

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

Marqeta FieldKard Field
tokentransactionId
user_tokenreferringPartnerUserId
user_transaction_timetransactionDate, authorizationDate
Note: Depending on status of transaction
settlement_datesettledDate
amountamount
statestatus
preceding_related_transaction_tokentransactionId
Note: valid for transactions after the first transaction event
card_acceptor.mccmcc
card_acceptor.namemerchantName
card_acceptor.street_addressmerchantAddrStreet
card_acceptor.citymerchantAddrCity
card_acceptor.statemerchantAddrState
card_acceptor.zipmerchantAddrZipcode
card.last_fourcardLastFour
card.pancardBIN
Note: Kard receives a masked PAN, only showing BIN and Last 4
currency_codecurrency
card_acceptor.midmerchantId
card_acceptor.namedescription
network_reference_idtransactionId
Note: This is relevant for specific integrations. Consult your Kard Account Manager with questions

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

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