Cardholder Group Management

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, a household, or another issuer-defined group. Each CHG can have one or more cardholders, and each cardholder can have one or more cards.

Cardholder group management includes:

• The cardholder group record.
• One or more cardholders.
• One or more cards for each cardholder.
• Settings that affect product behavior, localization, or SDK presentation.

The API uses chg in path segments and chg_ typed ids for cardholder group resources.

1. POST /api/v2/chg to create or update one cardholder group.
2. POST /api/v2/chg/bulk-upsert when syncing many cardholder groups.
3. GET /api/v2/chg/{chgId} to verify the cardholder group Percents stores.
4. Use the cardholder and card ids on card authorization event and settled transaction event ingestion.

All reads and writes are scoped by issuer credentials. A caller must not assume that a syntactically valid chg_, ch_, or card_ id is accessible to the current issuer. Percents enforces ownership on API operations.

Deleting a cardholder group, cardholder, or card is a soft deactivation. Historical transactions, reward events, and audit records remain available for reconciliation.