Branded balance and cashback can be earned by the same transaction, but they remain separate products in API responses and reconciliation.
Branded balance is merchant-scoped. A cardholder can spend a branded balance only with the merchant that created it and only after the balance is available.
Visual Brand Reward Lifecycle
Each branded balance earn creates or updates RewardGrant buckets. RewardGrant data is exposed so integrators can audit availability, expiry, and partial consumption.
| Bucket | Meaning |
|---|---|
originalAmountMinor | Original earned amount. |
earnedUnavailableAmountMinor | Earned value that cannot be spent yet. |
availableAmountMinor | Value currently eligible to spend, subject to merchant rules. |
spentAmountMinor | Value already consumed. |
clawedBackAmountMinor | Value reversed by a clawback. |
expiredAmountMinor | Value expired before spend. |
remainingAmountMinor | Unspent, unclawed, unexpired value remaining in the grant. |
Earned branded balance can be held unavailable for a configured availability delay before it is spend eligible. The availableAt timestamp is the time when the earned value becomes eligible to spend, assuming the grant has not expired, been spent, or been clawed back.
Two minimum-availability controls can apply:
- Issuer minimum availability delay: the issuer can require branded balance to remain unavailable for a global minimum amount of time after earn.
- Merchant minimum availability delay: a merchant can require its branded balance to remain unavailable for a merchant-specific minimum amount of time after earn.
When both controls apply, the greater delay wins. For example, if the issuer minimum is 2 days and the merchant minimum is 5 days, the grant uses the merchant delay and becomes available after 5 days. If the issuer minimum is 7 days and the merchant minimum is 3 days, the grant uses the issuer delay and becomes available after 7 days.
The issuer minimum availability delay also controls whether the issuer is floating branded balance value before receiving payout to cover that value. If branded balance becomes available before the periodic payout that funds the earned value, the issuer is effectively covering that float. If the issuer minimum availability delay is the same length as, or longer than, the periodic payout window, branded balance does not become spendable before the covering payout is expected, so availability timing does not create issuer float.
The API exposes the resulting availableAt timestamp on RewardGrant data. Eligibility responses can include issuer_delay_not_satisfied or merchant_delay_not_satisfied when the relevant minimum availability delay has not elapsed.
The expiresAt timestamp appears when the grant expires. A grant can be partial when only some value remains or only some value was consumed.
An available branded balance can be partially spent. After a partial spend, the RewardGrant can still have remainingAmountMinor, and that remaining unspent balance can still expire or be clawed back later. A full spend moves the grant into a fully consumed state, but the spent amount remains auditable and can still be reversed by a spent-balance clawback.
There are two clawback paths:
| Clawback path | Issuer handling |
|---|---|
| Unspent balance clawback | Preferred path. Percents prioritizes clawing back unspent available balance before reversing previously spent balance. No cardholder-level account action is required from the issuer because the cardholder has not received an statement credit for the unspent branded balance. |
| Spent balance clawback | Used when there is no unspent balance available to claw back. Percents does not support negative branded balances, so this requires the issuer to post a statement debit against the cardholder account to reverse the earlier branded balance statement credit. |
If one reversal spans both cases, process the unspent balance clawback first and apply cardholder account action only for the spent portion that cannot be covered by remaining unspent branded balance.
Cashback appears in the cashback section of reward summaries. Cashback does not become merchant-scoped branded balance and should not be added to merchant balance totals.
When branded balance is spent, the issuer should represent the posted branded balance spend as an statement credit on the cardholder account in the issuer platform. The credit should be tied back to the corresponding transaction, reward event, and webhook so support and reconciliation workflows can explain why the statement credit was created.
Cardholder rewards are the consumer-facing amounts shown as branded balance and cashback. Issuer commissions are separate records that may be created from the same qualifying activity when supported by the program.
Public reconciliation uses the related source events, reward events, and RewardGrant buckets.