Getting Started

Welcome to the Kard API Getting Started guide. This resource will walk you through recommended integration patterns and recommended user experiences to quickly jump start your rewards program through Kard. Whether you are making your first API call, testing parts of your integration or preparing for your pre-production credentials call, this guide will help you get started.

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

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

Authenticating with the API

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

Use our Postman API to test your connection

Postman Collection Coming Soon!

Recommended Integration Patterns

User Management

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

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

Code Recipe:

Creating a User:

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

Add cardInfo to User:

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

Targeted Offers

Each sandbox environment is configured with the following user personas:

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

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

Transaction CLO Matching

There are three common patterns for transmitting transactions.

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

Transaction Reconciliation

There are two standard reconciliation reports that Kard issues: Daily files and end of month (EOM) files. Both of these files can be retrieved using the GET Files endpoint.

Daily Reconciliation File

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

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

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

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

User Acceptance Test Cases

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.

Built with