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 to help you integrate quickly.
If you use Marqeta to process your transactions than you can see additional details below to help you set up your integration.
Kard uses OAuth 2.0 credentials for authentication. Read here to learn more about how to connect.
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. Users are enrolled via the Create Users endpoint. Card-level information (cardBIN, cardLastFour) is provided on each transaction sent to the Incoming Transactions endpoint.
Code Recipe:
Creating a User:
POST /v2/issuers/{organizationId}/usersid, enrolledRewardsUpdating a User:
PUT /v2/issuers/{organizationId}/users/{userId}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.
Our official 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:
See the TypeScript SDK docs 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.
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.
There are three common patterns for transmitting transactions.
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.
Code Recipe: Cleared, Signature Transaction
Temporary transaction event:
Final transaction event:
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:
Final transaction event:
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
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
Temporary transaction event: (1 of 1)
Final transaction event: (1 of 2)
Final transaction event: (2 of 2)
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.
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.
cardlinked-reconciliation-YYMMDD.jsonGET Files EndpointorganizationId path param: the organization id given to you by the Kard Team.fileType query param: dailyReconciliationFileUse the attributes.downloadUrl field in the returned response to access your daily
reconciliation files.
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.
cardlinked-reconciliation-YYMM.csvGET Files EndpointorganizationId path param: the organization id given to you by the Kard Team.fileType query param: monthlyReconciliationFileUse the attributes.downloadUrl field in the returned response to access your monthly
reconciliation files.
GET Get Offers By User EndpointorganizationId path param: the organization id given to you by the Kard Team.userId path param: sandbox-{issuerName}-new-customerGET Get Offers By User EndpointorganizationId path param: the organization id given to you by the Kard Team.userId path param: sandbox-{issuerName}-lapsed-customerGET Get Locations By User EndpointorganizationId path param: the organization id given to you by the Kard Team.userId path param: sandbox-{issuerName}-new-customerlongitude=-73.9930148latitude=40.74201480000001The following steps provide a demo experience from the perspective of the sandbox-{issuerName}-new-customer
user.
GET Get Offers By User EndpointPOST Incoming Transactions Endpointattributes.name to Incoming Transaction descriptionPOST Notifications Webhook
POST Incoming Transactions Endpointattributes.name to Incoming Transaction description
POST Notifications Webhookattributes.message to serve the push notification:
For issuers using event tracking via images on the eligibility endpoints:
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.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:
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.
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:
Note: The data mapping for the transaction events below also apply to Kard’s Earned Rewards Webhook.
FIPS State Abbreviation mappings FIPS codes are numbers which uniquely identify geographic areas