Authorization estimates and settlement rewards support different customer messages: early feedback and the amount actually awarded. Follow the purchase through these stages to understand when notifications arrive, how to handle ordering and when to look up the current result. These foundations apply to both cashback and branded rewards.
Send authorization data to POST /api/v2/incoming-auth if real-time notifications and updates are a requirement. A qualified approved authorization can produce a qualified_auth webhook. Its reward calculation uses the amount supplied with that authorization. It is an estimate, not an awarded settlement reward. Declined authorizations do not earn rewards.
For a 5% offer, subject to the earn cap:
| Purchase stage | Purchase amount | Reward |
|---|---|---|
| Authorization | $50.00 | $2.50 estimate |
| Settlement | $60.00 | $3.00 awarded |
Do not add the authorization estimate to the settlement reward.
If an authorization arrives or is processed after its settlement, Percents does not send an authorization webhook. The settlement result takes precedence.
Send settled purchase data to POST /api/v2/incoming-txn. A settlement can arrive with or without an authorization, including a force capture. A qualified_settlement webhook reports the actual amount awarded for that purchase, calculated from the submitted settlement amount and applicable offer conditions.
Percents sends a notification only when a purchase qualifies to earn or spend rewards:
- Earned rewards are included only when the purchase qualifies.
- Branded purchases can report tentative spending at authorization and actual spending at settlement, even when they earn nothing.
- A purchase before required offer activation produces no earn notification. Activation applies to subsequent purchases only.
When an earned reward is included, both webhook types include the applied cardholderEarnRate and maxEarnAmountMinor so your customer message reflects the calculation. The authorization estimate must never overwrite an awarded settlement result. There are no issuer-payment notifications.
The webhook guide defines the common schema, signature verification and retry handling. If a notification is missing or arrives out of order, look up the current result using your original purchase ID: cashback purchase lookup or branded purchase lookup. Lookup does not create accounts or rewards.
Branded rewards also have a merchant balance lifecycle after earning: value becomes available, can be spent and may expire or be clawed back. See the branded lifecycle for more details.