***
title: Kard API Reference
layout: overview
---------------------
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
Welcome to Kard’s API documentation. This serves as a resource to help you launch and manage your card’s rewards
program — all from enrolling your users into rewards, to sending transactions for further matching processing, to
consuming live offers to build your app UX.
**Kard's API is versioned using a calendar versioning approach. Date version 2024-10-01 is the most recent major
version.** All endpoints and features are available under this version. We recommend using this version for all
integrations to take full advantage of the latest capabilities and improvements.
The Kard API is [RESTful](https://en.wikipedia.org/wiki/REST), and uses
[standard HTTP](https://datatracker.ietf.org/doc/html/rfc9110) **request methods (GET, POST, PUT, DELETE), response
codes and errors (200, 400, 500)** and **authentication methods**. Header request attributes are **case-insensitive**.
The Kard API accepts and returns **JSON-encoded bodies**.
**Note:** **Non-breaking changes** like new endpoints, newly optional parameters, or additional response properties
(including new JSON fields) **won't result in a new date-based version**. **Breaking changes** like removed endpoints or
properties, newly required parameters, or response changes that affect existing requests **will result in a new version**.
As a best practice, **integrations should be built to handle evolving response structures and accept additional fields
gracefully**.
If you are just getting started with the Kard API, we recommend checking out our
**[Getting Started guide](/2024-10-01/api/getting-started)** for standard implementation requirements and patterns.
We also offer **[official SDKs](/2024-10-01/sdks)** to help you integrate quickly.
***
***
title: Developer SDKs
subtitle: Official SDKs for building with Kard
---------------------
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
Kard offers official, actively maintained **server-side SDKs** that make it easy to integrate with the Kard API using idiomatic, language-specific libraries, complete with documentation and examples.
These SDKs reduce boilerplate and handle common patterns so you can focus on building and maintaining your application.
If your language isn’t supported, you can use our Kard [REST APIs](https://docs.getkard.com/api/getting-started) directly.
### Available SDKs
Build Kard integrations using a fully typed TypeScript SDK designed for Node.js and modern JavaScript runtimes.
Integrate with Kard using a Java SDK that provides strong typing, clear models, and a familiar Java developer experience.
Use the Python SDK to interact with Kard APIs using simple, readable interfaces that fit naturally into Python applications.
***
title: WebView
---------------------
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
This guide covers how to integrate the Kard Rewards WebView in your mobile or web application.
## Introduction
Kard's Rewards WebView provides a turnkey front-end offers experience, complete with a rewards map and intuitive offer discovery for their users. Issuers can integrate Kard's WebView seamlessly into their existing experiences allowing them to launch and iterate on their rewards program quickly and easily.
It is designed to be embedded in:
* **Mobile apps** via native WebView components (iOS WKWebView, Android WebView, React Native WebView)
* **Web applications** via iframe
## Environment URLs
| Environment | URL |
| ----------- | --------------------------------------------- |
| Test | `https://webview-test-us-east-1.getkard.com/` |
| Production | `https://webview-prod-us-east-1.getkard.com/` |
## Query Parameters
### **`token`** (required)
A JWT authentication token that identifies the user and organization.
**Required JWT claims:**
| Claim | Description |
| ----------- | ------------------- |
| `sub` | The user ID |
| `issuer_id` | The organization ID |
The token is used for API authentication when the WebView makes requests to Kard services.
### **`theme`** (optional)
A base64url-encoded JSON string containing design token overrides for customizing the appearance. Uses RFC4648 base64url encoding which is URL-safe (uses `-` instead of `+`, `_` instead of `/`, and omits padding). No `encodeURIComponent` is needed when using base64url encoding.
**Structure:**
```json
{
"theme": "system" | "light" | "dark",
"styles": {
"light": { /* design tokens for light mode */ },
"dark": { /* design tokens for dark mode */ },
"layout": { /* mode-independent layout tokens (e.g., radius) */ }
},
"labels": {
"rewardsTitle": "Custom rewards page title",
"nearbyOffersTitle": "Custom nearby offers title",
"offersTitle": "Custom offers page title"
},
"layout": {
"showMap": true | false
}
}
```
These tokens are mode-dependent and can differ between light and dark themes:
| Token | Description |
| -------------------------- | ------------------------- |
| `background` | Page background color |
| `primary` | Primary brand color |
| `buttonPrimaryTextColor` | Text on primary buttons |
| `secondary` | Secondary color |
| `buttonSecondaryTextColor` | Text on secondary buttons |
| `textPrimary` | Primary text color |
| `textSecondary` | Secondary text color |
| `cardBackgroundColor` | Card background |
| `border` | Border color |
| `linkColor` | Link/button text color |
All color values must be valid CSS color values (hex, rgb, hsl, oklch, named colors, etc.).
These tokens are mode-independent and apply to both light and dark themes:
| Token | Description |
| ------------- | ------------------------------------------ |
| `radius` | Border radius (CSS length) |
| `chipRadius` | Filter chip border radius (CSS length) |
| `imageRadius` | Image container border radius (CSS length) |
| `cardRadius` | Card border radius (CSS length) |
### `labels` (optional)
The `labels` property within the theme parameter allows customization of page titles displayed in the WebView. All label properties are optional — if not specified, the default values are used.
| Label | Default | Description |
| ------------------- | --------------- | ----------------------------------------- |
| `rewardsTitle` | `Rewards` | Title displayed on the rewards page |
| `nearbyOffersTitle` | `Nearby offers` | Title displayed on the nearby offers page |
| `offersTitle` | `Offers` | Title displayed on the offers page |
### `layout` (optional)
The `layout` property within the theme parameter controls the visibility of page sections. All layout properties are optional — if not specified, the default values are used.
| Property | Type | Default | Description |
| --------- | ------- | ------- | -------------------------------------------------------------- |
| `showMap` | boolean | `true` | Show or hide the nearby offers map section on the rewards page |
## Fetching a WebView JWT Token
The Kard SDK provides methods to generate WebView tokens. The SDK is available in multiple languages:
* [**TypeScript SDK**](/2024-10-01/sdks/typescript-sdk/getting-started)
* [**Python SDK**](/2024-10-01/sdks/python-sdk/getting-started)
**SDK Method:**
```javascript
users.auth.getWebViewToken(organizationId, userId)
```
This returns a signed JWT that should be passed as the `token` query parameter.
WebView tokens can also be generated via REST API. Refer to the API documentation for [Get WebView Token](/2024-10-01/api/auth/get-web-view-token).
## Location Message Passing Contract
The WebView uses a message-passing protocol to request location data from the container application. This is required for the rewards map feature to display nearby offers.
### Message Types
| Type | Direction | Description |
| ------------------- | ------------------- | --------------------------------- |
| `REQUEST_LOCATION` | WebView → Container | WebView requests current location |
| `LOCATION_RESPONSE` | Container → WebView | Container sends location data |
| `ERROR` | Container → WebView | Container reports an error |
### Request Format (from WebView)
When the WebView needs location data, it sends:
```json
{
"type": "REQUEST_LOCATION"
}
```
### Success Response Format (to WebView)
When location is successfully retrieved:
```json
{
"type": "LOCATION_RESPONSE",
"payload": {
"ok": true,
"coords": {
"latitude": 40.7128,
"longitude": -74.0060,
"accuracy": 10,
"altitude": null,
"heading": null,
"speed": null
},
"timestamp": 1706380800000
}
}
```
**Coordinate fields:**
| Field | Type | Description |
| ----------- | -------------- | ---------------------- |
| `latitude` | number | Latitude in degrees |
| `longitude` | number | Longitude in degrees |
| `accuracy` | number \| null | Accuracy in meters |
| `altitude` | number \| null | Altitude in meters |
| `heading` | number \| null | Heading in degrees |
| `speed` | number \| null | Speed in meters/second |
### Error Response Format (to WebView)
When location cannot be retrieved:
```json
{
"type": "ERROR",
"payload": {
"ok": false,
"error": "Location permission not granted"
}
}
```
## Platform Integration Examples
```typescript
import { useCallback, useRef } from 'react';
import * as Location from 'expo-location';
import WebView, { ShouldStartLoadRequest } from 'react-native-webview';
const WEBVIEW_URL = 'https://webview-prod-us-east-1.getkard.com/';
const ALLOWED_ORIGIN = new URL(WEBVIEW_URL).origin;
interface RewardsWebViewProps {
token: string;
themeOverrides?: {
theme?: 'system' | 'light' | 'dark';
styles?: {
light?: Record;
dark?: Record;
};
labels?: {
rewardsTitle?: string;
nearbyOffersTitle?: string;
offersTitle?: string;
};
};
}
// RFC4648 base64url encoding (URL-safe, no padding)
function encodeThemeOverrides(overrides: object): string {
return btoa(JSON.stringify(overrides))
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
}
export function RewardsWebView({ token, themeOverrides }: RewardsWebViewProps) {
const webviewRef = useRef(null);
const handleMessage = useCallback(async (event: any) => {
try {
const msg = JSON.parse(event?.nativeEvent?.data);
if (msg?.type === 'REQUEST_LOCATION') {
// Request location permission
const { status } = await Location.requestForegroundPermissionsAsync();
if (status !== 'granted') {
webviewRef.current?.postMessage(JSON.stringify({
type: 'ERROR',
payload: { ok: false, error: 'Location permission not granted' }
}));
return;
}
// Get current position
const position = await Location.getCurrentPositionAsync({});
webviewRef.current?.postMessage(JSON.stringify({
type: 'LOCATION_RESPONSE',
payload: {
ok: true,
coords: {
latitude: position.coords.latitude,
longitude: position.coords.longitude,
accuracy: position.coords.accuracy,
altitude: position.coords.altitude,
heading: position.coords.heading,
speed: position.coords.speed,
},
timestamp: position.timestamp,
}
}));
}
} catch (error) {
console.error('Error handling WebView message:', error);
}
}, []);
// base64url is URL-safe, no encodeURIComponent needed for theme param
const themeParam = themeOverrides
? `&theme=${encodeThemeOverrides(themeOverrides)}`
: '';
const handleShouldStartLoadWithRequest = useCallback(
(request: ShouldStartLoadRequest) => {
try {
const url = new URL(request.url);
return url.origin === ALLOWED_ORIGIN;
} catch {
return false;
}
},
[],
);
return (
);
}
```
```swift
import WebKit
import CoreLocation
class RewardsWebViewController: UIViewController {
private var webView: WKWebView!
private let locationManager = CLLocationManager()
private var pendingLocationRequest = false
private let webviewURL = "https://webview-prod-us-east-1.getkard.com/"
private let webviewOrigin = "https://webview-prod-us-east-1.getkard.com"
override func viewDidLoad() {
super.viewDidLoad()
locationManager.delegate = self
// Configure WebView with message handler
let config = WKWebViewConfiguration()
let contentController = WKUserContentController()
contentController.add(self, name: "nativeHandler")
config.userContentController = contentController
// Inject message bridge to capture postMessage calls
let script = """
window.addEventListener('message', function(event) {
if (event.data && event.data.type === 'REQUEST_LOCATION') {
window.webkit.messageHandlers.nativeHandler.postMessage(event.data);
}
});
"""
let userScript = WKUserScript(
source: script,
injectionTime: .atDocumentStart,
forMainFrameOnly: false
)
config.userContentController.addUserScript(userScript)
webView = WKWebView(frame: view.bounds, configuration: config)
webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
view.addSubview(webView)
}
func load(token: String, themeOverrides: [String: Any]? = nil) {
var urlString = "\(webviewURL)?token=\(token.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? token)"
if let theme = themeOverrides,
let jsonData = try? JSONSerialization.data(withJSONObject: theme),
let jsonString = String(data: jsonData, encoding: .utf8) {
// RFC4648 base64url encoding (URL-safe, no escaping needed)
let base64Theme = Data(jsonString.utf8).base64EncodedString()
.replacingOccurrences(of: "+", with: "-")
.replacingOccurrences(of: "/", with: "_")
.trimmingCharacters(in: CharacterSet(charactersIn: "="))
urlString += "&theme=\(base64Theme)"
}
if let url = URL(string: urlString) {
webView.load(URLRequest(url: url))
}
}
private func sendLocationToWebView(_ location: CLLocation) {
let payload: [String: Any] = [
"type": "LOCATION_RESPONSE",
"payload": [
"ok": true,
"coords": [
"latitude": location.coordinate.latitude,
"longitude": location.coordinate.longitude,
"accuracy": location.horizontalAccuracy,
"altitude": location.altitude,
"heading": location.course >= 0 ? location.course : NSNull(),
"speed": location.speed >= 0 ? location.speed : NSNull()
],
"timestamp": Int(location.timestamp.timeIntervalSince1970 * 1000)
]
]
sendMessageToWebView(payload)
}
private func sendErrorToWebView(_ error: String) {
let payload: [String: Any] = [
"type": "ERROR",
"payload": [
"ok": false,
"error": error
]
]
sendMessageToWebView(payload)
}
private func sendMessageToWebView(_ message: [String: Any]) {
guard let jsonData = try? JSONSerialization.data(withJSONObject: message),
let jsonString = String(data: jsonData, encoding: .utf8) else {
return
}
let script = "window.postMessage(\(jsonString), '\(webviewOrigin)');"
webView.evaluateJavaScript(script, completionHandler: nil)
}
}
// MARK: - WKScriptMessageHandler
extension RewardsWebViewController: WKScriptMessageHandler {
func userContentController(
_ userContentController: WKUserContentController,
didReceive message: WKScriptMessage
) {
guard let body = message.body as? [String: Any],
let type = body["type"] as? String else {
return
}
if type == "REQUEST_LOCATION" {
pendingLocationRequest = true
locationManager.requestWhenInUseAuthorization()
locationManager.requestLocation()
}
}
}
// MARK: - CLLocationManagerDelegate
extension RewardsWebViewController: CLLocationManagerDelegate {
func locationManager(
_ manager: CLLocationManager,
didUpdateLocations locations: [CLLocation]
) {
guard pendingLocationRequest, let location = locations.last else { return }
pendingLocationRequest = false
sendLocationToWebView(location)
}
func locationManager(
_ manager: CLLocationManager,
didFailWithError error: Error
) {
guard pendingLocationRequest else { return }
pendingLocationRequest = false
sendErrorToWebView(error.localizedDescription)
}
}
```
```kotlin
import android.Manifest
import android.annotation.SuppressLint
import android.content.pm.PackageManager
import android.location.Location
import android.os.Bundle
import android.util.Base64
import android.webkit.JavascriptInterface
import android.webkit.WebView
import android.webkit.WebViewClient
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity
import androidx.core.content.ContextCompat
import com.google.android.gms.location.FusedLocationProviderClient
import com.google.android.gms.location.LocationServices
import org.json.JSONObject
class RewardsWebViewActivity : AppCompatActivity() {
private lateinit var webView: WebView
private lateinit var fusedLocationClient: FusedLocationProviderClient
private val webviewURL = "https://webview-prod-us-east-1.getkard.com/"
private val webviewOrigin = "https://webview-prod-us-east-1.getkard.com"
private val locationPermissionRequest = registerForActivityResult(
ActivityResultContracts.RequestMultiplePermissions()
) { permissions ->
when {
permissions[Manifest.permission.ACCESS_FINE_LOCATION] == true ||
permissions[Manifest.permission.ACCESS_COARSE_LOCATION] == true -> {
requestLocation()
}
else -> {
sendErrorToWebView("Location permission not granted")
}
}
}
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
fusedLocationClient = LocationServices.getFusedLocationProviderClient(this)
webView = WebView(this).apply {
settings.javaScriptEnabled = true
settings.domStorageEnabled = true
webViewClient = WebViewClient()
addJavascriptInterface(WebViewBridge(), "AndroidBridge")
}
setContentView(webView)
}
fun load(token: String, themeOverrides: JSONObject? = null) {
var url = "$webviewURL?token=${java.net.URLEncoder.encode(token, "UTF-8")}"
themeOverrides?.let { theme ->
// RFC4648 base64url encoding (URL-safe, no escaping needed)
val base64Theme = Base64.encodeToString(
theme.toString().toByteArray(),
Base64.URL_SAFE or Base64.NO_WRAP or Base64.NO_PADDING
)
url += "&theme=$base64Theme"
}
webView.loadUrl(url)
// Inject message listener
webView.evaluateJavascript("""
window.addEventListener('message', function(event) {
if (event.data && event.data.type === 'REQUEST_LOCATION') {
AndroidBridge.onLocationRequest();
}
});
""".trimIndent(), null)
}
@SuppressLint("MissingPermission")
private fun requestLocation() {
if (hasLocationPermission()) {
fusedLocationClient.lastLocation.addOnSuccessListener { location ->
if (location != null) {
sendLocationToWebView(location)
} else {
sendErrorToWebView("Unable to get location")
}
}.addOnFailureListener { e ->
sendErrorToWebView(e.message ?: "Location request failed")
}
} else {
locationPermissionRequest.launch(arrayOf(
Manifest.permission.ACCESS_FINE_LOCATION,
Manifest.permission.ACCESS_COARSE_LOCATION
))
}
}
private fun hasLocationPermission(): Boolean {
return ContextCompat.checkSelfPermission(
this, Manifest.permission.ACCESS_FINE_LOCATION
) == PackageManager.PERMISSION_GRANTED ||
ContextCompat.checkSelfPermission(
this, Manifest.permission.ACCESS_COARSE_LOCATION
) == PackageManager.PERMISSION_GRANTED
}
private fun sendLocationToWebView(location: Location) {
val payload = JSONObject().apply {
put("type", "LOCATION_RESPONSE")
put("payload", JSONObject().apply {
put("ok", true)
put("coords", JSONObject().apply {
put("latitude", location.latitude)
put("longitude", location.longitude)
put("accuracy", location.accuracy)
put("altitude", if (location.hasAltitude()) location.altitude else JSONObject.NULL)
put("heading", if (location.hasBearing()) location.bearing else JSONObject.NULL)
put("speed", if (location.hasSpeed()) location.speed else JSONObject.NULL)
})
put("timestamp", location.time)
})
}
runOnUiThread {
webView.evaluateJavascript(
"window.postMessage(${payload}, '$webviewOrigin');",
null
)
}
}
private fun sendErrorToWebView(error: String) {
val payload = JSONObject().apply {
put("type", "ERROR")
put("payload", JSONObject().apply {
put("ok", false)
put("error", error)
})
}
runOnUiThread {
webView.evaluateJavascript(
"window.postMessage(${payload}, '$webviewOrigin');",
null
)
}
}
inner class WebViewBridge {
@JavascriptInterface
fun onLocationRequest() {
requestLocation()
}
}
}
```
```typescript
import { useEffect, useRef } from 'react';
const WEBVIEW_URL = 'https://webview-prod-us-east-1.getkard.com/';
const EXPECTED_ORIGIN = new URL(WEBVIEW_URL).origin;
interface ThemeOverrides {
theme?: 'system' | 'light' | 'dark';
styles?: {
light?: Record;
dark?: Record;
};
labels?: {
rewardsTitle?: string;
nearbyOffersTitle?: string;
offersTitle?: string;
};
}
interface RewardsIFrameProps {
token: string;
themeOverrides?: ThemeOverrides;
}
// RFC4648 base64url encoding (URL-safe, no padding)
function encodeThemeOverrides(overrides: ThemeOverrides): string {
return btoa(JSON.stringify(overrides))
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
}
export function RewardsIFrame({ token, themeOverrides }: RewardsIFrameProps) {
const iframeRef = useRef(null);
useEffect(() => {
function handleMessage(event: MessageEvent) {
// Verify message origin and source match our iframe
if (
event.origin !== EXPECTED_ORIGIN ||
!iframeRef.current ||
event.source !== iframeRef.current.contentWindow
) {
return;
}
const msg = event.data;
if (msg?.type === 'REQUEST_LOCATION') {
navigator.geolocation.getCurrentPosition(
(position) => {
iframeRef.current?.contentWindow?.postMessage({
type: 'LOCATION_RESPONSE',
payload: {
ok: true,
coords: {
latitude: position.coords.latitude,
longitude: position.coords.longitude,
accuracy: position.coords.accuracy,
altitude: position.coords.altitude,
heading: position.coords.heading,
speed: position.coords.speed,
},
timestamp: position.timestamp,
}
}, EXPECTED_ORIGIN);
},
(error) => {
iframeRef.current?.contentWindow?.postMessage({
type: 'ERROR',
payload: {
ok: false,
error: error.message
}
}, EXPECTED_ORIGIN);
},
{ enableHighAccuracy: true }
);
}
}
window.addEventListener('message', handleMessage);
return () => window.removeEventListener('message', handleMessage);
}, []);
// base64url is URL-safe, no encodeURIComponent needed for theme param
const themeParam = themeOverrides
? `&theme=${encodeThemeOverrides(themeOverrides)}`
: '';
return (
);
}
```
## Theming Resources
Below is an example showing how to apply custom branding:
```typescript
// Define your brand colors
const themeOverrides = {
theme: 'light' as const,
styles: {
light: {
primary: '#0066cc',
buttonPrimaryTextColor: '#ffffff',
secondary: '#e0e0e0',
buttonSecondaryTextColor: '#1a1a1a',
background: '#f5f5f5',
textPrimary: '#1a1a1a',
textSecondary: '#6b7280',
cardBackgroundColor: '#ffffff',
border: '#e0e0e0',
linkColor: '#0066cc',
},
dark: {
primary: '#4da6ff',
buttonPrimaryTextColor: '#000000',
secondary: '#404040',
buttonSecondaryTextColor: '#f5f5f5',
background: '#1a1a1a',
textPrimary: '#f5f5f5',
textSecondary: '#a0a0a0',
cardBackgroundColor: '#2a2a2a',
border: '#404040',
linkColor: '#4da6ff',
},
layout: {
radius: '8px',
chipRadius: '9999px',
imageRadius: '9999px',
cardRadius: '12px',
}
},
labels: {
rewardsTitle: 'My Rewards',
nearbyOffersTitle: 'Deals near you',
offersTitle: 'All deals',
}
};
// RFC4648 base64url encoding (URL-safe, no padding)
function encodeThemeOverrides(overrides: object): string {
return btoa(JSON.stringify(overrides))
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
}
// base64url is URL-safe, no encodeURIComponent needed
const themeParam = encodeThemeOverrides(themeOverrides);
const url = `https://webview-prod-us-east-1.getkard.com/?token=${token}&theme=${themeParam}`;
```
***
title: Getting Started
---------------------
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
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.
## 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
## 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. Users are enrolled via the [Create Users](/2024-10-01/api/users/create) endpoint. Card-level
information (cardBIN, cardLastFour) is provided on each transaction sent to the
[Incoming Transactions](/2024-10-01/api/transactions/create) endpoint.
***Code Recipe:***
Creating a User:
* `POST /v2/issuers/{organizationId}/users`
* *required:* `id`, `enrolledRewards`
```json
{
"data": [
{
"type": "user",
"id": "438103",
"attributes": {
"email": "testuser@test-TEST.com",
"zipCode": "30047",
"enrolledRewards": ["CARDLINKED"]
}
}
]
}
```
Updating a User:
* `PUT /v2/issuers/{organizationId}/users/{userId}`
```json
{
"data": {
"type": "user",
"id": "438103",
"attributes": {
"zipCode": "30048",
"enrolledRewards": ["CARDLINKED"]
}
}
}
```
If your application allows users to link cards from other programs, transactions may originate
from a variety of different card networks. Card-level information (cardBIN, cardLastFour) is provided on each
transaction sent to the [Incoming Transactions](/2024-10-01/api/transactions/create) endpoint.
***Code Recipe:***
Creating a User:
* `POST /v2/issuers/{organizationId}/users`
* *required:* `id`, `enrolledRewards`
```json
{
"data": [
{
"type": "user",
"id": "438103",
"attributes": {
"email": "testuser@test-TEST.com",
"zipCode": "30047",
"enrolledRewards": ["CARDLINKED"]
}
}
]
}
```
*Note*: If a user tries to enroll a card of a direct partner the following error message will be returned
from the API:
```
"Invalid request: This card is already registered. Provide another card for user enrollment."
```
### 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
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,
}
}]
});
```
See the [TypeScript SDK docs](/2024-10-01/sdks/type-script-sdk/getting-started) for more details.
```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,
),
)
],
)
```
See the [Python SDK docs](/2024-10-01/sdks/python-sdk/getting-started) for more details.
```java
import com.kard.api.KardApiClient;
import com.kard.hem.HEM;
KardApiClient client = KardApiClient
.builder()
.clientId("YOUR_CLIENT_ID")
.clientSecret("YOUR_CLIENT_SECRET")
.build();
String hashedEmail = HEM.generateHEM("Jane.Doe+work@gmail.com");
// Pass hashedEmail as the "hashedEmail" attribute when creating users
```
See the [Java SDK docs](/2024-10-01/sdks/java-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.
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.
## 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](/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/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"
}
}
]
}
```
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/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
}
}
]
}
```
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/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***T17:48:06.135Z")
* settledDate timestamp ("2022-10-***30***T18: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***T17:48:06.135Z")
* settledDate timestamp ("2022-10-***31***T18: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`
- `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`
- `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
* `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);
});
```
* `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);
});
```
* `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);
});
```
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/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:
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/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:
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
* 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](https://www.getkard.com/docs/marqeta-kard-integration).
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\_token | referringPartnerUserId |
| 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 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 |
***
title: Authentication
---------------------
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
## Kard API
The Kard API supports authentication via OAuth2.0's client credentials. Issuer client will be provided
**`client_id`** and **`client_secret`** by Kard.
### Kard Authentication API v2
Use the new Kard Authentication API endpoint. Each client will have their own dedicated subdomain,
which will be provided by Kard.
The API follows OAuth2.0 client credentials flow and requires:
* **Authorization header**: Basic authentication with base64 encoded `{client_id}:{client_secret}`
* **Content-Type header**: Must be set to `application/x-www-form-urlencoded`
* **Request body**: Form data with `grant_type=client_credentials`
```javascript
const axios = require('axios');
const config = {
method: 'POST',
url: 'https://{your-client-subdomain}.getkard.com/v2/auth/token',
headers: {
'Authorization': 'Basic {base64_encoded_client_id:client_secret}',
'Content-Type': 'application/x-www-form-urlencoded'
},
data: 'grant_type=client_credentials'
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
```
Replace `{your-client-subdomain}` with the subdomain provided by Kard for your organization.
The returned access token must be used in the `Authorization` header as a bearer token
in subsequent requests.
### Multi-Issuer Authentication (Beta)
This feature is currently in **Beta**. If you are interested in using this feature, please contact your Kard representative.
If you manage multiple issuers on the Kard platform, you can scope your auth token to a specific issuer by including the `X-Kard-Target-Issuer` header in your token request. The response is identical to a standard authentication request, but the returned access token will be locked to the issuer specified in the header.
```javascript
const axios = require('axios');
const config = {
method: 'POST',
url: 'https://{your-client-subdomain}.getkard.com/v2/auth/token',
headers: {
'Authorization': 'Basic {base64_encoded_client_id:client_secret}',
'Content-Type': 'application/x-www-form-urlencoded',
'X-Kard-Target-Issuer': '{target_issuer_id}'
},
data: 'grant_type=client_credentials'
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
```
Example response:
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"token_type": "Bearer",
"expires_in": 3600
}
```
Any subsequent API calls made with this token will be scoped to the specified issuer. If you need to interact with a different issuer, request a new token with the corresponding `X-Kard-Target-Issuer` value.
## Response Examples
The API returns standard HTTP status codes:
* **200**: Successful authentication with access token
* **400**: Bad request (missing Authorization header or invalid grant\_type)
* **401**: Unauthorized (invalid credentials)
* **404**: Not found (client not found)
* **500**: Internal server error
Example Successful Response:
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"token_type": "Bearer",
"expires_in": 3600
}
```
### Direct Cognito (Deprecated)
**DEPRECATED**: The direct Cognito authentication method is deprecated and will be discontinued soon.
Please migrate to the new Authentication API v2 above.
* `GET Session Token` request in root directory
* baseURL: `https://test-rewards-api.auth.us-east-1.amazoncognito.com`
* `{clientHash}`: base64 encoded copy of `{client_id}:{client_secret}`, provided in the postman\_environment.json.
```javascript
const axios = require('axios');
const config = {
method: 'POST',
url: 'https://test-rewards-api.auth.us-east-1.amazoncognito.com/oauth2/token?grant_type=client_credentials',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'Authorization': 'Basic {clientHash}'
}
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
```
Example response:
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"token_type": "Bearer",
"expires_in": 3600
}
```
***
title: Notifications
---------------------
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
## Overview
As a part of the integration, Kard provides issuers with near real-time notifications via webhooks about important
event updates to your rewards program. These notifications are designed in a way where they can be sent directly to
your users, enhancing engagement and fostering a more connected, synchronous experience between you and your user base.
Notification webhooks are sent to the designated webhook URL provided by the issuer for each event type, ensuring timely
and reliable delivery. To receive notifications, you can self-subscribe to events via API with the [Create Subscriptions](/2024-10-01/api/notifications/subscriptions/create)
endpoint. For comprehensive details on payloads and supported event types, please refer to our [API Reference section](/2024-10-01/api/notifications/notification-webhook).
We currently support the following event types:
* **earnedRewardApproved**: receive notifications for when an approved transaction qualifies for a reward
* **earnedRewardSettled**: receive notifications for when a settled transaction qualifies for a reward
* **validTransaction**: receive notifications for when a transaction has been successfully validated
* **failedTransaction**: receive notifications for when a transaction failed validation
* **clawback**: receive notifications for when a transaction has been marked for clawback
Each notification payload includes:
* **Message**: A message field with suggested text enabling you to easily send out push notifications to your users.
* **Attribution**: An attribution field with attribution links enabling you to collect and send attribution related to your notifications. For more details on attribution and how to use these links, visit [this page](/2024-10-01/api/attributions).
* **Idempotency**: A unique id for each notification, which serves as an idempotency key to ensure consistent and reliable information delivery.
## Webhook Authentication
For the [notifications webhook](/api/notifications/notification-webhook), Kard will be posting outbound to a URL
provided by the issuer client. This webhook is validated via **HMAC signature**.
An issuer client will be provided with a webhook key that is used to generate an HMAC of the webhook body. The
HMAC is calculated by Kard and will be sent in the **`notify-signature`** header. Note that header request attributes
are processed as **case-insensitive**.
To validate, the issuer client should generate the HMAC with the provided key, body and SHA-256 hashing algorithm
and compare against the HMAC provided in the header.
The following is a Node.js code recipe that shows one approach to:
1. Stand up a service to ingest a notification webhook
2. Implement HMAC signature verification
### Code Recipe: Authenticating, then Ingesting a Notification Webhook
* `auth.js`: signature verification middleware
* `index.js`: POST endpoint
```
# auth.js
const { createHmac } = require("crypto");
const secretKey = issuer_webhook_key; //provided in postman_environment.json
const verifyToken = (req, res, next) => {
// grab HMAC signature from Notify-signature header of request
const token = req.get("notify-signature");
if (!token) {
return res.status(403).send("A token is required for authentication");
}
try {
// cast webhook as string
const stringRequest = JSON.stringify(req.body);
// hash using sha256, webhook key, and webhook body as string
const hash = createHmac('sha256', secretKey)
.update(stringRequest)
.digest('base64')
// verified request
if (token === hash){
return next();
}
// unverified request
return res.status(401).send("Invalid Token");
} catch (err) {
return res.status(400).send("Bad Request");
}
};
module.exports = verifyToken;
```
```
# index.js
const express = require('express');
const auth = require('./auth');
const port = 3000;
const app = express();
app.use(express.json());
app.post('/notifications-webhook', auth, (req, res) => {
try {
// insert code that processes the webhook
console.log('notification webhook: ', req.body);
}
catch (err) {
res.send(err);
}
res.status(200).send('Thanks Kard!');
});
app.listen(port, () => {
console.log(`Example app listening on port ${port}`);
});
```
***
title: Attributions
---------------------
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
## Overview
As part of the integration, Kard offers robust solutions for collecting user attribution data for in-app and mobile push notification touchpoints. These data points provide valuable insights into how users interact with your rewards program.
Attribution metrics are increasingly becoming a key requirement among merchants as Kard continues to partner with top-of-wallet, everyday-spend brands. By enabling user attribution data collection, you'll unlock access to more premium offers and drive stronger engagement within your program, ultimately helping you deliver greater value to your users.
## Event Types and Mediums
### Event Types
Kard's attribution system collects two event types:
* **`Impressions`:** Occur anytime a resource (like an offer logo or notification) is *loaded* within your app experience.
*Example:* When a user opens the rewards screen and offers are displayed — each offer loaded generates an `IMPRESSION` event.
See below for a visual representation of an impression event:
* **`Views`:** Occur anytime a user *acts* to view a specific resource.
*Example:* When a user clicks an offer to view its details, or taps on a push notification to open the rewards screen — this generates a `VIEW` event.
See below for a visual representation of a view event:
***
### Mediums
Each event must include a `medium` field to describe where in your experience the event occurred.
**Supported mediums:**
* **`BROWSE`** — User is viewing a list of offers in the rewards experience.
* **`MAP`** — User is exploring offers on a map view.
* **`SEARCH`** — User is viewing or clicking offers as part of a search experience.
* **`PUSH`** — Event occurred within a mobile push notification.
***
## Implementation Methods
Kard supports two integration options for real-time attribution tracking. You may use either, but not both for the same event type:
1. **Event Tracking via Image URLs** — Attribution tracking tokens are included with assets returned by Kard's APIs and webhooks.
2. **Event Tracking via the Attribution API Endpoint** — Provides direct event delivery if your system already tracks impressions and views.
***
## In-App Experiences
### Overview
In-app notifications and offer impressions are tracked when users interact with the rewards experience inside your application.
For **in-app impressions and views**, you can choose **either**:
1. **Image-based tracking**, or
2. **The Attribution API Endpoint**
Use a single method consistently for each event type to prevent duplication.
***
### Option 1: Image-Based Tracking
When loading offers or images from Kard, append the `eventCode` and `medium` parameters to the provided URL.
The images are provided in the [Get Offers by User](https://docs.getkard.com/api/rewards/offers) and [Get Locations by User](https://docs.getkard.com/api/rewards/locations) API endpoints in the `data.attributes.assets.url` fields.
**Example payload:**
```json
GET /v2/issuers/{{organizationId}}/users/{{userId}}/offers
{
"data": {
"attributes": {
...
"assets": [
{
"type": "LOGO_IMAGE",
"url": "https://attribution.getkard.com/image.jpg?token=valid.signed.jwt",
"alt": "Worlds Greatest Chicken Logo Image"
},
{
"type": "BANNER_IMAGE",
"url": "https://attribution.getkard.com/image.jpg?token=valid.signed.jwt",
"alt": "Worlds Greatest Chicken Banner Image"
}
...
],
...
},
},
}
...
```
User browsing the rewards list → `eventCode=IMPRESSION&medium=BROWSE`
```html
```
User opening an offer detail page upon browsing list → `eventCode=VIEW&medium=BROWSE`
```html
```
User viewing offers on a map → `eventCode=IMPRESSION&medium=MAP`
```html
```
Do not cache these image URLs. Kard's CDN already handles caching to ensure accurate, real-time tracking.
***
### Option 2: Attribution API Tracking
If you track these events yourself, you can send them directly to Kard via the Attribution API.
Note, in addition to providing an `eventCode` and a `medium` the API requires an `entityId` representing the Kard-provided `offerId` related to the attribution event and an `eventDate` capturing the timestamp the event occurred.
User browsing the rewards list `eventCode=IMPRESSION`, `medium=BROWSE`
```json
POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
{
"data": [
{
"type": "offerAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144c075",
"eventCode": "IMPRESSION",
"medium": "BROWSE",
"eventDate": "2025-01-01T00:00:00Z"
}
}
]
}
```
User opening an offer detail page upon a map → `eventCode=VIEW`, `medium=MAP`
```json
POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
{
"data": [
{
"type": "offerAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144c075",
"eventCode": "VIEW",
"medium": "MAP",
"eventDate": "2025-01-02T00:00:00Z"
}
}
]
}
```
***
## Mobile Push Notifications
### Overview
Kard supports attribution tracking for **mobile push notifications**, which allows you to measure engagement from the moment a notification is displayed (impression) through to user interaction (view).
For **push notifications**, Kard requires a **hybrid approach**:
* **`IMPRESSION` events:** Must be sent via the **Attribution API**
* **`VIEW` events:** Can be tracked **either** via the **Attribution API** *or* the **image-based tracking method**
***
### Push Notification Impressions
Triggered when a Kard-provided push notification is **displayed** on a user's device. **You must use the attribution API to send push notification impressions.**
Because iOS and Android do not provide a built-in, reliable way to capture notification impressions, this data should be sent on a **best-effort basis**. If your app or SDK can detect when a notification is actually shown (for example, using platform-specific APIs, analytics SDKs, or Firebase Cloud Messaging), use that signal to send the impression event.
If such tracking is not available, please instead send the event when the push notification is **sent** to the device.
***
### What Works Best
Use your existing notification or analytics SDKs (e.g., Firebase Cloud Messaging or other in-app event trackers) to detect when a push notification is **actually displayed** on the user's device. When available, this provides the most accurate impression data.
### What to Do Instead
If you do **not** have tools or SDKs capable of detecting impressions, you can still participate in attribution by sending an impression event when the notification is **sent** to the device.
This data collection helps Kard approximate impressions that were sent to the user when display data isn't available, without requiring any extra SDKs or configuration.
User's lock screen displays a push notification for an earned reward → `eventCode=IMPRESSION`, `medium=PUSH`
Note: in addition to `eventCode` and a `medium` the API requires an `entityId` representing the Kard-provided `notificationId` related to the attribution event and an `eventDate` capturing the timestamp the event occurred.
```json
POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
{
"data": [
{
"type": "notificationAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144a623",
"eventCode": "IMPRESSION",
"medium": "PUSH",
"eventDate": "2025-01-06T00:00:00Z"
}
}
]
}
```
***
### Push Notification Views
Triggered when a user **clicks** on a push notification and opens the app or relevant reward experience. You can choose **either** of the following implementations:
### Option 1: Image-Based Tracking
The blank image pixel is included in the relevant notification webhooks within the `data.attributes.attributionUrl` field. To use it, append the `eventCode` and `medium` parameters to the provided URL.
**Example payload:**
```json
{
"data": {
"attributes": {
"attributionUrl": "https://attribution.getkard.com/public/logos/transparent.png?token=valid.signed.jwt",
...
},
...
},
...
}
```
User clicks into push notification and opens into app → `eventCode=VIEW`, `medium=PUSH`
```html
```
### Option 2: Attribution API
If you track these events yourself, you can send them directly to Kard via the Attribution API.
User clicks into push notification and opens into app → `eventCode=VIEW`, `medium=PUSH`
Note: in addition to `eventCode` and a `medium` the API requires an `entityId` representing the Kard-provided `notificationId` related to the attribution event and an `eventDate` capturing the timestamp the event occurred.
```json
POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
{
"data": [
{
"type": "notificationAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144c178",
"eventCode": "VIEW",
"medium": "PUSH",
"eventDate": "2025-01-07T00:00:00Z"
}
}
]
}
```
***
## Best Practices
* **In-app experiences:** Use either Image-based tracking or the API for both event types.
* **Push Notification Impressions:** Must be sent via the Attribution API.
* **Push Notification Views:** Use either Image-based tracking or the API.
* Use **either** Image-based tracking **or** the Attribution API per event type — not both.
* Avoid caching attribution URLs if you choose to use the Image-based tracking.
* Send all API-based events promptly for real-time data accuracy.
***
title: Extended API Integration
---------------------
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
Kard's Extended API feature enhances our existing rewards endpoints with dynamic, per-user offer data. By requesting UI components through the `supportedComponents` query parameter, you can surface richer offer experiences to your end users including dynamic descriptions, call-to-action buttons, and contextual tags without building custom logic to interpret raw offer data.
This guide covers how to request and render extended offer fields from the [Get Offers by User](/2024-10-01/api/rewards/offers) and [Get Locations by User](/2024-10-01/api/rewards/locations) endpoints.
## Key Concepts
### Supported Components
The Extended API uses a **component-based model** to deliver dynamic offer data. You tell Kard which UI components your app supports, and the API returns the relevant data for each offer.
| Component | Description | Example Use Case |
| ------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `shortDescription` | A brief, dynamic description of the offer suitable for list views | "Multi-use", "Single use" |
| `longDescription` | A detailed description suitable for offer detail pages | "Use your linked card on qualifying purchases to redeem multiple times." |
| `cta` | A call-to-action button with text, style, and an optional action URL | "Tap to boost" button |
| `tags` | Contextual labels for the offer in list/browse views | `["New"]`, `["5 days left"]` |
| `detailTags` | Contextual labels for the offer detail page | `["Activated"]` |
| `baseReward` | A formatted reward string ready for display in your UI | `"5% cash back"` |
**Coming soon: Offer activations.** Some offers will require explicit user action to redeem such as tapping a call-to-action button to boost, renew, or activate an offer. Integrating with the `cta` component is strongly recommended to ensure the best end-user experience, making it clear to your users what actions are available and driving engagement with offers. Building support for this now gives you a head start so you're ready when these offers go live.
### How Components Are Returned
The components included in the response depend on what you request via the `supportedComponents` query parameter:
* **All components** (`shortDescription`, `longDescription`, `cta`, `tags`, `detailTags`, `baseReward`): The full experience. Provides dynamic descriptions, call-to-action buttons, contextual tags, and a formatted reward string for both list and detail views. Best for apps that support interactive elements.
* **Description + call-to-action components** (`shortDescription`, `longDescription`, `cta`): Provides dynamic descriptions that reflect per-user offer state along with a call-to-action button for actions like offer activation or offer boosts. Best for apps that want actionable offers without rendering tag-based UI.
* **Description-only components** (`shortDescription`, `longDescription`): Provides dynamic descriptions without interactive elements. Best for apps that cannot render buttons or tags. In this case, Kard uses a **VIEW event** on the offer as the activation signal. When a user views an offer detail page, you fire a VIEW attribution event. After the event, re-fetch the offer to display the updated descriptions reflecting the new user state.
You can request any combination of components. Kard evaluates each offer independently and returns the appropriate data based on what you request.
## Implementation
### Step 1: Add the `supportedComponents` Query Parameter
Append the `supportedComponents` query parameter to your existing Get Offers by User or Get Locations by User requests. Use repeated parameters for multiple component types.
**Get Offers by User with all components:**
```
GET /v2/issuers/{{organizationId}}/users/{{userId}}/offers?supportedComponents=shortDescription&supportedComponents=longDescription&supportedComponents=cta&supportedComponents=tags&supportedComponents=detailTags&supportedComponents=baseReward
```
**Get Offers by User with description + call-to-action components:**
```
GET /v2/issuers/{{organizationId}}/users/{{userId}}/offers?supportedComponents=longDescription&supportedComponents=shortDescription&supportedComponents=cta
```
**Get Locations by User with all components:**
```
GET /v2/issuers/{{organizationId}}/users/{{userId}}/locations?include=offers&supportedComponents=shortDescription&supportedComponents=longDescription&supportedComponents=cta&supportedComponents=tags&supportedComponents=detailTags&supportedComponents=baseReward
```
**Get Locations by User with description + call-to-action components:**
```
GET /v2/issuers/{{organizationId}}/users/{{userId}}/locations?include=offers&supportedComponents=longDescription&supportedComponents=shortDescription&supportedComponents=cta
```
**Get Offers by User with description-only components:**
```
GET /v2/issuers/{{organizationId}}/users/{{userId}}/offers?supportedComponents=shortDescription&supportedComponents=longDescription
```
**Get Locations by User with description-only components:**
```
GET /v2/issuers/{{organizationId}}/users/{{userId}}/locations?include=offers&supportedComponents=shortDescription&supportedComponents=longDescription
```
For Get Locations by User, you **must** include `include=offers` in the query to receive offer data with components.
### Step 2: Parse the `components` Object
When `supportedComponents` is provided and an offer is eligible for extended data, the response includes a `components` object within the offer `attributes`.
**Example Response with all components (offer not yet activated):**
```json
{
"data": [
{
"type": "standardOffer",
"id": "5e27318c9b346f00087fbb5c",
"attributes": {
"name": "Worlds Greatest Chicken",
"userReward": {
"type": "PERCENT",
"value": 5.7
},
"purchaseChannel": ["INSTORE"],
"startDate": "2024-11-17T05:00:00Z",
"expirationDate": "2025-03-17T05:00:00Z",
"terms": "Worlds Greatest Chicken offers are only available within US Locations.",
"isTargeted": true,
"assets": [
{
"type": "IMG_VIEW",
"url": "https://attribution.getkard.com/image.jpg?token=valid.signed.jwt",
"alt": "Worlds Greatest Chicken Logo Image"
}
],
"components": {
"shortDescription": "Multi-use",
"longDescription": "Use your linked card on qualifying purchases to redeem multiple times.",
"cta": {
"buttonText": "Tap to activate",
"buttonStyle": "PRIMARY",
"action": {
"url": "/v2/issuers/{{organizationId}}/users/{{userId}}/offers/5e27318c9b346f00087fbb5c/activate",
"method": "POST"
}
},
"tags": [],
"detailTags": ["Activated"],
"baseReward": "5.7% cash back"
}
},
"relationships": {
"category": {
"data": [
{ "type": "category", "id": "65920081b524d126068de24a" }
]
}
}
}
],
"links": {
"self": "/v2/issuers/{{organizationId}}/users/{{userId}}/offers?supportedComponents=shortDescription&supportedComponents=longDescription&supportedComponents=cta&supportedComponents=tags&supportedComponents=detailTags&supportedComponents=baseReward",
"prev": null,
"next": null
},
"included": [
{
"type": "category",
"id": "65920081b524d126068de24a",
"attributes": { "name": "Food & Beverage" }
}
]
}
```
**Example Response with all components (offer already activated):**
```json
"components": {
"shortDescription": "Multi-use",
"longDescription": "Use your linked card on qualifying purchases to redeem multiple times.",
"tags": [],
"detailTags": ["Activated"],
"baseReward": "5.7% cash back"
}
```
Note that when the offer is already activated, the `cta` component is not included in the response.
### Step 3: Render Components in Your UI
How you render the components depends on which ones you requested:
**If you requested all components (`shortDescription`, `longDescription`, `cta`, `tags`, `detailTags`, and `baseReward`)**
1. Display `shortDescription` on offer cards in list/browse views
2. Display `longDescription` on the offer detail page
3. If `cta` is present and `buttonStyle` is `PRIMARY`, display the call-to-action button using `buttonText` — when tapped, call the URL in `cta.action.url` using the specified `cta.action.method` (see Step 4a)
4. If `cta` is absent, the offer has already been activated — hide the call-to-action button
5. Render `tags` as overlays or badges on the offer card in list/browse views (may be empty)
6. Render `detailTags` as labels on the offer detail page
7. Display `baseReward` as the formatted reward amount on the offer card (e.g., "5.7% cash back")
**All components, offer not activated:**
**All components, offer is activated:**
**If you requested a subset of components (`shortDescription`, `longDescription`, and `cta`):**
1. Display `longDescription` on the offer detail page
2. Display `shortDescription` on offer cards in list views
3. If `cta` is present and `buttonStyle` is `PRIMARY`, display the call-to-action button using `buttonText` — when tapped, call the URL in `cta.action.url` using the specified `cta.action.method` (see Step 4a)
4. If `cta` is absent, the offer has already been activated — hide the call-to-action button
**Description + call-to-action components, offer not activated:**
**Description + call-to-action components, offer is activated:**
**If you requested description-only components (`shortDescription` and `longDescription`):**
This approach is for issuers that cannot render interactive call-to-action buttons. Instead of using a call-to-action button to activate or boost offers, the **VIEW event** serves as the activation signal.
1. Display `shortDescription` on offer cards in list/browse views
2. Display `longDescription` on the offer detail page
3. When a user navigates to the offer detail page, fire a **VIEW attribution event** (see Step 4b)
4. After the VIEW event, **re-fetch the offer** to get updated descriptions that reflect the new user state (e.g., descriptions change from "Tap to activate" to "Activated")
5. Re-render the offer with the updated `shortDescription` and `longDescription`
**Important:** Without a call-to-action button, the user has no explicit activation action. The VIEW event acts as a proxy for activation. You **must** re-fetch and re-render the offer after firing the VIEW event to display the updated state to the user.
### Step 4a: Handle Call-To-Action Events
**Activations are an upcoming feature.** Some offers will require user action before the offer can be redeemed. Supporting the call-to-action flow is key to delivering a clear, intuitive experience for your end users by surfacing actionable next steps directly in the UI. Integrating now means you'll be ready to support these offers as soon as they launch.
When a user taps a `PRIMARY` call-to-action button, call the activation endpoint provided in `cta.action`:
```
POST /v2/issuers/{{organizationId}}/users/{{userId}}/offers/{{offerId}}/activate
```
You can include `supportedComponents` and `include=offer` as query parameters to receive the updated offer in the response:
```
POST /v2/issuers/{{organizationId}}/users/{{userId}}/offers/{{offerId}}/activate?supportedComponents=shortDescription&supportedComponents=longDescription&supportedComponents=cta&supportedComponents=tags&supportedComponents=detailTags&supportedComponents=baseReward&include=offer
```
**Response (201 Created):**
```json
{
"data": {
"type": "offerAttribution",
"id": "attribution-event-id",
"attributes": {
"entityId": "5e27318c9b346f00087fbb5c",
"eventCode": "ACTIVATE",
"medium": "CTA",
"eventDate": "2025-01-07T16:30:00Z"
}
},
"included": [
{
"type": "standardOffer",
"id": "5e27318c9b346f00087fbb5c",
"attributes": {
"name": "Worlds Greatest Chicken",
"userReward": { "type": "PERCENT", "value": 5.7 },
"components": {
"shortDescription": "Multi-use",
"longDescription": "Use your linked card on qualifying purchases to redeem multiple times.",
"tags": [],
"detailTags": ["Activated"],
"baseReward": "5.7% cash back"
}
}
}
]
}
```
Use the updated offer from `included` to immediately refresh your UI without re-fetching the full offer list.
### Step 4b: Handle VIEW Event Activation (Description-Only)
If you are only using `shortDescription` and `longDescription` (no `cta`), use the VIEW attribution event to signal that a user has engaged with an offer. This acts as the activation trigger.
When a user opens an offer detail page, fire a VIEW event:
```
POST /v2/issuers/{{organizationId}}/users/{{userId}}/offers/{{offerId}}/view
```
After a successful VIEW event, **re-fetch the offer** with your supported components to get the updated descriptions:
```
GET /v2/issuers/{{organizationId}}/users/{{userId}}/offers?supportedComponents=shortDescription&supportedComponents=longDescription
```
The descriptions will now reflect the updated user state:
```json
"components": {
"shortDescription": "Activated",
"longDescription": "Activated"
}
```
Re-render the offer detail page with the updated `longDescription`, and update the offer card with the new `shortDescription` in your list views.
**We recommend integrating with call-to-action components when possible.** The call-to-action flow gives users a clear, explicit action to activate and boost offers and provides a better user experience than the implicit VIEW event approach.
## Component Reference
### `components` Object
| Field | Type | Description |
| ------------------ | --------------------- | ---------------------------------------------------------------------------------- |
| `shortDescription` | `string` (optional) | Brief dynamic description for list/browse views |
| `longDescription` | `string` (optional) | Detailed dynamic description for offer detail pages |
| `cta` | `object` (optional) | Call-to-action button configuration |
| `tags` | `string[]` (optional) | Contextual labels for list/browse views |
| `detailTags` | `string[]` (optional) | Contextual labels for offer detail pages |
| `baseReward` | `string` (optional) | Formatted reward string for display (e.g., "5.7% cash back" or "\$2.00 cash back") |
### `cta` Object
| Field | Type | Description |
| --------------- | -------- | -------------------------------------------------------------------------------------------- |
| `buttonText` | `string` | Text to display on the button (e.g., "Tap to activate") |
| `buttonStyle` | `enum` | `PRIMARY` (actionable). The `cta` component is omitted entirely once the offer is activated. |
| `action` | `object` | Contains the URL and method to call when the button is tapped |
| `action.url` | `string` | API endpoint to call when the button is tapped |
| `action.method` | `string` | HTTP method to use (e.g., `POST`) |
## Important Notes
**Component availability is per-offer.** Different offers in the same response may return different components depending on their configuration.
**The `components` object is additive.** Existing fields like `name`, `userReward`, `terms`, and `assets` are always returned regardless of whether you request components.
## Best Practices
* **Always check for the presence of `components` before rendering.** Not every offer will include it — your UI should gracefully fall back to standard offer fields.
* **Use `cta.action` exactly as provided.** The URL and method are pre-configured by Kard. Do not modify the URL path or method.
* **Render call-to-action state changes immediately.** After a successful activation call, use the updated offer from the response `included` array to update your UI without waiting for a full list refresh.
* **Choose components based on your UI capabilities.** If you cannot render interactive buttons, request `shortDescription` and `longDescription` instead of `cta`, `tags`, and `detailTags`.
* **Request only the components you support.** Avoid requesting components you don't intend to render.
* **Handle the absence of `cta` after activation.** When an offer has been activated, the `cta` component is not included in the response. Your UI should hide the call-to-action button when `cta` is absent.
* **Do not cache component data across sessions.** Component values like tags and CTA state are dynamic and may change between requests.
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Create Incoming Transactions
POST https://rewards-api.getkard.com/v2/issuers/{organizationId}/transactions
Content-Type: application/json
Call this endpoint to send all transactions made by all your enrolled users in your rewards program. The request body will depend on the transaction type.
Please use the correct type when calling the endpoint:
- `transaction`: These incoming transactions will be processed and matched by the Kard system. Learn more about the [Transaction CLO Matching](https://github.com/kard-financial/kard-postman#c-transaction-clo-matching) flow here.
- `matchedTransaction`: For pre-matched transactions that need validation on match by the Kard system.
- `coreTransaction`: For transactions from core banking systems with limited card-level data. Required scopes: `transaction:write` Note: `Maximum of 500 transactions can be created per request`.
Reference: https://docs.getkard.com/api/transactions/create
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/transactions:
post:
operationId: create
summary: Create Incoming Transactions
description: >-
Call this endpoint to send all transactions made by all your enrolled
users in your rewards program. The request body will depend on the
transaction type.
Please use the correct type when calling the endpoint:
- `transaction`: These incoming transactions will be processed and
matched by the Kard system. Learn more about the [Transaction CLO
Matching](https://github.com/kard-financial/kard-postman#c-transaction-clo-matching)
flow here.
- `matchedTransaction`: For pre-matched transactions that need
validation on match by the Kard system.
- `coreTransaction`: For transactions from core banking systems with
limited card-level data. Required scopes: `transaction:write` Note: `Maximum of 500 transactions can be created per request`.
tags:
- subpackage_transactions
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'202':
description: Response with status 202
content:
application/json:
schema:
$ref: '#/components/schemas/type_transactions:TransactionsResponse'
'207':
description: Error response with status 207
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_transactions:TransactionsMultiResponse
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'409':
description: Error response with status 409
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_transactions:TransactionsRequestBody'
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_transactions:TransactionStatus:
type: string
enum:
- APPROVED
- SETTLED
- REVERSED
- RETURNED
- DECLINED
title: TransactionStatus
type_transactions:States:
type: string
enum:
- AL
- AK
- AS
- AZ
- AR
- CA
- CO
- CT
- DE
- DC
- FM
- FL
- GA
- GU
- HI
- ID
- IL
- IN
- IA
- KS
- KY
- LA
- ME
- MH
- MD
- MA
- MI
- MN
- MS
- MO
- MT
- NE
- NV
- NH
- NJ
- NM
- NY
- NC
- ND
- MP
- OH
- OK
- OR
- PW
- PA
- PR
- RI
- SC
- SD
- TN
- TX
- UT
- VT
- VI
- VA
- WA
- WV
- WI
- WY
title: States
type_transactions:Merchant:
type: object
properties:
id:
type: string
description: >-
Acquirer Merchant Identification Number (MID) — usually a 15 digit
numerical identifier code. Note, this field is REQUIRED for local
offers. We HIGHLY RECOMMEND sending this field as it will be
required in the near future.
name:
type: string
description: Merchant name associated with transaction
addrStreet:
type: string
description: Merchant street address associated with transaction.
addrCity:
type: string
description: Merchant address city associated with transaction.
addrState:
$ref: '#/components/schemas/type_transactions:States'
description: Merchant address state associated with transaction.
addrZipcode:
type: string
description: Merchant address zip code associated with transaction.
addrCountry:
type: string
description: Merchant address country associated with transaction.
latitude:
type: string
description: Merchant latitude geocoordinate associated with transaction.
longitude:
type: string
description: Merchant longitude geocoordinate associated with transaction.
storeId:
type: string
description: Merchant store ID where transaction originated from
required:
- name
title: Merchant
type_transactions:DirectionType:
type: string
enum:
- DEBIT
- CREDIT
title: DirectionType
type_transactions:TransactionPaymentType:
type: string
enum:
- CARD
title: TransactionPaymentType
type_commons:CardNetwork:
type: string
enum:
- VISA
- MASTERCARD
- AMERICANEXPRESS
- DISCOVER
description: Supported card networks
title: CardNetwork
type_transactions:VisaMidDetails:
type: object
properties:
vmid:
type: string
description: Visa Merchant ID (VMID) associated with the transaction
vsid:
type: string
description: Visa Store ID (VSID) associated with the transaction
required:
- vmid
- vsid
title: VisaMidDetails
type_transactions:ProcessorMid:
oneOf:
- type: object
properties:
processor:
type: string
enum:
- VISA
description: 'Discriminator value: VISA'
mids:
$ref: '#/components/schemas/type_transactions:VisaMidDetails'
description: Merchant ID (MID) associated with the processor
required:
- processor
- mids
discriminator:
propertyName: processor
title: ProcessorMid
type_transactions:TransactionsAttributes:
type: object
properties:
userId:
type: string
description: The ID of the user as defined on the issuers system
amount:
type: integer
description: Transaction amount in cents
subtotal:
type: integer
description: >-
The base amount in cents excluding additional charges (such as tips,
taxes, and other fees).
status:
$ref: '#/components/schemas/type_transactions:TransactionStatus'
description: Transaction status
currency:
type: string
description: Currency of transaction
description:
type: string
description: >-
Description of transaction - usually includes merchant and other key
details on transaction
description2:
type: string
description: >-
Description2 of transaction — usually includes other merchant
identifying information
mcc:
type: string
description: >-
Merchant Category Code (usually a 4-digit numerical number).
Note, this field is REQUIRED for SOME national offers. We HIGHLY
RECOMMEND sending this field as it will be required in the near
future.
coreProviderId:
type: string
description: Name of processor associated with transaction
transactionDate:
type: string
format: date-time
description: >-
Timestamp for REVERSED, RETURNED, DECLINED transaction
events; REQUIRED for transactions with REVERSED, RETURNED,
DECLINED status. Date string should be in ISO 8601 format
i.e.`'YYYY-MM-DDThh:mm:ss.sTZD'` where TZD = time zone designator (Z
or +hh:mm or -hh:mm) i.e. `1994-11-05T08:15:30-05:00` OR
`1994-11-05T08:15:30Z`
authorizationDate:
type: string
format: date-time
description: >-
Timestamp for APPROVED transaction event; REQUIRED for
transactions with APPROVED status, and HIGHLY
RECOMMENDED to include for transactions with a SETTLED
status. Date string should be in ISO 8601 format
i.e.`'YYYY-MM-DDThh:mm:ss.sTZD'` where TZD = time zone designator (Z
or +hh:mm or -hh:mm) i.e. `1994-11-05T08:15:30-05:00 OR
1994-11-05T08:15:30Z`
settledDate:
type: string
format: date-time
description: >-
Timestamp for SETTLED transaction event, REQUIRED for
transactions with SETTLED status. Date string should be in
ISO 8601 format i.e.`'YYYY-MM-DDThh:mm:ss.sTZD'` where TZD = time
zone designator (Z or +hh:mm or -hh:mm) i.e.
`1994-11-05T08:15:30-05:00` OR `1994-11-05T08:15:30Z`
merchant:
$ref: '#/components/schemas/type_transactions:Merchant'
description: Merchant details
cardPresence:
type: string
description: Whether card was present at time of transaction
panEntryMode:
type: string
description: PAN entry mode
cardBIN:
type: string
description: >-
Bank identification number (BIN). Must be a valid BIN of 6 digits.
If over 6 digits, please send first 6.
cardLastFour:
type: string
description: Card last four digits.
authorizationCode:
type: string
description: Transaction approval code
retrievalReferenceNumber:
type: string
description: Retrieval Reference Number
systemTraceAuditNumber:
type: string
description: System Trace Audit Number
acquirerReferenceNumber:
type: string
description: Acquirer Reference Number
direction:
$ref: '#/components/schemas/type_transactions:DirectionType'
description: The direction in which the funds flow - DEBIT or CREDIT
paymentType:
$ref: '#/components/schemas/type_transactions:TransactionPaymentType'
description: The type of payment involved in the transaction.
cardNetwork:
$ref: '#/components/schemas/type_commons:CardNetwork'
description: The card network associated with the transaction
transactionId:
type: string
description: The transaction ID
cardProductId:
type: string
description: The card product ID associated with the transaction
userZipCode:
type: string
description: The zip code of the user who made the transaction
processorMids:
$ref: '#/components/schemas/type_transactions:ProcessorMid'
description: Network specific merchant IDs (MIDs) associated with the transaction
required:
- userId
- amount
- status
- currency
- description
- cardBIN
- cardLastFour
- direction
- paymentType
- transactionId
title: TransactionsAttributes
type_transactions:PaymentType:
type: string
enum:
- CARD
- CASH
- UNKNOWN
title: PaymentType
type_transactions:ReceiptMediumType:
type: string
enum:
- ELECTRONIC
- PHYSICAL
title: ReceiptMediumType
type_transactions:MatchedTransactionsAttributes:
type: object
properties:
userId:
type: string
description: The ID of the user as defined on the issuers system
amount:
type: integer
description: Transaction amount in cents
subtotal:
type: integer
description: >-
The base amount in cents excluding additional charges (such as tips,
taxes, and other fees).
description:
type: string
description: >-
Description of transaction - usually includes merchant and other key
details on transaction
authorizationDate:
type: string
format: date-time
description: >-
Timestamp for transaction event. Date string should be in ISO 8601
format i.e.`'YYYY-MM-DDThh:mm:ss.sTZD'` where TZD = time zone
designator (Z or +hh:mm or -hh:mm) i.e. `1994-11-05T08:15:30-05:00
OR 1994-11-05T08:15:30Z`
matchedOfferId:
type: string
description: >-
The ID of the Kard offer to which the transaction was matched. If
this field is omitted, the transaction will be considered unmatched
to any Kard offer. This field **must** be omitted when the
`paymentType` is `UNKNOWN` and neither an orderId nor a
`cardLastFour` is supplied.
matchedLocationId:
type: string
description: >-
The unique Kard location ID where the transaction took place. This
field **must** be omitted when `paymentType` is `UNKNOWN`.
merchant:
$ref: '#/components/schemas/type_transactions:Merchant'
description: Merchant details
paymentType:
$ref: '#/components/schemas/type_transactions:PaymentType'
description: The type of payment involved in the transaction.
cardBIN:
type: string
description: >-
Bank identification number (BIN). Must be a valid BIN of 6 digits.
If over 6 digits, please send first 6. This field **must** be
omitted when `paymentType` is `CASH` or `UNKNOWN`.
cardLastFour:
type: string
description: >-
Card last four digits. This field is **required** when `paymentType`
is `CARD` and `matchedOfferId` is provided. It **must** be omitted
when `paymentType` is `CASH`.
authorizationCode:
type: string
description: Transaction approval code
retrievalReferenceNumber:
type: string
description: Retrieval Reference Number
systemTraceAuditNumber:
type: string
description: System Trace Audit Number
acquirerReferenceNumber:
type: string
description: Acquirer Reference Number
direction:
$ref: '#/components/schemas/type_transactions:DirectionType'
description: The direction in which the funds flow - DEBIT or CREDIT
cardNetwork:
$ref: '#/components/schemas/type_commons:CardNetwork'
description: >-
The card network associated with the transaction. This field
**must** be omitted when `paymentType` is `CASH` or `UNKNOWN`.
transactionId:
type: string
description: The transaction ID
cardProductId:
type: string
description: >-
The card product ID associated with the transaction. This field
**must** be omitted when `paymentType` is `CASH` or `UNKNOWN`.
orderId:
type: string
description: >-
The unique identifier for an online order linked to this
transaction.
receiptMedium:
$ref: '#/components/schemas/type_transactions:ReceiptMediumType'
description: >-
Indicates the format of the receipt from which the transaction is
derived.
required:
- userId
- amount
- description
- authorizationDate
- paymentType
- direction
- transactionId
title: MatchedTransactionsAttributes
type_transactions:CoreTransactionAttributes:
type: object
properties:
userId:
type: string
description: The ID of the user as defined on the issuers system
transactionId:
type: string
description: The transaction ID from the core banking system
amount:
type: integer
description: Transaction amount in cents
currency:
type: string
description: Currency of transaction in ISO 4217 alpha-3 format
description:
type: string
description: >-
Description of transaction - usually includes merchant and other key
details on transaction
direction:
$ref: '#/components/schemas/type_transactions:DirectionType'
description: The direction in which the funds flow - DEBIT or CREDIT
status:
type: string
enum:
- SETTLED
description: Transaction status (always SETTLED for core transactions)
settledDate:
type: string
format: date-time
description: >-
Timestamp when transaction was settled. Date string should be in ISO
8601 format i.e.'YYYY-MM-DDThh:mm:ss.sTZD' where TZD = time zone
designator (Z or +hh:mm or -hh:mm) i.e. 1994-11-05T08:15:30-05:00 OR
1994-11-05T08:15:30Z
authorizationDate:
type: string
format: date-time
description: >-
Timestamp for transaction authorization. Date string should be in
ISO 8601 format i.e.'YYYY-MM-DDThh:mm:ss.sTZD' where TZD = time zone
designator (Z or +hh:mm or -hh:mm) i.e. 1994-11-05T08:15:30-05:00 OR
1994-11-05T08:15:30Z
financialInstitutionName:
type: string
description: >-
Deprecated. Use `financialInstitutionId` instead. Name of the
financial institution.
financialInstitutionId:
type: string
description: Unique identifier of the financial institution
cardLastFours:
type: array
items:
type: string
description: >-
Last four digits of the card(s) that may have been used for the
transaction. When the issuer cannot determine which specific card
was used, multiple values are provided as candidates.
required:
- userId
- transactionId
- amount
- currency
- description
- direction
- status
- settledDate
- authorizationDate
title: CoreTransactionAttributes
type_transactions:Transactions:
oneOf:
- type: object
properties:
type:
type: string
enum:
- transaction
description: 'Discriminator value: transaction'
id:
type: string
description: >-
Unique identifier for the transaction event. This must be
unique for each distinct event sent to the API.
attributes:
$ref: '#/components/schemas/type_transactions:TransactionsAttributes'
required:
- type
- id
- attributes
- type: object
properties:
type:
type: string
enum:
- matchedTransaction
description: 'Discriminator value: matchedTransaction'
id:
type: string
description: >-
Unique identifier for the transaction event. This must be
unique for each distinct event sent to the API.
attributes:
$ref: >-
#/components/schemas/type_transactions:MatchedTransactionsAttributes
required:
- type
- id
- attributes
- type: object
properties:
type:
type: string
enum:
- coreTransaction
description: 'Discriminator value: coreTransaction'
id:
type: string
description: >-
Unique identifier for the transaction event. This must be
unique for each distinct event sent to the API.
attributes:
$ref: '#/components/schemas/type_transactions:CoreTransactionAttributes'
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: Transactions
type_transactions:TransactionsRequestBody:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_transactions:Transactions'
description: >-
Discriminated union representing the request body for submitting a
transaction.
Use `type` to distinguish between the two:
- `transaction`: For transactions requiring processing and matching
by the Kard system.
- `matchedTransaction`: For pre-matched transactions that need
validation on match by the Kard system.
- `coreTransaction`: For transactions from core banking systems with
limited card-level data.
required:
- data
title: TransactionsRequestBody
type_commons:ResourceType:
type: string
description: Type of document returned
title: ResourceType
type_commons:JobStatus:
type: string
enum:
- queued
description: Status of the job
title: JobStatus
type_commons:Job:
type: object
properties:
status:
$ref: '#/components/schemas/type_commons:JobStatus'
message:
type: string
description: Message regarding the status of the job request
required:
- status
- message
title: Job
type_transactions:TransactionsResponseData:
type: object
properties:
type:
$ref: '#/components/schemas/type_commons:ResourceType'
id:
type: string
description: The request id of the pending job
attributes:
$ref: '#/components/schemas/type_commons:Job'
required:
- type
- id
- attributes
title: TransactionsResponseData
type_transactions:TransactionsResponse:
type: object
properties:
data:
$ref: '#/components/schemas/type_transactions:TransactionsResponseData'
required:
- data
title: TransactionsResponse
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_transactions:TransactionsMultiResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
data:
$ref: '#/components/schemas/type_transactions:TransactionsResponseData'
required:
- errors
- data
title: TransactionsMultiResponse
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python Transaction
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/transactions"
payload = { "data": [
{
"type": "transaction",
"attributes": {
"userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
"amount": 1000,
"status": "APPROVED",
"currency": "USD",
"description": "ADVANCEAUTO",
"cardBIN": "123456",
"cardLastFour": "4321",
"direction": "DEBIT",
"paymentType": "CARD",
"transactionId": "2467de37-cbdc-416d-a359-75de87bfffb0",
"subtotal": 800,
"description2": "ADVANCEAUTO",
"mcc": "1234",
"authorizationDate": "2021-07-02T17:47:06Z",
"merchant": {
"name": "ADVANCEAUTO",
"id": "12345678901234567",
"addrStreet": "125 Main St",
"addrCity": "Philadelphia",
"addrState": "PA",
"addrZipcode": "19147",
"addrCountry": "United States",
"latitude": "37.9419429",
"longitude": "-73.1446869",
"storeId": "12345"
},
"authorizationCode": "123456",
"retrievalReferenceNumber": "100804333919",
"systemTraceAuditNumber": "333828",
"acquirerReferenceNumber": "1234567890123456789012345678",
"cardProductId": "1234567890123456789012345678",
"processorMids": {
"processor": "VISA",
"mids": {
"vmid": "12345678901",
"vsid": "12345678"
}
}
},
"id": "309rjfoincor3icno3rind093cdow3jciwjdwcm"
}
] }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript Transaction
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/transactions';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":[{"type":"transaction","attributes":{"userId":"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69","amount":1000,"status":"APPROVED","currency":"USD","description":"ADVANCEAUTO","cardBIN":"123456","cardLastFour":"4321","direction":"DEBIT","paymentType":"CARD","transactionId":"2467de37-cbdc-416d-a359-75de87bfffb0","subtotal":800,"description2":"ADVANCEAUTO","mcc":"1234","authorizationDate":"2021-07-02T17:47:06Z","merchant":{"name":"ADVANCEAUTO","id":"12345678901234567","addrStreet":"125 Main St","addrCity":"Philadelphia","addrState":"PA","addrZipcode":"19147","addrCountry":"United States","latitude":"37.9419429","longitude":"-73.1446869","storeId":"12345"},"authorizationCode":"123456","retrievalReferenceNumber":"100804333919","systemTraceAuditNumber":"333828","acquirerReferenceNumber":"1234567890123456789012345678","cardProductId":"1234567890123456789012345678","processorMids":{"processor":"VISA","mids":{"vmid":"12345678901","vsid":"12345678"}}},"id":"309rjfoincor3icno3rind093cdow3jciwjdwcm"}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go Transaction
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/transactions"
payload := strings.NewReader("{\n \"data\": [\n {\n \"type\": \"transaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 1000,\n \"status\": \"APPROVED\",\n \"currency\": \"USD\",\n \"description\": \"ADVANCEAUTO\",\n \"cardBIN\": \"123456\",\n \"cardLastFour\": \"4321\",\n \"direction\": \"DEBIT\",\n \"paymentType\": \"CARD\",\n \"transactionId\": \"2467de37-cbdc-416d-a359-75de87bfffb0\",\n \"subtotal\": 800,\n \"description2\": \"ADVANCEAUTO\",\n \"mcc\": \"1234\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"merchant\": {\n \"name\": \"ADVANCEAUTO\",\n \"id\": \"12345678901234567\",\n \"addrStreet\": \"125 Main St\",\n \"addrCity\": \"Philadelphia\",\n \"addrState\": \"PA\",\n \"addrZipcode\": \"19147\",\n \"addrCountry\": \"United States\",\n \"latitude\": \"37.9419429\",\n \"longitude\": \"-73.1446869\",\n \"storeId\": \"12345\"\n },\n \"authorizationCode\": \"123456\",\n \"retrievalReferenceNumber\": \"100804333919\",\n \"systemTraceAuditNumber\": \"333828\",\n \"acquirerReferenceNumber\": \"1234567890123456789012345678\",\n \"cardProductId\": \"1234567890123456789012345678\",\n \"processorMids\": {\n \"processor\": \"VISA\",\n \"mids\": {\n \"vmid\": \"12345678901\",\n \"vsid\": \"12345678\"\n }\n }\n },\n \"id\": \"309rjfoincor3icno3rind093cdow3jciwjdwcm\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby Transaction
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/transactions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": [\n {\n \"type\": \"transaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 1000,\n \"status\": \"APPROVED\",\n \"currency\": \"USD\",\n \"description\": \"ADVANCEAUTO\",\n \"cardBIN\": \"123456\",\n \"cardLastFour\": \"4321\",\n \"direction\": \"DEBIT\",\n \"paymentType\": \"CARD\",\n \"transactionId\": \"2467de37-cbdc-416d-a359-75de87bfffb0\",\n \"subtotal\": 800,\n \"description2\": \"ADVANCEAUTO\",\n \"mcc\": \"1234\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"merchant\": {\n \"name\": \"ADVANCEAUTO\",\n \"id\": \"12345678901234567\",\n \"addrStreet\": \"125 Main St\",\n \"addrCity\": \"Philadelphia\",\n \"addrState\": \"PA\",\n \"addrZipcode\": \"19147\",\n \"addrCountry\": \"United States\",\n \"latitude\": \"37.9419429\",\n \"longitude\": \"-73.1446869\",\n \"storeId\": \"12345\"\n },\n \"authorizationCode\": \"123456\",\n \"retrievalReferenceNumber\": \"100804333919\",\n \"systemTraceAuditNumber\": \"333828\",\n \"acquirerReferenceNumber\": \"1234567890123456789012345678\",\n \"cardProductId\": \"1234567890123456789012345678\",\n \"processorMids\": {\n \"processor\": \"VISA\",\n \"mids\": {\n \"vmid\": \"12345678901\",\n \"vsid\": \"12345678\"\n }\n }\n },\n \"id\": \"309rjfoincor3icno3rind093cdow3jciwjdwcm\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
```java Transaction
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/organization-123/transactions")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": [\n {\n \"type\": \"transaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 1000,\n \"status\": \"APPROVED\",\n \"currency\": \"USD\",\n \"description\": \"ADVANCEAUTO\",\n \"cardBIN\": \"123456\",\n \"cardLastFour\": \"4321\",\n \"direction\": \"DEBIT\",\n \"paymentType\": \"CARD\",\n \"transactionId\": \"2467de37-cbdc-416d-a359-75de87bfffb0\",\n \"subtotal\": 800,\n \"description2\": \"ADVANCEAUTO\",\n \"mcc\": \"1234\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"merchant\": {\n \"name\": \"ADVANCEAUTO\",\n \"id\": \"12345678901234567\",\n \"addrStreet\": \"125 Main St\",\n \"addrCity\": \"Philadelphia\",\n \"addrState\": \"PA\",\n \"addrZipcode\": \"19147\",\n \"addrCountry\": \"United States\",\n \"latitude\": \"37.9419429\",\n \"longitude\": \"-73.1446869\",\n \"storeId\": \"12345\"\n },\n \"authorizationCode\": \"123456\",\n \"retrievalReferenceNumber\": \"100804333919\",\n \"systemTraceAuditNumber\": \"333828\",\n \"acquirerReferenceNumber\": \"1234567890123456789012345678\",\n \"cardProductId\": \"1234567890123456789012345678\",\n \"processorMids\": {\n \"processor\": \"VISA\",\n \"mids\": {\n \"vmid\": \"12345678901\",\n \"vsid\": \"12345678\"\n }\n }\n },\n \"id\": \"309rjfoincor3icno3rind093cdow3jciwjdwcm\"\n }\n ]\n}")
.asString();
```
```php Transaction
request('POST', 'https://rewards-api.getkard.com/v2/issuers/organization-123/transactions', [
'body' => '{
"data": [
{
"type": "transaction",
"attributes": {
"userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
"amount": 1000,
"status": "APPROVED",
"currency": "USD",
"description": "ADVANCEAUTO",
"cardBIN": "123456",
"cardLastFour": "4321",
"direction": "DEBIT",
"paymentType": "CARD",
"transactionId": "2467de37-cbdc-416d-a359-75de87bfffb0",
"subtotal": 800,
"description2": "ADVANCEAUTO",
"mcc": "1234",
"authorizationDate": "2021-07-02T17:47:06Z",
"merchant": {
"name": "ADVANCEAUTO",
"id": "12345678901234567",
"addrStreet": "125 Main St",
"addrCity": "Philadelphia",
"addrState": "PA",
"addrZipcode": "19147",
"addrCountry": "United States",
"latitude": "37.9419429",
"longitude": "-73.1446869",
"storeId": "12345"
},
"authorizationCode": "123456",
"retrievalReferenceNumber": "100804333919",
"systemTraceAuditNumber": "333828",
"acquirerReferenceNumber": "1234567890123456789012345678",
"cardProductId": "1234567890123456789012345678",
"processorMids": {
"processor": "VISA",
"mids": {
"vmid": "12345678901",
"vsid": "12345678"
}
}
},
"id": "309rjfoincor3icno3rind093cdow3jciwjdwcm"
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp Transaction
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/transactions");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": [\n {\n \"type\": \"transaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 1000,\n \"status\": \"APPROVED\",\n \"currency\": \"USD\",\n \"description\": \"ADVANCEAUTO\",\n \"cardBIN\": \"123456\",\n \"cardLastFour\": \"4321\",\n \"direction\": \"DEBIT\",\n \"paymentType\": \"CARD\",\n \"transactionId\": \"2467de37-cbdc-416d-a359-75de87bfffb0\",\n \"subtotal\": 800,\n \"description2\": \"ADVANCEAUTO\",\n \"mcc\": \"1234\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"merchant\": {\n \"name\": \"ADVANCEAUTO\",\n \"id\": \"12345678901234567\",\n \"addrStreet\": \"125 Main St\",\n \"addrCity\": \"Philadelphia\",\n \"addrState\": \"PA\",\n \"addrZipcode\": \"19147\",\n \"addrCountry\": \"United States\",\n \"latitude\": \"37.9419429\",\n \"longitude\": \"-73.1446869\",\n \"storeId\": \"12345\"\n },\n \"authorizationCode\": \"123456\",\n \"retrievalReferenceNumber\": \"100804333919\",\n \"systemTraceAuditNumber\": \"333828\",\n \"acquirerReferenceNumber\": \"1234567890123456789012345678\",\n \"cardProductId\": \"1234567890123456789012345678\",\n \"processorMids\": {\n \"processor\": \"VISA\",\n \"mids\": {\n \"vmid\": \"12345678901\",\n \"vsid\": \"12345678\"\n }\n }\n },\n \"id\": \"309rjfoincor3icno3rind093cdow3jciwjdwcm\"\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift Transaction
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
[
"type": "transaction",
"attributes": [
"userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
"amount": 1000,
"status": "APPROVED",
"currency": "USD",
"description": "ADVANCEAUTO",
"cardBIN": "123456",
"cardLastFour": "4321",
"direction": "DEBIT",
"paymentType": "CARD",
"transactionId": "2467de37-cbdc-416d-a359-75de87bfffb0",
"subtotal": 800,
"description2": "ADVANCEAUTO",
"mcc": "1234",
"authorizationDate": "2021-07-02T17:47:06Z",
"merchant": [
"name": "ADVANCEAUTO",
"id": "12345678901234567",
"addrStreet": "125 Main St",
"addrCity": "Philadelphia",
"addrState": "PA",
"addrZipcode": "19147",
"addrCountry": "United States",
"latitude": "37.9419429",
"longitude": "-73.1446869",
"storeId": "12345"
],
"authorizationCode": "123456",
"retrievalReferenceNumber": "100804333919",
"systemTraceAuditNumber": "333828",
"acquirerReferenceNumber": "1234567890123456789012345678",
"cardProductId": "1234567890123456789012345678",
"processorMids": [
"processor": "VISA",
"mids": [
"vmid": "12345678901",
"vsid": "12345678"
]
]
],
"id": "309rjfoincor3icno3rind093cdow3jciwjdwcm"
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/transactions")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
```python Matched Transaction
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/transactions"
payload = { "data": [
{
"type": "matchedTransaction",
"attributes": {
"userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
"amount": 1000,
"description": "ADVANCEAUTO",
"authorizationDate": "2021-07-02T17:47:06Z",
"paymentType": "CARD",
"direction": "DEBIT",
"transactionId": "2467de37-cbdc-416d-a359-75de87bfffb0",
"subtotal": 800,
"matchedOfferId": "5eb2d4a39ce24e00081488c4",
"matchedLocationId": "5eb2d4a39ce24e00081488d5",
"merchant": {
"name": "ADVANCEAUTO",
"id": "12345678901234567",
"addrStreet": "125 Main St",
"addrCity": "Philadephia",
"addrState": "PA",
"addrZipcode": "19147",
"addrCountry": "United States"
},
"cardBIN": "12345",
"cardLastFour": "4321",
"authorizationCode": "1234",
"retrievalReferenceNumber": "100804333919",
"systemTraceAuditNumber": "333828",
"acquirerReferenceNumber": "1234567890123456789012345678",
"cardProductId": "1234567890123456789012345678",
"orderId": "23q49807iklasdf238904",
"receiptMedium": "ELECTRONIC"
},
"id": "soduinfwoer82498h248h298heo2eic"
}
] }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript Matched Transaction
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/transactions';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":[{"type":"matchedTransaction","attributes":{"userId":"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69","amount":1000,"description":"ADVANCEAUTO","authorizationDate":"2021-07-02T17:47:06Z","paymentType":"CARD","direction":"DEBIT","transactionId":"2467de37-cbdc-416d-a359-75de87bfffb0","subtotal":800,"matchedOfferId":"5eb2d4a39ce24e00081488c4","matchedLocationId":"5eb2d4a39ce24e00081488d5","merchant":{"name":"ADVANCEAUTO","id":"12345678901234567","addrStreet":"125 Main St","addrCity":"Philadephia","addrState":"PA","addrZipcode":"19147","addrCountry":"United States"},"cardBIN":"12345","cardLastFour":"4321","authorizationCode":"1234","retrievalReferenceNumber":"100804333919","systemTraceAuditNumber":"333828","acquirerReferenceNumber":"1234567890123456789012345678","cardProductId":"1234567890123456789012345678","orderId":"23q49807iklasdf238904","receiptMedium":"ELECTRONIC"},"id":"soduinfwoer82498h248h298heo2eic"}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go Matched Transaction
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/transactions"
payload := strings.NewReader("{\n \"data\": [\n {\n \"type\": \"matchedTransaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 1000,\n \"description\": \"ADVANCEAUTO\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"paymentType\": \"CARD\",\n \"direction\": \"DEBIT\",\n \"transactionId\": \"2467de37-cbdc-416d-a359-75de87bfffb0\",\n \"subtotal\": 800,\n \"matchedOfferId\": \"5eb2d4a39ce24e00081488c4\",\n \"matchedLocationId\": \"5eb2d4a39ce24e00081488d5\",\n \"merchant\": {\n \"name\": \"ADVANCEAUTO\",\n \"id\": \"12345678901234567\",\n \"addrStreet\": \"125 Main St\",\n \"addrCity\": \"Philadephia\",\n \"addrState\": \"PA\",\n \"addrZipcode\": \"19147\",\n \"addrCountry\": \"United States\"\n },\n \"cardBIN\": \"12345\",\n \"cardLastFour\": \"4321\",\n \"authorizationCode\": \"1234\",\n \"retrievalReferenceNumber\": \"100804333919\",\n \"systemTraceAuditNumber\": \"333828\",\n \"acquirerReferenceNumber\": \"1234567890123456789012345678\",\n \"cardProductId\": \"1234567890123456789012345678\",\n \"orderId\": \"23q49807iklasdf238904\",\n \"receiptMedium\": \"ELECTRONIC\"\n },\n \"id\": \"soduinfwoer82498h248h298heo2eic\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby Matched Transaction
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/transactions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": [\n {\n \"type\": \"matchedTransaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 1000,\n \"description\": \"ADVANCEAUTO\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"paymentType\": \"CARD\",\n \"direction\": \"DEBIT\",\n \"transactionId\": \"2467de37-cbdc-416d-a359-75de87bfffb0\",\n \"subtotal\": 800,\n \"matchedOfferId\": \"5eb2d4a39ce24e00081488c4\",\n \"matchedLocationId\": \"5eb2d4a39ce24e00081488d5\",\n \"merchant\": {\n \"name\": \"ADVANCEAUTO\",\n \"id\": \"12345678901234567\",\n \"addrStreet\": \"125 Main St\",\n \"addrCity\": \"Philadephia\",\n \"addrState\": \"PA\",\n \"addrZipcode\": \"19147\",\n \"addrCountry\": \"United States\"\n },\n \"cardBIN\": \"12345\",\n \"cardLastFour\": \"4321\",\n \"authorizationCode\": \"1234\",\n \"retrievalReferenceNumber\": \"100804333919\",\n \"systemTraceAuditNumber\": \"333828\",\n \"acquirerReferenceNumber\": \"1234567890123456789012345678\",\n \"cardProductId\": \"1234567890123456789012345678\",\n \"orderId\": \"23q49807iklasdf238904\",\n \"receiptMedium\": \"ELECTRONIC\"\n },\n \"id\": \"soduinfwoer82498h248h298heo2eic\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
```java Matched Transaction
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/organization-123/transactions")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": [\n {\n \"type\": \"matchedTransaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 1000,\n \"description\": \"ADVANCEAUTO\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"paymentType\": \"CARD\",\n \"direction\": \"DEBIT\",\n \"transactionId\": \"2467de37-cbdc-416d-a359-75de87bfffb0\",\n \"subtotal\": 800,\n \"matchedOfferId\": \"5eb2d4a39ce24e00081488c4\",\n \"matchedLocationId\": \"5eb2d4a39ce24e00081488d5\",\n \"merchant\": {\n \"name\": \"ADVANCEAUTO\",\n \"id\": \"12345678901234567\",\n \"addrStreet\": \"125 Main St\",\n \"addrCity\": \"Philadephia\",\n \"addrState\": \"PA\",\n \"addrZipcode\": \"19147\",\n \"addrCountry\": \"United States\"\n },\n \"cardBIN\": \"12345\",\n \"cardLastFour\": \"4321\",\n \"authorizationCode\": \"1234\",\n \"retrievalReferenceNumber\": \"100804333919\",\n \"systemTraceAuditNumber\": \"333828\",\n \"acquirerReferenceNumber\": \"1234567890123456789012345678\",\n \"cardProductId\": \"1234567890123456789012345678\",\n \"orderId\": \"23q49807iklasdf238904\",\n \"receiptMedium\": \"ELECTRONIC\"\n },\n \"id\": \"soduinfwoer82498h248h298heo2eic\"\n }\n ]\n}")
.asString();
```
```php Matched Transaction
request('POST', 'https://rewards-api.getkard.com/v2/issuers/organization-123/transactions', [
'body' => '{
"data": [
{
"type": "matchedTransaction",
"attributes": {
"userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
"amount": 1000,
"description": "ADVANCEAUTO",
"authorizationDate": "2021-07-02T17:47:06Z",
"paymentType": "CARD",
"direction": "DEBIT",
"transactionId": "2467de37-cbdc-416d-a359-75de87bfffb0",
"subtotal": 800,
"matchedOfferId": "5eb2d4a39ce24e00081488c4",
"matchedLocationId": "5eb2d4a39ce24e00081488d5",
"merchant": {
"name": "ADVANCEAUTO",
"id": "12345678901234567",
"addrStreet": "125 Main St",
"addrCity": "Philadephia",
"addrState": "PA",
"addrZipcode": "19147",
"addrCountry": "United States"
},
"cardBIN": "12345",
"cardLastFour": "4321",
"authorizationCode": "1234",
"retrievalReferenceNumber": "100804333919",
"systemTraceAuditNumber": "333828",
"acquirerReferenceNumber": "1234567890123456789012345678",
"cardProductId": "1234567890123456789012345678",
"orderId": "23q49807iklasdf238904",
"receiptMedium": "ELECTRONIC"
},
"id": "soduinfwoer82498h248h298heo2eic"
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp Matched Transaction
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/transactions");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": [\n {\n \"type\": \"matchedTransaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 1000,\n \"description\": \"ADVANCEAUTO\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"paymentType\": \"CARD\",\n \"direction\": \"DEBIT\",\n \"transactionId\": \"2467de37-cbdc-416d-a359-75de87bfffb0\",\n \"subtotal\": 800,\n \"matchedOfferId\": \"5eb2d4a39ce24e00081488c4\",\n \"matchedLocationId\": \"5eb2d4a39ce24e00081488d5\",\n \"merchant\": {\n \"name\": \"ADVANCEAUTO\",\n \"id\": \"12345678901234567\",\n \"addrStreet\": \"125 Main St\",\n \"addrCity\": \"Philadephia\",\n \"addrState\": \"PA\",\n \"addrZipcode\": \"19147\",\n \"addrCountry\": \"United States\"\n },\n \"cardBIN\": \"12345\",\n \"cardLastFour\": \"4321\",\n \"authorizationCode\": \"1234\",\n \"retrievalReferenceNumber\": \"100804333919\",\n \"systemTraceAuditNumber\": \"333828\",\n \"acquirerReferenceNumber\": \"1234567890123456789012345678\",\n \"cardProductId\": \"1234567890123456789012345678\",\n \"orderId\": \"23q49807iklasdf238904\",\n \"receiptMedium\": \"ELECTRONIC\"\n },\n \"id\": \"soduinfwoer82498h248h298heo2eic\"\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift Matched Transaction
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
[
"type": "matchedTransaction",
"attributes": [
"userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
"amount": 1000,
"description": "ADVANCEAUTO",
"authorizationDate": "2021-07-02T17:47:06Z",
"paymentType": "CARD",
"direction": "DEBIT",
"transactionId": "2467de37-cbdc-416d-a359-75de87bfffb0",
"subtotal": 800,
"matchedOfferId": "5eb2d4a39ce24e00081488c4",
"matchedLocationId": "5eb2d4a39ce24e00081488d5",
"merchant": [
"name": "ADVANCEAUTO",
"id": "12345678901234567",
"addrStreet": "125 Main St",
"addrCity": "Philadephia",
"addrState": "PA",
"addrZipcode": "19147",
"addrCountry": "United States"
],
"cardBIN": "12345",
"cardLastFour": "4321",
"authorizationCode": "1234",
"retrievalReferenceNumber": "100804333919",
"systemTraceAuditNumber": "333828",
"acquirerReferenceNumber": "1234567890123456789012345678",
"cardProductId": "1234567890123456789012345678",
"orderId": "23q49807iklasdf238904",
"receiptMedium": "ELECTRONIC"
],
"id": "soduinfwoer82498h248h298heo2eic"
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/transactions")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
```python Matched Transaction w/ UNKNOWN payment type
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/transactions"
payload = { "data": [
{
"type": "matchedTransaction",
"attributes": {
"userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
"amount": 2500,
"description": "ONLINE STORE PURCHASE",
"authorizationDate": "2021-07-02T17:47:06Z",
"paymentType": "UNKNOWN",
"direction": "DEBIT",
"transactionId": "unknown-txn-4567-efgh-ijkl-mnop-qrstuvwxyz01",
"subtotal": 2000,
"matchedOfferId": "5eb2d4a39ce24e00081488c4",
"merchant": {
"name": "ONLINE STORE",
"id": "98765432109876543",
"addrStreet": "456 Web St",
"addrCity": "Online City",
"addrState": "CA",
"addrZipcode": "90210",
"addrCountry": "United States"
},
"cardLastFour": "7890",
"authorizationCode": "5678",
"retrievalReferenceNumber": "200804333919",
"systemTraceAuditNumber": "444939",
"acquirerReferenceNumber": "9876543210987654321098765432",
"orderId": "online_order_789012",
"receiptMedium": "ELECTRONIC"
},
"id": "unknown_payment_txn_12345"
}
] }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript Matched Transaction w/ UNKNOWN payment type
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/transactions';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":[{"type":"matchedTransaction","attributes":{"userId":"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69","amount":2500,"description":"ONLINE STORE PURCHASE","authorizationDate":"2021-07-02T17:47:06Z","paymentType":"UNKNOWN","direction":"DEBIT","transactionId":"unknown-txn-4567-efgh-ijkl-mnop-qrstuvwxyz01","subtotal":2000,"matchedOfferId":"5eb2d4a39ce24e00081488c4","merchant":{"name":"ONLINE STORE","id":"98765432109876543","addrStreet":"456 Web St","addrCity":"Online City","addrState":"CA","addrZipcode":"90210","addrCountry":"United States"},"cardLastFour":"7890","authorizationCode":"5678","retrievalReferenceNumber":"200804333919","systemTraceAuditNumber":"444939","acquirerReferenceNumber":"9876543210987654321098765432","orderId":"online_order_789012","receiptMedium":"ELECTRONIC"},"id":"unknown_payment_txn_12345"}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go Matched Transaction w/ UNKNOWN payment type
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/transactions"
payload := strings.NewReader("{\n \"data\": [\n {\n \"type\": \"matchedTransaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 2500,\n \"description\": \"ONLINE STORE PURCHASE\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"paymentType\": \"UNKNOWN\",\n \"direction\": \"DEBIT\",\n \"transactionId\": \"unknown-txn-4567-efgh-ijkl-mnop-qrstuvwxyz01\",\n \"subtotal\": 2000,\n \"matchedOfferId\": \"5eb2d4a39ce24e00081488c4\",\n \"merchant\": {\n \"name\": \"ONLINE STORE\",\n \"id\": \"98765432109876543\",\n \"addrStreet\": \"456 Web St\",\n \"addrCity\": \"Online City\",\n \"addrState\": \"CA\",\n \"addrZipcode\": \"90210\",\n \"addrCountry\": \"United States\"\n },\n \"cardLastFour\": \"7890\",\n \"authorizationCode\": \"5678\",\n \"retrievalReferenceNumber\": \"200804333919\",\n \"systemTraceAuditNumber\": \"444939\",\n \"acquirerReferenceNumber\": \"9876543210987654321098765432\",\n \"orderId\": \"online_order_789012\",\n \"receiptMedium\": \"ELECTRONIC\"\n },\n \"id\": \"unknown_payment_txn_12345\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby Matched Transaction w/ UNKNOWN payment type
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/transactions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": [\n {\n \"type\": \"matchedTransaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 2500,\n \"description\": \"ONLINE STORE PURCHASE\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"paymentType\": \"UNKNOWN\",\n \"direction\": \"DEBIT\",\n \"transactionId\": \"unknown-txn-4567-efgh-ijkl-mnop-qrstuvwxyz01\",\n \"subtotal\": 2000,\n \"matchedOfferId\": \"5eb2d4a39ce24e00081488c4\",\n \"merchant\": {\n \"name\": \"ONLINE STORE\",\n \"id\": \"98765432109876543\",\n \"addrStreet\": \"456 Web St\",\n \"addrCity\": \"Online City\",\n \"addrState\": \"CA\",\n \"addrZipcode\": \"90210\",\n \"addrCountry\": \"United States\"\n },\n \"cardLastFour\": \"7890\",\n \"authorizationCode\": \"5678\",\n \"retrievalReferenceNumber\": \"200804333919\",\n \"systemTraceAuditNumber\": \"444939\",\n \"acquirerReferenceNumber\": \"9876543210987654321098765432\",\n \"orderId\": \"online_order_789012\",\n \"receiptMedium\": \"ELECTRONIC\"\n },\n \"id\": \"unknown_payment_txn_12345\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
```java Matched Transaction w/ UNKNOWN payment type
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/organization-123/transactions")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": [\n {\n \"type\": \"matchedTransaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 2500,\n \"description\": \"ONLINE STORE PURCHASE\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"paymentType\": \"UNKNOWN\",\n \"direction\": \"DEBIT\",\n \"transactionId\": \"unknown-txn-4567-efgh-ijkl-mnop-qrstuvwxyz01\",\n \"subtotal\": 2000,\n \"matchedOfferId\": \"5eb2d4a39ce24e00081488c4\",\n \"merchant\": {\n \"name\": \"ONLINE STORE\",\n \"id\": \"98765432109876543\",\n \"addrStreet\": \"456 Web St\",\n \"addrCity\": \"Online City\",\n \"addrState\": \"CA\",\n \"addrZipcode\": \"90210\",\n \"addrCountry\": \"United States\"\n },\n \"cardLastFour\": \"7890\",\n \"authorizationCode\": \"5678\",\n \"retrievalReferenceNumber\": \"200804333919\",\n \"systemTraceAuditNumber\": \"444939\",\n \"acquirerReferenceNumber\": \"9876543210987654321098765432\",\n \"orderId\": \"online_order_789012\",\n \"receiptMedium\": \"ELECTRONIC\"\n },\n \"id\": \"unknown_payment_txn_12345\"\n }\n ]\n}")
.asString();
```
```php Matched Transaction w/ UNKNOWN payment type
request('POST', 'https://rewards-api.getkard.com/v2/issuers/organization-123/transactions', [
'body' => '{
"data": [
{
"type": "matchedTransaction",
"attributes": {
"userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
"amount": 2500,
"description": "ONLINE STORE PURCHASE",
"authorizationDate": "2021-07-02T17:47:06Z",
"paymentType": "UNKNOWN",
"direction": "DEBIT",
"transactionId": "unknown-txn-4567-efgh-ijkl-mnop-qrstuvwxyz01",
"subtotal": 2000,
"matchedOfferId": "5eb2d4a39ce24e00081488c4",
"merchant": {
"name": "ONLINE STORE",
"id": "98765432109876543",
"addrStreet": "456 Web St",
"addrCity": "Online City",
"addrState": "CA",
"addrZipcode": "90210",
"addrCountry": "United States"
},
"cardLastFour": "7890",
"authorizationCode": "5678",
"retrievalReferenceNumber": "200804333919",
"systemTraceAuditNumber": "444939",
"acquirerReferenceNumber": "9876543210987654321098765432",
"orderId": "online_order_789012",
"receiptMedium": "ELECTRONIC"
},
"id": "unknown_payment_txn_12345"
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp Matched Transaction w/ UNKNOWN payment type
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/transactions");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": [\n {\n \"type\": \"matchedTransaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 2500,\n \"description\": \"ONLINE STORE PURCHASE\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"paymentType\": \"UNKNOWN\",\n \"direction\": \"DEBIT\",\n \"transactionId\": \"unknown-txn-4567-efgh-ijkl-mnop-qrstuvwxyz01\",\n \"subtotal\": 2000,\n \"matchedOfferId\": \"5eb2d4a39ce24e00081488c4\",\n \"merchant\": {\n \"name\": \"ONLINE STORE\",\n \"id\": \"98765432109876543\",\n \"addrStreet\": \"456 Web St\",\n \"addrCity\": \"Online City\",\n \"addrState\": \"CA\",\n \"addrZipcode\": \"90210\",\n \"addrCountry\": \"United States\"\n },\n \"cardLastFour\": \"7890\",\n \"authorizationCode\": \"5678\",\n \"retrievalReferenceNumber\": \"200804333919\",\n \"systemTraceAuditNumber\": \"444939\",\n \"acquirerReferenceNumber\": \"9876543210987654321098765432\",\n \"orderId\": \"online_order_789012\",\n \"receiptMedium\": \"ELECTRONIC\"\n },\n \"id\": \"unknown_payment_txn_12345\"\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift Matched Transaction w/ UNKNOWN payment type
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
[
"type": "matchedTransaction",
"attributes": [
"userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
"amount": 2500,
"description": "ONLINE STORE PURCHASE",
"authorizationDate": "2021-07-02T17:47:06Z",
"paymentType": "UNKNOWN",
"direction": "DEBIT",
"transactionId": "unknown-txn-4567-efgh-ijkl-mnop-qrstuvwxyz01",
"subtotal": 2000,
"matchedOfferId": "5eb2d4a39ce24e00081488c4",
"merchant": [
"name": "ONLINE STORE",
"id": "98765432109876543",
"addrStreet": "456 Web St",
"addrCity": "Online City",
"addrState": "CA",
"addrZipcode": "90210",
"addrCountry": "United States"
],
"cardLastFour": "7890",
"authorizationCode": "5678",
"retrievalReferenceNumber": "200804333919",
"systemTraceAuditNumber": "444939",
"acquirerReferenceNumber": "9876543210987654321098765432",
"orderId": "online_order_789012",
"receiptMedium": "ELECTRONIC"
],
"id": "unknown_payment_txn_12345"
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/transactions")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
```python Core Transaction
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/transactions"
payload = { "data": [
{
"type": "coreTransaction",
"attributes": {
"userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
"transactionId": "CORE-TXN-2024-001234",
"amount": 4599,
"currency": "USD",
"description": "WALMART SUPERCENTER",
"direction": "DEBIT",
"status": "SETTLED",
"settledDate": "2024-10-15T14:30:00Z",
"authorizationDate": "2024-10-15T14:25:00Z",
"financialInstitutionId": "fin-inst-001",
"cardLastFours": ["4321"]
},
"id": "core_txn_98765432109876543210"
}
] }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript Core Transaction
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/transactions';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":[{"type":"coreTransaction","attributes":{"userId":"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69","transactionId":"CORE-TXN-2024-001234","amount":4599,"currency":"USD","description":"WALMART SUPERCENTER","direction":"DEBIT","status":"SETTLED","settledDate":"2024-10-15T14:30:00Z","authorizationDate":"2024-10-15T14:25:00Z","financialInstitutionId":"fin-inst-001","cardLastFours":["4321"]},"id":"core_txn_98765432109876543210"}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go Core Transaction
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/transactions"
payload := strings.NewReader("{\n \"data\": [\n {\n \"type\": \"coreTransaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"transactionId\": \"CORE-TXN-2024-001234\",\n \"amount\": 4599,\n \"currency\": \"USD\",\n \"description\": \"WALMART SUPERCENTER\",\n \"direction\": \"DEBIT\",\n \"status\": \"SETTLED\",\n \"settledDate\": \"2024-10-15T14:30:00Z\",\n \"authorizationDate\": \"2024-10-15T14:25:00Z\",\n \"financialInstitutionId\": \"fin-inst-001\",\n \"cardLastFours\": [\n \"4321\"\n ]\n },\n \"id\": \"core_txn_98765432109876543210\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby Core Transaction
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/transactions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": [\n {\n \"type\": \"coreTransaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"transactionId\": \"CORE-TXN-2024-001234\",\n \"amount\": 4599,\n \"currency\": \"USD\",\n \"description\": \"WALMART SUPERCENTER\",\n \"direction\": \"DEBIT\",\n \"status\": \"SETTLED\",\n \"settledDate\": \"2024-10-15T14:30:00Z\",\n \"authorizationDate\": \"2024-10-15T14:25:00Z\",\n \"financialInstitutionId\": \"fin-inst-001\",\n \"cardLastFours\": [\n \"4321\"\n ]\n },\n \"id\": \"core_txn_98765432109876543210\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
```java Core Transaction
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/organization-123/transactions")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": [\n {\n \"type\": \"coreTransaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"transactionId\": \"CORE-TXN-2024-001234\",\n \"amount\": 4599,\n \"currency\": \"USD\",\n \"description\": \"WALMART SUPERCENTER\",\n \"direction\": \"DEBIT\",\n \"status\": \"SETTLED\",\n \"settledDate\": \"2024-10-15T14:30:00Z\",\n \"authorizationDate\": \"2024-10-15T14:25:00Z\",\n \"financialInstitutionId\": \"fin-inst-001\",\n \"cardLastFours\": [\n \"4321\"\n ]\n },\n \"id\": \"core_txn_98765432109876543210\"\n }\n ]\n}")
.asString();
```
```php Core Transaction
request('POST', 'https://rewards-api.getkard.com/v2/issuers/organization-123/transactions', [
'body' => '{
"data": [
{
"type": "coreTransaction",
"attributes": {
"userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
"transactionId": "CORE-TXN-2024-001234",
"amount": 4599,
"currency": "USD",
"description": "WALMART SUPERCENTER",
"direction": "DEBIT",
"status": "SETTLED",
"settledDate": "2024-10-15T14:30:00Z",
"authorizationDate": "2024-10-15T14:25:00Z",
"financialInstitutionId": "fin-inst-001",
"cardLastFours": [
"4321"
]
},
"id": "core_txn_98765432109876543210"
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp Core Transaction
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/transactions");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": [\n {\n \"type\": \"coreTransaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"transactionId\": \"CORE-TXN-2024-001234\",\n \"amount\": 4599,\n \"currency\": \"USD\",\n \"description\": \"WALMART SUPERCENTER\",\n \"direction\": \"DEBIT\",\n \"status\": \"SETTLED\",\n \"settledDate\": \"2024-10-15T14:30:00Z\",\n \"authorizationDate\": \"2024-10-15T14:25:00Z\",\n \"financialInstitutionId\": \"fin-inst-001\",\n \"cardLastFours\": [\n \"4321\"\n ]\n },\n \"id\": \"core_txn_98765432109876543210\"\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift Core Transaction
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
[
"type": "coreTransaction",
"attributes": [
"userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
"transactionId": "CORE-TXN-2024-001234",
"amount": 4599,
"currency": "USD",
"description": "WALMART SUPERCENTER",
"direction": "DEBIT",
"status": "SETTLED",
"settledDate": "2024-10-15T14:30:00Z",
"authorizationDate": "2024-10-15T14:25:00Z",
"financialInstitutionId": "fin-inst-001",
"cardLastFours": ["4321"]
],
"id": "core_txn_98765432109876543210"
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/transactions")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/transactions"
payload = { "data": [
{
"type": "transaction",
"attributes": {
"userId": "string",
"amount": 0,
"status": "APPROVED",
"currency": "string",
"description": "string",
"cardBIN": "string",
"cardLastFour": "string",
"direction": "DEBIT",
"paymentType": "CARD",
"transactionId": "string"
},
"id": "string"
}
] }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/transactions';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":[{"type":"transaction","attributes":{"userId":"string","amount":0,"status":"APPROVED","currency":"string","description":"string","cardBIN":"string","cardLastFour":"string","direction":"DEBIT","paymentType":"CARD","transactionId":"string"},"id":"string"}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/transactions"
payload := strings.NewReader("{\n \"data\": [\n {\n \"type\": \"transaction\",\n \"attributes\": {\n \"userId\": \"string\",\n \"amount\": 0,\n \"status\": \"APPROVED\",\n \"currency\": \"string\",\n \"description\": \"string\",\n \"cardBIN\": \"string\",\n \"cardLastFour\": \"string\",\n \"direction\": \"DEBIT\",\n \"paymentType\": \"CARD\",\n \"transactionId\": \"string\"\n },\n \"id\": \"string\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/transactions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": [\n {\n \"type\": \"transaction\",\n \"attributes\": {\n \"userId\": \"string\",\n \"amount\": 0,\n \"status\": \"APPROVED\",\n \"currency\": \"string\",\n \"description\": \"string\",\n \"cardBIN\": \"string\",\n \"cardLastFour\": \"string\",\n \"direction\": \"DEBIT\",\n \"paymentType\": \"CARD\",\n \"transactionId\": \"string\"\n },\n \"id\": \"string\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/transactions")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": [\n {\n \"type\": \"transaction\",\n \"attributes\": {\n \"userId\": \"string\",\n \"amount\": 0,\n \"status\": \"APPROVED\",\n \"currency\": \"string\",\n \"description\": \"string\",\n \"cardBIN\": \"string\",\n \"cardLastFour\": \"string\",\n \"direction\": \"DEBIT\",\n \"paymentType\": \"CARD\",\n \"transactionId\": \"string\"\n },\n \"id\": \"string\"\n }\n ]\n}")
.asString();
```
```php
request('POST', 'https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/transactions', [
'body' => '{
"data": [
{
"type": "transaction",
"attributes": {
"userId": "string",
"amount": 0,
"status": "APPROVED",
"currency": "string",
"description": "string",
"cardBIN": "string",
"cardLastFour": "string",
"direction": "DEBIT",
"paymentType": "CARD",
"transactionId": "string"
},
"id": "string"
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/transactions");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": [\n {\n \"type\": \"transaction\",\n \"attributes\": {\n \"userId\": \"string\",\n \"amount\": 0,\n \"status\": \"APPROVED\",\n \"currency\": \"string\",\n \"description\": \"string\",\n \"cardBIN\": \"string\",\n \"cardLastFour\": \"string\",\n \"direction\": \"DEBIT\",\n \"paymentType\": \"CARD\",\n \"transactionId\": \"string\"\n },\n \"id\": \"string\"\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
[
"type": "transaction",
"attributes": [
"userId": "string",
"amount": 0,
"status": "APPROVED",
"currency": "string",
"description": "string",
"cardBIN": "string",
"cardLastFour": "string",
"direction": "DEBIT",
"paymentType": "CARD",
"transactionId": "string"
],
"id": "string"
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/transactions")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Flag Fraudulent Transactions
POST https://rewards-api.getkard.com/v2/issuers/{organizationId}/fraud
Content-Type: application/json
Call this endpoint to flag a submitted transaction as fraudulent. This will prevent it from being rewarded. Required scopes: `transaction:write` Note: `Maximum of 500 fraudulent transactions can be created per request`.
Reference: https://docs.getkard.com/api/transactions/create-fraud-markers
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/fraud:
post:
operationId: create-fraud-markers
summary: Flag Fraudulent Transactions
description: >-
Call this endpoint to flag a submitted transaction as fraudulent. This
will prevent it from being rewarded. Required scopes: `transaction:write` Note: `Maximum of 500 fraudulent transactions can be created per
request`.
tags:
- subpackage_transactions
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_transactions:FraudulentTransactionObject
'207':
description: Error response with status 207
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_transactions:FraudulentTransactionResponse
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_transactions:FraudulentTransactionRequestBody
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_transactions:FraudulentTransactionAttributes:
type: object
properties:
userId:
type: string
description: User ID the transaction belongs to
required:
- userId
title: FraudulentTransactionAttributes
type_transactions:FraudulentTransactionData:
type: object
properties:
id:
type: string
description: transactionId of the fraudulent transaction
type:
type: string
description: only value allowed is "fraudulentTransaction"
attributes:
$ref: >-
#/components/schemas/type_transactions:FraudulentTransactionAttributes
required:
- id
- type
- attributes
title: FraudulentTransactionData
type_transactions:FraudulentTransactionRequestBody:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_transactions:FraudulentTransactionData'
description: List of fraudulent transactions to report
required:
- data
title: FraudulentTransactionRequestBody
type_transactions:FraudulentTransactionObject:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_transactions:FraudulentTransactionData'
required:
- data
title: FraudulentTransactionObject
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_transactions:FraudulentTransactionResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
data:
type: array
items:
$ref: '#/components/schemas/type_transactions:FraudulentTransactionData'
required:
- errors
- data
title: FraudulentTransactionResponse
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python Fraudulent Transaction
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/fraud"
payload = { "data": [
{
"id": "myTxnId12345",
"type": "fraudulentTransaction",
"attributes": { "userId": "userId123" }
}
] }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript Fraudulent Transaction
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/fraud';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":[{"id":"myTxnId12345","type":"fraudulentTransaction","attributes":{"userId":"userId123"}}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go Fraudulent Transaction
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/fraud"
payload := strings.NewReader("{\n \"data\": [\n {\n \"id\": \"myTxnId12345\",\n \"type\": \"fraudulentTransaction\",\n \"attributes\": {\n \"userId\": \"userId123\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby Fraudulent Transaction
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/fraud")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": [\n {\n \"id\": \"myTxnId12345\",\n \"type\": \"fraudulentTransaction\",\n \"attributes\": {\n \"userId\": \"userId123\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
```java Fraudulent Transaction
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/organization-123/fraud")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": [\n {\n \"id\": \"myTxnId12345\",\n \"type\": \"fraudulentTransaction\",\n \"attributes\": {\n \"userId\": \"userId123\"\n }\n }\n ]\n}")
.asString();
```
```php Fraudulent Transaction
request('POST', 'https://rewards-api.getkard.com/v2/issuers/organization-123/fraud', [
'body' => '{
"data": [
{
"id": "myTxnId12345",
"type": "fraudulentTransaction",
"attributes": {
"userId": "userId123"
}
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp Fraudulent Transaction
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/fraud");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": [\n {\n \"id\": \"myTxnId12345\",\n \"type\": \"fraudulentTransaction\",\n \"attributes\": {\n \"userId\": \"userId123\"\n }\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift Fraudulent Transaction
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
[
"id": "myTxnId12345",
"type": "fraudulentTransaction",
"attributes": ["userId": "userId123"]
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/fraud")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/fraud"
payload = { "data": [
{
"id": "string",
"type": "string",
"attributes": { "userId": "string" }
}
] }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/fraud';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":[{"id":"string","type":"string","attributes":{"userId":"string"}}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/fraud"
payload := strings.NewReader("{\n \"data\": [\n {\n \"id\": \"string\",\n \"type\": \"string\",\n \"attributes\": {\n \"userId\": \"string\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/fraud")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": [\n {\n \"id\": \"string\",\n \"type\": \"string\",\n \"attributes\": {\n \"userId\": \"string\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/fraud")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": [\n {\n \"id\": \"string\",\n \"type\": \"string\",\n \"attributes\": {\n \"userId\": \"string\"\n }\n }\n ]\n}")
.asString();
```
```php
request('POST', 'https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/fraud', [
'body' => '{
"data": [
{
"id": "string",
"type": "string",
"attributes": {
"userId": "string"
}
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/fraud");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": [\n {\n \"id\": \"string\",\n \"type\": \"string\",\n \"attributes\": {\n \"userId\": \"string\"\n }\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
[
"id": "string",
"type": "string",
"attributes": ["userId": "string"]
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/fraud")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Create Audits
POST https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/audits
Content-Type: application/json
Call this endpoint to request that a particular transaction be audited further by the Kard system, in the event of a missing cashback claim, incorrect cashback amount claim or other mis-match claims. Required scopes: `audit:write`
Reference: https://docs.getkard.com/api/transactions/create-audits
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/users/{userId}/audits:
post:
operationId: create-audits
summary: Create Audits
description: >-
Call this endpoint to request that a particular transaction be audited
further by the Kard system, in the event of a missing cashback claim,
incorrect cashback amount claim or other mis-match claims. Required scopes: `audit:write`
tags:
- subpackage_transactions
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: userId
in: path
description: The ID of the user as defined on the issuers system
required: true
schema:
type: string
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'201':
description: Response with status 201
content:
application/json:
schema:
$ref: '#/components/schemas/type_transactions:CreateAuditResponseBody'
'207':
description: Error response with status 207
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_transactions:CreateAuditMultiStatusResponse
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'409':
description: Error response with status 409
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_transactions:CreateAuditRequestBody'
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_transactions:AuditAttributes:
type: object
properties:
auditCode:
type: integer
description: >-
Audit Code - Enum. Please submit the code that is most relevant to
your audit request.
`3005` : Customer is claiming cashback is incorrect - INCORRECT CASHBACK CLAIM
`3006` : Transaction is missing the cashback award - MISSING CASHBACK AWARD
`8001` : Other - check audit description
merchantName:
type: string
description: Merchant name related to the transaction audit
auditDescription:
type: string
description: Audit Description. Please provide more details around the audit
transactionId:
type: string
description: Transaction ID from issuer to audit
required:
- auditCode
- merchantName
- auditDescription
- transactionId
title: AuditAttributes
type_transactions:CreateAuditRequestDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- audit
description: 'Discriminator value: audit'
attributes:
$ref: '#/components/schemas/type_transactions:AuditAttributes'
required:
- type
- attributes
discriminator:
propertyName: type
title: CreateAuditRequestDataUnion
type_transactions:CreateAuditRequestBody:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_transactions:CreateAuditRequestDataUnion'
required:
- data
title: CreateAuditRequestBody
type_transactions:AuditResponseAttributes:
type: object
properties:
transactionId:
type: string
description: Cardlinked Transaction ID
required:
- transactionId
title: AuditResponseAttributes
type_transactions:CreateAuditResponseDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- audit
description: 'Discriminator value: audit'
id:
type: string
description: Audit Request ID
attributes:
$ref: '#/components/schemas/type_transactions:AuditResponseAttributes'
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: CreateAuditResponseDataUnion
type_transactions:CreateAuditResponseBody:
type: object
properties:
data:
type: array
items:
$ref: >-
#/components/schemas/type_transactions:CreateAuditResponseDataUnion
required:
- data
title: CreateAuditResponseBody
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_transactions:CreateAuditMultiStatusResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
data:
type: array
items:
$ref: >-
#/components/schemas/type_transactions:CreateAuditResponseDataUnion
required:
- errors
title: CreateAuditMultiStatusResponse
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python Create Audit Request
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/audits"
payload = { "data": [
{
"type": "audit",
"attributes": {
"auditCode": 8001,
"merchantName": "Caribbean Goodness",
"auditDescription": "duplicate transaction",
"transactionId": "issuerTransaction123"
}
}
] }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript Create Audit Request
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/audits';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":[{"type":"audit","attributes":{"auditCode":8001,"merchantName":"Caribbean Goodness","auditDescription":"duplicate transaction","transactionId":"issuerTransaction123"}}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go Create Audit Request
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/audits"
payload := strings.NewReader("{\n \"data\": [\n {\n \"type\": \"audit\",\n \"attributes\": {\n \"auditCode\": 8001,\n \"merchantName\": \"Caribbean Goodness\",\n \"auditDescription\": \"duplicate transaction\",\n \"transactionId\": \"issuerTransaction123\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby Create Audit Request
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/audits")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": [\n {\n \"type\": \"audit\",\n \"attributes\": {\n \"auditCode\": 8001,\n \"merchantName\": \"Caribbean Goodness\",\n \"auditDescription\": \"duplicate transaction\",\n \"transactionId\": \"issuerTransaction123\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
```java Create Audit Request
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/audits")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": [\n {\n \"type\": \"audit\",\n \"attributes\": {\n \"auditCode\": 8001,\n \"merchantName\": \"Caribbean Goodness\",\n \"auditDescription\": \"duplicate transaction\",\n \"transactionId\": \"issuerTransaction123\"\n }\n }\n ]\n}")
.asString();
```
```php Create Audit Request
request('POST', 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/audits', [
'body' => '{
"data": [
{
"type": "audit",
"attributes": {
"auditCode": 8001,
"merchantName": "Caribbean Goodness",
"auditDescription": "duplicate transaction",
"transactionId": "issuerTransaction123"
}
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp Create Audit Request
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/audits");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": [\n {\n \"type\": \"audit\",\n \"attributes\": {\n \"auditCode\": 8001,\n \"merchantName\": \"Caribbean Goodness\",\n \"auditDescription\": \"duplicate transaction\",\n \"transactionId\": \"issuerTransaction123\"\n }\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift Create Audit Request
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
[
"type": "audit",
"attributes": [
"auditCode": 8001,
"merchantName": "Caribbean Goodness",
"auditDescription": "duplicate transaction",
"transactionId": "issuerTransaction123"
]
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/audits")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users/%3AuserId/audits"
payload = { "data": [
{
"type": "audit",
"attributes": {
"auditCode": 0,
"merchantName": "string",
"auditDescription": "string",
"transactionId": "string"
}
}
] }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users/%3AuserId/audits';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":[{"type":"audit","attributes":{"auditCode":0,"merchantName":"string","auditDescription":"string","transactionId":"string"}}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users/%3AuserId/audits"
payload := strings.NewReader("{\n \"data\": [\n {\n \"type\": \"audit\",\n \"attributes\": {\n \"auditCode\": 0,\n \"merchantName\": \"string\",\n \"auditDescription\": \"string\",\n \"transactionId\": \"string\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users/%3AuserId/audits")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": [\n {\n \"type\": \"audit\",\n \"attributes\": {\n \"auditCode\": 0,\n \"merchantName\": \"string\",\n \"auditDescription\": \"string\",\n \"transactionId\": \"string\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users/%3AuserId/audits")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": [\n {\n \"type\": \"audit\",\n \"attributes\": {\n \"auditCode\": 0,\n \"merchantName\": \"string\",\n \"auditDescription\": \"string\",\n \"transactionId\": \"string\"\n }\n }\n ]\n}")
.asString();
```
```php
request('POST', 'https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users/%3AuserId/audits', [
'body' => '{
"data": [
{
"type": "audit",
"attributes": {
"auditCode": 0,
"merchantName": "string",
"auditDescription": "string",
"transactionId": "string"
}
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users/%3AuserId/audits");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": [\n {\n \"type\": \"audit\",\n \"attributes\": {\n \"auditCode\": 0,\n \"merchantName\": \"string\",\n \"auditDescription\": \"string\",\n \"transactionId\": \"string\"\n }\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
[
"type": "audit",
"attributes": [
"auditCode": 0,
"merchantName": "string",
"auditDescription": "string",
"transactionId": "string"
]
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users/%3AuserId/audits")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Create Bulk Transactions Upload URL
POST https://rewards-api.getkard.com/v2/issuers/{organizationId}/transactions/uploads
Content-Type: application/json
Generates up to 10 presigned PUT URLs for uploading JSONL transaction files (up to 5GB each) directly
to storage. Each URL is valid for 15 minutes. Use the returned URL to upload the file via an HTTP PUT request with the
binary file content as the body. If a URL expires before the upload completes, you must request a new one.
Files can be uploaded as plain JSONL or as a gzip-compressed file.
Only `coreTransaction` type is supported for bulk file uploads.
Required scopes: `transaction:write`
Reference: https://docs.getkard.com/api/transactions/create-bulk-transactions-upload-url
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/transactions/uploads:
post:
operationId: create-bulk-transactions-upload-url
summary: Create Bulk Transactions Upload URL
description: >-
Generates up to 10 presigned PUT URLs for uploading JSONL transaction
files (up to 5GB each) directly
to storage. Each URL is valid for 15 minutes. Use the returned URL to
upload the file via an HTTP PUT request with the
binary file content as the body. If a URL expires before the upload
completes, you must request a new one.
Files can be uploaded as plain JSONL or as a gzip-compressed file.
Only `coreTransaction` type is supported for bulk file uploads.
Required scopes: `transaction:write`
tags:
- subpackage_transactions
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'201':
description: Response with status 201
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_transactions:CreateFileUploadUrlResponse
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'403':
description: Error response with status 403
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_transactions:CreateFileUploadRequestBody
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_transactions:FileUploadType:
type: string
enum:
- incomingTransactionsFile
- historicalTransactionsFile
description: >-
Specifies the category of transaction file being uploaded. Use
`incomingTransactionsFile` for new, real-time transactions that need to
be processed and matched as they arrive. Use
`historicalTransactionsFile` for back-filled or retroactive transaction
data that covers a past time period.
title: FileUploadType
type_transactions:CreateFileUploadAttributes:
type: object
properties:
filename:
type: string
description: >-
Name of the file to upload, including extension (e.g.
"transaction_12345.jsonl")
required:
- filename
title: CreateFileUploadAttributes
type_transactions:CreateFileUploadData:
type: object
properties:
type:
$ref: '#/components/schemas/type_transactions:FileUploadType'
attributes:
$ref: '#/components/schemas/type_transactions:CreateFileUploadAttributes'
required:
- type
- attributes
title: CreateFileUploadData
type_transactions:CreateFileUploadRequestBody:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_transactions:CreateFileUploadData'
description: List of file upload requests (1–10 items per request).
required:
- data
title: CreateFileUploadRequestBody
type_transactions:FileUploadUrlAttributes:
type: object
properties:
url:
type: string
description: |-
Presigned PUT URL for uploading the file directly to storage.
Use HTTP PUT with binary body. Expires after 15 minutes.
expiresIn:
type: integer
description: Time in seconds until the presigned URL expires (900)
required:
- url
- expiresIn
title: FileUploadUrlAttributes
type_transactions:FileUploadUrlData:
type: object
properties:
type:
$ref: '#/components/schemas/type_transactions:FileUploadType'
id:
type: string
description: Upload session ID for traceability
attributes:
$ref: '#/components/schemas/type_transactions:FileUploadUrlAttributes'
required:
- type
- id
- attributes
title: FileUploadUrlData
type_transactions:CreateFileUploadUrlResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_transactions:FileUploadUrlData'
description: List of created file upload sessions.
required:
- data
title: CreateFileUploadUrlResponse
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python Bulk Transactions Upload URL
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/transactions/uploads"
payload = { "data": [
{
"type": "incomingTransactionsFile",
"attributes": { "filename": "transaction_12345.jsonl" }
},
{
"type": "incomingTransactionsFile",
"attributes": { "filename": "transaction_67890.jsonl" }
}
] }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript Bulk Transactions Upload URL
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/transactions/uploads';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":[{"type":"incomingTransactionsFile","attributes":{"filename":"transaction_12345.jsonl"}},{"type":"incomingTransactionsFile","attributes":{"filename":"transaction_67890.jsonl"}}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go Bulk Transactions Upload URL
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/transactions/uploads"
payload := strings.NewReader("{\n \"data\": [\n {\n \"type\": \"incomingTransactionsFile\",\n \"attributes\": {\n \"filename\": \"transaction_12345.jsonl\"\n }\n },\n {\n \"type\": \"incomingTransactionsFile\",\n \"attributes\": {\n \"filename\": \"transaction_67890.jsonl\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby Bulk Transactions Upload URL
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/transactions/uploads")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": [\n {\n \"type\": \"incomingTransactionsFile\",\n \"attributes\": {\n \"filename\": \"transaction_12345.jsonl\"\n }\n },\n {\n \"type\": \"incomingTransactionsFile\",\n \"attributes\": {\n \"filename\": \"transaction_67890.jsonl\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
```java Bulk Transactions Upload URL
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/organization-123/transactions/uploads")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": [\n {\n \"type\": \"incomingTransactionsFile\",\n \"attributes\": {\n \"filename\": \"transaction_12345.jsonl\"\n }\n },\n {\n \"type\": \"incomingTransactionsFile\",\n \"attributes\": {\n \"filename\": \"transaction_67890.jsonl\"\n }\n }\n ]\n}")
.asString();
```
```php Bulk Transactions Upload URL
request('POST', 'https://rewards-api.getkard.com/v2/issuers/organization-123/transactions/uploads', [
'body' => '{
"data": [
{
"type": "incomingTransactionsFile",
"attributes": {
"filename": "transaction_12345.jsonl"
}
},
{
"type": "incomingTransactionsFile",
"attributes": {
"filename": "transaction_67890.jsonl"
}
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp Bulk Transactions Upload URL
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/transactions/uploads");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": [\n {\n \"type\": \"incomingTransactionsFile\",\n \"attributes\": {\n \"filename\": \"transaction_12345.jsonl\"\n }\n },\n {\n \"type\": \"incomingTransactionsFile\",\n \"attributes\": {\n \"filename\": \"transaction_67890.jsonl\"\n }\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift Bulk Transactions Upload URL
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
[
"type": "incomingTransactionsFile",
"attributes": ["filename": "transaction_12345.jsonl"]
],
[
"type": "incomingTransactionsFile",
"attributes": ["filename": "transaction_67890.jsonl"]
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/transactions/uploads")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Get Earned Rewards
GET https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/earned-rewards
Retrieve rewarded transaction history for a specific user. Returns only SETTLED transactions within the last 12 months.
Required scopes: `transaction:read`
Query Limit: Maximum of 12 months of transaction data can be queried.
Reference: https://docs.getkard.com/api/transactions/get-earned-rewards
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/users/{userId}/earned-rewards:
get:
operationId: get-earned-rewards
summary: Get Earned Rewards
description: >-
Retrieve rewarded transaction history for a specific user. Returns only
SETTLED transactions within the last 12 months.
Required scopes: `transaction:read`
Query Limit: Maximum of 12 months of transaction data can be
queried.
tags:
- subpackage_transactions
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: userId
in: path
description: The ID of the user as defined on the issuers system
required: true
schema:
type: string
- name: page[after]
in: query
description: Cursor for next page (base64-encoded timestamp + transaction ID)
required: false
schema:
type: string
- name: page[before]
in: query
description: Cursor for previous page (base64-encoded timestamp + transaction ID)
required: false
schema:
type: string
- name: page[size]
in: query
description: Number of results per page
required: false
schema:
type: integer
- name: include
in: query
description: >-
Comma-separated list of related resources to include in the
response. Supported values are `merchant` and `offer`.
required: false
schema:
type: string
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_transactions:GetEarnedRewardsResponse
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_transactions:RewardedTransactionStatus:
type: string
enum:
- SETTLED
title: RewardedTransactionStatus
type_transactions:PaymentStatus:
type: string
enum:
- UNPAID
- PAID_IN_FULL
title: PaymentStatus
type_commons:CommissionValueType:
type: string
enum:
- cents
description: The type of commission value
title: CommissionValueType
type_commons:CommissionValue:
type: object
properties:
type:
$ref: '#/components/schemas/type_commons:CommissionValueType'
description: The type of commission
value:
type: integer
description: The commission value.
required:
- type
- value
title: CommissionValue
type_transactions:CommissionEarnedDetails:
type: object
properties:
issuer:
$ref: '#/components/schemas/type_commons:CommissionValue'
user:
$ref: '#/components/schemas/type_commons:CommissionValue'
required:
- issuer
- user
title: CommissionEarnedDetails
type_transactions:RewardedTransactionAttributes:
type: object
properties:
status:
$ref: '#/components/schemas/type_transactions:RewardedTransactionStatus'
description: Status of the rewarded transaction
transactionId:
type: string
description: The transaction identifier
transactionAmountInCents:
type: integer
description: Transaction amount in cents
transactionTimestamp:
type: string
format: date-time
description: Timestamp of the transaction in ISO 8601 format
paidToIssuer:
$ref: '#/components/schemas/type_transactions:PaymentStatus'
description: Payment status to issuer
commissionEarned:
$ref: '#/components/schemas/type_transactions:CommissionEarnedDetails'
payoutTimestamp:
type: string
format: date-time
description: >-
Timestamp representing the month when the transaction has been paid
out to issuer
cardBIN:
type: string
description: Bank identification number (BIN).
cardLastFour:
type: string
description: Card last four digits.
required:
- status
- transactionId
- transactionAmountInCents
- transactionTimestamp
- paidToIssuer
- commissionEarned
title: RewardedTransactionAttributes
type_commons:ResourceType:
type: string
description: Type of document returned
title: ResourceType
type_commons:RelationshipData:
type: object
properties:
type:
$ref: '#/components/schemas/type_commons:ResourceType'
id:
type: string
description: The ID of the related resource
required:
- type
- id
title: RelationshipData
type_commons:RelationshipSingle:
type: object
properties:
data:
$ref: '#/components/schemas/type_commons:RelationshipData'
required:
- data
title: RelationshipSingle
type_transactions:RewardedTransactionRelationships:
type: object
properties:
user:
$ref: '#/components/schemas/type_commons:RelationshipSingle'
merchant:
$ref: '#/components/schemas/type_commons:RelationshipSingle'
offer:
$ref: '#/components/schemas/type_commons:RelationshipSingle'
required:
- user
- merchant
- offer
title: RewardedTransactionRelationships
type_transactions:RewardedTransactionUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- rewardedTransaction
description: 'Discriminator value: rewardedTransaction'
id:
type: string
description: Unique transaction identifier
attributes:
$ref: >-
#/components/schemas/type_transactions:RewardedTransactionAttributes
relationships:
$ref: >-
#/components/schemas/type_transactions:RewardedTransactionRelationships
required:
- type
- id
- attributes
- relationships
discriminator:
propertyName: type
title: RewardedTransactionUnion
type_commons:Links:
type: object
properties:
self:
type: string
prev:
type: string
next:
type: string
required:
- self
description: Related links to the API call
title: Links
type_transactions:TransactionMerchantAttributes:
type: object
properties:
name:
type: string
description: Merchant name
required:
- name
title: TransactionMerchantAttributes
type_transactions:TransactionOfferAttributes:
type: object
properties:
purchaseChannel:
type: array
items:
type: string
description: Purchase channels
required:
- purchaseChannel
title: TransactionOfferAttributes
type_transactions:TransactionIncludedResource:
oneOf:
- type: object
properties:
type:
type: string
enum:
- merchant
description: 'Discriminator value: merchant'
id:
type: string
description: Merchant identifier
attributes:
$ref: >-
#/components/schemas/type_transactions:TransactionMerchantAttributes
description: Merchant attributes
required:
- type
- id
- attributes
- type: object
properties:
type:
type: string
enum:
- offer
description: 'Discriminator value: offer'
id:
type: string
description: Offer identifier
attributes:
$ref: >-
#/components/schemas/type_transactions:TransactionOfferAttributes
description: Offer attributes
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: TransactionIncludedResource
type_transactions:GetEarnedRewardsResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_transactions:RewardedTransactionUnion'
links:
$ref: '#/components/schemas/type_commons:Links'
included:
type: array
items:
$ref: '#/components/schemas/type_transactions:TransactionIncludedResource'
description: Additional resources referenced in the response
required:
- data
- links
title: GetEarnedRewardsResponse
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python Get Earned Rewards
import requests
url = "https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards"
querystring = {"page[size]":"10","include":"merchant,offer"}
headers = {"Authorization": "Bearer "}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
```
```javascript Get Earned Rewards
const url = 'https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards?page%5Bsize%5D=10&include=merchant%2Coffer';
const options = {method: 'GET', headers: {Authorization: 'Bearer '}};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go Get Earned Rewards
package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards?page%5Bsize%5D=10&include=merchant%2Coffer"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer ")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby Get Earned Rewards
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards?page%5Bsize%5D=10&include=merchant%2Coffer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer '
response = http.request(request)
puts response.read_body
```
```java Get Earned Rewards
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.get("https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards?page%5Bsize%5D=10&include=merchant%2Coffer")
.header("Authorization", "Bearer ")
.asString();
```
```php Get Earned Rewards
request('GET', 'https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards?page%5Bsize%5D=10&include=merchant%2Coffer', [
'headers' => [
'Authorization' => 'Bearer ',
],
]);
echo $response->getBody();
```
```csharp Get Earned Rewards
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards?page%5Bsize%5D=10&include=merchant%2Coffer");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer ");
IRestResponse response = client.Execute(request);
```
```swift Get Earned Rewards
import Foundation
let headers = ["Authorization": "Bearer "]
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards?page%5Bsize%5D=10&include=merchant%2Coffer")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Create Users
POST https://rewards-api.getkard.com/v2/issuers/{organizationId}/users
Content-Type: application/json
Call this endpoint to enroll a specified user into your rewards program. Required scopes: `user:write` Note: `Maximum of 100 users can be created per request`.
Reference: https://docs.getkard.com/api/users/create
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/users:
post:
operationId: create
summary: Create Users
description: >-
Call this endpoint to enroll a specified user into your rewards
program. Required scopes: `user:write` Note: `Maximum of 100 users can be created per request`.
tags:
- subpackage_users
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'201':
description: Response with status 201
content:
application/json:
schema:
$ref: '#/components/schemas/type_users:CreateUsersObject'
'207':
description: Error response with status 207
content:
application/json:
schema:
$ref: '#/components/schemas/type_users:CreateUsersMultiStatusResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'409':
description: Error response with status 409
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_users:CreateUsersObject'
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_commons:UserId:
type: string
description: The ID of the user as defined on the issuers system
title: UserId
type_commons:EnrolledRewardsType:
type: string
enum:
- CARDLINKED
description: Enrolled Rewards
title: EnrolledRewardsType
type_users:UserRequestAttributes:
type: object
properties:
enrolledRewards:
type: array
items:
$ref: '#/components/schemas/type_commons:EnrolledRewardsType'
description: >-
Rewards programs to enroll the user in. If an empty array is
supplied, the user will not be enrolled in any programs.
zipCode:
type: string
description: Zipcode of user
email:
type: string
description: Email address of user
hashedEmail:
type: string
description: Hashed email address of user (using SHA-256)
phoneNumber:
type: string
description: Phone number of user in E.164 format
birthYear:
type: string
description: Birth year of user
historicalTransactionsSent:
type: boolean
description: >-
Indicates whether historical transactions have been sent for this
user
required:
- enrolledRewards
title: UserRequestAttributes
type_users:UserRequestDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- user
description: 'Discriminator value: user'
id:
$ref: '#/components/schemas/type_commons:UserId'
attributes:
$ref: '#/components/schemas/type_users:UserRequestAttributes'
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: UserRequestDataUnion
type_users:CreateUsersObject:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_users:UserRequestDataUnion'
required:
- data
title: CreateUsersObject
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_users:CreateUsersMultiStatusResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
data:
type: array
items:
$ref: '#/components/schemas/type_users:UserRequestDataUnion'
required:
- errors
title: CreateUsersMultiStatusResponse
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users"
payload = { "data": [
{
"type": "user",
"attributes": {
"enrolledRewards": ["CARDLINKED"],
"zipCode": "11238",
"email": "user@example.com",
"hashedEmail": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1",
"phoneNumber": "+14155552671",
"birthYear": "1990",
"historicalTransactionsSent": True
},
"id": "1234567890"
}
] }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":[{"type":"user","attributes":{"enrolledRewards":["CARDLINKED"],"zipCode":"11238","email":"user@example.com","hashedEmail":"a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1","phoneNumber":"+14155552671","birthYear":"1990","historicalTransactionsSent":true},"id":"1234567890"}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users"
payload := strings.NewReader("{\n \"data\": [\n {\n \"type\": \"user\",\n \"attributes\": {\n \"enrolledRewards\": [\n \"CARDLINKED\"\n ],\n \"zipCode\": \"11238\",\n \"email\": \"user@example.com\",\n \"hashedEmail\": \"a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1\",\n \"phoneNumber\": \"+14155552671\",\n \"birthYear\": \"1990\",\n \"historicalTransactionsSent\": true\n },\n \"id\": \"1234567890\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/users")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": [\n {\n \"type\": \"user\",\n \"attributes\": {\n \"enrolledRewards\": [\n \"CARDLINKED\"\n ],\n \"zipCode\": \"11238\",\n \"email\": \"user@example.com\",\n \"hashedEmail\": \"a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1\",\n \"phoneNumber\": \"+14155552671\",\n \"birthYear\": \"1990\",\n \"historicalTransactionsSent\": true\n },\n \"id\": \"1234567890\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/organization-123/users")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": [\n {\n \"type\": \"user\",\n \"attributes\": {\n \"enrolledRewards\": [\n \"CARDLINKED\"\n ],\n \"zipCode\": \"11238\",\n \"email\": \"user@example.com\",\n \"hashedEmail\": \"a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1\",\n \"phoneNumber\": \"+14155552671\",\n \"birthYear\": \"1990\",\n \"historicalTransactionsSent\": true\n },\n \"id\": \"1234567890\"\n }\n ]\n}")
.asString();
```
```php
request('POST', 'https://rewards-api.getkard.com/v2/issuers/organization-123/users', [
'body' => '{
"data": [
{
"type": "user",
"attributes": {
"enrolledRewards": [
"CARDLINKED"
],
"zipCode": "11238",
"email": "user@example.com",
"hashedEmail": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1",
"phoneNumber": "+14155552671",
"birthYear": "1990",
"historicalTransactionsSent": true
},
"id": "1234567890"
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/users");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": [\n {\n \"type\": \"user\",\n \"attributes\": {\n \"enrolledRewards\": [\n \"CARDLINKED\"\n ],\n \"zipCode\": \"11238\",\n \"email\": \"user@example.com\",\n \"hashedEmail\": \"a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1\",\n \"phoneNumber\": \"+14155552671\",\n \"birthYear\": \"1990\",\n \"historicalTransactionsSent\": true\n },\n \"id\": \"1234567890\"\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
[
"type": "user",
"attributes": [
"enrolledRewards": ["CARDLINKED"],
"zipCode": "11238",
"email": "user@example.com",
"hashedEmail": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1",
"phoneNumber": "+14155552671",
"birthYear": "1990",
"historicalTransactionsSent": true
],
"id": "1234567890"
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/users")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users"
payload = { "data": [
{
"type": "user",
"attributes": { "enrolledRewards": ["CARDLINKED"] },
"id": "string"
}
] }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":[{"type":"user","attributes":{"enrolledRewards":["CARDLINKED"]},"id":"string"}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users"
payload := strings.NewReader("{\n \"data\": [\n {\n \"type\": \"user\",\n \"attributes\": {\n \"enrolledRewards\": [\n \"CARDLINKED\"\n ]\n },\n \"id\": \"string\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": [\n {\n \"type\": \"user\",\n \"attributes\": {\n \"enrolledRewards\": [\n \"CARDLINKED\"\n ]\n },\n \"id\": \"string\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": [\n {\n \"type\": \"user\",\n \"attributes\": {\n \"enrolledRewards\": [\n \"CARDLINKED\"\n ]\n },\n \"id\": \"string\"\n }\n ]\n}")
.asString();
```
```php
request('POST', 'https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users', [
'body' => '{
"data": [
{
"type": "user",
"attributes": {
"enrolledRewards": [
"CARDLINKED"
]
},
"id": "string"
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": [\n {\n \"type\": \"user\",\n \"attributes\": {\n \"enrolledRewards\": [\n \"CARDLINKED\"\n ]\n },\n \"id\": \"string\"\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
[
"type": "user",
"attributes": ["enrolledRewards": ["CARDLINKED"]],
"id": "string"
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Update User
PUT https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}
Content-Type: application/json
Call this endpoint to update the details on a specified user. Required scopes: `user:update`
Reference: https://docs.getkard.com/api/users/update
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/users/{userId}:
put:
operationId: update
summary: Update User
description: |-
Call this endpoint to update the details on a specified user. Required scopes: `user:update`
tags:
- subpackage_users
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: userId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:UserId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_users:UserResponseObject'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_users:UpdateUserObject'
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_commons:UserId:
type: string
description: The ID of the user as defined on the issuers system
title: UserId
type_commons:EnrolledRewardsType:
type: string
enum:
- CARDLINKED
description: Enrolled Rewards
title: EnrolledRewardsType
type_users:UpdateUserRequestAttributes:
type: object
properties:
enrolledRewards:
type: array
items:
$ref: '#/components/schemas/type_commons:EnrolledRewardsType'
description: >-
Rewards programs to enroll the user in. If an empty array is
supplied, the user will not be enrolled in any programs.
zipCode:
type: string
description: Zipcode of user
email:
type: string
description: Email address of user
hashedEmail:
type: string
description: Hashed email address of user (using SHA-256)
phoneNumber:
type: string
description: Phone number of user in E.164 format
birthYear:
type: string
description: Birth year of user
required:
- enrolledRewards
title: UpdateUserRequestAttributes
type_users:UpdateUserRequestDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- user
description: 'Discriminator value: user'
id:
$ref: '#/components/schemas/type_commons:UserId'
attributes:
$ref: '#/components/schemas/type_users:UpdateUserRequestAttributes'
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: UpdateUserRequestDataUnion
type_users:UpdateUserObject:
type: object
properties:
data:
$ref: '#/components/schemas/type_users:UpdateUserRequestDataUnion'
required:
- data
title: UpdateUserObject
type_users:UserRequestAttributes:
type: object
properties:
enrolledRewards:
type: array
items:
$ref: '#/components/schemas/type_commons:EnrolledRewardsType'
description: >-
Rewards programs to enroll the user in. If an empty array is
supplied, the user will not be enrolled in any programs.
zipCode:
type: string
description: Zipcode of user
email:
type: string
description: Email address of user
hashedEmail:
type: string
description: Hashed email address of user (using SHA-256)
phoneNumber:
type: string
description: Phone number of user in E.164 format
birthYear:
type: string
description: Birth year of user
historicalTransactionsSent:
type: boolean
description: >-
Indicates whether historical transactions have been sent for this
user
required:
- enrolledRewards
title: UserRequestAttributes
type_users:UserRequestDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- user
description: 'Discriminator value: user'
id:
$ref: '#/components/schemas/type_commons:UserId'
attributes:
$ref: '#/components/schemas/type_users:UserRequestAttributes'
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: UserRequestDataUnion
type_users:UserResponseObject:
type: object
properties:
data:
$ref: '#/components/schemas/type_users:UserRequestDataUnion'
required:
- data
title: UserResponseObject
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123"
payload = { "data": {
"type": "user",
"attributes": {
"enrolledRewards": ["CARDLINKED"],
"zipCode": "11238",
"email": "user@example.com",
"hashedEmail": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1",
"phoneNumber": "+14155552671",
"birthYear": "1990"
},
"id": "1234567890"
} }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123';
const options = {
method: 'PUT',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":{"type":"user","attributes":{"enrolledRewards":["CARDLINKED"],"zipCode":"11238","email":"user@example.com","hashedEmail":"a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1","phoneNumber":"+14155552671","birthYear":"1990"},"id":"1234567890"}}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123"
payload := strings.NewReader("{\n \"data\": {\n \"type\": \"user\",\n \"attributes\": {\n \"enrolledRewards\": [\n \"CARDLINKED\"\n ],\n \"zipCode\": \"11238\",\n \"email\": \"user@example.com\",\n \"hashedEmail\": \"a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1\",\n \"phoneNumber\": \"+14155552671\",\n \"birthYear\": \"1990\"\n },\n \"id\": \"1234567890\"\n }\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"type\": \"user\",\n \"attributes\": {\n \"enrolledRewards\": [\n \"CARDLINKED\"\n ],\n \"zipCode\": \"11238\",\n \"email\": \"user@example.com\",\n \"hashedEmail\": \"a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1\",\n \"phoneNumber\": \"+14155552671\",\n \"birthYear\": \"1990\"\n },\n \"id\": \"1234567890\"\n }\n}"
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.put("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"type\": \"user\",\n \"attributes\": {\n \"enrolledRewards\": [\n \"CARDLINKED\"\n ],\n \"zipCode\": \"11238\",\n \"email\": \"user@example.com\",\n \"hashedEmail\": \"a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1\",\n \"phoneNumber\": \"+14155552671\",\n \"birthYear\": \"1990\"\n },\n \"id\": \"1234567890\"\n }\n}")
.asString();
```
```php
request('PUT', 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123', [
'body' => '{
"data": {
"type": "user",
"attributes": {
"enrolledRewards": [
"CARDLINKED"
],
"zipCode": "11238",
"email": "user@example.com",
"hashedEmail": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1",
"phoneNumber": "+14155552671",
"birthYear": "1990"
},
"id": "1234567890"
}
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": {\n \"type\": \"user\",\n \"attributes\": {\n \"enrolledRewards\": [\n \"CARDLINKED\"\n ],\n \"zipCode\": \"11238\",\n \"email\": \"user@example.com\",\n \"hashedEmail\": \"a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1\",\n \"phoneNumber\": \"+14155552671\",\n \"birthYear\": \"1990\"\n },\n \"id\": \"1234567890\"\n }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
"type": "user",
"attributes": [
"enrolledRewards": ["CARDLINKED"],
"zipCode": "11238",
"email": "user@example.com",
"hashedEmail": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3e2d8a5b76e45a1d4c4e2e3a1",
"phoneNumber": "+14155552671",
"birthYear": "1990"
],
"id": "1234567890"
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Delete User
DELETE https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}
Call this endpoint to delete a specified enrolled user from the rewards program and Kard's system. Users can be re-enrolled into rewards by calling the [Create User](/2024-10-01/api/users/create) endpoint using the same `id` from before. Required scopes: `user:delete`
Reference: https://docs.getkard.com/api/users/delete
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/users/{userId}:
delete:
operationId: delete
summary: Delete User
description: >-
Call this endpoint to delete a specified enrolled user from the rewards
program and Kard's system. Users can be re-enrolled into rewards by
calling the [Create User](/2024-10-01/api/users/create) endpoint using
the same `id` from before. Required scopes: `user:delete`
tags:
- subpackage_users
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: userId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:UserId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_users:DeleteUserResponseObject'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_commons:UserId:
type: string
description: The ID of the user as defined on the issuers system
title: UserId
type_commons:EmptyObject:
type: object
properties: {}
title: EmptyObject
type_users:UserResponseUnionNoData:
oneOf:
- type: object
properties:
type:
type: string
enum:
- user
description: 'Discriminator value: user'
id:
$ref: '#/components/schemas/type_commons:UserId'
attributes:
$ref: '#/components/schemas/type_commons:EmptyObject'
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: UserResponseUnionNoData
type_users:DeleteUserResponseObject:
type: object
properties:
data:
$ref: '#/components/schemas/type_users:UserResponseUnionNoData'
required:
- data
title: DeleteUserResponseObject
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123"
headers = {"Authorization": "Bearer "}
response = requests.delete(url, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123';
const options = {method: 'DELETE', headers: {Authorization: 'Bearer '}};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123"
req, _ := http.NewRequest("DELETE", url, nil)
req.Header.Add("Authorization", "Bearer ")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer '
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.delete("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123")
.header("Authorization", "Bearer ")
.asString();
```
```php
request('DELETE', 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123', [
'headers' => [
'Authorization' => 'Bearer ',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Authorization", "Bearer ");
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = ["Authorization": "Bearer "]
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Get User By ID
GET https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}
Call this endpoint to fetch the details on a specified user.
Required scopes: `user:read`
Reference: https://docs.getkard.com/api/users/get
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/users/{userId}:
get:
operationId: get
summary: Get User By ID
description: |-
Call this endpoint to fetch the details on a specified user.
Required scopes: `user:read`
tags:
- subpackage_users
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: userId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:UserId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_users:UserResponseObject'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_commons:UserId:
type: string
description: The ID of the user as defined on the issuers system
title: UserId
type_commons:EnrolledRewardsType:
type: string
enum:
- CARDLINKED
description: Enrolled Rewards
title: EnrolledRewardsType
type_users:UserRequestAttributes:
type: object
properties:
enrolledRewards:
type: array
items:
$ref: '#/components/schemas/type_commons:EnrolledRewardsType'
description: >-
Rewards programs to enroll the user in. If an empty array is
supplied, the user will not be enrolled in any programs.
zipCode:
type: string
description: Zipcode of user
email:
type: string
description: Email address of user
hashedEmail:
type: string
description: Hashed email address of user (using SHA-256)
phoneNumber:
type: string
description: Phone number of user in E.164 format
birthYear:
type: string
description: Birth year of user
historicalTransactionsSent:
type: boolean
description: >-
Indicates whether historical transactions have been sent for this
user
required:
- enrolledRewards
title: UserRequestAttributes
type_users:UserRequestDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- user
description: 'Discriminator value: user'
id:
$ref: '#/components/schemas/type_commons:UserId'
attributes:
$ref: '#/components/schemas/type_users:UserRequestAttributes'
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: UserRequestDataUnion
type_users:UserResponseObject:
type: object
properties:
data:
$ref: '#/components/schemas/type_users:UserRequestDataUnion'
required:
- data
title: UserResponseObject
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123"
headers = {"Authorization": "Bearer "}
response = requests.get(url, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123';
const options = {method: 'GET', headers: {Authorization: 'Bearer '}};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer ")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer '
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.get("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123")
.header("Authorization", "Bearer ")
.asString();
```
```php
request('GET', 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123', [
'headers' => [
'Authorization' => 'Bearer ',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer ");
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = ["Authorization": "Bearer "]
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Get Offers By User
GET https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/offers
Retrieve national brand offers that a specified user is eligible for. Call this endpoint to build out your
[targeted offers UX experience](/2024-10-01/api/getting-started#b-discover-a-lapsed-customer-clo). Local offers details
can be found by calling the [Get Eligible Locations](/2024-10-01/api/rewards/locations). Required scopes: `rewards:read`
Reference: https://docs.getkard.com/api/rewards/offers
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/users/{userId}/offers:
get:
operationId: offers
summary: Get Offers By User
description: >-
Retrieve national brand offers that a specified user is eligible for.
Call this endpoint to build out your
[targeted offers UX
experience](/2024-10-01/api/getting-started#b-discover-a-lapsed-customer-clo).
Local offers details
can be found by calling the [Get Eligible
Locations](/2024-10-01/api/rewards/locations). Required scopes: `rewards:read`
tags:
- subpackage_users.subpackage_users/rewards
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: userId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:UserId'
- name: page[size]
in: query
required: false
schema:
type: integer
- name: page[after]
in: query
required: false
schema:
type: string
- name: page[before]
in: query
required: false
schema:
type: string
- name: filter[search]
in: query
description: Case-insensitive search string to filter offers by merchant name
required: false
schema:
type: string
- name: filter[purchaseChannel]
in: query
required: false
schema:
type: array
items:
$ref: '#/components/schemas/type_commons:PurchaseChannel'
- name: filter[category]
in: query
required: false
schema:
$ref: '#/components/schemas/type_commons:CategoryOption'
- name: filter[isTargeted]
in: query
required: false
schema:
type: boolean
- name: sort
in: query
description: If provided, response will be sorted by the specified fields
required: false
schema:
$ref: '#/components/schemas/type_users/rewards:OfferSortOptions'
- name: include
in: query
description: >-
CSV list of included resources in the response (e.g "categories").
Allowed value is `categories`.
required: false
schema:
type: string
- name: supportedComponents
in: query
description: UI component types to include in the response.
required: false
schema:
$ref: '#/components/schemas/type_users/rewards:ComponentType'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_users/rewards:OffersResponseObject'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_commons:UserId:
type: string
description: The ID of the user as defined on the issuers system
title: UserId
type_commons:PurchaseChannel:
type: string
enum:
- INSTORE
- ONLINE
description: Purchase channel of offer
title: PurchaseChannel
type_commons:CategoryOption:
type: string
enum:
- Arts & Entertainment
- Baby, Kids & Toys
- Books & Digital Media
- Clothing, Shoes & Accessories
- Computers, Electronics & Software
- Convenience
- Gas
- Department Stores
- Food & Beverage
- Health & Beauty
- Home & Garden
- Miscellaneous
- Occasions & Gifts
- Pets
- Sports & Outdoors
- Supplies & Services
- Travel
description: >-
Category of merchant. Please use URL Encode for non single word
categories. (Food & Beverage should be Food%20%26%20Beverage)
title: CategoryOption
type_users/rewards:OfferSortOptions:
type: string
enum:
- startDate
- '-startDate'
- expirationDate
- '-expirationDate'
- name
- '-name'
title: OfferSortOptions
type_users/rewards:ComponentType:
type: string
enum:
- shortDescription
- longDescription
- baseReward
- boostedReward
- cta
- tags
- detailTags
- logoFlare
- progressBar
description: Available UI component types for offers
title: ComponentType
type_commons:MongoId:
type: string
description: The unique identifier for a document in the database
title: MongoId
type_commons:CommissionType:
type: string
enum:
- FLAT
- PERCENT
description: Type of commission on offer (% or a flat $)
title: CommissionType
type_users/rewards:Commission:
type: object
properties:
type:
$ref: '#/components/schemas/type_commons:CommissionType'
value:
type: number
format: double
required:
- type
- value
title: Commission
type_users/rewards:Asset:
type: object
properties:
type:
type: string
url:
type: string
description: URL of the asset containing an attribution token
alt:
type: string
description: Alt text of the asset
required:
- type
- url
- alt
title: Asset
type_users/rewards:AmountType:
type: string
enum:
- CENTS
title: AmountType
type_users/rewards:Amount:
type: object
properties:
type:
$ref: '#/components/schemas/type_users/rewards:AmountType'
value:
type: integer
required:
- type
- value
title: Amount
type_users/rewards:ButtonStyle:
type: string
enum:
- PRIMARY
- SECONDARY
- DISABLED
description: Available button styles for CTA components
title: ButtonStyle
type_users/rewards:CtaAction:
type: object
properties:
url:
type: string
description: URL endpoint to call when button is clicked
method:
type: string
description: HTTP method to use (e.g., POST)
required:
- url
- method
description: Action configuration for CTA button
title: CtaAction
type_users/rewards:CtaComponent:
type: object
properties:
buttonText:
type: string
description: Text to display on the button
buttonStyle:
$ref: '#/components/schemas/type_users/rewards:ButtonStyle'
description: Style of the button
action:
$ref: '#/components/schemas/type_users/rewards:CtaAction'
description: Action to perform when the button is clicked
startIcon:
type: string
description: Icon identifier to display on the button
required:
- buttonText
- buttonStyle
description: Call-to-action button component for offers
title: CtaComponent
type_users/rewards:LogoFlareBorderColor:
type: string
enum:
- PRIMARY
- SECONDARY
description: Available border color options for logo flare
title: LogoFlareBorderColor
type_users/rewards:LogoFlareBadgePosition:
type: string
enum:
- TOP_RIGHT
- TOP_LEFT
- BOTTOM_RIGHT
- BOTTOM_LEFT
description: Available positions for the logo flare badge
title: LogoFlareBadgePosition
type_users/rewards:LogoFlareBadge:
type: object
properties:
icon:
type: string
description: Icon identifier for the badge
position:
$ref: '#/components/schemas/type_users/rewards:LogoFlareBadgePosition'
description: Position of the badge on the logo
required:
- icon
- position
description: Badge configuration for logo flare
title: LogoFlareBadge
type_users/rewards:LogoFlare:
type: object
properties:
borderColor:
$ref: '#/components/schemas/type_users/rewards:LogoFlareBorderColor'
description: Border color style for the logo flare
badge:
$ref: '#/components/schemas/type_users/rewards:LogoFlareBadge'
description: Optional badge to display on the logo
required:
- borderColor
description: Logo flare configuration for offer display
title: LogoFlare
type_users/rewards:ProgressBarSegmentPosition:
type: string
enum:
- LEFT
- RIGHT
- FULL_WIDTH
description: Supported segment positions
title: ProgressBarSegmentPosition
type_users/rewards:ProgressBarSegment:
type: object
properties:
icon:
type: string
description: SVG icon to use for each segment
position:
$ref: '#/components/schemas/type_users/rewards:ProgressBarSegmentPosition'
description: Position of the segment within the layout
required:
- position
description: Segment configuration for a specific layout
title: ProgressBarSegment
type_users/rewards:ProgressBarSegments:
type: object
properties:
details:
$ref: '#/components/schemas/type_users/rewards:ProgressBarSegment'
description: Segment configuration for the details view
default:
$ref: '#/components/schemas/type_users/rewards:ProgressBarSegment'
description: Segment configuration for the default view
required:
- default
description: Segment configuration for the progress bar in different layouts
title: ProgressBarSegments
type_users/rewards:ProgressBarLabelPair:
type: object
properties:
left:
type: string
description: Text content for the left label
right:
type: string
description: Text content for the right label
description: Left and right label configuration for a specific layout
title: ProgressBarLabelPair
type_users/rewards:ProgressBarLabels:
type: object
properties:
details:
$ref: '#/components/schemas/type_users/rewards:ProgressBarLabelPair'
description: Label configuration for the details view
default:
$ref: '#/components/schemas/type_users/rewards:ProgressBarLabelPair'
description: Label configuration for the default view
required:
- default
description: Labels to render around the progress bar in different layouts
title: ProgressBarLabels
type_users/rewards:ProgressBar:
type: object
properties:
total:
type: integer
description: Total number of redemptions allowed
currentProgress:
type: integer
description: Number of redemptions the user has completed
label:
type: string
description: Formatted label for the progress bar
segmented:
type: boolean
description: Whether the progress bar should be displayed as segmented
segments:
$ref: '#/components/schemas/type_users/rewards:ProgressBarSegments'
description: Segment configuration for the progress bar in different layouts
labels:
$ref: '#/components/schemas/type_users/rewards:ProgressBarLabels'
description: Labels to render around the progress bar in different layouts
required:
- total
- currentProgress
- label
- segmented
- labels
description: Progress bar component for tracking offer redemption progress
title: ProgressBar
type_users/rewards:OfferComponents:
type: object
properties:
shortDescription:
type: string
description: Short description for the offer
longDescription:
type: string
description: Long description for the offer
baseReward:
type: string
description: Formatted reward string
boostedReward:
type: string
description: Formatted boosted reward string
cta:
$ref: '#/components/schemas/type_users/rewards:CtaComponent'
description: Call-to-action button component
tags:
type: array
items:
type: string
description: Tags for the offer
detailTags:
type: array
items:
type: string
description: Detail tags for the offer
logoFlare:
$ref: '#/components/schemas/type_users/rewards:LogoFlare'
description: Logo flare configuration for the offer
progressBar:
$ref: '#/components/schemas/type_users/rewards:ProgressBar'
description: Progress bar component for tracking offer redemptions
description: UI component data for rendering offer details
title: OfferComponents
type_users/rewards:StandardOfferFields:
type: object
properties:
terms:
type: string
description: Terms and conditions on offer
maxRedemptions:
type: integer
description: Maximum times cardholder can redeem offer, if applicable
name:
type: string
description: Name of offer
purchaseChannel:
type: array
items:
$ref: '#/components/schemas/type_commons:PurchaseChannel'
userReward:
$ref: '#/components/schemas/type_users/rewards:Commission'
assets:
type: array
items:
$ref: '#/components/schemas/type_users/rewards:Asset'
description: Assets associated with offer
startDate:
type: string
format: date-time
description: Beginning date of offer (UTC)
expirationDate:
type: string
format: date-time
description: Expiration date of offer if applicable (UTC)
isTargeted:
type: boolean
description: >-
True returns only targeted offers, false returns only non-targeted
offers
minTransactionAmount:
$ref: '#/components/schemas/type_users/rewards:Amount'
description: >-
Minimum Transaction Amount required to redeem offer, if available on
offer
maxTransactionAmount:
$ref: '#/components/schemas/type_users/rewards:Amount'
description: >-
Maximum Transaction Amount allowed to redeem offer, if available on
offer
minRewardAmount:
$ref: '#/components/schemas/type_users/rewards:Amount'
description: Minimum Reward Amount, if available on offer
maxRewardAmount:
$ref: '#/components/schemas/type_users/rewards:Amount'
description: Maximum Reward Amount, if available on offer
websiteUrl:
type: string
description: URL to the website of the offer provider
description:
type: string
description: Description of the offer
components:
$ref: '#/components/schemas/type_users/rewards:OfferComponents'
description: >-
UI component data for the offer, returned when supportedComponents
query parameter is provided
required:
- terms
- name
- purchaseChannel
- userReward
- assets
- startDate
- expirationDate
- isTargeted
title: StandardOfferFields
type_users/rewards:CategoryData:
type: object
properties:
id:
type: string
description: id of the category
type:
type: string
enum:
- category
required:
- id
- type
title: CategoryData
type_users/rewards:CategoryRelationship:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_users/rewards:CategoryData'
required:
- data
title: CategoryRelationship
type_users/rewards:CategoryRelationshipObject:
type: object
properties:
category:
$ref: '#/components/schemas/type_users/rewards:CategoryRelationship'
required:
- category
title: CategoryRelationshipObject
type_users/rewards:EligibilityOfferRelationship:
oneOf:
- $ref: '#/components/schemas/type_users/rewards:CategoryRelationshipObject'
title: EligibilityOfferRelationship
type_users/rewards:OfferDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- standardOffer
description: 'Discriminator value: standardOffer'
id:
$ref: '#/components/schemas/type_commons:MongoId'
description: Offer ID in Kard's system
attributes:
$ref: '#/components/schemas/type_users/rewards:StandardOfferFields'
relationships:
$ref: >-
#/components/schemas/type_users/rewards:EligibilityOfferRelationship
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: OfferDataUnion
type_commons:Links:
type: object
properties:
self:
type: string
prev:
type: string
next:
type: string
required:
- self
description: Related links to the API call
title: Links
type_users/rewards:CategoryFields:
type: object
properties:
name:
$ref: '#/components/schemas/type_commons:CategoryOption'
description: Name of the category
required:
- name
title: CategoryFields
type_users/rewards:CategoryIncluded:
type: object
properties:
id:
type: string
description: id of the category
type:
type: string
enum:
- category
attributes:
$ref: '#/components/schemas/type_users/rewards:CategoryFields'
required:
- id
- type
- attributes
title: CategoryIncluded
type_users/rewards:EligibilityOfferIncluded:
oneOf:
- $ref: '#/components/schemas/type_users/rewards:CategoryIncluded'
title: EligibilityOfferIncluded
type_users/rewards:OffersMeta:
type: object
properties:
availableCategories:
type: array
items:
$ref: '#/components/schemas/type_users/rewards:CategoryIncluded'
description: >-
All distinct categories available across the entire filtered result
set, not just the current page
description: Metadata about the full result set across all pages
title: OffersMeta
type_users/rewards:OffersResponseObject:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_users/rewards:OfferDataUnion'
links:
$ref: '#/components/schemas/type_commons:Links'
included:
type: array
items:
$ref: '#/components/schemas/type_users/rewards:EligibilityOfferIncluded'
meta:
$ref: '#/components/schemas/type_users/rewards:OffersMeta'
required:
- data
- links
title: OffersResponseObject
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers"
querystring = {"page[size]":"1","filter[isTargeted]":"true","sort":"-startDate"}
headers = {"Authorization": "Bearer "}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers?page%5Bsize%5D=1&filter%5BisTargeted%5D=true&sort=-startDate';
const options = {method: 'GET', headers: {Authorization: 'Bearer '}};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers?page%5Bsize%5D=1&filter%5BisTargeted%5D=true&sort=-startDate"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer ")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers?page%5Bsize%5D=1&filter%5BisTargeted%5D=true&sort=-startDate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer '
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.get("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers?page%5Bsize%5D=1&filter%5BisTargeted%5D=true&sort=-startDate")
.header("Authorization", "Bearer ")
.asString();
```
```php
request('GET', 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers?page%5Bsize%5D=1&filter%5BisTargeted%5D=true&sort=-startDate', [
'headers' => [
'Authorization' => 'Bearer ',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers?page%5Bsize%5D=1&filter%5BisTargeted%5D=true&sort=-startDate");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer ");
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = ["Authorization": "Bearer "]
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers?page%5Bsize%5D=1&filter%5BisTargeted%5D=true&sort=-startDate")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Get Locations By User
GET https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/locations
Retrieve national and local geographic locations that a specified user has eligible in-store offers at. Use this endpoint to build
out your [map-specific UX experiences](/2024-10-01/api/getting-started#c-discover-clos-near-you-map-view). Please note
that Longitude and Latitude fields are prioritized over State, City and Zipcode and are the recommended search
pattern.
Required scopes: `rewards:read`
Reference: https://docs.getkard.com/api/rewards/locations
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/users/{userId}/locations:
get:
operationId: locations
summary: Get Locations By User
description: >-
Retrieve national and local geographic locations that a specified user
has eligible in-store offers at. Use this endpoint to build
out your [map-specific UX
experiences](/2024-10-01/api/getting-started#c-discover-clos-near-you-map-view).
Please note
that Longitude and Latitude fields are prioritized over State, City and
Zipcode and are the recommended search
pattern.
Required scopes: `rewards:read`
tags:
- subpackage_users.subpackage_users/rewards
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: userId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:UserId'
- name: page[size]
in: query
required: false
schema:
type: integer
- name: page[after]
in: query
required: false
schema:
type: string
- name: page[before]
in: query
required: false
schema:
type: string
- name: filter[name]
in: query
required: false
schema:
type: string
- name: filter[city]
in: query
required: false
schema:
type: string
- name: filter[zipCode]
in: query
required: false
schema:
type: string
- name: filter[state]
in: query
required: false
schema:
$ref: '#/components/schemas/type_commons:State'
- name: filter[category]
in: query
required: false
schema:
$ref: '#/components/schemas/type_commons:CategoryOption'
- name: filter[longitude]
in: query
required: false
schema:
type: number
format: double
- name: filter[latitude]
in: query
required: false
schema:
type: number
format: double
- name: filter[radius]
in: query
required: false
schema:
type: integer
- name: sort
in: query
description: If provided, response will be sorted by the specified fields
required: false
schema:
$ref: '#/components/schemas/type_users/rewards:LocationSortOptions'
- name: include
in: query
description: >-
CSV list of included resources in the response (e.g
"offers,categories"). Allowed values are `offers` and `categories`.
required: false
schema:
type: string
- name: supportedComponents
in: query
description: UI component types to include in included offers.
required: false
schema:
$ref: '#/components/schemas/type_users/rewards:ComponentType'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_users/rewards:LocationsResponseObject
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_commons:UserId:
type: string
description: The ID of the user as defined on the issuers system
title: UserId
type_commons:State:
type: string
enum:
- AL
- AK
- AS
- AZ
- AR
- CA
- CO
- CT
- DE
- DC
- FM
- FL
- GA
- GU
- HI
- ID
- IL
- IN
- IA
- KS
- KY
- LA
- ME
- MH
- MD
- MA
- MI
- MN
- MS
- MO
- MT
- NE
- NV
- NH
- NJ
- NM
- NY
- NC
- ND
- MP
- OH
- OK
- OR
- PW
- PA
- PR
- RI
- SC
- SD
- TN
- TX
- UT
- VT
- VI
- VA
- WA
- WV
- WI
- WY
title: State
type_commons:CategoryOption:
type: string
enum:
- Arts & Entertainment
- Baby, Kids & Toys
- Books & Digital Media
- Clothing, Shoes & Accessories
- Computers, Electronics & Software
- Convenience
- Gas
- Department Stores
- Food & Beverage
- Health & Beauty
- Home & Garden
- Miscellaneous
- Occasions & Gifts
- Pets
- Sports & Outdoors
- Supplies & Services
- Travel
description: >-
Category of merchant. Please use URL Encode for non single word
categories. (Food & Beverage should be Food%20%26%20Beverage)
title: CategoryOption
type_users/rewards:LocationSortOptions:
type: string
enum:
- locationName
- '-locationName'
title: LocationSortOptions
type_users/rewards:ComponentType:
type: string
enum:
- shortDescription
- longDescription
- baseReward
- boostedReward
- cta
- tags
- detailTags
- logoFlare
- progressBar
description: Available UI component types for offers
title: ComponentType
type_commons:MongoId:
type: string
description: The unique identifier for a document in the database
title: MongoId
type_users/rewards:EligibilityLocationAddress:
type: object
properties:
street:
type: string
city:
type: string
state:
type: string
zipCode:
type: string
required:
- street
- city
- state
- zipCode
title: EligibilityLocationAddress
type_users/rewards:Coordinates:
type: object
properties:
longitude:
type: number
format: double
latitude:
type: number
format: double
required:
- longitude
- latitude
title: Coordinates
type_users/rewards:OperationTime:
type: object
properties:
day:
type: integer
time:
type: string
required:
- day
- time
title: OperationTime
type_users/rewards:OperationPeriod:
type: object
properties:
close:
$ref: '#/components/schemas/type_users/rewards:OperationTime'
open:
$ref: '#/components/schemas/type_users/rewards:OperationTime'
required:
- close
- open
title: OperationPeriod
type_users/rewards:OperationHours:
type: object
properties:
periods:
type: array
items:
$ref: '#/components/schemas/type_users/rewards:OperationPeriod'
weekdayText:
type: array
items:
type: string
required:
- periods
- weekdayText
title: OperationHours
type_users/rewards:LocationAttributes:
type: object
properties:
name:
type: string
address:
$ref: '#/components/schemas/type_users/rewards:EligibilityLocationAddress'
coordinates:
$ref: '#/components/schemas/type_users/rewards:Coordinates'
phone:
type: string
operationHours:
$ref: '#/components/schemas/type_users/rewards:OperationHours'
required:
- name
- address
- coordinates
- phone
- operationHours
title: LocationAttributes
type_commons:ResourceType:
type: string
description: Type of document returned
title: ResourceType
type_commons:RelationshipData:
type: object
properties:
type:
$ref: '#/components/schemas/type_commons:ResourceType'
id:
type: string
description: The ID of the related resource
required:
- type
- id
title: RelationshipData
type_commons:RelationshipMultiple:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_commons:RelationshipData'
required:
- data
title: RelationshipMultiple
type_users/rewards:LocationRelationships:
type: object
properties:
offers:
$ref: '#/components/schemas/type_commons:RelationshipMultiple'
category:
$ref: '#/components/schemas/type_commons:RelationshipMultiple'
required:
- offers
- category
title: LocationRelationships
type_users/rewards:LocationData:
type: object
properties:
type:
type: string
enum:
- location
id:
$ref: '#/components/schemas/type_commons:MongoId'
description: Location ID in Kard's system
attributes:
$ref: '#/components/schemas/type_users/rewards:LocationAttributes'
relationships:
$ref: '#/components/schemas/type_users/rewards:LocationRelationships'
description: Related resources to the offer
required:
- type
- id
- attributes
title: LocationData
type_commons:Links:
type: object
properties:
self:
type: string
prev:
type: string
next:
type: string
required:
- self
description: Related links to the API call
title: Links
type_commons:PurchaseChannel:
type: string
enum:
- INSTORE
- ONLINE
description: Purchase channel of offer
title: PurchaseChannel
type_commons:CommissionType:
type: string
enum:
- FLAT
- PERCENT
description: Type of commission on offer (% or a flat $)
title: CommissionType
type_users/rewards:Commission:
type: object
properties:
type:
$ref: '#/components/schemas/type_commons:CommissionType'
value:
type: number
format: double
required:
- type
- value
title: Commission
type_users/rewards:Asset:
type: object
properties:
type:
type: string
url:
type: string
description: URL of the asset containing an attribution token
alt:
type: string
description: Alt text of the asset
required:
- type
- url
- alt
title: Asset
type_users/rewards:AmountType:
type: string
enum:
- CENTS
title: AmountType
type_users/rewards:Amount:
type: object
properties:
type:
$ref: '#/components/schemas/type_users/rewards:AmountType'
value:
type: integer
required:
- type
- value
title: Amount
type_users/rewards:ButtonStyle:
type: string
enum:
- PRIMARY
- SECONDARY
- DISABLED
description: Available button styles for CTA components
title: ButtonStyle
type_users/rewards:CtaAction:
type: object
properties:
url:
type: string
description: URL endpoint to call when button is clicked
method:
type: string
description: HTTP method to use (e.g., POST)
required:
- url
- method
description: Action configuration for CTA button
title: CtaAction
type_users/rewards:CtaComponent:
type: object
properties:
buttonText:
type: string
description: Text to display on the button
buttonStyle:
$ref: '#/components/schemas/type_users/rewards:ButtonStyle'
description: Style of the button
action:
$ref: '#/components/schemas/type_users/rewards:CtaAction'
description: Action to perform when the button is clicked
startIcon:
type: string
description: Icon identifier to display on the button
required:
- buttonText
- buttonStyle
description: Call-to-action button component for offers
title: CtaComponent
type_users/rewards:LogoFlareBorderColor:
type: string
enum:
- PRIMARY
- SECONDARY
description: Available border color options for logo flare
title: LogoFlareBorderColor
type_users/rewards:LogoFlareBadgePosition:
type: string
enum:
- TOP_RIGHT
- TOP_LEFT
- BOTTOM_RIGHT
- BOTTOM_LEFT
description: Available positions for the logo flare badge
title: LogoFlareBadgePosition
type_users/rewards:LogoFlareBadge:
type: object
properties:
icon:
type: string
description: Icon identifier for the badge
position:
$ref: '#/components/schemas/type_users/rewards:LogoFlareBadgePosition'
description: Position of the badge on the logo
required:
- icon
- position
description: Badge configuration for logo flare
title: LogoFlareBadge
type_users/rewards:LogoFlare:
type: object
properties:
borderColor:
$ref: '#/components/schemas/type_users/rewards:LogoFlareBorderColor'
description: Border color style for the logo flare
badge:
$ref: '#/components/schemas/type_users/rewards:LogoFlareBadge'
description: Optional badge to display on the logo
required:
- borderColor
description: Logo flare configuration for offer display
title: LogoFlare
type_users/rewards:ProgressBarSegmentPosition:
type: string
enum:
- LEFT
- RIGHT
- FULL_WIDTH
description: Supported segment positions
title: ProgressBarSegmentPosition
type_users/rewards:ProgressBarSegment:
type: object
properties:
icon:
type: string
description: SVG icon to use for each segment
position:
$ref: '#/components/schemas/type_users/rewards:ProgressBarSegmentPosition'
description: Position of the segment within the layout
required:
- position
description: Segment configuration for a specific layout
title: ProgressBarSegment
type_users/rewards:ProgressBarSegments:
type: object
properties:
details:
$ref: '#/components/schemas/type_users/rewards:ProgressBarSegment'
description: Segment configuration for the details view
default:
$ref: '#/components/schemas/type_users/rewards:ProgressBarSegment'
description: Segment configuration for the default view
required:
- default
description: Segment configuration for the progress bar in different layouts
title: ProgressBarSegments
type_users/rewards:ProgressBarLabelPair:
type: object
properties:
left:
type: string
description: Text content for the left label
right:
type: string
description: Text content for the right label
description: Left and right label configuration for a specific layout
title: ProgressBarLabelPair
type_users/rewards:ProgressBarLabels:
type: object
properties:
details:
$ref: '#/components/schemas/type_users/rewards:ProgressBarLabelPair'
description: Label configuration for the details view
default:
$ref: '#/components/schemas/type_users/rewards:ProgressBarLabelPair'
description: Label configuration for the default view
required:
- default
description: Labels to render around the progress bar in different layouts
title: ProgressBarLabels
type_users/rewards:ProgressBar:
type: object
properties:
total:
type: integer
description: Total number of redemptions allowed
currentProgress:
type: integer
description: Number of redemptions the user has completed
label:
type: string
description: Formatted label for the progress bar
segmented:
type: boolean
description: Whether the progress bar should be displayed as segmented
segments:
$ref: '#/components/schemas/type_users/rewards:ProgressBarSegments'
description: Segment configuration for the progress bar in different layouts
labels:
$ref: '#/components/schemas/type_users/rewards:ProgressBarLabels'
description: Labels to render around the progress bar in different layouts
required:
- total
- currentProgress
- label
- segmented
- labels
description: Progress bar component for tracking offer redemption progress
title: ProgressBar
type_users/rewards:OfferComponents:
type: object
properties:
shortDescription:
type: string
description: Short description for the offer
longDescription:
type: string
description: Long description for the offer
baseReward:
type: string
description: Formatted reward string
boostedReward:
type: string
description: Formatted boosted reward string
cta:
$ref: '#/components/schemas/type_users/rewards:CtaComponent'
description: Call-to-action button component
tags:
type: array
items:
type: string
description: Tags for the offer
detailTags:
type: array
items:
type: string
description: Detail tags for the offer
logoFlare:
$ref: '#/components/schemas/type_users/rewards:LogoFlare'
description: Logo flare configuration for the offer
progressBar:
$ref: '#/components/schemas/type_users/rewards:ProgressBar'
description: Progress bar component for tracking offer redemptions
description: UI component data for rendering offer details
title: OfferComponents
type_users/rewards:StandardOfferFields:
type: object
properties:
terms:
type: string
description: Terms and conditions on offer
maxRedemptions:
type: integer
description: Maximum times cardholder can redeem offer, if applicable
name:
type: string
description: Name of offer
purchaseChannel:
type: array
items:
$ref: '#/components/schemas/type_commons:PurchaseChannel'
userReward:
$ref: '#/components/schemas/type_users/rewards:Commission'
assets:
type: array
items:
$ref: '#/components/schemas/type_users/rewards:Asset'
description: Assets associated with offer
startDate:
type: string
format: date-time
description: Beginning date of offer (UTC)
expirationDate:
type: string
format: date-time
description: Expiration date of offer if applicable (UTC)
isTargeted:
type: boolean
description: >-
True returns only targeted offers, false returns only non-targeted
offers
minTransactionAmount:
$ref: '#/components/schemas/type_users/rewards:Amount'
description: >-
Minimum Transaction Amount required to redeem offer, if available on
offer
maxTransactionAmount:
$ref: '#/components/schemas/type_users/rewards:Amount'
description: >-
Maximum Transaction Amount allowed to redeem offer, if available on
offer
minRewardAmount:
$ref: '#/components/schemas/type_users/rewards:Amount'
description: Minimum Reward Amount, if available on offer
maxRewardAmount:
$ref: '#/components/schemas/type_users/rewards:Amount'
description: Maximum Reward Amount, if available on offer
websiteUrl:
type: string
description: URL to the website of the offer provider
description:
type: string
description: Description of the offer
components:
$ref: '#/components/schemas/type_users/rewards:OfferComponents'
description: >-
UI component data for the offer, returned when supportedComponents
query parameter is provided
required:
- terms
- name
- purchaseChannel
- userReward
- assets
- startDate
- expirationDate
- isTargeted
title: StandardOfferFields
type_users/rewards:CategoryData:
type: object
properties:
id:
type: string
description: id of the category
type:
type: string
enum:
- category
required:
- id
- type
title: CategoryData
type_users/rewards:CategoryRelationship:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_users/rewards:CategoryData'
required:
- data
title: CategoryRelationship
type_users/rewards:CategoryRelationshipObject:
type: object
properties:
category:
$ref: '#/components/schemas/type_users/rewards:CategoryRelationship'
required:
- category
title: CategoryRelationshipObject
type_users/rewards:EligibilityOfferRelationship:
oneOf:
- $ref: '#/components/schemas/type_users/rewards:CategoryRelationshipObject'
title: EligibilityOfferRelationship
type_users/rewards:OfferDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- standardOffer
description: 'Discriminator value: standardOffer'
id:
$ref: '#/components/schemas/type_commons:MongoId'
description: Offer ID in Kard's system
attributes:
$ref: '#/components/schemas/type_users/rewards:StandardOfferFields'
relationships:
$ref: >-
#/components/schemas/type_users/rewards:EligibilityOfferRelationship
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: OfferDataUnion
type_users/rewards:CategoryFields:
type: object
properties:
name:
$ref: '#/components/schemas/type_commons:CategoryOption'
description: Name of the category
required:
- name
title: CategoryFields
type_users/rewards:CategoryIncluded:
type: object
properties:
id:
type: string
description: id of the category
type:
type: string
enum:
- category
attributes:
$ref: '#/components/schemas/type_users/rewards:CategoryFields'
required:
- id
- type
- attributes
title: CategoryIncluded
type_users/rewards:EligibilityLocationIncluded:
oneOf:
- $ref: '#/components/schemas/type_users/rewards:OfferDataUnion'
- $ref: '#/components/schemas/type_users/rewards:CategoryIncluded'
title: EligibilityLocationIncluded
type_users/rewards:LocationsResponseObject:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_users/rewards:LocationData'
links:
$ref: '#/components/schemas/type_commons:Links'
included:
type: array
items:
$ref: >-
#/components/schemas/type_users/rewards:EligibilityLocationIncluded
required:
- data
- links
title: LocationsResponseObject
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations"
querystring = {"page[size]":"1","filter[latitude]":"39.9419429","filter[longitude]":"-75.1446869","filter[radius]":"10","include":"offers,categories"}
headers = {"Authorization": "Bearer "}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations?page%5Bsize%5D=1&filter%5Blatitude%5D=39.9419429&filter%5Blongitude%5D=-75.1446869&filter%5Bradius%5D=10&include=offers%2Ccategories';
const options = {method: 'GET', headers: {Authorization: 'Bearer '}};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations?page%5Bsize%5D=1&filter%5Blatitude%5D=39.9419429&filter%5Blongitude%5D=-75.1446869&filter%5Bradius%5D=10&include=offers%2Ccategories"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer ")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations?page%5Bsize%5D=1&filter%5Blatitude%5D=39.9419429&filter%5Blongitude%5D=-75.1446869&filter%5Bradius%5D=10&include=offers%2Ccategories")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer '
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.get("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations?page%5Bsize%5D=1&filter%5Blatitude%5D=39.9419429&filter%5Blongitude%5D=-75.1446869&filter%5Bradius%5D=10&include=offers%2Ccategories")
.header("Authorization", "Bearer ")
.asString();
```
```php
request('GET', 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations?page%5Bsize%5D=1&filter%5Blatitude%5D=39.9419429&filter%5Blongitude%5D=-75.1446869&filter%5Bradius%5D=10&include=offers%2Ccategories', [
'headers' => [
'Authorization' => 'Bearer ',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations?page%5Bsize%5D=1&filter%5Blatitude%5D=39.9419429&filter%5Blongitude%5D=-75.1446869&filter%5Bradius%5D=10&include=offers%2Ccategories");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer ");
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = ["Authorization": "Bearer "]
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations?page%5Bsize%5D=1&filter%5Blatitude%5D=39.9419429&filter%5Blongitude%5D=-75.1446869&filter%5Bradius%5D=10&include=offers%2Ccategories")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Notification Webhook
POST
This is an outbound webhook for issuers to receive notifications from Kard.
Learn more about how to configure, ingest and trigger your notification
webhooks [here](/2024-10-01/api/notifications).
Reference: https://docs.getkard.com/api/notifications/notification-webhook
## OpenAPI 3.1 Webhook Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths: {}
webhooks:
notification-webhook:
post:
operationId: notification-webhook
summary: Notification Webhook
description: >-
This is an outbound webhook for issuers to receive notifications from
Kard.
Learn more about how to configure, ingest and trigger your notification
webhooks [here](/2024-10-01/api/notifications).
responses:
'200':
description: Webhook received successfully
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_notifications:NotificationPayload'
components:
schemas:
type_notifications:EarnedRewardAttributes:
type: object
properties:
message:
type: string
description: The display message associated to the notification
name:
type: string
description: The name of the merchant
attributionUrl:
type: string
description: >-
The attribution URL to track user's interactions with the
notification
surveyUrl:
type: string
description: >-
Post experience survey URL, if available. This will be present for
rewards associated with local offers.
cardProductId:
type: string
description: The ID of the card product
required:
- message
- name
- attributionUrl
title: EarnedRewardAttributes
type_commons:ResourceType:
type: string
description: Type of document returned
title: ResourceType
type_commons:RelationshipData:
type: object
properties:
type:
$ref: '#/components/schemas/type_commons:ResourceType'
id:
type: string
description: The ID of the related resource
required:
- type
- id
title: RelationshipData
type_commons:RelationshipSingle:
type: object
properties:
data:
$ref: '#/components/schemas/type_commons:RelationshipData'
required:
- data
title: RelationshipSingle
type_notifications:EarnedRewardRelationships:
type: object
properties:
user:
$ref: '#/components/schemas/type_commons:RelationshipSingle'
transaction:
$ref: '#/components/schemas/type_commons:RelationshipSingle'
required:
- user
- transaction
title: EarnedRewardRelationships
type_commons:CommissionValueType:
type: string
enum:
- cents
description: The type of commission value
title: CommissionValueType
type_commons:CommissionValue:
type: object
properties:
type:
$ref: '#/components/schemas/type_commons:CommissionValueType'
description: The type of commission
value:
type: integer
description: The commission value.
required:
- type
- value
title: CommissionValue
type_notifications:EarnedRewardSettledAttributes:
type: object
properties:
message:
type: string
description: The display message associated to the notification
name:
type: string
description: The name of the merchant
attributionUrl:
type: string
description: >-
The attribution URL to track user's interactions with the
notification
surveyUrl:
type: string
description: >-
Post experience survey URL, if available. This will be present for
rewards associated with local offers.
cardProductId:
type: string
description: The ID of the card product
commissionEarned:
$ref: '#/components/schemas/type_commons:CommissionValue'
required:
- message
- name
- attributionUrl
- commissionEarned
title: EarnedRewardSettledAttributes
type_notifications:ValidTransactionCommissionEarned:
type: object
properties:
issuer:
$ref: '#/components/schemas/type_commons:CommissionValue'
user:
$ref: '#/components/schemas/type_commons:CommissionValue'
required:
- issuer
- user
title: ValidTransactionCommissionEarned
type_notifications:ValidTransactionAttributes:
type: object
properties:
message:
type: string
description: The display message associated to the notification
name:
type: string
description: The name of the merchant
attributionUrl:
type: string
description: >-
The attribution URL to track user's interactions with the
notification
surveyUrl:
type: string
description: >-
Post experience survey URL, if available. This will be present for
rewards associated with local offers.
cardProductId:
type: string
description: The ID of the card product
commissionEarned:
$ref: >-
#/components/schemas/type_notifications:ValidTransactionCommissionEarned
required:
- message
- name
- attributionUrl
- commissionEarned
title: ValidTransactionAttributes
type_notifications:TransactionRelationships:
type: object
properties:
user:
$ref: '#/components/schemas/type_commons:RelationshipSingle'
offer:
$ref: '#/components/schemas/type_commons:RelationshipSingle'
transaction:
$ref: '#/components/schemas/type_commons:RelationshipSingle'
required:
- user
- offer
- transaction
title: TransactionRelationships
type_notifications:FailedTransactionAttributes:
type: object
properties:
message:
type: string
description: The display message associated to the notification
reason:
type: string
description: The reason for the transaction failure
name:
type: string
description: The name of the merchant
cardProductId:
type: string
description: The ID of the card product
required:
- message
- reason
- name
title: FailedTransactionAttributes
type_notifications:FailedTransactionRelationships:
type: object
properties:
user:
$ref: '#/components/schemas/type_commons:RelationshipSingle'
offer:
$ref: '#/components/schemas/type_commons:RelationshipSingle'
transaction:
$ref: '#/components/schemas/type_commons:RelationshipSingle'
required:
- user
- offer
- transaction
title: FailedTransactionRelationships
type_transactions:AuditStatus:
type: string
enum:
- NEW
- IN_PROGRESS
- CLOSED
title: AuditStatus
type_notifications:AuditUpdateAttributes:
type: object
properties:
status:
$ref: '#/components/schemas/type_transactions:AuditStatus'
description: The status of the audit
auditCode:
type: integer
description: |-
Audit Code - Enum. Code to define audit.
`3005` : Customer is claiming cashback is incorrect - INCORRECT CASHBACK CLAIM
`3006` : Transaction is missing the cashback award - MISSING CASHBACK AWARD
`8001` : Other - check audit description
merchantName:
type: string
description: The merchant name related to the transaction audit
auditDescription:
type: string
description: The description of the audit
transactionId:
type: string
description: The transaction ID associated with audit
resolutionCode:
type: integer
description: >-
Resolution Code - Enum. field is available when audit is status
CLOSED.
`5001` : Transaction will be deleted
`5002` : Settlement amount will be adjusted
`5003` : Return amount will be adjusted
`5004` : Reward dispute resolved
`5005` : Transaction will be marked for writeoff
`5006` : Transaction will be marked as rejected
`5007` : Transaction will be resent through webhook
`5008` : Transaction will be resent through daily file
`5009` : No change needed
`9001` : Ineligible item in purchase
`9002` : Return was made
`9003` : User ineligible for offer (usually because of participation through another program)
`9004` : Redemption limit hit (if offer has a set number of redemptions and it isn't handled programmatically)
`9005` : Transaction not captured
resolutionDescription:
type: string
description: >-
The resolution description; field is available when audit is status
CLOSED
resolutionTimeStamp:
type: string
format: date-time
description: >-
The resolution timestamp of when the audit was marked as status
CLOSED in ISO format; available when audit is closed.
required:
- status
- auditCode
- merchantName
- auditDescription
- transactionId
title: AuditUpdateAttributes
type_notifications:AuditUpdateRelationships:
type: object
properties:
user:
$ref: '#/components/schemas/type_commons:RelationshipSingle'
audit:
$ref: '#/components/schemas/type_commons:RelationshipSingle'
required:
- user
- audit
title: AuditUpdateRelationships
type_files:FileMetadataAttribute:
type: object
properties:
fileName:
type: string
description: The name of the file.
sentAt:
type: string
description: >-
ISO 8601 timestamp (ISO8601) when the file was originally
sent/created.
lastModified:
type: string
description: ISO 8601 timestamp (ISO8601) when the file was last modified.
downloadUrl:
type: string
description: >-
Temporary URL that provides direct access to download the file for
30 minutes.
required:
- fileName
- sentAt
- lastModified
- downloadUrl
title: FileMetadataAttribute
type_notifications:NotificationDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- earnedRewardApproved
description: 'Discriminator value: earnedRewardApproved'
id:
type: string
description: The internal ID of the notification
attributes:
$ref: '#/components/schemas/type_notifications:EarnedRewardAttributes'
relationships:
$ref: >-
#/components/schemas/type_notifications:EarnedRewardRelationships
required:
- type
- id
- attributes
- relationships
- type: object
properties:
type:
type: string
enum:
- earnedRewardSettled
description: 'Discriminator value: earnedRewardSettled'
id:
type: string
description: The internal ID of the notification
attributes:
$ref: >-
#/components/schemas/type_notifications:EarnedRewardSettledAttributes
relationships:
$ref: >-
#/components/schemas/type_notifications:EarnedRewardRelationships
required:
- type
- id
- attributes
- relationships
- type: object
properties:
type:
type: string
enum:
- validTransaction
description: 'Discriminator value: validTransaction'
id:
type: string
description: The internal ID of the notification
attributes:
$ref: >-
#/components/schemas/type_notifications:ValidTransactionAttributes
relationships:
$ref: '#/components/schemas/type_notifications:TransactionRelationships'
required:
- type
- id
- attributes
- relationships
- type: object
properties:
type:
type: string
enum:
- failedTransaction
description: 'Discriminator value: failedTransaction'
id:
type: string
description: The internal ID of the notification
attributes:
$ref: >-
#/components/schemas/type_notifications:FailedTransactionAttributes
relationships:
$ref: >-
#/components/schemas/type_notifications:FailedTransactionRelationships
required:
- type
- id
- attributes
- relationships
- type: object
properties:
type:
type: string
enum:
- clawback
description: 'Discriminator value: clawback'
id:
type: string
description: The internal ID of the notification
attributes:
$ref: >-
#/components/schemas/type_notifications:FailedTransactionAttributes
relationships:
$ref: >-
#/components/schemas/type_notifications:FailedTransactionRelationships
required:
- type
- id
- attributes
- relationships
- type: object
properties:
type:
type: string
enum:
- auditUpdate
description: 'Discriminator value: auditUpdate'
id:
type: string
description: The internal ID of the notification
attributes:
$ref: '#/components/schemas/type_notifications:AuditUpdateAttributes'
relationships:
$ref: '#/components/schemas/type_notifications:AuditUpdateRelationships'
required:
- type
- id
- attributes
- relationships
- type: object
properties:
type:
type: string
enum:
- fileProcessingResult
description: 'Discriminator value: fileProcessingResult'
id:
type: string
description: The internal ID of the notification
attributes:
$ref: '#/components/schemas/type_files:FileMetadataAttribute'
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: NotificationDataUnion
type_notifications:NotificationMetadata:
type: object
properties:
issuerId:
type: string
issuerName:
type: string
required:
- issuerId
- issuerName
title: NotificationMetadata
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_notifications:NotificationPayload:
type: object
properties:
data:
$ref: '#/components/schemas/type_notifications:NotificationDataUnion'
meta:
$ref: '#/components/schemas/type_notifications:NotificationMetadata'
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- data
title: NotificationPayload
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Get Subscriptions
GET https://rewards-api.getkard.com/v2/issuers/{organizationId}/subscriptions
Call this endpoint to fetch the subscriptions of the provided issuer. Required scopes: `notifications:read`
Reference: https://docs.getkard.com/api/notifications/subscriptions/get
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/subscriptions:
get:
operationId: get
summary: Get Subscriptions
description: >-
Call this endpoint to fetch the subscriptions of the provided
issuer. Required scopes: `notifications:read`
tags:
- subpackage_notifications.subpackage_notifications/subscriptions
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: filter[eventName]
in: query
required: false
schema:
$ref: '#/components/schemas/type_commons:NotificationType'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_notifications/subscriptions:SubscriptionsResponseObject
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_commons:NotificationType:
type: string
enum:
- earnedRewardApproved
- earnedRewardSettled
- validTransaction
- failedTransaction
- clawback
- auditUpdate
- fileProcessingResult
title: NotificationType
type_notifications/subscriptions:SubscriptionAttributes:
type: object
properties:
eventName:
$ref: '#/components/schemas/type_commons:NotificationType'
description: The name of the event
webhookUrl:
type: string
description: The URL to which notifications will be sent
enabled:
type: boolean
description: Indicates whether the subscription is active
required:
- eventName
- webhookUrl
- enabled
title: SubscriptionAttributes
type_notifications/subscriptions:SubscriptionUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- subscription
description: 'Discriminator value: subscription'
id:
type: string
description: The ID of the subscription
attributes:
$ref: >-
#/components/schemas/type_notifications/subscriptions:SubscriptionAttributes
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: SubscriptionUnion
type_notifications/subscriptions:SubscriptionsResponseObject:
type: object
properties:
data:
type: array
items:
$ref: >-
#/components/schemas/type_notifications/subscriptions:SubscriptionUnion
required:
- data
title: SubscriptionsResponseObject
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions"
headers = {"Authorization": "Bearer "}
response = requests.get(url, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions';
const options = {method: 'GET', headers: {Authorization: 'Bearer '}};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer ")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer '
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.get("https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions")
.header("Authorization", "Bearer ")
.asString();
```
```php
request('GET', 'https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions', [
'headers' => [
'Authorization' => 'Bearer ',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer ");
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = ["Authorization": "Bearer "]
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Create Subscription
POST https://rewards-api.getkard.com/v2/issuers/{organizationId}/subscriptions
Content-Type: application/json
Call this endpoint to subscribe to notification events. Required scopes: `notifications:write`
Reference: https://docs.getkard.com/api/notifications/subscriptions/create
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/subscriptions:
post:
operationId: create
summary: Create Subscription
description: |-
Call this endpoint to subscribe to notification events. Required scopes: `notifications:write`
tags:
- subpackage_notifications.subpackage_notifications/subscriptions
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'201':
description: Response with status 201
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_notifications/subscriptions:CreateSubscriptionsResponseObject
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'409':
description: Error response with status 409
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_notifications/subscriptions:SubscriptionRequestBody
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_commons:NotificationType:
type: string
enum:
- earnedRewardApproved
- earnedRewardSettled
- validTransaction
- failedTransaction
- clawback
- auditUpdate
- fileProcessingResult
title: NotificationType
type_notifications/subscriptions:SubscriptionRequestAttributes:
type: object
properties:
eventName:
$ref: '#/components/schemas/type_commons:NotificationType'
description: The name of the event for the subscription
webhookUrl:
type: string
description: The URL where notifications will be delivered
enabled:
type: boolean
description: Indicates whether the subscription is active
required:
- eventName
- webhookUrl
- enabled
title: SubscriptionRequestAttributes
type_notifications/subscriptions:SubscriptionRequestUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- subscription
description: 'Discriminator value: subscription'
attributes:
$ref: >-
#/components/schemas/type_notifications/subscriptions:SubscriptionRequestAttributes
required:
- type
- attributes
discriminator:
propertyName: type
title: SubscriptionRequestUnion
type_notifications/subscriptions:SubscriptionRequestBody:
type: object
properties:
data:
type: array
items:
$ref: >-
#/components/schemas/type_notifications/subscriptions:SubscriptionRequestUnion
required:
- data
title: SubscriptionRequestBody
type_notifications/subscriptions:CreateSubscriptionUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- subscription
description: 'Discriminator value: subscription'
attributes:
$ref: >-
#/components/schemas/type_notifications/subscriptions:SubscriptionRequestAttributes
id:
type: string
description: The ID of the subscription
required:
- type
- attributes
- id
discriminator:
propertyName: type
title: CreateSubscriptionUnion
type_notifications/subscriptions:CreateSubscriptionsResponseObject:
type: object
properties:
data:
type: array
items:
$ref: >-
#/components/schemas/type_notifications/subscriptions:CreateSubscriptionUnion
required:
- data
title: CreateSubscriptionsResponseObject
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions"
payload = { "data": [
{
"type": "subscription",
"attributes": {
"eventName": "earnedRewardApproved",
"webhookUrl": "https://webhookUrl.com/post",
"enabled": True
}
}
] }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":[{"type":"subscription","attributes":{"eventName":"earnedRewardApproved","webhookUrl":"https://webhookUrl.com/post","enabled":true}}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions"
payload := strings.NewReader("{\n \"data\": [\n {\n \"type\": \"subscription\",\n \"attributes\": {\n \"eventName\": \"earnedRewardApproved\",\n \"webhookUrl\": \"https://webhookUrl.com/post\",\n \"enabled\": true\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": [\n {\n \"type\": \"subscription\",\n \"attributes\": {\n \"eventName\": \"earnedRewardApproved\",\n \"webhookUrl\": \"https://webhookUrl.com/post\",\n \"enabled\": true\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": [\n {\n \"type\": \"subscription\",\n \"attributes\": {\n \"eventName\": \"earnedRewardApproved\",\n \"webhookUrl\": \"https://webhookUrl.com/post\",\n \"enabled\": true\n }\n }\n ]\n}")
.asString();
```
```php
request('POST', 'https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions', [
'body' => '{
"data": [
{
"type": "subscription",
"attributes": {
"eventName": "earnedRewardApproved",
"webhookUrl": "https://webhookUrl.com/post",
"enabled": true
}
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": [\n {\n \"type\": \"subscription\",\n \"attributes\": {\n \"eventName\": \"earnedRewardApproved\",\n \"webhookUrl\": \"https://webhookUrl.com/post\",\n \"enabled\": true\n }\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
[
"type": "subscription",
"attributes": [
"eventName": "earnedRewardApproved",
"webhookUrl": "https://webhookUrl.com/post",
"enabled": true
]
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Update Subscription
PATCH https://rewards-api.getkard.com/v2/issuers/{organizationId}/subscriptions/{subscriptionId}
Content-Type: application/json
Call this endpoint to update existing notification subscriptions. Required scopes: `notifications:write`
Reference: https://docs.getkard.com/api/notifications/subscriptions/update
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/subscriptions/{subscriptionId}:
patch:
operationId: update
summary: Update Subscription
description: |-
Call this endpoint to update existing notification subscriptions. Required scopes: `notifications:write`
tags:
- subpackage_notifications.subpackage_notifications/subscriptions
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: subscriptionId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:SubscriptionId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_notifications/subscriptions:UpdateSubscriptionsResponseObject
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_notifications/subscriptions:UpdateSubscriptionRequestBody
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_commons:SubscriptionId:
type: string
description: The ID of the subscription
title: SubscriptionId
type_commons:NotificationType:
type: string
enum:
- earnedRewardApproved
- earnedRewardSettled
- validTransaction
- failedTransaction
- clawback
- auditUpdate
- fileProcessingResult
title: NotificationType
type_notifications/subscriptions:UpdateSubscriptionRequestAttributes:
type: object
properties:
eventName:
$ref: '#/components/schemas/type_commons:NotificationType'
description: The name of the event for the subscription
webhookUrl:
type: string
description: The URL where notifications will be delivered
enabled:
type: boolean
description: Indicates whether the subscription is active
title: UpdateSubscriptionRequestAttributes
type_notifications/subscriptions:UpdateSubscriptionRequestUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- subscription
description: 'Discriminator value: subscription'
attributes:
$ref: >-
#/components/schemas/type_notifications/subscriptions:UpdateSubscriptionRequestAttributes
required:
- type
- attributes
discriminator:
propertyName: type
title: UpdateSubscriptionRequestUnion
type_notifications/subscriptions:UpdateSubscriptionRequestBody:
type: object
properties:
data:
$ref: >-
#/components/schemas/type_notifications/subscriptions:UpdateSubscriptionRequestUnion
required:
- data
title: UpdateSubscriptionRequestBody
type_notifications/subscriptions:SubscriptionRequestAttributes:
type: object
properties:
eventName:
$ref: '#/components/schemas/type_commons:NotificationType'
description: The name of the event for the subscription
webhookUrl:
type: string
description: The URL where notifications will be delivered
enabled:
type: boolean
description: Indicates whether the subscription is active
required:
- eventName
- webhookUrl
- enabled
title: SubscriptionRequestAttributes
type_notifications/subscriptions:CreateSubscriptionUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- subscription
description: 'Discriminator value: subscription'
attributes:
$ref: >-
#/components/schemas/type_notifications/subscriptions:SubscriptionRequestAttributes
id:
type: string
description: The ID of the subscription
required:
- type
- attributes
- id
discriminator:
propertyName: type
title: CreateSubscriptionUnion
type_notifications/subscriptions:UpdateSubscriptionsResponseObject:
type: object
properties:
data:
$ref: >-
#/components/schemas/type_notifications/subscriptions:CreateSubscriptionUnion
required:
- data
title: UpdateSubscriptionsResponseObject
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions/subscription-123"
payload = { "data": {
"type": "subscription",
"attributes": {
"eventName": "earnedRewardApproved",
"webhookUrl": "https://webhookUrl.com/post",
"enabled": True
}
} }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions/subscription-123';
const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":{"type":"subscription","attributes":{"eventName":"earnedRewardApproved","webhookUrl":"https://webhookUrl.com/post","enabled":true}}}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions/subscription-123"
payload := strings.NewReader("{\n \"data\": {\n \"type\": \"subscription\",\n \"attributes\": {\n \"eventName\": \"earnedRewardApproved\",\n \"webhookUrl\": \"https://webhookUrl.com/post\",\n \"enabled\": true\n }\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions/subscription-123")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"type\": \"subscription\",\n \"attributes\": {\n \"eventName\": \"earnedRewardApproved\",\n \"webhookUrl\": \"https://webhookUrl.com/post\",\n \"enabled\": true\n }\n }\n}"
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.patch("https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions/subscription-123")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"type\": \"subscription\",\n \"attributes\": {\n \"eventName\": \"earnedRewardApproved\",\n \"webhookUrl\": \"https://webhookUrl.com/post\",\n \"enabled\": true\n }\n }\n}")
.asString();
```
```php
request('PATCH', 'https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions/subscription-123', [
'body' => '{
"data": {
"type": "subscription",
"attributes": {
"eventName": "earnedRewardApproved",
"webhookUrl": "https://webhookUrl.com/post",
"enabled": true
}
}
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions/subscription-123");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": {\n \"type\": \"subscription\",\n \"attributes\": {\n \"eventName\": \"earnedRewardApproved\",\n \"webhookUrl\": \"https://webhookUrl.com/post\",\n \"enabled\": true\n }\n }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
"type": "subscription",
"attributes": [
"eventName": "earnedRewardApproved",
"webhookUrl": "https://webhookUrl.com/post",
"enabled": true
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/subscriptions/subscription-123")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Create Attribution Events
POST https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/attributions
Content-Type: application/json
Call this endpoint to send attribution events made by a single enrolled user for processing. A maximum of 100 events can be included in a single request.
Required scopes: `attributions:write`
Reference: https://docs.getkard.com/api/attributions/create
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/users/{userId}/attributions:
post:
operationId: create
summary: Create Attribution Events
description: >-
Call this endpoint to send attribution events made by a single enrolled
user for processing. A maximum of 100 events can be included in a single
request.
Required scopes: `attributions:write`
tags:
- subpackage_users.subpackage_users/attributions
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: userId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:UserId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'202':
description: Response with status 202
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_users/attributions:CreateAttributionResponse
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_users/attributions:CreateAttributionRequestObject
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_commons:UserId:
type: string
description: The ID of the user as defined on the issuers system
title: UserId
type_users/attributions:EventCode:
type: string
enum:
- IMPRESSION
- VIEW
- ACTIVATE
- BOOST
description: The event code of attribution event.
title: EventCode
type_users/attributions:OfferMedium:
type: string
enum:
- BROWSE
- EMAIL
- MAP
- SEARCH
- CTA
description: >-
Where the offer attribution event is taking place in your rewards
experience.
title: OfferMedium
type_users/attributions:AttributionFilter:
type: object
properties:
name:
type: string
value:
type: string
required:
- name
- value
title: AttributionFilter
type_users/attributions:AttributionState:
type: object
properties:
rank:
type: integer
description: The position of the offer in the list shown to the user (1-indexed)
filters:
type: array
items:
$ref: '#/components/schemas/type_users/attributions:AttributionFilter'
description: The active filters when the user saw the offer
title: AttributionState
type_users/attributions:OfferAttributionAttributes:
type: object
properties:
entityId:
type: string
description: The offer ID
eventCode:
$ref: '#/components/schemas/type_users/attributions:EventCode'
medium:
$ref: '#/components/schemas/type_users/attributions:OfferMedium'
eventDate:
type: string
format: date-time
description: |-
The timestamp of the attribution event.
Must be in ISO 8601 format (e.g., "2025-01-01T00:00:00Z").
state:
$ref: '#/components/schemas/type_users/attributions:AttributionState'
description: Placement context for the attribution event
required:
- entityId
- eventCode
- medium
- eventDate
title: OfferAttributionAttributes
type_users/attributions:NotificationMedium:
type: string
enum:
- PUSH
description: >-
Where the notification attribution event is taking place in your rewards
experience.
title: NotificationMedium
type_users/attributions:NotificationAttributionAttributes:
type: object
properties:
entityId:
type: string
description: The notification ID
eventCode:
$ref: '#/components/schemas/type_users/attributions:EventCode'
medium:
$ref: '#/components/schemas/type_users/attributions:NotificationMedium'
eventDate:
type: string
format: date-time
description: |-
The timestamp of the attribution event.
Must be in ISO 8601 format (e.g., "2025-01-01T00:00:00Z").
state:
$ref: '#/components/schemas/type_users/attributions:AttributionState'
description: Placement context for the attribution event
required:
- entityId
- eventCode
- medium
- eventDate
title: NotificationAttributionAttributes
type_users/attributions:CreateAttributionRequestUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- offerAttribution
description: 'Discriminator value: offerAttribution'
attributes:
$ref: >-
#/components/schemas/type_users/attributions:OfferAttributionAttributes
required:
- type
- attributes
- type: object
properties:
type:
type: string
enum:
- notificationAttribution
description: 'Discriminator value: notificationAttribution'
attributes:
$ref: >-
#/components/schemas/type_users/attributions:NotificationAttributionAttributes
required:
- type
- attributes
discriminator:
propertyName: type
title: CreateAttributionRequestUnion
type_users/attributions:CreateAttributionRequestObject:
type: object
properties:
data:
type: array
items:
$ref: >-
#/components/schemas/type_users/attributions:CreateAttributionRequestUnion
description: >-
Discriminated union representing the request body for submitting
attribution events.
Use `type` to distinguish between the two:
- `offerAttribution`: Events related to viewing or interacting with
an offer.
- `notificationAttribution`: Events related to viewing or
interacting with a notification.
required:
- data
title: CreateAttributionRequestObject
type_commons:ResourceType:
type: string
description: Type of document returned
title: ResourceType
type_commons:JobStatus:
type: string
enum:
- queued
description: Status of the job
title: JobStatus
type_commons:Job:
type: object
properties:
status:
$ref: '#/components/schemas/type_commons:JobStatus'
message:
type: string
description: Message regarding the status of the job request
required:
- status
- message
title: Job
type_commons:JobResponse:
type: object
properties:
type:
$ref: '#/components/schemas/type_commons:ResourceType'
id:
type: string
description: The request id of the pending job
attributes:
$ref: '#/components/schemas/type_commons:Job'
required:
- type
- id
- attributes
title: JobResponse
type_users/attributions:CreateAttributionResponse:
type: object
properties:
data:
$ref: '#/components/schemas/type_commons:JobResponse'
required:
- data
title: CreateAttributionResponse
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/attributions"
payload = { "data": [
{
"type": "offerAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144c075",
"eventCode": "VIEW",
"medium": "SEARCH",
"eventDate": "2025-01-01T00:00:00Z"
}
},
{
"type": "offerAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144c077",
"eventCode": "IMPRESSION",
"medium": "EMAIL",
"eventDate": "2025-01-01T00:00:00Z"
}
},
{
"type": "notificationAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144c076",
"eventCode": "IMPRESSION",
"medium": "PUSH",
"eventDate": "2025-01-01T00:00:00Z"
}
}
] }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/attributions';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":[{"type":"offerAttribution","attributes":{"entityId":"60e4ba1da31c5a22a144c075","eventCode":"VIEW","medium":"SEARCH","eventDate":"2025-01-01T00:00:00Z"}},{"type":"offerAttribution","attributes":{"entityId":"60e4ba1da31c5a22a144c077","eventCode":"IMPRESSION","medium":"EMAIL","eventDate":"2025-01-01T00:00:00Z"}},{"type":"notificationAttribution","attributes":{"entityId":"60e4ba1da31c5a22a144c076","eventCode":"IMPRESSION","medium":"PUSH","eventDate":"2025-01-01T00:00:00Z"}}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/attributions"
payload := strings.NewReader("{\n \"data\": [\n {\n \"type\": \"offerAttribution\",\n \"attributes\": {\n \"entityId\": \"60e4ba1da31c5a22a144c075\",\n \"eventCode\": \"VIEW\",\n \"medium\": \"SEARCH\",\n \"eventDate\": \"2025-01-01T00:00:00Z\"\n }\n },\n {\n \"type\": \"offerAttribution\",\n \"attributes\": {\n \"entityId\": \"60e4ba1da31c5a22a144c077\",\n \"eventCode\": \"IMPRESSION\",\n \"medium\": \"EMAIL\",\n \"eventDate\": \"2025-01-01T00:00:00Z\"\n }\n },\n {\n \"type\": \"notificationAttribution\",\n \"attributes\": {\n \"entityId\": \"60e4ba1da31c5a22a144c076\",\n \"eventCode\": \"IMPRESSION\",\n \"medium\": \"PUSH\",\n \"eventDate\": \"2025-01-01T00:00:00Z\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/attributions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": [\n {\n \"type\": \"offerAttribution\",\n \"attributes\": {\n \"entityId\": \"60e4ba1da31c5a22a144c075\",\n \"eventCode\": \"VIEW\",\n \"medium\": \"SEARCH\",\n \"eventDate\": \"2025-01-01T00:00:00Z\"\n }\n },\n {\n \"type\": \"offerAttribution\",\n \"attributes\": {\n \"entityId\": \"60e4ba1da31c5a22a144c077\",\n \"eventCode\": \"IMPRESSION\",\n \"medium\": \"EMAIL\",\n \"eventDate\": \"2025-01-01T00:00:00Z\"\n }\n },\n {\n \"type\": \"notificationAttribution\",\n \"attributes\": {\n \"entityId\": \"60e4ba1da31c5a22a144c076\",\n \"eventCode\": \"IMPRESSION\",\n \"medium\": \"PUSH\",\n \"eventDate\": \"2025-01-01T00:00:00Z\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/attributions")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": [\n {\n \"type\": \"offerAttribution\",\n \"attributes\": {\n \"entityId\": \"60e4ba1da31c5a22a144c075\",\n \"eventCode\": \"VIEW\",\n \"medium\": \"SEARCH\",\n \"eventDate\": \"2025-01-01T00:00:00Z\"\n }\n },\n {\n \"type\": \"offerAttribution\",\n \"attributes\": {\n \"entityId\": \"60e4ba1da31c5a22a144c077\",\n \"eventCode\": \"IMPRESSION\",\n \"medium\": \"EMAIL\",\n \"eventDate\": \"2025-01-01T00:00:00Z\"\n }\n },\n {\n \"type\": \"notificationAttribution\",\n \"attributes\": {\n \"entityId\": \"60e4ba1da31c5a22a144c076\",\n \"eventCode\": \"IMPRESSION\",\n \"medium\": \"PUSH\",\n \"eventDate\": \"2025-01-01T00:00:00Z\"\n }\n }\n ]\n}")
.asString();
```
```php
request('POST', 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/attributions', [
'body' => '{
"data": [
{
"type": "offerAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144c075",
"eventCode": "VIEW",
"medium": "SEARCH",
"eventDate": "2025-01-01T00:00:00Z"
}
},
{
"type": "offerAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144c077",
"eventCode": "IMPRESSION",
"medium": "EMAIL",
"eventDate": "2025-01-01T00:00:00Z"
}
},
{
"type": "notificationAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144c076",
"eventCode": "IMPRESSION",
"medium": "PUSH",
"eventDate": "2025-01-01T00:00:00Z"
}
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/attributions");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": [\n {\n \"type\": \"offerAttribution\",\n \"attributes\": {\n \"entityId\": \"60e4ba1da31c5a22a144c075\",\n \"eventCode\": \"VIEW\",\n \"medium\": \"SEARCH\",\n \"eventDate\": \"2025-01-01T00:00:00Z\"\n }\n },\n {\n \"type\": \"offerAttribution\",\n \"attributes\": {\n \"entityId\": \"60e4ba1da31c5a22a144c077\",\n \"eventCode\": \"IMPRESSION\",\n \"medium\": \"EMAIL\",\n \"eventDate\": \"2025-01-01T00:00:00Z\"\n }\n },\n {\n \"type\": \"notificationAttribution\",\n \"attributes\": {\n \"entityId\": \"60e4ba1da31c5a22a144c076\",\n \"eventCode\": \"IMPRESSION\",\n \"medium\": \"PUSH\",\n \"eventDate\": \"2025-01-01T00:00:00Z\"\n }\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
[
"type": "offerAttribution",
"attributes": [
"entityId": "60e4ba1da31c5a22a144c075",
"eventCode": "VIEW",
"medium": "SEARCH",
"eventDate": "2025-01-01T00:00:00Z"
]
],
[
"type": "offerAttribution",
"attributes": [
"entityId": "60e4ba1da31c5a22a144c077",
"eventCode": "IMPRESSION",
"medium": "EMAIL",
"eventDate": "2025-01-01T00:00:00Z"
]
],
[
"type": "notificationAttribution",
"attributes": [
"entityId": "60e4ba1da31c5a22a144c076",
"eventCode": "IMPRESSION",
"medium": "PUSH",
"eventDate": "2025-01-01T00:00:00Z"
]
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/attributions")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Activate Offer
POST https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/offers/{offerId}/activate
Record when a user activates an offer. Creates an attribution event with eventCode=ACTIVATE and medium=CTA.
Optionally include the offer data by passing `include=offer`.
Reference: https://docs.getkard.com/api/attributions/activate
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/users/{userId}/offers/{offerId}/activate:
post:
operationId: activate
summary: Activate Offer
description: >-
Record when a user activates an offer. Creates an attribution event with
eventCode=ACTIVATE and medium=CTA.
Optionally include the offer data by passing `include=offer`.
tags:
- subpackage_users.subpackage_users/attributions
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: userId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:UserId'
- name: offerId
in: path
description: The unique identifier of the offer being activated
required: true
schema:
type: string
- name: supportedComponents
in: query
description: >-
UI component types to include in the offer response (when
include=offer).
required: false
schema:
$ref: '#/components/schemas/type_users/rewards:ComponentType'
- name: include
in: query
description: >-
Related resources to include in the response. Allowed value is
`offer`.
required: false
schema:
$ref: >-
#/components/schemas/type_users/attributions:ActivateOfferIncludeOption
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'201':
description: Response with status 201
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_users/attributions:ActivateOfferResponse
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_commons:UserId:
type: string
description: The ID of the user as defined on the issuers system
title: UserId
type_users/rewards:ComponentType:
type: string
enum:
- shortDescription
- longDescription
- baseReward
- boostedReward
- cta
- tags
- detailTags
- logoFlare
- progressBar
description: Available UI component types for offers
title: ComponentType
type_users/attributions:ActivateOfferIncludeOption:
type: string
enum:
- offer
description: Options for what to include in the activate offer response
title: ActivateOfferIncludeOption
type_users/attributions:ActivateOfferResponseAttributes:
type: object
properties:
entityId:
type: string
eventCode:
type: string
medium:
type: string
eventDate:
type: string
format: date-time
required:
- entityId
- eventCode
- medium
- eventDate
title: ActivateOfferResponseAttributes
type_users/attributions:ActivateOfferResponseData:
type: object
properties:
type:
type: string
id:
type: string
attributes:
$ref: >-
#/components/schemas/type_users/attributions:ActivateOfferResponseAttributes
required:
- type
- id
- attributes
title: ActivateOfferResponseData
type_commons:MongoId:
type: string
description: The unique identifier for a document in the database
title: MongoId
type_commons:PurchaseChannel:
type: string
enum:
- INSTORE
- ONLINE
description: Purchase channel of offer
title: PurchaseChannel
type_commons:CommissionType:
type: string
enum:
- FLAT
- PERCENT
description: Type of commission on offer (% or a flat $)
title: CommissionType
type_users/rewards:Commission:
type: object
properties:
type:
$ref: '#/components/schemas/type_commons:CommissionType'
value:
type: number
format: double
required:
- type
- value
title: Commission
type_users/rewards:Asset:
type: object
properties:
type:
type: string
url:
type: string
description: URL of the asset containing an attribution token
alt:
type: string
description: Alt text of the asset
required:
- type
- url
- alt
title: Asset
type_users/rewards:AmountType:
type: string
enum:
- CENTS
title: AmountType
type_users/rewards:Amount:
type: object
properties:
type:
$ref: '#/components/schemas/type_users/rewards:AmountType'
value:
type: integer
required:
- type
- value
title: Amount
type_users/rewards:ButtonStyle:
type: string
enum:
- PRIMARY
- SECONDARY
- DISABLED
description: Available button styles for CTA components
title: ButtonStyle
type_users/rewards:CtaAction:
type: object
properties:
url:
type: string
description: URL endpoint to call when button is clicked
method:
type: string
description: HTTP method to use (e.g., POST)
required:
- url
- method
description: Action configuration for CTA button
title: CtaAction
type_users/rewards:CtaComponent:
type: object
properties:
buttonText:
type: string
description: Text to display on the button
buttonStyle:
$ref: '#/components/schemas/type_users/rewards:ButtonStyle'
description: Style of the button
action:
$ref: '#/components/schemas/type_users/rewards:CtaAction'
description: Action to perform when the button is clicked
startIcon:
type: string
description: Icon identifier to display on the button
required:
- buttonText
- buttonStyle
description: Call-to-action button component for offers
title: CtaComponent
type_users/rewards:LogoFlareBorderColor:
type: string
enum:
- PRIMARY
- SECONDARY
description: Available border color options for logo flare
title: LogoFlareBorderColor
type_users/rewards:LogoFlareBadgePosition:
type: string
enum:
- TOP_RIGHT
- TOP_LEFT
- BOTTOM_RIGHT
- BOTTOM_LEFT
description: Available positions for the logo flare badge
title: LogoFlareBadgePosition
type_users/rewards:LogoFlareBadge:
type: object
properties:
icon:
type: string
description: Icon identifier for the badge
position:
$ref: '#/components/schemas/type_users/rewards:LogoFlareBadgePosition'
description: Position of the badge on the logo
required:
- icon
- position
description: Badge configuration for logo flare
title: LogoFlareBadge
type_users/rewards:LogoFlare:
type: object
properties:
borderColor:
$ref: '#/components/schemas/type_users/rewards:LogoFlareBorderColor'
description: Border color style for the logo flare
badge:
$ref: '#/components/schemas/type_users/rewards:LogoFlareBadge'
description: Optional badge to display on the logo
required:
- borderColor
description: Logo flare configuration for offer display
title: LogoFlare
type_users/rewards:ProgressBarSegmentPosition:
type: string
enum:
- LEFT
- RIGHT
- FULL_WIDTH
description: Supported segment positions
title: ProgressBarSegmentPosition
type_users/rewards:ProgressBarSegment:
type: object
properties:
icon:
type: string
description: SVG icon to use for each segment
position:
$ref: '#/components/schemas/type_users/rewards:ProgressBarSegmentPosition'
description: Position of the segment within the layout
required:
- position
description: Segment configuration for a specific layout
title: ProgressBarSegment
type_users/rewards:ProgressBarSegments:
type: object
properties:
details:
$ref: '#/components/schemas/type_users/rewards:ProgressBarSegment'
description: Segment configuration for the details view
default:
$ref: '#/components/schemas/type_users/rewards:ProgressBarSegment'
description: Segment configuration for the default view
required:
- default
description: Segment configuration for the progress bar in different layouts
title: ProgressBarSegments
type_users/rewards:ProgressBarLabelPair:
type: object
properties:
left:
type: string
description: Text content for the left label
right:
type: string
description: Text content for the right label
description: Left and right label configuration for a specific layout
title: ProgressBarLabelPair
type_users/rewards:ProgressBarLabels:
type: object
properties:
details:
$ref: '#/components/schemas/type_users/rewards:ProgressBarLabelPair'
description: Label configuration for the details view
default:
$ref: '#/components/schemas/type_users/rewards:ProgressBarLabelPair'
description: Label configuration for the default view
required:
- default
description: Labels to render around the progress bar in different layouts
title: ProgressBarLabels
type_users/rewards:ProgressBar:
type: object
properties:
total:
type: integer
description: Total number of redemptions allowed
currentProgress:
type: integer
description: Number of redemptions the user has completed
label:
type: string
description: Formatted label for the progress bar
segmented:
type: boolean
description: Whether the progress bar should be displayed as segmented
segments:
$ref: '#/components/schemas/type_users/rewards:ProgressBarSegments'
description: Segment configuration for the progress bar in different layouts
labels:
$ref: '#/components/schemas/type_users/rewards:ProgressBarLabels'
description: Labels to render around the progress bar in different layouts
required:
- total
- currentProgress
- label
- segmented
- labels
description: Progress bar component for tracking offer redemption progress
title: ProgressBar
type_users/rewards:OfferComponents:
type: object
properties:
shortDescription:
type: string
description: Short description for the offer
longDescription:
type: string
description: Long description for the offer
baseReward:
type: string
description: Formatted reward string
boostedReward:
type: string
description: Formatted boosted reward string
cta:
$ref: '#/components/schemas/type_users/rewards:CtaComponent'
description: Call-to-action button component
tags:
type: array
items:
type: string
description: Tags for the offer
detailTags:
type: array
items:
type: string
description: Detail tags for the offer
logoFlare:
$ref: '#/components/schemas/type_users/rewards:LogoFlare'
description: Logo flare configuration for the offer
progressBar:
$ref: '#/components/schemas/type_users/rewards:ProgressBar'
description: Progress bar component for tracking offer redemptions
description: UI component data for rendering offer details
title: OfferComponents
type_users/rewards:StandardOfferFields:
type: object
properties:
terms:
type: string
description: Terms and conditions on offer
maxRedemptions:
type: integer
description: Maximum times cardholder can redeem offer, if applicable
name:
type: string
description: Name of offer
purchaseChannel:
type: array
items:
$ref: '#/components/schemas/type_commons:PurchaseChannel'
userReward:
$ref: '#/components/schemas/type_users/rewards:Commission'
assets:
type: array
items:
$ref: '#/components/schemas/type_users/rewards:Asset'
description: Assets associated with offer
startDate:
type: string
format: date-time
description: Beginning date of offer (UTC)
expirationDate:
type: string
format: date-time
description: Expiration date of offer if applicable (UTC)
isTargeted:
type: boolean
description: >-
True returns only targeted offers, false returns only non-targeted
offers
minTransactionAmount:
$ref: '#/components/schemas/type_users/rewards:Amount'
description: >-
Minimum Transaction Amount required to redeem offer, if available on
offer
maxTransactionAmount:
$ref: '#/components/schemas/type_users/rewards:Amount'
description: >-
Maximum Transaction Amount allowed to redeem offer, if available on
offer
minRewardAmount:
$ref: '#/components/schemas/type_users/rewards:Amount'
description: Minimum Reward Amount, if available on offer
maxRewardAmount:
$ref: '#/components/schemas/type_users/rewards:Amount'
description: Maximum Reward Amount, if available on offer
websiteUrl:
type: string
description: URL to the website of the offer provider
description:
type: string
description: Description of the offer
components:
$ref: '#/components/schemas/type_users/rewards:OfferComponents'
description: >-
UI component data for the offer, returned when supportedComponents
query parameter is provided
required:
- terms
- name
- purchaseChannel
- userReward
- assets
- startDate
- expirationDate
- isTargeted
title: StandardOfferFields
type_users/rewards:CategoryData:
type: object
properties:
id:
type: string
description: id of the category
type:
type: string
enum:
- category
required:
- id
- type
title: CategoryData
type_users/rewards:CategoryRelationship:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_users/rewards:CategoryData'
required:
- data
title: CategoryRelationship
type_users/rewards:CategoryRelationshipObject:
type: object
properties:
category:
$ref: '#/components/schemas/type_users/rewards:CategoryRelationship'
required:
- category
title: CategoryRelationshipObject
type_users/rewards:EligibilityOfferRelationship:
oneOf:
- $ref: '#/components/schemas/type_users/rewards:CategoryRelationshipObject'
title: EligibilityOfferRelationship
type_users/rewards:OfferDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- standardOffer
description: 'Discriminator value: standardOffer'
id:
$ref: '#/components/schemas/type_commons:MongoId'
description: Offer ID in Kard's system
attributes:
$ref: '#/components/schemas/type_users/rewards:StandardOfferFields'
relationships:
$ref: >-
#/components/schemas/type_users/rewards:EligibilityOfferRelationship
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: OfferDataUnion
type_commons:CategoryOption:
type: string
enum:
- Arts & Entertainment
- Baby, Kids & Toys
- Books & Digital Media
- Clothing, Shoes & Accessories
- Computers, Electronics & Software
- Convenience
- Gas
- Department Stores
- Food & Beverage
- Health & Beauty
- Home & Garden
- Miscellaneous
- Occasions & Gifts
- Pets
- Sports & Outdoors
- Supplies & Services
- Travel
description: >-
Category of merchant. Please use URL Encode for non single word
categories. (Food & Beverage should be Food%20%26%20Beverage)
title: CategoryOption
type_users/rewards:CategoryFields:
type: object
properties:
name:
$ref: '#/components/schemas/type_commons:CategoryOption'
description: Name of the category
required:
- name
title: CategoryFields
type_users/rewards:CategoryIncluded:
type: object
properties:
id:
type: string
description: id of the category
type:
type: string
enum:
- category
attributes:
$ref: '#/components/schemas/type_users/rewards:CategoryFields'
required:
- id
- type
- attributes
title: CategoryIncluded
type_users/attributions:ActivateOfferIncluded:
oneOf:
- $ref: '#/components/schemas/type_users/rewards:OfferDataUnion'
- $ref: '#/components/schemas/type_users/rewards:CategoryIncluded'
title: ActivateOfferIncluded
type_users/attributions:ActivateOfferResponse:
type: object
properties:
data:
$ref: >-
#/components/schemas/type_users/attributions:ActivateOfferResponseData
included:
type: array
items:
$ref: '#/components/schemas/type_users/attributions:ActivateOfferIncluded'
required:
- data
title: ActivateOfferResponse
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers/offer-456/activate"
headers = {"Authorization": "Bearer "}
response = requests.post(url, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers/offer-456/activate';
const options = {method: 'POST', headers: {Authorization: 'Bearer '}};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers/offer-456/activate"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "Bearer ")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers/offer-456/activate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers/offer-456/activate")
.header("Authorization", "Bearer ")
.asString();
```
```php
request('POST', 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers/offer-456/activate', [
'headers' => [
'Authorization' => 'Bearer ',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers/offer-456/activate");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = ["Authorization": "Bearer "]
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers/offer-456/activate")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Boost Offer
POST https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/offers/{offerId}/boost
Record when a user boosts an offer. Creates an attribution event with eventCode=BOOST and medium=CTA.
Optionally include the offer data by passing `include=offer`.
Reference: https://docs.getkard.com/api/attributions/boost
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/users/{userId}/offers/{offerId}/boost:
post:
operationId: boost
summary: Boost Offer
description: >-
Record when a user boosts an offer. Creates an attribution event with
eventCode=BOOST and medium=CTA.
Optionally include the offer data by passing `include=offer`.
tags:
- subpackage_users.subpackage_users/attributions
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: userId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:UserId'
- name: offerId
in: path
description: The unique identifier of the offer being boosted
required: true
schema:
type: string
- name: supportedComponents
in: query
description: >-
UI component types to include in the offer response (when
include=offer).
required: false
schema:
$ref: '#/components/schemas/type_users/rewards:ComponentType'
- name: include
in: query
description: >-
Related resources to include in the response. Allowed value is
`offer`.
required: false
schema:
$ref: >-
#/components/schemas/type_users/attributions:BoostOfferIncludeOption
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'201':
description: Response with status 201
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_users/attributions:BoostOfferResponse
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_commons:UserId:
type: string
description: The ID of the user as defined on the issuers system
title: UserId
type_users/rewards:ComponentType:
type: string
enum:
- shortDescription
- longDescription
- baseReward
- boostedReward
- cta
- tags
- detailTags
- logoFlare
- progressBar
description: Available UI component types for offers
title: ComponentType
type_users/attributions:BoostOfferIncludeOption:
type: string
enum:
- offer
description: Options for what to include in the boost offer response
title: BoostOfferIncludeOption
type_users/attributions:BoostOfferResponseAttributes:
type: object
properties:
entityId:
type: string
eventCode:
type: string
medium:
type: string
eventDate:
type: string
format: date-time
required:
- entityId
- eventCode
- medium
- eventDate
title: BoostOfferResponseAttributes
type_users/attributions:BoostOfferResponseData:
type: object
properties:
type:
type: string
id:
type: string
attributes:
$ref: >-
#/components/schemas/type_users/attributions:BoostOfferResponseAttributes
required:
- type
- id
- attributes
title: BoostOfferResponseData
type_commons:MongoId:
type: string
description: The unique identifier for a document in the database
title: MongoId
type_commons:PurchaseChannel:
type: string
enum:
- INSTORE
- ONLINE
description: Purchase channel of offer
title: PurchaseChannel
type_commons:CommissionType:
type: string
enum:
- FLAT
- PERCENT
description: Type of commission on offer (% or a flat $)
title: CommissionType
type_users/rewards:Commission:
type: object
properties:
type:
$ref: '#/components/schemas/type_commons:CommissionType'
value:
type: number
format: double
required:
- type
- value
title: Commission
type_users/rewards:Asset:
type: object
properties:
type:
type: string
url:
type: string
description: URL of the asset containing an attribution token
alt:
type: string
description: Alt text of the asset
required:
- type
- url
- alt
title: Asset
type_users/rewards:AmountType:
type: string
enum:
- CENTS
title: AmountType
type_users/rewards:Amount:
type: object
properties:
type:
$ref: '#/components/schemas/type_users/rewards:AmountType'
value:
type: integer
required:
- type
- value
title: Amount
type_users/rewards:ButtonStyle:
type: string
enum:
- PRIMARY
- SECONDARY
- DISABLED
description: Available button styles for CTA components
title: ButtonStyle
type_users/rewards:CtaAction:
type: object
properties:
url:
type: string
description: URL endpoint to call when button is clicked
method:
type: string
description: HTTP method to use (e.g., POST)
required:
- url
- method
description: Action configuration for CTA button
title: CtaAction
type_users/rewards:CtaComponent:
type: object
properties:
buttonText:
type: string
description: Text to display on the button
buttonStyle:
$ref: '#/components/schemas/type_users/rewards:ButtonStyle'
description: Style of the button
action:
$ref: '#/components/schemas/type_users/rewards:CtaAction'
description: Action to perform when the button is clicked
startIcon:
type: string
description: Icon identifier to display on the button
required:
- buttonText
- buttonStyle
description: Call-to-action button component for offers
title: CtaComponent
type_users/rewards:LogoFlareBorderColor:
type: string
enum:
- PRIMARY
- SECONDARY
description: Available border color options for logo flare
title: LogoFlareBorderColor
type_users/rewards:LogoFlareBadgePosition:
type: string
enum:
- TOP_RIGHT
- TOP_LEFT
- BOTTOM_RIGHT
- BOTTOM_LEFT
description: Available positions for the logo flare badge
title: LogoFlareBadgePosition
type_users/rewards:LogoFlareBadge:
type: object
properties:
icon:
type: string
description: Icon identifier for the badge
position:
$ref: '#/components/schemas/type_users/rewards:LogoFlareBadgePosition'
description: Position of the badge on the logo
required:
- icon
- position
description: Badge configuration for logo flare
title: LogoFlareBadge
type_users/rewards:LogoFlare:
type: object
properties:
borderColor:
$ref: '#/components/schemas/type_users/rewards:LogoFlareBorderColor'
description: Border color style for the logo flare
badge:
$ref: '#/components/schemas/type_users/rewards:LogoFlareBadge'
description: Optional badge to display on the logo
required:
- borderColor
description: Logo flare configuration for offer display
title: LogoFlare
type_users/rewards:ProgressBarSegmentPosition:
type: string
enum:
- LEFT
- RIGHT
- FULL_WIDTH
description: Supported segment positions
title: ProgressBarSegmentPosition
type_users/rewards:ProgressBarSegment:
type: object
properties:
icon:
type: string
description: SVG icon to use for each segment
position:
$ref: '#/components/schemas/type_users/rewards:ProgressBarSegmentPosition'
description: Position of the segment within the layout
required:
- position
description: Segment configuration for a specific layout
title: ProgressBarSegment
type_users/rewards:ProgressBarSegments:
type: object
properties:
details:
$ref: '#/components/schemas/type_users/rewards:ProgressBarSegment'
description: Segment configuration for the details view
default:
$ref: '#/components/schemas/type_users/rewards:ProgressBarSegment'
description: Segment configuration for the default view
required:
- default
description: Segment configuration for the progress bar in different layouts
title: ProgressBarSegments
type_users/rewards:ProgressBarLabelPair:
type: object
properties:
left:
type: string
description: Text content for the left label
right:
type: string
description: Text content for the right label
description: Left and right label configuration for a specific layout
title: ProgressBarLabelPair
type_users/rewards:ProgressBarLabels:
type: object
properties:
details:
$ref: '#/components/schemas/type_users/rewards:ProgressBarLabelPair'
description: Label configuration for the details view
default:
$ref: '#/components/schemas/type_users/rewards:ProgressBarLabelPair'
description: Label configuration for the default view
required:
- default
description: Labels to render around the progress bar in different layouts
title: ProgressBarLabels
type_users/rewards:ProgressBar:
type: object
properties:
total:
type: integer
description: Total number of redemptions allowed
currentProgress:
type: integer
description: Number of redemptions the user has completed
label:
type: string
description: Formatted label for the progress bar
segmented:
type: boolean
description: Whether the progress bar should be displayed as segmented
segments:
$ref: '#/components/schemas/type_users/rewards:ProgressBarSegments'
description: Segment configuration for the progress bar in different layouts
labels:
$ref: '#/components/schemas/type_users/rewards:ProgressBarLabels'
description: Labels to render around the progress bar in different layouts
required:
- total
- currentProgress
- label
- segmented
- labels
description: Progress bar component for tracking offer redemption progress
title: ProgressBar
type_users/rewards:OfferComponents:
type: object
properties:
shortDescription:
type: string
description: Short description for the offer
longDescription:
type: string
description: Long description for the offer
baseReward:
type: string
description: Formatted reward string
boostedReward:
type: string
description: Formatted boosted reward string
cta:
$ref: '#/components/schemas/type_users/rewards:CtaComponent'
description: Call-to-action button component
tags:
type: array
items:
type: string
description: Tags for the offer
detailTags:
type: array
items:
type: string
description: Detail tags for the offer
logoFlare:
$ref: '#/components/schemas/type_users/rewards:LogoFlare'
description: Logo flare configuration for the offer
progressBar:
$ref: '#/components/schemas/type_users/rewards:ProgressBar'
description: Progress bar component for tracking offer redemptions
description: UI component data for rendering offer details
title: OfferComponents
type_users/rewards:StandardOfferFields:
type: object
properties:
terms:
type: string
description: Terms and conditions on offer
maxRedemptions:
type: integer
description: Maximum times cardholder can redeem offer, if applicable
name:
type: string
description: Name of offer
purchaseChannel:
type: array
items:
$ref: '#/components/schemas/type_commons:PurchaseChannel'
userReward:
$ref: '#/components/schemas/type_users/rewards:Commission'
assets:
type: array
items:
$ref: '#/components/schemas/type_users/rewards:Asset'
description: Assets associated with offer
startDate:
type: string
format: date-time
description: Beginning date of offer (UTC)
expirationDate:
type: string
format: date-time
description: Expiration date of offer if applicable (UTC)
isTargeted:
type: boolean
description: >-
True returns only targeted offers, false returns only non-targeted
offers
minTransactionAmount:
$ref: '#/components/schemas/type_users/rewards:Amount'
description: >-
Minimum Transaction Amount required to redeem offer, if available on
offer
maxTransactionAmount:
$ref: '#/components/schemas/type_users/rewards:Amount'
description: >-
Maximum Transaction Amount allowed to redeem offer, if available on
offer
minRewardAmount:
$ref: '#/components/schemas/type_users/rewards:Amount'
description: Minimum Reward Amount, if available on offer
maxRewardAmount:
$ref: '#/components/schemas/type_users/rewards:Amount'
description: Maximum Reward Amount, if available on offer
websiteUrl:
type: string
description: URL to the website of the offer provider
description:
type: string
description: Description of the offer
components:
$ref: '#/components/schemas/type_users/rewards:OfferComponents'
description: >-
UI component data for the offer, returned when supportedComponents
query parameter is provided
required:
- terms
- name
- purchaseChannel
- userReward
- assets
- startDate
- expirationDate
- isTargeted
title: StandardOfferFields
type_users/rewards:CategoryData:
type: object
properties:
id:
type: string
description: id of the category
type:
type: string
enum:
- category
required:
- id
- type
title: CategoryData
type_users/rewards:CategoryRelationship:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_users/rewards:CategoryData'
required:
- data
title: CategoryRelationship
type_users/rewards:CategoryRelationshipObject:
type: object
properties:
category:
$ref: '#/components/schemas/type_users/rewards:CategoryRelationship'
required:
- category
title: CategoryRelationshipObject
type_users/rewards:EligibilityOfferRelationship:
oneOf:
- $ref: '#/components/schemas/type_users/rewards:CategoryRelationshipObject'
title: EligibilityOfferRelationship
type_users/rewards:OfferDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- standardOffer
description: 'Discriminator value: standardOffer'
id:
$ref: '#/components/schemas/type_commons:MongoId'
description: Offer ID in Kard's system
attributes:
$ref: '#/components/schemas/type_users/rewards:StandardOfferFields'
relationships:
$ref: >-
#/components/schemas/type_users/rewards:EligibilityOfferRelationship
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: OfferDataUnion
type_commons:CategoryOption:
type: string
enum:
- Arts & Entertainment
- Baby, Kids & Toys
- Books & Digital Media
- Clothing, Shoes & Accessories
- Computers, Electronics & Software
- Convenience
- Gas
- Department Stores
- Food & Beverage
- Health & Beauty
- Home & Garden
- Miscellaneous
- Occasions & Gifts
- Pets
- Sports & Outdoors
- Supplies & Services
- Travel
description: >-
Category of merchant. Please use URL Encode for non single word
categories. (Food & Beverage should be Food%20%26%20Beverage)
title: CategoryOption
type_users/rewards:CategoryFields:
type: object
properties:
name:
$ref: '#/components/schemas/type_commons:CategoryOption'
description: Name of the category
required:
- name
title: CategoryFields
type_users/rewards:CategoryIncluded:
type: object
properties:
id:
type: string
description: id of the category
type:
type: string
enum:
- category
attributes:
$ref: '#/components/schemas/type_users/rewards:CategoryFields'
required:
- id
- type
- attributes
title: CategoryIncluded
type_users/attributions:BoostOfferIncluded:
oneOf:
- $ref: '#/components/schemas/type_users/rewards:OfferDataUnion'
- $ref: '#/components/schemas/type_users/rewards:CategoryIncluded'
title: BoostOfferIncluded
type_users/attributions:BoostOfferResponse:
type: object
properties:
data:
$ref: '#/components/schemas/type_users/attributions:BoostOfferResponseData'
included:
type: array
items:
$ref: '#/components/schemas/type_users/attributions:BoostOfferIncluded'
required:
- data
title: BoostOfferResponse
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers/offer-456/boost"
headers = {"Authorization": "Bearer "}
response = requests.post(url, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers/offer-456/boost';
const options = {method: 'POST', headers: {Authorization: 'Bearer '}};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers/offer-456/boost"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "Bearer ")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers/offer-456/boost")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers/offer-456/boost")
.header("Authorization", "Bearer ")
.asString();
```
```php
request('POST', 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers/offer-456/boost', [
'headers' => [
'Authorization' => 'Bearer ',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers/offer-456/boost");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = ["Authorization": "Bearer "]
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers/offer-456/boost")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Get Files
GET https://rewards-api.getkard.com/v2/issuers/{organizationId}/files/metadata
Retrieves metadata for files associated with a specific issuer/organization.
This endpoint supports pagination and sorting options to efficiently navigate
through potentially large sets of file metadata.
Required scopes: `files.read`
Reference: https://docs.getkard.com/api/files/get-metadata
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/files/metadata:
get:
operationId: get-metadata
summary: Get Files
description: >-
Retrieves metadata for files associated with a specific
issuer/organization.
This endpoint supports pagination and sorting options to efficiently
navigate
through potentially large sets of file metadata.
Required scopes: `files.read`
tags:
- subpackage_files
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: filter[dateFrom]
in: query
description: >-
Start date for filtering files (format ISO8601). If not provided,
defaults to current date minus 1 month.
required: false
schema:
type: string
- name: filter[dateTo]
in: query
description: >-
End date for filtering files (format ISO8601). If not provided,
defaults to current date.
required: false
schema:
type: string
- name: filter[fileType]
in: query
description: The document file type.
required: false
schema:
$ref: '#/components/schemas/type_files:FileType'
- name: page[size]
in: query
description: >-
Number of items per page. Defaults to 10 if not specified and
maximum value allowed 100 items per page.
required: false
schema:
type: integer
- name: page[after]
in: query
description: Cursor for forward pagination (next page).
required: false
schema:
type: string
- name: page[before]
in: query
description: Cursor for backward pagination (previous page).
required: false
schema:
type: string
- name: sort
in: query
description: >-
If provided, response will be sorted by the specified fields.
Defaults to descending sentDate, equivalent to "-sentDate"
required: false
schema:
$ref: '#/components/schemas/type_files:FilesMetadataSortOptions'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_files:GetFilesMetadataResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'403':
description: Error response with status 403
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_files:FileType:
type: string
enum:
- earnedRewardApprovedDailyReconciliationFile
- earnedRewardSettledDailyReconciliationFile
- validatedTransactionDailyReconciliationFile
- monthlyReconciliationFile
title: FileType
type_files:FilesMetadataSortOptions:
type: string
enum:
- sentDate
- '-sentDate'
title: FilesMetadataSortOptions
type_files:FileMetadataAttribute:
type: object
properties:
fileName:
type: string
description: The name of the file.
sentAt:
type: string
description: >-
ISO 8601 timestamp (ISO8601) when the file was originally
sent/created.
lastModified:
type: string
description: ISO 8601 timestamp (ISO8601) when the file was last modified.
downloadUrl:
type: string
description: >-
Temporary URL that provides direct access to download the file for
30 minutes.
required:
- fileName
- sentAt
- lastModified
- downloadUrl
title: FileMetadataAttribute
type_files:FileMetadataWithURL:
type: object
properties:
type:
$ref: '#/components/schemas/type_files:FileType'
description: The type of the generated file.
attributes:
$ref: '#/components/schemas/type_files:FileMetadataAttribute'
description: Attributes of the filetype
id:
type: string
description: The File ID in Kard’s system
required:
- type
- attributes
- id
title: FileMetadataWithURL
type_commons:Links:
type: object
properties:
self:
type: string
prev:
type: string
next:
type: string
required:
- self
description: Related links to the API call
title: Links
type_files:PaginationMeta:
type: object
properties:
pageSize:
type: integer
description: Number of items per page.
hasNextPage:
type: boolean
description: Indicates if there are more pages available after the current one.
required:
- pageSize
- hasNextPage
title: PaginationMeta
type_files:GetFilesMetadataResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_files:FileMetadataWithURL'
description: List of file metadata objects with their pre-signed URLs.
links:
$ref: '#/components/schemas/type_commons:Links'
description: Navigation links for paginated results.
meta:
$ref: '#/components/schemas/type_files:PaginationMeta'
description: Metadata about the pagination status.
required:
- data
- links
- meta
title: GetFilesMetadataResponse
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/files/metadata"
querystring = {"page[size]":"5","filter[dateFrom]":"2025-02-20T21:56:23Z","filter[dateTo]":"2025-03-20T21:56:23Z","filter[fileType]":"earnedRewardApprovedDailyReconciliationFile","sort":"-sentDate"}
headers = {"Authorization": "Bearer "}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/files/metadata?page%5Bsize%5D=5&filter%5BdateFrom%5D=2025-02-20T21%3A56%3A23Z&filter%5BdateTo%5D=2025-03-20T21%3A56%3A23Z&filter%5BfileType%5D=earnedRewardApprovedDailyReconciliationFile&sort=-sentDate';
const options = {method: 'GET', headers: {Authorization: 'Bearer '}};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/files/metadata?page%5Bsize%5D=5&filter%5BdateFrom%5D=2025-02-20T21%3A56%3A23Z&filter%5BdateTo%5D=2025-03-20T21%3A56%3A23Z&filter%5BfileType%5D=earnedRewardApprovedDailyReconciliationFile&sort=-sentDate"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer ")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/files/metadata?page%5Bsize%5D=5&filter%5BdateFrom%5D=2025-02-20T21%3A56%3A23Z&filter%5BdateTo%5D=2025-03-20T21%3A56%3A23Z&filter%5BfileType%5D=earnedRewardApprovedDailyReconciliationFile&sort=-sentDate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer '
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.get("https://rewards-api.getkard.com/v2/issuers/organization-123/files/metadata?page%5Bsize%5D=5&filter%5BdateFrom%5D=2025-02-20T21%3A56%3A23Z&filter%5BdateTo%5D=2025-03-20T21%3A56%3A23Z&filter%5BfileType%5D=earnedRewardApprovedDailyReconciliationFile&sort=-sentDate")
.header("Authorization", "Bearer ")
.asString();
```
```php
request('GET', 'https://rewards-api.getkard.com/v2/issuers/organization-123/files/metadata?page%5Bsize%5D=5&filter%5BdateFrom%5D=2025-02-20T21%3A56%3A23Z&filter%5BdateTo%5D=2025-03-20T21%3A56%3A23Z&filter%5BfileType%5D=earnedRewardApprovedDailyReconciliationFile&sort=-sentDate', [
'headers' => [
'Authorization' => 'Bearer ',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/files/metadata?page%5Bsize%5D=5&filter%5BdateFrom%5D=2025-02-20T21%3A56%3A23Z&filter%5BdateTo%5D=2025-03-20T21%3A56%3A23Z&filter%5BfileType%5D=earnedRewardApprovedDailyReconciliationFile&sort=-sentDate");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer ");
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = ["Authorization": "Bearer "]
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/files/metadata?page%5Bsize%5D=5&filter%5BdateFrom%5D=2025-02-20T21%3A56%3A23Z&filter%5BdateTo%5D=2025-03-20T21%3A56%3A23Z&filter%5BfileType%5D=earnedRewardApprovedDailyReconciliationFile&sort=-sentDate")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Create Upload
POST https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/uploads
Content-Type: application/json
Call this endpoint to create an upload session and retrieve an upload ID. Using the upload ID in the [Add Upload
Part](/api/uploads/create-upload-part) endpoint, historical transactions can be sent in batches for further processing.
Required scopes: `transaction:write`
Reference: https://docs.getkard.com/api/uploads/create
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/users/{userId}/uploads:
post:
operationId: create
summary: Create Upload
description: >-
Call this endpoint to create an upload session and retrieve an upload
ID. Using the upload ID in the [Add Upload
Part](/api/uploads/create-upload-part) endpoint, historical transactions
can be sent in batches for further processing.
Required scopes: `transaction:write`
tags:
- subpackage_users.subpackage_users/uploads
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: userId
in: path
description: The ID of the user as defined on the issuers system
required: true
schema:
type: string
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_users/uploads:CreateUploadResponseObject
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_users/uploads:CreateUploadRequestObject
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_commons:EmptyObject:
type: object
properties: {}
title: EmptyObject
type_users/uploads:CreateUploadRequestDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- historicalTransactionStart
description: 'Discriminator value: historicalTransactionStart'
attributes:
$ref: '#/components/schemas/type_commons:EmptyObject'
required:
- type
- attributes
discriminator:
propertyName: type
title: CreateUploadRequestDataUnion
type_users/uploads:CreateUploadRequestObject:
type: object
properties:
data:
$ref: '#/components/schemas/type_users/uploads:CreateUploadRequestDataUnion'
required:
- data
title: CreateUploadRequestObject
type_users/uploads:CreateUploadResponseDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- historicalTransactionStart
description: 'Discriminator value: historicalTransactionStart'
id:
type: string
description: Upload id to reference in subsequent upload request
attributes:
$ref: '#/components/schemas/type_commons:EmptyObject'
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: CreateUploadResponseDataUnion
type_users/uploads:CreateUploadResponseObject:
type: object
properties:
data:
$ref: >-
#/components/schemas/type_users/uploads:CreateUploadResponseDataUnion
required:
- data
title: CreateUploadResponseObject
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads"
payload = { "data": {
"type": "historicalTransactionStart",
"attributes": {}
} }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":{"type":"historicalTransactionStart","attributes":{}}}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads"
payload := strings.NewReader("{\n \"data\": {\n \"type\": \"historicalTransactionStart\",\n \"attributes\": {}\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"type\": \"historicalTransactionStart\",\n \"attributes\": {}\n }\n}"
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"type\": \"historicalTransactionStart\",\n \"attributes\": {}\n }\n}")
.asString();
```
```php
request('POST', 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads', [
'body' => '{
"data": {
"type": "historicalTransactionStart",
"attributes": {}
}
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": {\n \"type\": \"historicalTransactionStart\",\n \"attributes\": {}\n }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
"type": "historicalTransactionStart",
"attributes": []
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Add Upload Part
PUT https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/uploads/{uploadId}/parts
Content-Type: application/json
Call this endpoint using the upload ID provided in the [Create Upload](/api/uploads/create-upload) endpoint to add parts to your upload. Currently, this endpoint supports adding historical transactions.
Required scopes: `transaction:write`
Note: `Maximum of 500 transactions can be uploaded per request`.
Reference: https://docs.getkard.com/api/uploads/create-part
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/users/{userId}/uploads/{uploadId}/parts:
put:
operationId: create-part
summary: Add Upload Part
description: >-
Call this endpoint using the upload ID provided in the [Create
Upload](/api/uploads/create-upload) endpoint to add parts to your
upload. Currently, this endpoint supports adding historical
transactions.
Required scopes: `transaction:write`
Note: `Maximum of 500 transactions can be uploaded per request`.
tags:
- subpackage_users.subpackage_users/uploads
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: userId
in: path
description: The ID of the user as defined on the issuers system
required: true
schema:
type: string
- name: uploadId
in: path
description: The upload ID identifying the upload session to add parts
required: true
schema:
type: string
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_users/uploads:CreateUploadPartResponseObject
'207':
description: Error response with status 207
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_users/uploads:CreateUploadPartMultiStatusResponse
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_users/uploads:CreateUploadPartRequestObject
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_transactions:TransactionStatus:
type: string
enum:
- APPROVED
- SETTLED
- REVERSED
- RETURNED
- DECLINED
title: TransactionStatus
type_transactions:States:
type: string
enum:
- AL
- AK
- AS
- AZ
- AR
- CA
- CO
- CT
- DE
- DC
- FM
- FL
- GA
- GU
- HI
- ID
- IL
- IN
- IA
- KS
- KY
- LA
- ME
- MH
- MD
- MA
- MI
- MN
- MS
- MO
- MT
- NE
- NV
- NH
- NJ
- NM
- NY
- NC
- ND
- MP
- OH
- OK
- OR
- PW
- PA
- PR
- RI
- SC
- SD
- TN
- TX
- UT
- VT
- VI
- VA
- WA
- WV
- WI
- WY
title: States
type_transactions:Merchant:
type: object
properties:
id:
type: string
description: >-
Acquirer Merchant Identification Number (MID) — usually a 15 digit
numerical identifier code. Note, this field is REQUIRED for local
offers. We HIGHLY RECOMMEND sending this field as it will be
required in the near future.
name:
type: string
description: Merchant name associated with transaction
addrStreet:
type: string
description: Merchant street address associated with transaction.
addrCity:
type: string
description: Merchant address city associated with transaction.
addrState:
$ref: '#/components/schemas/type_transactions:States'
description: Merchant address state associated with transaction.
addrZipcode:
type: string
description: Merchant address zip code associated with transaction.
addrCountry:
type: string
description: Merchant address country associated with transaction.
latitude:
type: string
description: Merchant latitude geocoordinate associated with transaction.
longitude:
type: string
description: Merchant longitude geocoordinate associated with transaction.
storeId:
type: string
description: Merchant store ID where transaction originated from
required:
- name
title: Merchant
type_transactions:DirectionType:
type: string
enum:
- DEBIT
- CREDIT
title: DirectionType
type_transactions:TransactionPaymentType:
type: string
enum:
- CARD
title: TransactionPaymentType
type_commons:CardNetwork:
type: string
enum:
- VISA
- MASTERCARD
- AMERICANEXPRESS
- DISCOVER
description: Supported card networks
title: CardNetwork
type_transactions:VisaMidDetails:
type: object
properties:
vmid:
type: string
description: Visa Merchant ID (VMID) associated with the transaction
vsid:
type: string
description: Visa Store ID (VSID) associated with the transaction
required:
- vmid
- vsid
title: VisaMidDetails
type_transactions:ProcessorMid:
oneOf:
- type: object
properties:
processor:
type: string
enum:
- VISA
description: 'Discriminator value: VISA'
mids:
$ref: '#/components/schemas/type_transactions:VisaMidDetails'
description: Merchant ID (MID) associated with the processor
required:
- processor
- mids
discriminator:
propertyName: processor
title: ProcessorMid
type_transactions:TransactionsAttributes:
type: object
properties:
userId:
type: string
description: The ID of the user as defined on the issuers system
amount:
type: integer
description: Transaction amount in cents
subtotal:
type: integer
description: >-
The base amount in cents excluding additional charges (such as tips,
taxes, and other fees).
status:
$ref: '#/components/schemas/type_transactions:TransactionStatus'
description: Transaction status
currency:
type: string
description: Currency of transaction
description:
type: string
description: >-
Description of transaction - usually includes merchant and other key
details on transaction
description2:
type: string
description: >-
Description2 of transaction — usually includes other merchant
identifying information
mcc:
type: string
description: >-
Merchant Category Code (usually a 4-digit numerical number).
Note, this field is REQUIRED for SOME national offers. We HIGHLY
RECOMMEND sending this field as it will be required in the near
future.
coreProviderId:
type: string
description: Name of processor associated with transaction
transactionDate:
type: string
format: date-time
description: >-
Timestamp for REVERSED, RETURNED, DECLINED transaction
events; REQUIRED for transactions with REVERSED, RETURNED,
DECLINED status. Date string should be in ISO 8601 format
i.e.`'YYYY-MM-DDThh:mm:ss.sTZD'` where TZD = time zone designator (Z
or +hh:mm or -hh:mm) i.e. `1994-11-05T08:15:30-05:00` OR
`1994-11-05T08:15:30Z`
authorizationDate:
type: string
format: date-time
description: >-
Timestamp for APPROVED transaction event; REQUIRED for
transactions with APPROVED status, and HIGHLY
RECOMMENDED to include for transactions with a SETTLED
status. Date string should be in ISO 8601 format
i.e.`'YYYY-MM-DDThh:mm:ss.sTZD'` where TZD = time zone designator (Z
or +hh:mm or -hh:mm) i.e. `1994-11-05T08:15:30-05:00 OR
1994-11-05T08:15:30Z`
settledDate:
type: string
format: date-time
description: >-
Timestamp for SETTLED transaction event, REQUIRED for
transactions with SETTLED status. Date string should be in
ISO 8601 format i.e.`'YYYY-MM-DDThh:mm:ss.sTZD'` where TZD = time
zone designator (Z or +hh:mm or -hh:mm) i.e.
`1994-11-05T08:15:30-05:00` OR `1994-11-05T08:15:30Z`
merchant:
$ref: '#/components/schemas/type_transactions:Merchant'
description: Merchant details
cardPresence:
type: string
description: Whether card was present at time of transaction
panEntryMode:
type: string
description: PAN entry mode
cardBIN:
type: string
description: >-
Bank identification number (BIN). Must be a valid BIN of 6 digits.
If over 6 digits, please send first 6.
cardLastFour:
type: string
description: Card last four digits.
authorizationCode:
type: string
description: Transaction approval code
retrievalReferenceNumber:
type: string
description: Retrieval Reference Number
systemTraceAuditNumber:
type: string
description: System Trace Audit Number
acquirerReferenceNumber:
type: string
description: Acquirer Reference Number
direction:
$ref: '#/components/schemas/type_transactions:DirectionType'
description: The direction in which the funds flow - DEBIT or CREDIT
paymentType:
$ref: '#/components/schemas/type_transactions:TransactionPaymentType'
description: The type of payment involved in the transaction.
cardNetwork:
$ref: '#/components/schemas/type_commons:CardNetwork'
description: The card network associated with the transaction
transactionId:
type: string
description: The transaction ID
cardProductId:
type: string
description: The card product ID associated with the transaction
userZipCode:
type: string
description: The zip code of the user who made the transaction
processorMids:
$ref: '#/components/schemas/type_transactions:ProcessorMid'
description: Network specific merchant IDs (MIDs) associated with the transaction
required:
- userId
- amount
- status
- currency
- description
- cardBIN
- cardLastFour
- direction
- paymentType
- transactionId
title: TransactionsAttributes
type_users/uploads:CreateUploadPartDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- historicalTransaction
description: 'Discriminator value: historicalTransaction'
id:
type: string
description: >-
Unique identifier for the transaction event. This must be
unique for each distinct event sent to the API.
attributes:
$ref: '#/components/schemas/type_transactions:TransactionsAttributes'
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: CreateUploadPartDataUnion
type_users/uploads:CreateUploadPartRequestObject:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/type_users/uploads:CreateUploadPartDataUnion'
required:
- data
title: CreateUploadPartRequestObject
type_commons:EmptyObject:
type: object
properties: {}
title: EmptyObject
type_users/uploads:CreateUploadPartResponseDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- historicalTransaction
description: 'Discriminator value: historicalTransaction'
id:
type: string
description: Id of the upload to add parts
attributes:
$ref: '#/components/schemas/type_commons:EmptyObject'
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: CreateUploadPartResponseDataUnion
type_users/uploads:CreateUploadPartResponseObject:
type: object
properties:
data:
type: array
items:
$ref: >-
#/components/schemas/type_users/uploads:CreateUploadPartResponseDataUnion
required:
- data
title: CreateUploadPartResponseObject
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
type_users/uploads:CreateUploadPartMultiStatusResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
data:
type: array
items:
$ref: >-
#/components/schemas/type_users/uploads:CreateUploadPartResponseDataUnion
required:
- errors
title: CreateUploadPartMultiStatusResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads/upload-123/parts"
payload = { "data": [
{
"type": "historicalTransaction",
"attributes": {
"userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
"amount": 1000,
"status": "APPROVED",
"currency": "USD",
"description": "ADVANCEAUTO",
"cardBIN": "123456",
"cardLastFour": "4321",
"direction": "DEBIT",
"paymentType": "CARD",
"transactionId": "2467de37-cbdc-416d-a359-75de87bfffb0",
"subtotal": 800,
"description2": "ADVANCEAUTO",
"mcc": "1234",
"authorizationDate": "2021-07-02T17:47:06Z",
"merchant": {
"name": "ADVANCEAUTO",
"id": "12345678901234567",
"addrStreet": "125 Main St",
"addrCity": "Philadelphia",
"addrState": "PA",
"addrZipcode": "19147",
"addrCountry": "United States",
"latitude": "37.9419429",
"longitude": "-73.1446869",
"storeId": "12345"
},
"authorizationCode": "123456",
"retrievalReferenceNumber": "100804333919",
"systemTraceAuditNumber": "333828",
"acquirerReferenceNumber": "1234567890123456789012345678"
},
"id": "309rjfoincor3icno3rind093cdow3jciwjdwcm"
}
] }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads/upload-123/parts';
const options = {
method: 'PUT',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":[{"type":"historicalTransaction","attributes":{"userId":"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69","amount":1000,"status":"APPROVED","currency":"USD","description":"ADVANCEAUTO","cardBIN":"123456","cardLastFour":"4321","direction":"DEBIT","paymentType":"CARD","transactionId":"2467de37-cbdc-416d-a359-75de87bfffb0","subtotal":800,"description2":"ADVANCEAUTO","mcc":"1234","authorizationDate":"2021-07-02T17:47:06Z","merchant":{"name":"ADVANCEAUTO","id":"12345678901234567","addrStreet":"125 Main St","addrCity":"Philadelphia","addrState":"PA","addrZipcode":"19147","addrCountry":"United States","latitude":"37.9419429","longitude":"-73.1446869","storeId":"12345"},"authorizationCode":"123456","retrievalReferenceNumber":"100804333919","systemTraceAuditNumber":"333828","acquirerReferenceNumber":"1234567890123456789012345678"},"id":"309rjfoincor3icno3rind093cdow3jciwjdwcm"}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads/upload-123/parts"
payload := strings.NewReader("{\n \"data\": [\n {\n \"type\": \"historicalTransaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 1000,\n \"status\": \"APPROVED\",\n \"currency\": \"USD\",\n \"description\": \"ADVANCEAUTO\",\n \"cardBIN\": \"123456\",\n \"cardLastFour\": \"4321\",\n \"direction\": \"DEBIT\",\n \"paymentType\": \"CARD\",\n \"transactionId\": \"2467de37-cbdc-416d-a359-75de87bfffb0\",\n \"subtotal\": 800,\n \"description2\": \"ADVANCEAUTO\",\n \"mcc\": \"1234\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"merchant\": {\n \"name\": \"ADVANCEAUTO\",\n \"id\": \"12345678901234567\",\n \"addrStreet\": \"125 Main St\",\n \"addrCity\": \"Philadelphia\",\n \"addrState\": \"PA\",\n \"addrZipcode\": \"19147\",\n \"addrCountry\": \"United States\",\n \"latitude\": \"37.9419429\",\n \"longitude\": \"-73.1446869\",\n \"storeId\": \"12345\"\n },\n \"authorizationCode\": \"123456\",\n \"retrievalReferenceNumber\": \"100804333919\",\n \"systemTraceAuditNumber\": \"333828\",\n \"acquirerReferenceNumber\": \"1234567890123456789012345678\"\n },\n \"id\": \"309rjfoincor3icno3rind093cdow3jciwjdwcm\"\n }\n ]\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads/upload-123/parts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": [\n {\n \"type\": \"historicalTransaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 1000,\n \"status\": \"APPROVED\",\n \"currency\": \"USD\",\n \"description\": \"ADVANCEAUTO\",\n \"cardBIN\": \"123456\",\n \"cardLastFour\": \"4321\",\n \"direction\": \"DEBIT\",\n \"paymentType\": \"CARD\",\n \"transactionId\": \"2467de37-cbdc-416d-a359-75de87bfffb0\",\n \"subtotal\": 800,\n \"description2\": \"ADVANCEAUTO\",\n \"mcc\": \"1234\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"merchant\": {\n \"name\": \"ADVANCEAUTO\",\n \"id\": \"12345678901234567\",\n \"addrStreet\": \"125 Main St\",\n \"addrCity\": \"Philadelphia\",\n \"addrState\": \"PA\",\n \"addrZipcode\": \"19147\",\n \"addrCountry\": \"United States\",\n \"latitude\": \"37.9419429\",\n \"longitude\": \"-73.1446869\",\n \"storeId\": \"12345\"\n },\n \"authorizationCode\": \"123456\",\n \"retrievalReferenceNumber\": \"100804333919\",\n \"systemTraceAuditNumber\": \"333828\",\n \"acquirerReferenceNumber\": \"1234567890123456789012345678\"\n },\n \"id\": \"309rjfoincor3icno3rind093cdow3jciwjdwcm\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.put("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads/upload-123/parts")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": [\n {\n \"type\": \"historicalTransaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 1000,\n \"status\": \"APPROVED\",\n \"currency\": \"USD\",\n \"description\": \"ADVANCEAUTO\",\n \"cardBIN\": \"123456\",\n \"cardLastFour\": \"4321\",\n \"direction\": \"DEBIT\",\n \"paymentType\": \"CARD\",\n \"transactionId\": \"2467de37-cbdc-416d-a359-75de87bfffb0\",\n \"subtotal\": 800,\n \"description2\": \"ADVANCEAUTO\",\n \"mcc\": \"1234\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"merchant\": {\n \"name\": \"ADVANCEAUTO\",\n \"id\": \"12345678901234567\",\n \"addrStreet\": \"125 Main St\",\n \"addrCity\": \"Philadelphia\",\n \"addrState\": \"PA\",\n \"addrZipcode\": \"19147\",\n \"addrCountry\": \"United States\",\n \"latitude\": \"37.9419429\",\n \"longitude\": \"-73.1446869\",\n \"storeId\": \"12345\"\n },\n \"authorizationCode\": \"123456\",\n \"retrievalReferenceNumber\": \"100804333919\",\n \"systemTraceAuditNumber\": \"333828\",\n \"acquirerReferenceNumber\": \"1234567890123456789012345678\"\n },\n \"id\": \"309rjfoincor3icno3rind093cdow3jciwjdwcm\"\n }\n ]\n}")
.asString();
```
```php
request('PUT', 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads/upload-123/parts', [
'body' => '{
"data": [
{
"type": "historicalTransaction",
"attributes": {
"userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
"amount": 1000,
"status": "APPROVED",
"currency": "USD",
"description": "ADVANCEAUTO",
"cardBIN": "123456",
"cardLastFour": "4321",
"direction": "DEBIT",
"paymentType": "CARD",
"transactionId": "2467de37-cbdc-416d-a359-75de87bfffb0",
"subtotal": 800,
"description2": "ADVANCEAUTO",
"mcc": "1234",
"authorizationDate": "2021-07-02T17:47:06Z",
"merchant": {
"name": "ADVANCEAUTO",
"id": "12345678901234567",
"addrStreet": "125 Main St",
"addrCity": "Philadelphia",
"addrState": "PA",
"addrZipcode": "19147",
"addrCountry": "United States",
"latitude": "37.9419429",
"longitude": "-73.1446869",
"storeId": "12345"
},
"authorizationCode": "123456",
"retrievalReferenceNumber": "100804333919",
"systemTraceAuditNumber": "333828",
"acquirerReferenceNumber": "1234567890123456789012345678"
},
"id": "309rjfoincor3icno3rind093cdow3jciwjdwcm"
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads/upload-123/parts");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": [\n {\n \"type\": \"historicalTransaction\",\n \"attributes\": {\n \"userId\": \"6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69\",\n \"amount\": 1000,\n \"status\": \"APPROVED\",\n \"currency\": \"USD\",\n \"description\": \"ADVANCEAUTO\",\n \"cardBIN\": \"123456\",\n \"cardLastFour\": \"4321\",\n \"direction\": \"DEBIT\",\n \"paymentType\": \"CARD\",\n \"transactionId\": \"2467de37-cbdc-416d-a359-75de87bfffb0\",\n \"subtotal\": 800,\n \"description2\": \"ADVANCEAUTO\",\n \"mcc\": \"1234\",\n \"authorizationDate\": \"2021-07-02T17:47:06Z\",\n \"merchant\": {\n \"name\": \"ADVANCEAUTO\",\n \"id\": \"12345678901234567\",\n \"addrStreet\": \"125 Main St\",\n \"addrCity\": \"Philadelphia\",\n \"addrState\": \"PA\",\n \"addrZipcode\": \"19147\",\n \"addrCountry\": \"United States\",\n \"latitude\": \"37.9419429\",\n \"longitude\": \"-73.1446869\",\n \"storeId\": \"12345\"\n },\n \"authorizationCode\": \"123456\",\n \"retrievalReferenceNumber\": \"100804333919\",\n \"systemTraceAuditNumber\": \"333828\",\n \"acquirerReferenceNumber\": \"1234567890123456789012345678\"\n },\n \"id\": \"309rjfoincor3icno3rind093cdow3jciwjdwcm\"\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
[
"type": "historicalTransaction",
"attributes": [
"userId": "6FHt5b6Fnp0qdomMEy5AN6PXcSJIeX69",
"amount": 1000,
"status": "APPROVED",
"currency": "USD",
"description": "ADVANCEAUTO",
"cardBIN": "123456",
"cardLastFour": "4321",
"direction": "DEBIT",
"paymentType": "CARD",
"transactionId": "2467de37-cbdc-416d-a359-75de87bfffb0",
"subtotal": 800,
"description2": "ADVANCEAUTO",
"mcc": "1234",
"authorizationDate": "2021-07-02T17:47:06Z",
"merchant": [
"name": "ADVANCEAUTO",
"id": "12345678901234567",
"addrStreet": "125 Main St",
"addrCity": "Philadelphia",
"addrState": "PA",
"addrZipcode": "19147",
"addrCountry": "United States",
"latitude": "37.9419429",
"longitude": "-73.1446869",
"storeId": "12345"
],
"authorizationCode": "123456",
"retrievalReferenceNumber": "100804333919",
"systemTraceAuditNumber": "333828",
"acquirerReferenceNumber": "1234567890123456789012345678"
],
"id": "309rjfoincor3icno3rind093cdow3jciwjdwcm"
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads/upload-123/parts")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users/%3AuserId/uploads/%3AuploadId/parts"
payload = { "data": [
{
"type": "historicalTransaction",
"attributes": {
"userId": "string",
"amount": 0,
"status": "APPROVED",
"currency": "string",
"description": "string",
"cardBIN": "string",
"cardLastFour": "string",
"direction": "DEBIT",
"paymentType": "CARD",
"transactionId": "string"
},
"id": "string"
}
] }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users/%3AuserId/uploads/%3AuploadId/parts';
const options = {
method: 'PUT',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":[{"type":"historicalTransaction","attributes":{"userId":"string","amount":0,"status":"APPROVED","currency":"string","description":"string","cardBIN":"string","cardLastFour":"string","direction":"DEBIT","paymentType":"CARD","transactionId":"string"},"id":"string"}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users/%3AuserId/uploads/%3AuploadId/parts"
payload := strings.NewReader("{\n \"data\": [\n {\n \"type\": \"historicalTransaction\",\n \"attributes\": {\n \"userId\": \"string\",\n \"amount\": 0,\n \"status\": \"APPROVED\",\n \"currency\": \"string\",\n \"description\": \"string\",\n \"cardBIN\": \"string\",\n \"cardLastFour\": \"string\",\n \"direction\": \"DEBIT\",\n \"paymentType\": \"CARD\",\n \"transactionId\": \"string\"\n },\n \"id\": \"string\"\n }\n ]\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
```ruby
require 'uri'
require 'net/http'
url = URI("https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users/%3AuserId/uploads/%3AuploadId/parts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": [\n {\n \"type\": \"historicalTransaction\",\n \"attributes\": {\n \"userId\": \"string\",\n \"amount\": 0,\n \"status\": \"APPROVED\",\n \"currency\": \"string\",\n \"description\": \"string\",\n \"cardBIN\": \"string\",\n \"cardLastFour\": \"string\",\n \"direction\": \"DEBIT\",\n \"paymentType\": \"CARD\",\n \"transactionId\": \"string\"\n },\n \"id\": \"string\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.put("https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users/%3AuserId/uploads/%3AuploadId/parts")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"data\": [\n {\n \"type\": \"historicalTransaction\",\n \"attributes\": {\n \"userId\": \"string\",\n \"amount\": 0,\n \"status\": \"APPROVED\",\n \"currency\": \"string\",\n \"description\": \"string\",\n \"cardBIN\": \"string\",\n \"cardLastFour\": \"string\",\n \"direction\": \"DEBIT\",\n \"paymentType\": \"CARD\",\n \"transactionId\": \"string\"\n },\n \"id\": \"string\"\n }\n ]\n}")
.asString();
```
```php
request('PUT', 'https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users/%3AuserId/uploads/%3AuploadId/parts', [
'body' => '{
"data": [
{
"type": "historicalTransaction",
"attributes": {
"userId": "string",
"amount": 0,
"status": "APPROVED",
"currency": "string",
"description": "string",
"cardBIN": "string",
"cardLastFour": "string",
"direction": "DEBIT",
"paymentType": "CARD",
"transactionId": "string"
},
"id": "string"
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
```
```csharp
using RestSharp;
var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users/%3AuserId/uploads/%3AuploadId/parts");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"data\": [\n {\n \"type\": \"historicalTransaction\",\n \"attributes\": {\n \"userId\": \"string\",\n \"amount\": 0,\n \"status\": \"APPROVED\",\n \"currency\": \"string\",\n \"description\": \"string\",\n \"cardBIN\": \"string\",\n \"cardLastFour\": \"string\",\n \"direction\": \"DEBIT\",\n \"paymentType\": \"CARD\",\n \"transactionId\": \"string\"\n },\n \"id\": \"string\"\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
```swift
import Foundation
let headers = [
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = ["data": [
[
"type": "historicalTransaction",
"attributes": [
"userId": "string",
"amount": 0,
"status": "APPROVED",
"currency": "string",
"description": "string",
"cardBIN": "string",
"cardLastFour": "string",
"direction": "DEBIT",
"paymentType": "CARD",
"transactionId": "string"
],
"id": "string"
]
]] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/%3AorganizationId/users/%3AuserId/uploads/%3AuploadId/parts")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
# Update Upload
PUT https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/uploads/{uploadId}
Content-Type: application/json
Call this endpoint to update your upload session. Currently, you can signal completing a historical transactions upload.
Required scopes: `transaction:write`
Reference: https://docs.getkard.com/api/uploads/update
## OpenAPI Specification
```yaml
openapi: 3.1.0
info:
title: '2024-10-01'
version: 1.0.0
paths:
/v2/issuers/{organizationId}/users/{userId}/uploads/{uploadId}:
put:
operationId: update
summary: Update Upload
description: >-
Call this endpoint to update your upload session. Currently, you can
signal completing a historical transactions upload.
Required scopes: `transaction:write`
tags:
- subpackage_users.subpackage_users/uploads
parameters:
- name: organizationId
in: path
required: true
schema:
$ref: '#/components/schemas/type_commons:OrganizationId'
- name: userId
in: path
description: The ID of the user as defined on the issuers system
required: true
schema:
type: string
- name: uploadId
in: path
description: The upload ID identifying the upload session to update
required: true
schema:
type: string
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_users/uploads:UpdateUploadResponseObject
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'401':
description: Error response with status 401
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'409':
description: Error response with status 409
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
'500':
description: Error response with status 500
content:
application/json:
schema:
$ref: '#/components/schemas/type_commons:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/type_users/uploads:UpdateUploadRequestObject
servers:
- url: https://rewards-api.getkard.com
- url: https://test-rewards-api.getkard.com
components:
schemas:
type_commons:OrganizationId:
type: string
description: Your issuer organization ID, provided by Kard
title: OrganizationId
type_commons:EmptyObject:
type: object
properties: {}
title: EmptyObject
type_users/uploads:UpdateUploadRequestDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- historicalTransactionComplete
description: 'Discriminator value: historicalTransactionComplete'
id:
type: string
description: Upload id the issuer can use in reference to the upload session
attributes:
$ref: '#/components/schemas/type_commons:EmptyObject'
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: UpdateUploadRequestDataUnion
type_users/uploads:UpdateUploadRequestObject:
type: object
properties:
data:
$ref: '#/components/schemas/type_users/uploads:UpdateUploadRequestDataUnion'
required:
- data
title: UpdateUploadRequestObject
type_users/uploads:UpdateUploadResponseDataUnion:
oneOf:
- type: object
properties:
type:
type: string
enum:
- historicalTransactionComplete
description: 'Discriminator value: historicalTransactionComplete'
id:
type: string
description: Upload id to reference in subsequent upload request
attributes:
$ref: '#/components/schemas/type_commons:EmptyObject'
required:
- type
- id
- attributes
discriminator:
propertyName: type
title: UpdateUploadResponseDataUnion
type_users/uploads:UpdateUploadResponseObject:
type: object
properties:
data:
$ref: >-
#/components/schemas/type_users/uploads:UpdateUploadResponseDataUnion
required:
- data
title: UpdateUploadResponseObject
type_commons:ErrorSource:
type: object
properties:
pointer:
type: string
description: >-
A JSON pointer to the value in the request document that caused the
error
parameter:
type: string
description: A string indicating which URI query parameter caused the error
header:
type: string
description: >-
A string indicating the name of a single request header which caused
the error
title: ErrorSource
type_commons:ErrorObject:
type: object
properties:
status:
type: string
description: Status code returned from the request
title:
type: string
description: Name of error
detail:
type: string
description: Description of the specific occurance of the error
source:
$ref: '#/components/schemas/type_commons:ErrorSource'
description: An object containing a reference to the primary source of the error
id:
type: string
description: >-
The id of the resource which caused the error. Always returned for
multi-status errors.
required:
- status
- title
- detail
title: ErrorObject
type_commons:ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/type_commons:ErrorObject'
required:
- errors
title: ErrorResponse
securitySchemes:
OAuthScheme:
type: http
scheme: bearer
```
## SDK Code Examples
```python
import requests
url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads/upload-123"
payload = { "data": {
"type": "historicalTransactionComplete",
"attributes": {},
"id": "7e382223-b9a5-4825-91fb-436c8957a2e7"
} }
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.json())
```
```javascript
const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads/upload-123';
const options = {
method: 'PUT',
headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'},
body: '{"data":{"type":"historicalTransactionComplete","attributes":{},"id":"7e382223-b9a5-4825-91fb-436c8957a2e7"}}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/uploads/upload-123"
payload := strings.NewReader("{\n \"data\": {\n \"type\": \"historicalTransactionComplete\",\n \"attributes\": {},\n \"id\": \"7e382223-b9a5-4825-91fb-436c8957a2e7\"\n }\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer
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/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:
* **`Views`:** Occur anytime a user *acts* to view a specific resource.
*Example:* When a user clicks an offer to view its details, or taps on a push notification to open the rewards screen — this generates a `VIEW` event.
See below for a visual representation of a view event:
***
### Mediums
Each event must include a `medium` field to describe where in your experience the event occurred.
**Supported mediums:**
* **`BROWSE`** — User is viewing a list of offers in the rewards experience.
* **`MAP`** — User is exploring offers on a map view.
* **`SEARCH`** — User is viewing or clicking offers as part of a search experience.
* **`PUSH`** — Event occurred within a mobile push notification.
***
## Implementation Methods
Kard supports two integration options for real-time attribution tracking. You may use either, but not both for the same event type:
1. **Event Tracking via Image URLs** — Attribution tracking tokens are included with assets returned by Kard's APIs and webhooks.
2. **Event Tracking via the Attribution API Endpoint** — Provides direct event delivery if your system already tracks impressions and views.
***
## In-App Experiences
### Overview
In-app notifications and offer impressions are tracked when users interact with the rewards experience inside your application.
For **in-app impressions and views**, you can choose **either**:
1. **Image-based tracking**, or
2. **The Attribution API Endpoint**
Use a single method consistently for each event type to prevent duplication.
***
### Option 1: Image-Based Tracking
When loading offers or images from Kard, append the `eventCode` and `medium` parameters to the provided URL.
The images are provided in the [Get Offers by User](https://docs.getkard.com/api/rewards/offers) and [Get Locations by User](https://docs.getkard.com/api/rewards/locations) API endpoints in the `data.attributes.assets.url` fields.
**Example payload:**
```json
GET /v2/issuers/{{organizationId}}/users/{{userId}}/offers
{
"data": {
"attributes": {
...
"assets": [
{
"type": "LOGO_IMAGE",
"url": "https://attribution.getkard.com/image.jpg?token=valid.signed.jwt",
"alt": "Worlds Greatest Chicken Logo Image"
},
{
"type": "BANNER_IMAGE",
"url": "https://attribution.getkard.com/image.jpg?token=valid.signed.jwt",
"alt": "Worlds Greatest Chicken Banner Image"
}
...
],
...
},
},
}
...
```
User browsing the rewards list → `eventCode=IMPRESSION&medium=BROWSE`
```html
```
User opening an offer detail page upon browsing list → `eventCode=VIEW&medium=BROWSE`
```html
```
User viewing offers on a map → `eventCode=IMPRESSION&medium=MAP`
```html
```
```
### Option 2: Attribution API
If you track these events yourself, you can send them directly to Kard via the Attribution API.
User clicks into push notification and opens into app → `eventCode=VIEW`, `medium=PUSH`
Note: in addition to `eventCode` and a `medium` the API requires an `entityId` representing the Kard-provided `notificationId` related to the attribution event and an `eventDate` capturing the timestamp the event occurred.
```json
POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
{
"data": [
{
"type": "notificationAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144c178",
"eventCode": "VIEW",
"medium": "PUSH",
"eventDate": "2025-01-07T00:00:00Z"
}
}
]
}
```
***
## Best Practices
* **In-app experiences:** Use either Image-based tracking or the API for both event types.
* **Push Notification Impressions:** Must be sent via the Attribution API.
* **Push Notification Views:** Use either Image-based tracking or the API.
* Use **either** Image-based tracking **or** the Attribution API per event type — not both.
* Avoid caching attribution URLs if you choose to use the Image-based tracking.
* Send all API-based events promptly for real-time data accuracy.
***
title: Extended API Integration
---------------------
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.getkard.com/llms.txt. For full documentation content, see https://docs.getkard.com/llms-full.txt.
Kard's Extended API feature enhances our existing rewards endpoints with dynamic, per-user offer data. By requesting UI components through the `supportedComponents` query parameter, you can surface richer offer experiences to your end users including dynamic descriptions, call-to-action buttons, and contextual tags without building custom logic to interpret raw offer data.
This guide covers how to request and render extended offer fields from the [Get Offers by User](/2024-10-01/api/rewards/offers) and [Get Locations by User](/2024-10-01/api/rewards/locations) endpoints.
## Key Concepts
### Supported Components
The Extended API uses a **component-based model** to deliver dynamic offer data. You tell Kard which UI components your app supports, and the API returns the relevant data for each offer.
| Component | Description | Example Use Case |
| ------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `shortDescription` | A brief, dynamic description of the offer suitable for list views | "Multi-use", "Single use" |
| `longDescription` | A detailed description suitable for offer detail pages | "Use your linked card on qualifying purchases to redeem multiple times." |
| `cta` | A call-to-action button with text, style, and an optional action URL | "Tap to boost" button |
| `tags` | Contextual labels for the offer in list/browse views | `["New"]`, `["5 days left"]` |
| `detailTags` | Contextual labels for the offer detail page | `["Activated"]` |
| `baseReward` | A formatted reward string ready for display in your UI | `"5% cash back"` |
**All components, offer is activated:**
**If you requested a subset of components (`shortDescription`, `longDescription`, and `cta`):**
1. Display `longDescription` on the offer detail page
2. Display `shortDescription` on offer cards in list views
3. If `cta` is present and `buttonStyle` is `PRIMARY`, display the call-to-action button using `buttonText` — when tapped, call the URL in `cta.action.url` using the specified `cta.action.method` (see Step 4a)
4. If `cta` is absent, the offer has already been activated — hide the call-to-action button
**Description + call-to-action components, offer not activated:**
**Description + call-to-action components, offer is activated:**
**If you requested description-only components (`shortDescription` and `longDescription`):**
This approach is for issuers that cannot render interactive call-to-action buttons. Instead of using a call-to-action button to activate or boost offers, the **VIEW event** serves as the activation signal.
1. Display `shortDescription` on offer cards in list/browse views
2. Display `longDescription` on the offer detail page
3. When a user navigates to the offer detail page, fire a **VIEW attribution event** (see Step 4b)
4. After the VIEW event, **re-fetch the offer** to get updated descriptions that reflect the new user state (e.g., descriptions change from "Tap to activate" to "Activated")
5. Re-render the offer with the updated `shortDescription` and `longDescription`