Cashback notifications let your wallet show estimated earnings at authorization and awarded cashback at settlement. Use the event types and payloads below to connect each reward to the cardholder and purchase, then update customer messaging as the result changes. Both types follow the standard webhook schema.
The reward lifecycle explains qualification and ordering, including why no authorization webhook is sent after settlement.
{
"webhookId": "evt_cccccccc-cccc-4ccc-8ccc-cccccccccccc",
"type": "qualified_auth",
"data": {
"source": {
"externalId": "issuer-auth-001",
"percentsId": "auth_77777777-7777-4777-8777-777777777777"
},
"cardholderGroupId": "chg_22222222-2222-4222-8222-222222222222",
"reward": {
"merchantId": "mp_55555555-5555-4555-8555-555555555555",
"offerId": "mpo_66666666-6666-4666-8666-666666666666",
"currency": "usd",
"amountMinor": 250,
"maxEarnAmountMinor": 400,
"rewardProductType": "cashback",
"cardholderEarnRate": {
"kind": "basis_points",
"basisPoints": 500
}
}
}
}The amount is calculated using the authorization amount submitted. The example uses a $50 authorization at 5%, capped at $4.
{
"webhookId": "evt_dddddddd-dddd-4ddd-8ddd-dddddddddddd",
"type": "qualified_settlement",
"data": {
"source": {
"externalId": "issuer-txn-001",
"percentsId": "txn_99999999-9999-4999-8999-999999999999"
},
"cardholderGroupId": "chg_22222222-2222-4222-8222-222222222222",
"reward": {
"merchantId": "mp_55555555-5555-4555-8555-555555555555",
"offerId": "mpo_66666666-6666-4666-8666-666666666666",
"currency": "usd",
"amountMinor": 250,
"maxEarnAmountMinor": 400,
"rewardProductType": "cashback",
"cardholderEarnRate": {
"kind": "basis_points",
"basisPoints": 500
}
}
}
}The example uses a $50 settlement at the same rate and cap. The reward can differ from the authorization estimate, especially if the purchase amount changes. Use the settlement reward for the settled purchase. Do not add the authorization estimate.
source: your submitted purchase ID and its Percents ID, for purchase correlation and lookup.cardholderGroupId: identifies the group receiving the reward.reward: qualified amount, currency, merchant, offer, earn rate and maximum earn cap. Use the embedded rate and cap for reward messaging. Null cap means uncapped.segmentSourcemay appear insiderewardto explain whether selection used purchase history, a policy-based fallback or an unsegmented offer. See Offer Segments and Purchase History.lazilyProvisionedAccountsappears only when this purchase created accounts, and contains only those accounts. Store their external and Percents ID mappings.
Verify the signature and deduplicate each delivery using the webhook handling rules. When you need to verify the current outcome, use purchase lookup with the purchase ID from source.
For recovery without routine cashback clawback webhooks, see fraud and abuse follow-up.