{"templateId":"markdown","versions":[{"version":"2.0","label":"v2.0","link":"/percents-api/branded-rewards/webhooks","default":true,"active":true,"folderId":"27d36c3a"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Branded rewards webhooks"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"branded-rewards-webhooks","__idx":0},"children":["Branded rewards webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Branded reward notifications let your wallet explain earned merchant value, spending and clawbacks. Use the payloads below to distinguish authorization estimates from settled amounts and identify when to update balances or apply a customer statement credit. Every event follows 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":"qualified-outcomes","__idx":1},"children":["Qualified Outcomes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authorization and settlement notifications can contain ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spend"]}," or both. Each field is omitted when it does not apply, and no notification is sent when neither applies. A purchase before required earning activation produces no earn notification. Branded spending can still qualify without new earnings."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"earning-after-branded-spending","__idx":2},"children":["Earning After Branded Spending"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a purchase both spends branded balance and earns new rewards, the earning calculation subtracts the branded spending from the purchase amount. Available balance that is not applied to the purchase is not deducted."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Webhook"},"children":["Webhook"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Amount used to calculate new earnings"},"children":["Amount used to calculate new earnings"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"How to use the result"},"children":["How to use the result"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["qualified_auth"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authorization amount minus tentative ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.spend.amountMinor"]},", when present."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.reward.amountMinor"]}," as an estimate. No balance is consumed and no spend credit should be applied yet."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["qualified_settlement"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Settlement amount minus ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.spend.amountMinor"]}," actually consumed, when present."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.reward.amountMinor"]}," as the awarded reward and the separate spending amount for the customer statement credit."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A $105 purchase with $5 applied at 10% (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1000"]}," basis points) earns $10 on the remaining $100, assuming the offer qualifies and no cap reduces the reward. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/reward-lifecycle#how-spending-branded-balance-changes-new-earnings"},"children":["calculation example"]}," and its ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/reward-lifecycle#settlement-webhook-for-this-example"},"children":["matching settlement webhook"]},". Use the settlement result if the purchase amount or branded spending differs from the authorization estimate."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authorization-estimate","__idx":3},"children":["Authorization estimate"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["qualified_auth"]}," can include an estimated reward and tentative spending. It uses the submitted authorization amount and purchase time. No balance is consumed at authorization, and the issuer must wait for settlement before applying a spend credit. An authorization arriving or processed after settlement produces no auth webhook."]},{"$$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    \"spend\": {\n      \"merchantId\": \"mp_55555555-5555-4555-8555-555555555555\",\n      \"currency\": \"usd\",\n      \"amountMinor\": 100\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This purchase has a tentative $1 spend and no new earn. When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward"]}," is present, it includes the applied ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardholderEarnRate"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["maxEarnAmountMinor"]}," for customer messaging."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"settlement-outcome","__idx":4},"children":["Settlement outcome"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["qualified_settlement"]}," reports the actual earned reward and any branded balance actually consumed. Apply ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.spend.amountMinor"]}," once as the customer statement credit. If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spend"]}," is absent, there is no spend credit to apply. A purchase before required earning activation can still spend eligible existing value. Its notification omits ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"webhookId\": \"evt_eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee\",\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\": 245,\n      \"maxEarnAmountMinor\": 400,\n      \"rewardProductType\": \"branded_balance\",\n      \"cardholderEarnRate\": {\n        \"kind\": \"basis_points\",\n        \"basisPoints\": 500\n      }\n    },\n    \"spend\": {\n      \"merchantId\": \"mp_55555555-5555-4555-8555-555555555555\",\n      \"currency\": \"usd\",\n      \"amountMinor\": 100\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This $50 purchase spends $1 of existing value and earns $2.45 on the remaining $49 at 5%, below the $4 cap. Settlement can differ from the authorization estimate. Do not add estimates to actual amounts or apply a second credit from an authorization webhook. Omit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward"]}," entirely for a settlement that only spends balance. No offer ID, earn rate or cap is needed for spending alone."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Spending consumes eligible branded grants in order of expiry, using the grant that expires soonest first. A valid authorization time within the spend window is honored even when settlement arrives after expiry. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/reward-lifecycle#authorization-time-and-delayed-settlement"},"children":["branded lifecycle"]}," for more details."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lazilyProvisionedAccounts"]}," appears only when this purchase created accounts and contains only the new mappings to store. Earn details can include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["segmentSource"]}," to distinguish purchase history, a policy-based fallback and 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":"Heading","attributes":{"level":2,"id":"supported-branded-reversal","__idx":5},"children":["Supported branded reversal"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["earnedAmountReversedMinor"]}," is the value clawed back from the cardholder's branded balance. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shortfallAmountMinor"]}," is the debit against the issuer because previously spent value could not be clawed back. Expiry does not create this shortfall."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"webhookId\": \"evt_aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\n  \"type\": \"clawback\",\n  \"data\": {\n    \"source\": {\n      \"externalId\": \"issuer-refund-001\",\n      \"percentsId\": \"txn_99999999-9999-4999-8999-999999999999\"\n    },\n    \"cardholderGroupId\": \"chg_22222222-2222-4222-8222-222222222222\",\n    \"merchantId\": \"mp_55555555-5555-4555-8555-555555555555\",\n    \"currency\": \"usd\",\n    \"earnedAmountReversedMinor\": 50,\n    \"shortfallAmountMinor\": 200\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this $2.50 clawback:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Amount"},"children":["Amount"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Outcome"},"children":["Outcome"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["$0.50 remaining balance"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Removed from the branded balance."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["$2 already spent"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reported as an issuer debit."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The debit may be applied against the issuer's next payment or a later reward earned by the cardholder at this merchant."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The issuer chooses how to handle its cost: a statement debit, absorbing it or another approach. We recommend a $2 statement debit but do not require it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the missing $2 had expired instead, it would not create this issuer debit."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhookId"]}," to prevent duplicate account actions."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Verify ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/auth-security/webhooks"},"children":["signatures and delivery IDs"]}," before applying any account action. Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/reconciliation"},"children":["current balances and purchase lookup"]}," when a notification is missing or arrives out of order."]}]},"headings":[{"value":"Branded rewards webhooks","id":"branded-rewards-webhooks","depth":1},{"value":"Qualified Outcomes","id":"qualified-outcomes","depth":2},{"value":"Earning After Branded Spending","id":"earning-after-branded-spending","depth":2},{"value":"Authorization estimate","id":"authorization-estimate","depth":2},{"value":"Settlement outcome","id":"settlement-outcome","depth":2},{"value":"Supported branded reversal","id":"supported-branded-reversal","depth":2}],"frontmatter":{"title":"Branded rewards webhooks","description":"Authorization estimates, settlement earning and spending, and supported reversals.","seo":{"title":"Branded rewards webhooks"}},"lastModified":"2026-11-10T20:25:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/percents-api/branded-rewards/webhooks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}