Getting Started | Kard API

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

Prerequisites

Python 3.8+
KARD_CLIENT_ID and KARD_CLIENT_SECRET
Package manager: pip

Install the SDK

$ pip install kard-financial-sdk

Create a Client

Import and instantiate the KardApi client using your credentials.

This SDK supports two authentication methods:

OAuth Client Credentials

1 from kard import KardApi
2 
3 client = KardApi(
4     ..., client_id="your-client-id", client_secret="your-client-secret"
5 )

Bearer Token Authentication

1 from kard import KardApi
2 
3 client = KardApi(..., token="my-pre-generated-bearer-token")

The client automatically handles authentication, retries, and timeouts.

Make Your First API Calls

1. Creating a User:

1 from kard import KardApi
2 from kard.users import UserRequestAttributes, UserRequestDataUnion_User
3 
4 client = KardApi(
5     client_id="YOUR_CLIENT_ID",
6     client_secret="YOUR_CLIENT_SECRET",
7 )
8 
9 client.users.create(
10     organization_id="organization-123",
11     data=[
12         UserRequestDataUnion_User(
13             id="1234567890",
14             attributes=UserRequestAttributes(
15                 zip_code="11238",
16                 enrolled_rewards=["CARDLINKED"],
17             ),
18         )
19     ],
20 )

2. Fetching Offers for User:

1 from kard import KardApi
2 
3 client = KardApi(
4     client_id="YOUR_CLIENT_ID",
5     client_secret="YOUR_CLIENT_SECRET",
6 )
7 
8 client.users.rewards.offers(
9     organization_id="organization-123",
10     user_id="1234567890",
11     page_size=1,
12     filter_is_targeted=True,
13     sort="-startDate",
14 )

3. Submitting Transaction for User:

1 import datetime
2 from kard import KardApi
3 from kard.transactions import (
4     Merchant,
5     Transactions_Transaction,
6     TransactionsAttributes,
7 )
8 
9 client = KardApi(
10     client_id="YOUR_CLIENT_ID",
11     client_secret="YOUR_CLIENT_SECRET",
12 )
13 
14 client.transactions.create(
15     organization_id="organization-123",
16     data=[
17         Transactions_Transaction(
18             id="12345610",
19             attributes=TransactionsAttributes(
20                 user_id="1234567890",
21                 amount=1000,
22                 subtotal=800,
23                 status="APPROVED",
24                 currency="USD",
25                 description="ADVANCEAUTO",
26                 authorization_date=datetime.datetime.fromisoformat(
27                     "2021-07-02 17:47:06+00:00",
28                 ),
29                 payment_type="CARD",
30                 direction="DEBIT",
31                 merchant=Merchant(
32                     id="12345678901234567",
33                     name="ADVANCEAUTO",
34                     addr_street="125 Main St",
35                     addr_city="Philadelphia",
36                     addr_state="PA",
37                     addr_zipcode="19147",
38                     addr_country="United States",
39                     latitude="37.9419429",
40                     longitude="-73.1446869",
41                     storeId="12345",
42                 ),
43                 card_bin="123456",
44                 card_last_four="4321",
45                 authorization_code="123456",
46                 retrieval_reference_number="100804333919",
47                 system_trace_audit_number="333828",
48                 acquirer_reference_number="1234567890123456789012345678",
49                 transaction_id="12345611",
50             ),
51         )
52     ],
53 )

All SDK methods return typed responses and raise typed errors.

Async Client

The SDK also provides an async client for non-blocking API calls.

1 import asyncio
2 from kard import AsyncKardApi
3 from kard.users import UserRequestAttributes, UserRequestDataUnion_User
4 
5 client = AsyncKardApi(
6     client_id="YOUR_CLIENT_ID",
7     client_secret="YOUR_CLIENT_SECRET",
8 )
9 
10 async def main() -> None:
11     await client.users.create(
12         organization_id="organization-123",
13         data=[
14             UserRequestDataUnion_User(
15                 id="1234567890",
16                 attributes=UserRequestAttributes(
17                     zip_code="11238",
18                     enrolled_rewards=["CARDLINKED"],
19                 ),
20             )
21         ],
22     )
23 
24 asyncio.run(main())

Handling Errors

If an API request fails (4xx or 5xx), the SDK raises an ApiError.

1 from kard.core.api_error import ApiError
2 
3 try:
4     client.users.create(...)
5 except ApiError as e:
6     print("Status:", e.status_code)
7     print("Body:", e.body)

Common Configuration Options

Configure Retries

Retries are enabled by default (max 2 attempts).

1 client.users.create(
2     ...,
3     request_options={
4         "max_retries": 1
5     }
6 )

Set a Timeout

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

1 client = KardApi(
2     ...,
3     timeout=20.0,
4 )
5 
6 client.users.create(..., request_options={
7     "timeout_in_seconds": 1
8 })

Access Raw HTTP Responses

To inspect headers or status codes, use with_raw_response.

1 response = client.users.with_raw_response.create(...)
2 
3 print(response.headers)
4 print(response.data)

Custom HTTP Client

You can supply a custom httpx.Client to customize transports, proxies, or networking behavior.

1 import httpx
2 from kard import KardApi
3 
4 client = KardApi(
5     ...,
6     httpx_client=httpx.Client(
7         proxy="http://my.test.proxy.example.com",
8         transport=httpx.HTTPTransport(local_address="0.0.0.0"),
9     ),
10 )