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.

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.