> ## Documentation Index
> Fetch the complete documentation index at: https://next-developers.opencard.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Current Card Issuer Integration

> Integrate OpenCard when a client already has another card issuer feed — retroactive replay and deduplicating cleared transaction events.

Your client may already receive card transactions from the same card program through a direct issuer integration or another middleware. That is common during rollout.

***

## What to expect with two feeds

|                            | Existing integration | OpenCard                              |
| -------------------------- | -------------------- | ------------------------------------- |
| **Typical states**         | Often `cleared` only | `authorized` → `cleared` → `invoiced` |
| **Starts per card holder** | Varies               | On `card_holder.identified`           |

**Authorized events are OpenCard-specific.** Many legacy feeds never send authorisations. You will see `card.transaction.authorized` from OpenCard that have no counterpart on the old feed — use them for in-app previews, not for deduplication against the other source.

**Retroactive batch on onboard.** When `card_holder.identified` fires, OpenCard replays transaction states since the latest card invoice for that person's cards on the TPA. The same cleared purchases may already exist in your system from the other integration.

→ [Card holder onboarding](/ems/card-holders) (Path 🅰️ and Path 🅱️)

***

## Deduplicating with `card_issuer_reference`

The practical way to run both feeds in parallel:

1. Start processing OpenCard per card holder when **`card_holder.identified`** arrives.
2. **Upsert on OpenCard transaction `id`** as your primary key for the OpenCard feed.
3. On **`card.transaction.cleared`**, check whether you already stored the purchase from the other feed using **`card_issuer_reference`** on the cleared payload.

**Cleared matches cleared** — compare `card_issuer_reference` only on `card.transaction.cleared`, not on `authorized`. The same purchase can carry **different** `card_issuer_reference` values on `authorized` vs `cleared`; that depends on the card issuer and OpenCard cannot normalize it.

4. To end the old feed, your **client** terminates it with their **card issuer**. Agree with your client when to stop processing the other integration on your side.

→ [Transaction webhook upsert rules](/ems/webhooks/transactions)