# Guided Overview

An issuer integration has four required phases:

1. Create or update the cardholder group.
2. Present merchants and offers, activate the merchant for the cardholder group, and read earn/spend eligibility.
3. Ingest card authorization events and settled transaction events.
4. Process webhooks and reconcile balances, cashback, and audit records.


A cardholder group (CHG) is a collection of one or more cardholders that Percents treats as one reward entity. Cardholders in the same CHG share merchant activation, cashback, and branded balance state, so they can earn rewards and spend branded balance as if they were one. A CHG commonly maps to authorized users on an account, employees of a business, or another issuer-defined group. Each CHG can have one or more cardholders, and each cardholder can have one or more cards. The API uses `chg` in path segments and `chg_` typed ids for cardholder group resources.

```mermaid
sequenceDiagram
  participant Issuer
  participant Percents
  participant Cardholder

  Issuer->>Percents: Upsert cardholder group, cardholders, cards
  Issuer->>Percents: List merchants and offers
  Cardholder->>Issuer: Activates offer for merchant
  Issuer->>Percents: Activate merchant for cardholder group
  Issuer->>Percents: Read earn/spend eligibility
  Issuer->>Percents: Ingest card authorization event
  Percents-->>Issuer: qualified_auth webhook when applicable
  Issuer->>Percents: Ingest settled transaction
  Percents-->>Issuer: qualified_settlement webhook when applicable
  Issuer->>Percents: Read balances, activity, and transaction details
```

## MVP Integration Checklist

Before moving beyond sandbox, an integration should have:

- Cardholder group creation for each account, business, household, or other issuer-defined group that should earn and spend as one reward entity.
- Stable issuer-side `cardholderId` and `cardId` values on ingested transactions.
- Merchant activation storage on the issuer side so the issuer can present current state for cashback and branded balance offers.
- Idempotent transaction ingestion keyed by issuer-provided card authorization event ids and settled transaction event ids.
- Webhook verification using `X-PERCENTS-SIGNATURE`.
- Webhook idempotency keyed by `webhookId`.
- Reconciliation against reward activity, transaction reward detail, and posted event totals.
- Support workflows for public error `uuid` values.