A branded purchase can earn merchant value, spend an existing balance or be affected by a later clawback. Use purchase lookup, transaction reward detail and merchant balances to explain those outcomes and show what the cardholder can spend next.
GET <env-host>/api/v2/transaction/resolve?externalId=issuer-txn-001
GET <env-host>/api/v2/authorization/resolve?externalId=issuer-auth-001The settlement lookup and authorization lookup return the public source ID and current processing result. Percent encode the external ID once.
| Status | Meaning and next action |
|---|---|
pending | Check again later. |
processed | The result is ready. |
failed | Inspect the returned error before retrying. |
Missing or inaccessible purchases return 404. These reads do not create accounts or rewards.
A processed result can have reward: null while still having spent branded balance. Use the returned txn_ ID for the detail reads below. Do not treat a null earned reward as proof that no value was spent.
| Route | Use |
|---|---|
GET /api/v2/chg/{chgId}/rewards/summary | Branded balance totals, with amounts earned, available, spent and expired. |
GET /api/v2/chg/{chgId}/rewards/activity | Branded earning, spending, expiry and clawback activity visible to customers. |
GET /api/v2/chg/{chgId}/rewards/expiring | Branded value nearing expiry. |
GET /api/v2/chg/{chgId}/merchant/{merchantId}/balance | One merchant's branded balance and grant detail. |
GET /api/v2/chg/{chgId}/transaction/{txnId}/reward-detail | Result of one settlement. |
POST /api/v2/chg/{chgId}/transactions/reward-overviews | Results for multiple public transaction IDs. |
curl --fail-with-body -X GET 'https://sandbox.percents.com/api/v2/chg/chg_22222222-2222-4222-8222-222222222222/merchant/mp_55555555-5555-4555-8555-555555555555/balance' \
-H 'Authorization: token tok_11111111-1111-4111-8111-111111111111:api_test_secret'For overview requests, use the exact request body from the API reference.
The merchant balance summary shows earned value by its current status. For example, a cardholder who earned $12.50 and then spent $2.50 has $10.00 remaining and available:
{
"originalAmountMinor": 1250,
"earnedUnavailableAmountMinor": 0,
"availableAmountMinor": 1000,
"spentAmountMinor": 250,
"clawedBackAmountMinor": 0,
"expiredAmountMinor": 0,
"remainingAmountMinor": 1000
}These are the response's amountBuckets. The original amount equals the sum of unavailable, available, spent, clawed back and expired amounts. Remaining value is unavailable plus available value. The merchant balance detail also lists the grants that make up those totals. Use canSpendNow and spendRestrictionReasons to decide what spend action to show. Activation belongs to offer eligibility.
Keep these records:
- Issuer and Percents source IDs.
- Group mapping and selected offer.
- Webhook ID, type and receive time.
- Signature verification result.
- Status of any customer statement action.
Use each webhook ID once. A replay should receive success if it was already durably processed. Compare branded grant amounts with merchant balance totals and retain the distinction between partial spending and partial reversal.
Branded spending and a resulting statement credit are separate steps. Record your institution's actual statement action so a replay cannot produce another credit.
For refunds, use the reported balance clawback and issuer debit for spent value rather than inferring an outcome. Each issuer chooses how to handle its cost, such as a statement debit, absorbing it, or another approach. We recommend a statement debit but do not require it. Record any chosen account action once.
Expiry alone does not create this issuer debit. See branded lifecycle for how it may offset an issuer payment or a later cardholder reward at that merchant.
Transaction reward detail reports spentAmountMinor and any refund shortfallAmountMinor. The merchant balance reports the value currently available and its grants. A reward grant uses an rg_ ID. It represents earned branded value, not the purchase itself.
Use identity lookup to read current account mappings after a lost creation response. Lookup does not create accounts or return a lazy provisioning key.