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.
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.
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"
}
JSONThis 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.
| Operation | Purpose |
|---|---|
POST /api/v2/chg | Create or update one group with its supplied cardholder/card data. |
POST /api/v2/chg/bulk-upsert | Explicit 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}/cardholder | Add 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 card | Soft-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.
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 state | Resolution |
|---|---|
| Group, cardholder and card already exist | Reuse all three. |
| Group and cardholder exist. Card is new | Create only the card under that cardholder. |
| Explicit group exists. Cardholder/card are new | Create the new cardholder and card in that group. |
| Explicit external group is new. Cardholder/card are new | Create all three using the issuer's group key. |
| Group omitted. Cardholder already assigned | Reuse its existing group. Create only a missing card. |
| Group omitted. Cardholder is new and unassigned | Create 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 assignment | Reject. 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
externalIdto 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 value | ID to send |
|---|---|
externalCardholderGroupId | The group's configured externalId, including the automatically assigned value after lazy provisioning. |
chgId in a resource path | The 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.
- Shared accounts: supply your
externalCardholderGroupIdbefore 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
cardholderIdandcardId, even for an existing group.
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 result | Returned mappings |
|---|---|
| All accounts already exist | No lazilyProvisionedAccounts key. |
| New card under an existing cardholder/group | card only. |
| New cardholder under an existing group | cardholder, plus card for purchase intake. |
| New cardholder and group | cardholderGroup, cardholder, plus card for purchase intake. |
| Retry after accounts were already created | No 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.
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"
}
}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.