Skip to content
Last updated

Cardholders & Cardholder Groups

Reward results need to reach the right cardholder or shared account. Register cardholders and cards in advance or let incoming activity create missing accounts, then use the returned ID mappings to connect purchases and rewards to your customers. A cardholder group holds rewards for one or more cardholders, and each card belongs to one cardholder.

Registration Options

Register cardholders and cardholder groups in either of two ways:

  • Proactively, before use.
  • Lazily, when a supported activity or purchase record first includes an external ID Percents has not seen before.

Both approaches support cashback and branded rewards.

Explicit setup

Register accounts in advance to use targeted offers. Activity and purchase intake can also create missing accounts. Use the same issuer credential for all customer operations:

curl --fail-with-body -X POST 'https://sandbox.percents.com/api/v2/chg' \
  -H 'Authorization: token tok_11111111-1111-4111-8111-111111111111:api_test_secret' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "externalId": "issuer-group-001",
  "defaultLanguage": "en",
  "active": true,
  "cardholders": [
    {
      "externalId": "issuer-cardholder-001",
      "active": true,
      "cards": [
        {
          "externalId": "issuer-card-001",
          "last4": "4242",
          "bin": "411111",
          "network": "visa",
          "physical": true,
          "billingZip": "10001",
          "active": true
        }
      ]
    }
  ],
  "idempotencyKey": "setup-001"
}
JSON

This example registers a group, cardholder and card before offer discovery. Keep an existing cardholder in their assigned group. Keep the returned id and nested cardholder/card IDs. Use your internal IDs in V2 purchase intake and public IDs in V2 resource paths. Units and IDs explains the distinction.

OperationPurpose
POST /api/v2/chgCreate or update one group with its supplied cardholder/card data.
POST /api/v2/chg/bulk-upsertExplicit batch setup. Mixed row success/failure returns 207. Use the body and limits in the API reference.
GET /api/v2/chg/{chgId}Read the persisted group and nested mappings.
POST /api/v2/chg/{chgId}/cardholderAdd a cardholder to an existing group.
PUT /api/v2/chg/{chgId}/cardholder/{cardholderId}Update the identified cardholder.
PUT /api/v2/chg/{chgId}/cardholder/{cardholderId}/card/{cardId}Create or update the identified card.
Existing DELETE operations on group, cardholder and cardSoft-deactivate the resource. Preserve historical results.

Use the specified idempotency key when retrying explicit upserts and deactivations. All operations enforce issuer and parent ownership. The account must belong to your issuer and the specified parent. Intake cannot silently reactivate an inactive/deleted identity or move a cardholder or card to a different parent.

Lazy provisioning

When you send an authorization or settlement, Percents finds existing accounts and creates missing accounts when the supplied details allow it. User activity resolves or creates the cardholder and group without requiring a card.

Supplied/known stateResolution
Group, cardholder and card already existReuse all three.
Group and cardholder exist. Card is newCreate only the card under that cardholder.
Explicit group exists. Cardholder/card are newCreate the new cardholder and card in that group.
Explicit external group is new. Cardholder/card are newCreate all three using the issuer's group key.
Group omitted. Cardholder already assignedReuse its existing group. Create only a missing card.
Group omitted. Cardholder is new and unassignedCreate a group containing only that cardholder, with the same external ID as the cardholder, plus the cardholder and the card for purchase intake.
Conflicting, ambiguous, inactive or deleted assignmentReject. Do not move, reactivate or leave partial creations.

Supply externalCardholderGroupId when the cardholder belongs to a group identified in your system, including shared accounts. Use that group's configured ID consistently. Do not put a Percents chg_ ID in this field.

If you omit the group ID:

  • Percents reuses the cardholder's existing group assignment when one exists.
  • For a new, unassigned cardholder, Percents creates a group for that cardholder alone and automatically sets its externalId to the cardholder's internal ID.

Save the returned mappings after lazy provisioning. Later requests must use the ID expected by the field or route:

Field or route valueID to send
externalCardholderGroupIdThe group's configured externalId, including the automatically assigned value after lazy provisioning.
chgId in a resource pathThe group's public Percents chg_ ID from percentsId.

These rules also apply when supplying group context with cardholder activity. Supplying a different group ID does not move an already assigned cardholder. If an internal cardholder ID matches more than one account, resolve that conflict before retrying. Percents does not choose a match for you. BIN and last four digits do not prove card ownership.

Exceptions

  • Shared accounts: supply your externalCardholderGroupId before first intake when several cardholders should share rewards. Otherwise a new unassigned cardholder gets a group for that cardholder alone whose external group ID equals its external cardholder ID. Do not assume a household or account can be inferred from card facts.
  • Existing assignments: an omitted group reuses the cardholder's persisted group. The default equality of external group and cardholder IDs applies only when creating a new single-cardholder group. It is not a rule for every customer.
  • Key collisions: if that default external group ID already belongs to a different assignment, reject the event. Do not generate a suffix or silently join the customer to another group.
  • Conflicting parents: an assigned cardholder cannot move to a new group through intake. A new cardholder cannot claim another cardholder's card. Resolve the conflict before retrying.
  • Inactive, deleted or ambiguous identities: reject without reactivation, arbitrary selection or partial creation. BIN and last four digits do not establish ownership.
  • No card yet: activity can provision only group/cardholder. Every authorization and settlement still requires external cardholderId and cardId, even for an existing group.

Created account mappings

lazilyProvisionedAccounts appears only when an operation creates accounts. It contains only the accounts created by that operation, using externalId and percentsId for each. Existing accounts are omitted. If no account is created, the key is absent.

Operation resultReturned mappings
All accounts already existNo lazilyProvisionedAccounts key.
New card under an existing cardholder/groupcard only.
New cardholder under an existing groupcardholder, plus card for purchase intake.
New cardholder and groupcardholderGroup, cardholder, plus card for purchase intake.
Retry after accounts were already createdNo new accounts. No provisioning key.

An activity creation response looks like:

{
  "lazilyProvisionedAccounts": {
    "cardholderGroup": {
      "externalId": "issuer-cardholder-001",
      "percentsId": "chg_22222222-2222-4222-8222-222222222222"
    },
    "cardholder": {
      "externalId": "issuer-cardholder-001",
      "percentsId": "ch_33333333-3333-4333-8333-333333333333"
    }
  }
}

For purchase batches, the 201 response contains an array of mapping objects for input events that created accounts, in input order. Store these mappings. For a lost response, use identity lookup. A lookup does not create accounts.

Identity lookup

GET /api/v2/chg/resolve?externalCardholderId=... returns the current persisted group and cardholder mappings. It does not create accounts and does not include lazilyProvisionedAccounts.

{
  "cardholderGroup": {
    "externalId": "issuer-cardholder-001",
    "percentsId": "chg_22222222-2222-4222-8222-222222222222"
  },
  "cardholder": {
    "externalId": "issuer-cardholder-001",
    "percentsId": "ch_33333333-3333-4333-8333-333333333333"
  }
}

Activation scope

CLICK and VIEW activation applies across the cardholder group. The offer's activationScope controls how many redemptions it covers. Branded ONE_TIME activation applies to the merchant and group. User activity and merchant activation explain the timing rules.