{"templateId":"markdown","versions":[{"version":"2.0","label":"v2.0","link":"/percents-api/cashback/webhooks","default":true,"active":true,"folderId":"27d36c3a"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Cashback webhooks"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"cashback-webhooks","__idx":0},"children":["Cashback webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/auth-security/webhooks#standard-webhook-schema"},"children":["standard webhook schema"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authorization-estimate","__idx":1},"children":["Authorization estimate"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/reward-lifecycle"},"children":["reward lifecycle"]}," explains qualification and ordering, including why no authorization webhook is sent after settlement."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"webhookId\": \"evt_cccccccc-cccc-4ccc-8ccc-cccccccccccc\",\n  \"type\": \"qualified_auth\",\n  \"data\": {\n    \"source\": {\n      \"externalId\": \"issuer-auth-001\",\n      \"percentsId\": \"auth_77777777-7777-4777-8777-777777777777\"\n    },\n    \"cardholderGroupId\": \"chg_22222222-2222-4222-8222-222222222222\",\n    \"reward\": {\n      \"merchantId\": \"mp_55555555-5555-4555-8555-555555555555\",\n      \"offerId\": \"mpo_66666666-6666-4666-8666-666666666666\",\n      \"currency\": \"usd\",\n      \"amountMinor\": 250,\n      \"maxEarnAmountMinor\": 400,\n      \"rewardProductType\": \"cashback\",\n      \"cardholderEarnRate\": {\n        \"kind\": \"basis_points\",\n        \"basisPoints\": 500\n      }\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The amount is calculated using the authorization amount submitted. The example uses a $50 authorization at 5%, capped at $4."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"settlement-reward","__idx":2},"children":["Settlement reward"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"webhookId\": \"evt_dddddddd-dddd-4ddd-8ddd-dddddddddddd\",\n  \"type\": \"qualified_settlement\",\n  \"data\": {\n    \"source\": {\n      \"externalId\": \"issuer-txn-001\",\n      \"percentsId\": \"txn_99999999-9999-4999-8999-999999999999\"\n    },\n    \"cardholderGroupId\": \"chg_22222222-2222-4222-8222-222222222222\",\n    \"reward\": {\n      \"merchantId\": \"mp_55555555-5555-4555-8555-555555555555\",\n      \"offerId\": \"mpo_66666666-6666-4666-8666-666666666666\",\n      \"currency\": \"usd\",\n      \"amountMinor\": 250,\n      \"maxEarnAmountMinor\": 400,\n      \"rewardProductType\": \"cashback\",\n      \"cardholderEarnRate\": {\n        \"kind\": \"basis_points\",\n        \"basisPoints\": 500\n      }\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"fields-and-handling","__idx":3},"children":["Fields and handling"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]},": your submitted purchase ID and its Percents ID, for purchase correlation and lookup."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardholderGroupId"]},": identifies the group receiving the reward."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["segmentSource"]}," may appear inside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward"]}," to explain whether selection used purchase history, a policy-based fallback or an unsegmented offer. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/merchant-segments#understand-the-selection-result"},"children":["Offer Segments and Purchase History"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lazilyProvisionedAccounts"]}," appears only when this purchase created accounts, and contains only those accounts. Store their external and Percents ID mappings."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Verify the signature and deduplicate each delivery using the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/auth-security/webhooks#deduplication-ordering-and-acknowledgement"},"children":["webhook handling rules"]},". When you need to verify the current outcome, use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/cashback/reconciliation"},"children":["purchase lookup"]}," with the purchase ID from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For recovery without routine cashback clawback webhooks, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/transaction-ingestion/settlements#report-refunds-and-disputes"},"children":["fraud and abuse follow-up"]},"."]}]},"headings":[{"value":"Cashback webhooks","id":"cashback-webhooks","depth":1},{"value":"Authorization estimate","id":"authorization-estimate","depth":2},{"value":"Settlement reward","id":"settlement-reward","depth":2},{"value":"Fields and handling","id":"fields-and-handling","depth":2}],"frontmatter":{"title":"Cashback webhooks","description":"Qualified authorization estimates and settled purchase rewards.","seo":{"title":"Cashback webhooks"}},"lastModified":"2026-11-10T20:25:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/percents-api/cashback/webhooks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}