{"templateId":"markdown","versions":[{"version":"2.0","label":"v2.0","link":"/percents-api/branded-rewards/quickstart","default":true,"active":true,"folderId":"27d36c3a"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["code-group"]},"type":"markdown"},"seo":{"title":"Branded Rewards Quickstart"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"branded-rewards-quickstart","__idx":0},"children":["Branded Rewards Quickstart"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Branded rewards let cardholders earn value at a merchant and spend it there on later purchases. Follow this walkthrough to authenticate, present and activate an offer, submit a purchase, handle reward outcomes and display merchant balances. You can build the wallet interface yourself or use the optional SDK linked at the end."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication","__idx":1},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Percents provisions your issuer API credential and provides it securely. Keep it on your server and include it in every API request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"Authorization: token <tok_id>:<api_secret>\n","lang":"http"},"children":[]},{"$$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":"Environment"},"children":["Environment"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Host"},"children":["Host"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Testing"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://sandbox.percents.com"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Production"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://prod.percents.com"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Replace ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<env-host>"]}," in this guide with the correct host and use the credential for that environment. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/auth-security/authentication"},"children":["API authentication"]}," for setup and access requirements."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"register-accounts-when-you-need-them","__idx":2},"children":["Register Accounts When You Need Them"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/cardholder-groups#explicit-setup"},"children":["register cardholder accounts first"]},", or let Percents create missing accounts when it receives a new external cardholder or card ID. This guide uses lazy provisioning. A cardholder group holds rewards for one cardholder or several who share an account."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lazilyProvisionedAccounts"]}," when returned. It maps your internal IDs to Percents IDs and contains only accounts created by that request. Use the group mapping to connect webhook ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.cardholderGroupId"]}," to your customer."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For testing, use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/overview/sandbox#merchant-ids-on-purchase-events"},"children":["sandbox merchant setup"]},". Keep its matching override out of production."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-present-an-offer","__idx":3},"children":["1. Present an Offer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Read ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/merchant-activation-eligibility#general-offers"},"children":["general offers"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET <env-host>/api/v2/offers\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Choose a live offer with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rewardProductType: branded_balance"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["activationType: CLICK"]},". Show its rate and terms to the cardholder. Use its actual offer ID in step 2."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Request pages with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageSize"]},". Continue while ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hasNextPage"]}," is true. Stop if no suitable offer is available. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/merchant-activation-eligibility#targeted-offers-and-merchant-eligibility"},"children":["offer guide"]}," explains offers for a specific customer after accounts have been registered."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The purchase in step 3 must be at the selected offer's merchant and meet its dates, activation requirement and terms. Selecting an offer alone does not make a purchase qualify."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-record-the-cardholders-click","__idx":4},"children":["2. Record the Cardholder's Click"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After the cardholder clicks the offer, send the click to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/recordExternalCardholderUserActivity"},"children":["activity endpoint"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST <env-host>/api/v2/cardholder/external/issuer-cardholder-001/user-activity\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"events\": [\n    {\n      \"eventId\": \"issuer-activity-001\",\n      \"offerId\": \"mpo_66666666-6666-4666-8666-666666666666\",\n      \"occurredAt\": \"2026-07-01T18:41:00.000Z\",\n      \"type\": \"CLICK\",\n      \"clickFlavor\": \"ACTIVATE\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the time of the real click. Do not send a click just because an offer was displayed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A new cardholder gets ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lazilyProvisionedAccounts"]},". Save those ID mappings."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An existing cardholder gets ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204 No Content"]},". This call does not need or create a card."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This example uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLICK"]},". ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/user-activity#view-events"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIEW"]}," offers accept clicks or qualifying visibility events"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PASSIVE"]}," offers need no activation. Still report observed views and clicks for engagement measurement. Branded ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ONE_TIME"]}," offers use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/merchant-activation-eligibility#branded-merchant-activation"},"children":["merchant activation"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3-submit-the-settled-purchase","__idx":5},"children":["3. Submit the Settled Purchase"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the purchase settles, send the purchase and card details:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST <env-host>/api/v2/incoming-txn\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"issuer-txn-001\",\n  \"amount\": 5000,\n  \"currency\": \"usd\",\n  \"merchantDescriptor\": \"Example Coffee\",\n  \"merchantId\": \"processor-merchant-001\",\n  \"mcc\": \"5814\",\n  \"createdAt\": \"2026-07-01T18:42:00.000Z\",\n  \"authTimestamp\": \"2026-07-01T18:41:30.000Z\",\n  \"cardholderId\": \"issuer-cardholder-001\",\n  \"cardId\": \"issuer-card-001\",\n  \"cardLast4\": \"4242\",\n  \"cardBIN\": \"411111\",\n  \"physical\": true,\n  \"billingZip\": \"10001\",\n  \"network\": \"visa\",\n  \"authMethod\": \"contactless\",\n  \"authCode\": \"123456\",\n  \"arn\": \"12345678901234567890123\",\n  \"state\": \"settled\",\n  \"merchantAddressStreet\": \"123 Main Street\",\n  \"merchantAddressCity\": \"New York\",\n  \"merchantAddressState\": \"NY\",\n  \"merchantAddressCountry\": \"US\",\n  \"merchantAddressZip\": \"10001\",\n  \"merchantLat\": \"40.7128\",\n  \"merchantLong\": \"-74.0060\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Replace the sample values with actual event times and purchase details:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5000"]}," means $50.00 USD."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the same external cardholder ID as step 2."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep the purchase ID when retrying the same event. Use a new ID for a different purchase."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantId"]}," is the network or processor's ID, not a catalog ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mp_"]}," ID."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include the original authorization ID as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalAuthId"]}," when you sent that authorization."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For shared accounts, follow the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/cardholder-groups#lazy-provisioning"},"children":["group identity rules"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save any new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lazilyProvisionedAccounts"]}," mappings. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/recordIncomingTxn"},"children":["settlement reference"]}," for required fields and additional purchase details, and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/transaction-ingestion/settlements#report-refunds-and-disputes"},"children":["refund and dispute reporting"]}," for later events."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send authorizations if real-time notifications and updates are a requirement. Use the resulting estimates for early customer feedback and the settlement result for the actual reward. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/reward-lifecycle"},"children":["reward lifecycle"]}," for details."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"4-listen-for-reward-webhooks","__idx":6},"children":["4. Listen for Reward Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["qualified_settlement"]}," webhook reports earned merchant value, available branded balance spent on the purchase, or both. A purchase can spend balance without earning a new reward."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Display the reported earned reward for the customer identified by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.cardholderGroupId"]},", using your saved group mapping. Earned value may become available later. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/reward-lifecycle"},"children":["branded lifecycle"]}," for more details."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spend"]}," is present, apply ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spend.amountMinor"]}," as a customer statement credit once per ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.source.percentsId"]},", the Percents settlement ID."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the $50 purchase submitted as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["issuer-txn-001"]},", suppose the cardholder has $1 of eligible existing merchant balance. Spending that $1 leaves $49 eligible to earn at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}," basis points (5%). The result is $2.45 of new merchant value, below the $4 cap, and a separate $1 statement credit for the balance spent."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webhook excerpt"]}," — selected fields from the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/webhooks#settlement-outcome"},"children":["full branded settlement example"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"qualified_settlement\",\n  \"data\": {\n    \"source\": { \"externalId\": \"issuer-txn-001\" },\n    \"reward\": {\n      \"rewardProductType\": \"branded_balance\",\n      \"currency\": \"usd\",\n      \"amountMinor\": 245,\n      \"cardholderEarnRate\": { \"kind\": \"basis_points\", \"basisPoints\": 500 },\n      \"maxEarnAmountMinor\": 400\n    },\n    \"spend\": { \"currency\": \"usd\", \"amountMinor\": 100 }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Show the $2.45 earned in the merchant wallet, with its availability timing. Apply the $1 settled spending as a customer statement credit. A cardholder without an eligible existing balance receives no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spend"]}," field and no spend credit."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/auth-security/webhooks"},"children":["webhook setup and delivery"]}," for receiving these notifications."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Only qualifying outcomes produce a notification. If a result is missing, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/reconciliation"},"children":["look up the purchase"]}," using your original purchase ID. Follow the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/webhooks#supported-branded-reversal"},"children":["branded webhook guide"]}," for later clawbacks, balance deductions and issuer debits."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"5-show-wallet-balances-and-usage","__idx":7},"children":["5. Show Wallet Balances and Usage"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Give cardholders a view of what they have earned, what is ready to spend and what they have used at each merchant. Read ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/getBalances"},"children":["merchant balance summaries"]}," with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/getBalances"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v2/chg/{chgId}/balances"]}]},". Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/getBalanceDetails"},"children":["merchant balance details"]}," for a closer view of earned, available, spent and expired value."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Show available balance separately from pending value. Refresh balances after reward notifications and when the cardholder opens the wallet. The example below shows merchant cards with available balances and a separate pending amount. It illustrates a possible layout, not live balances or guaranteed merchant availability."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/branded-wallet-example.6a205b2606b8b7f911f12d6d02b24bc6114e033190cb37b708bf9cdd41afba70.de6e0f62.png","alt":"Example branded wallet showing merchant balances and a separate pending reward amount"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"full-quickstart-script","__idx":8},"children":["Full Quickstart Script"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These pseudocode examples show every applicable request field, including optional fields, in seven languages. They are not a Percents SDK and omit imports, HTTP client setup and a web server."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The examples use an internal group ID to keep the cardholder in the same group across activity and purchases. Omit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCardholderGroupId"]}," if you rely on the default lazy assignment. Include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalAuthId"]}," when the original authorization ID is available. Supply optional merchant details, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authCode"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arn"]}," from your purchase data when available. Do not invent missing values."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Implement these helpers in your application:"]},{"$$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":"Helper"},"children":["Helper"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it does"},"children":["What it does"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Uses your host and issuer credential. Parses JSON, handles empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204"]}," responses and stops on HTTP errors or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["207"]}," batch failures."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["findOffer"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Starts with the URL shown and increments ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]},", keeping ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageSize"]},", until it finds a live offer for the selected product and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLICK"]}," policy. Stops if there is no match."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accounts.saveCreated"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Saves mappings from external IDs to Percents IDs when present. Does nothing when the key is absent."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook.listen"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delivers events to your handler using the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/auth-security/webhooks"},"children":["shared webhook setup and delivery rules"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wallet"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Displays offers, earned rewards and merchant balance summaries in your wallet."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["statements.creditOnce"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Applies the reported branded spending as a statement credit, once per settlement ID."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Optional field access (such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["optional(...)"]}," in Python) returns no value when a key is absent. Helper names follow each language's style. Replace sample IDs and times with real events and percent encode external IDs in URLs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The settlement handler processes earning and spending. Add the clawback handler from the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/webhooks#supported-branded-reversal"},"children":["branded webhook guide"]}," for the full refund workflow."]},{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"tabs"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","data-title":"TypeScript","header":{"title":"TypeScript","controls":{"copy":{}}},"source":"// Authentication: configure api on your server with the environment host and securely provided issuer credential.\nconst PRODUCT = \"branded_balance\"\n\n// 1. Present a live CLICK offer. Stop if none is available.\nconst offer = await api.findOffer(\"/api/v2/offers?page=1&pageSize=25\", PRODUCT, \"CLICK\")\nwallet.showOffer(offer)\n\n// 2. Send this only after the cardholder really clicks the offer.\nconst activity = await api.post(\n  \"/api/v2/cardholder/external/issuer-cardholder-001/user-activity\",\n  { externalCardholderGroupId: \"issuer-group-001\", events: [{ eventId: \"issuer-activity-001\", offerId: offer.id,\n    type: \"CLICK\", clickFlavor: \"ACTIVATE\", occurredAt: \"2026-07-01T18:41:00.000Z\" }] }\n)\naccounts.saveCreated(activity?.lazilyProvisionedAccounts)\n\n// 4. Use qualified settlement outcomes to update the customer wallet.\nwebhook.listen(\"qualified_settlement\", event => {\n  if (event.data.reward?.rewardProductType === PRODUCT) {\n    wallet.showEarnedReward(event.data.cardholderGroupId, event.data.reward)\n  }\n  if (event.data.spend) {\n    statements.creditOnce(event.data.source.percentsId, event.data.spend)\n  }\n})\n\n// 3. Send the actual purchase after settlement. Reuse this ID for retries.\n// Include optional fields only when available in your purchase data.\nconst purchase = {\n  \"id\": \"issuer-txn-001\", \"amount\": 5000,\n  \"currency\": \"usd\", \"merchantDescriptor\": \"Example Coffee\",\n  \"merchantId\": \"processor-merchant-001\", \"mcc\": \"5814\",\n  \"createdAt\": \"2026-07-01T18:42:00.000Z\", \"authTimestamp\": \"2026-07-01T18:41:30.000Z\",\n  \"cardholderId\": \"issuer-cardholder-001\", \"cardId\": \"issuer-card-001\",\n  \"cardLast4\": \"4242\", \"cardBIN\": \"411111\",\n  \"physical\": true, \"billingZip\": \"10001\",\n  \"network\": \"visa\", \"authMethod\": \"contactless\",\n  \"externalCardholderGroupId\": \"issuer-group-001\",\n  \"externalAuthId\": \"issuer-auth-001\",\n  \"authCode\": \"123456\",\n  \"arn\": \"12345678901234567890123\",\n  \"merchantAddressStreet\": \"123 Main Street\",\n  \"merchantAddressCity\": \"New York\",\n  \"merchantAddressState\": \"NY\",\n  \"merchantAddressCountry\": \"US\",\n  \"merchantAddressZip\": \"10001\",\n  \"merchantLat\": \"40.7128\",\n  \"merchantLong\": \"-74.0060\",\n  \"state\": \"settled\"\n}\nconst result = await api.post(\"/api/v2/incoming-txn\", purchase)\naccounts.saveCreated(result?.lazilyProvisionedAccounts)\n\n// 5. On wallet open or after a reward notification, use the saved Percents group ID.\nconst balances = await api.get(`/api/v2/chg/${cardholderGroupId}/balances`)\nwallet.showBalances(balances)\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","data-title":"Python","header":{"title":"Python","controls":{"copy":{}}},"source":"# Authentication: configure api on your server with the environment host and securely provided issuer credential.\nPRODUCT = \"branded_balance\"\n\n# 1. Present a live CLICK offer. Stop if none is available.\noffer = api.find_offer(\"/api/v2/offers?page=1&pageSize=25\", PRODUCT, \"CLICK\")\nwallet.show_offer(offer)\n\n# 2. Send this only after the cardholder really clicks the offer.\nactivity = api.post(\n    \"/api/v2/cardholder/external/issuer-cardholder-001/user-activity\",\n    {\"externalCardholderGroupId\": \"issuer-group-001\", \"events\": [{\"eventId\": \"issuer-activity-001\", \"offerId\": offer.id,\n      \"type\": \"CLICK\", \"clickFlavor\": \"ACTIVATE\", \"occurredAt\": \"2026-07-01T18:41:00.000Z\"}]}\n)\naccounts.save_created(optional(activity, \"lazilyProvisionedAccounts\"))\n\n# 4. Use qualified settlement outcomes to update the customer wallet.\ndef on_settlement(event):\n    if optional(event.data, \"reward\") and event.data.reward.rewardProductType == PRODUCT:\n        wallet.show_earned_reward(event.data.cardholderGroupId, event.data.reward)\n    if optional(event.data, \"spend\"):\n        statements.credit_once(event.data.source.percentsId, event.data.spend)\n\nwebhook.listen(\"qualified_settlement\", on_settlement)\n\n# 3. Send the actual purchase after settlement. Reuse this ID for retries.\n# Include optional fields only when available in your purchase data.\npurchase = {\n  \"id\": \"issuer-txn-001\", \"amount\": 5000,\n  \"currency\": \"usd\", \"merchantDescriptor\": \"Example Coffee\",\n  \"merchantId\": \"processor-merchant-001\", \"mcc\": \"5814\",\n  \"createdAt\": \"2026-07-01T18:42:00.000Z\", \"authTimestamp\": \"2026-07-01T18:41:30.000Z\",\n  \"cardholderId\": \"issuer-cardholder-001\", \"cardId\": \"issuer-card-001\",\n  \"cardLast4\": \"4242\", \"cardBIN\": \"411111\",\n  \"physical\": True, \"billingZip\": \"10001\",\n  \"network\": \"visa\", \"authMethod\": \"contactless\",\n  \"externalCardholderGroupId\": \"issuer-group-001\",\n  \"externalAuthId\": \"issuer-auth-001\",\n  \"authCode\": \"123456\",\n  \"arn\": \"12345678901234567890123\",\n  \"merchantAddressStreet\": \"123 Main Street\",\n  \"merchantAddressCity\": \"New York\",\n  \"merchantAddressState\": \"NY\",\n  \"merchantAddressCountry\": \"US\",\n  \"merchantAddressZip\": \"10001\",\n  \"merchantLat\": \"40.7128\",\n  \"merchantLong\": \"-74.0060\",\n  \"state\": \"settled\"\n}\nresult = api.post(\"/api/v2/incoming-txn\", purchase)\naccounts.save_created(optional(result, \"lazilyProvisionedAccounts\"))\n\n# 5. On wallet open or after a reward notification, use the saved Percents group ID.\nbalances = api.get(f\"/api/v2/chg/{cardholder_group_id}/balances\")\nwallet.show_balances(balances)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"go","data-title":"Go","header":{"title":"Go","controls":{"copy":{}}},"source":"// Authentication: configure api on your server with the environment host and securely provided issuer credential.\nproduct := \"branded_balance\"\n\n// 1. Present a live CLICK offer. Stop if none is available.\noffer := api.FindOffer(\"/api/v2/offers?page=1&pageSize=25\", product, \"CLICK\")\nwallet.ShowOffer(offer)\n\n// 2. Send this only after the cardholder really clicks the offer.\nactivity := api.Post(\"/api/v2/cardholder/external/issuer-cardholder-001/user-activity\", Object{\n  \"externalCardholderGroupId\": \"issuer-group-001\",\n  \"events\": []Object{{\"eventId\": \"issuer-activity-001\", \"offerId\": offer.ID,\n    \"type\": \"CLICK\", \"clickFlavor\": \"ACTIVATE\", \"occurredAt\": \"2026-07-01T18:41:00.000Z\"}},\n})\naccounts.SaveCreated(activity.Optional(\"lazilyProvisionedAccounts\"))\n\n// 4. Use qualified settlement outcomes to update the customer wallet.\nwebhook.Listen(\"qualified_settlement\", func(event Event) {\n  if event.Data.Reward != nil && event.Data.Reward.RewardProductType == product {\n    wallet.ShowEarnedReward(event.Data.CardholderGroupID, event.Data.Reward)\n  }\n  if event.Data.Spend != nil {\n    statements.CreditOnce(event.Data.Source.PercentsID, event.Data.Spend)\n  }\n})\n\n// 3. Send the actual purchase after settlement. Reuse this ID for retries.\n// Include optional fields only when available in your purchase data.\npurchase := Object{\n  \"id\": \"issuer-txn-001\", \"amount\": 5000,\n  \"currency\": \"usd\", \"merchantDescriptor\": \"Example Coffee\",\n  \"merchantId\": \"processor-merchant-001\", \"mcc\": \"5814\",\n  \"createdAt\": \"2026-07-01T18:42:00.000Z\", \"authTimestamp\": \"2026-07-01T18:41:30.000Z\",\n  \"cardholderId\": \"issuer-cardholder-001\", \"cardId\": \"issuer-card-001\",\n  \"cardLast4\": \"4242\", \"cardBIN\": \"411111\",\n  \"physical\": true, \"billingZip\": \"10001\",\n  \"network\": \"visa\", \"authMethod\": \"contactless\",\n  \"externalCardholderGroupId\": \"issuer-group-001\",\n  \"externalAuthId\": \"issuer-auth-001\",\n  \"authCode\": \"123456\",\n  \"arn\": \"12345678901234567890123\",\n  \"merchantAddressStreet\": \"123 Main Street\",\n  \"merchantAddressCity\": \"New York\",\n  \"merchantAddressState\": \"NY\",\n  \"merchantAddressCountry\": \"US\",\n  \"merchantAddressZip\": \"10001\",\n  \"merchantLat\": \"40.7128\",\n  \"merchantLong\": \"-74.0060\",\n  \"state\": \"settled\",\n}\nresult := api.Post(\"/api/v2/incoming-txn\", purchase)\naccounts.SaveCreated(result.Optional(\"lazilyProvisionedAccounts\"))\n\n// 5. On wallet open or after a reward notification, use the saved Percents group ID.\nbalances := api.Get(\"/api/v2/chg/\" + cardholderGroupID + \"/balances\")\nwallet.ShowBalances(balances)\n","lang":"go"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","data-title":"Java","header":{"title":"Java","controls":{"copy":{}}},"source":"// Authentication: configure api on your server with the environment host and securely provided issuer credential.\nvar PRODUCT = \"branded_balance\";\n\n// 1. Present a live CLICK offer. Stop if none is available.\nvar offer = api.findOffer(\"/api/v2/offers?page=1&pageSize=25\", PRODUCT, \"CLICK\");\nwallet.showOffer(offer);\n\n// 2. Send this only after the cardholder really clicks the offer.\nvar activity = api.post(\"/api/v2/cardholder/external/issuer-cardholder-001/user-activity\",\n  object(\"externalCardholderGroupId\", \"issuer-group-001\", \"events\", list(object(\"eventId\", \"issuer-activity-001\", \"offerId\", offer.id,\n    \"type\", \"CLICK\", \"clickFlavor\", \"ACTIVATE\", \"occurredAt\", \"2026-07-01T18:41:00.000Z\"))));\naccounts.saveCreated(optional(activity, \"lazilyProvisionedAccounts\"));\n\n// 4. Use qualified settlement outcomes to update the customer wallet.\nwebhook.listen(\"qualified_settlement\", event -> {\n  if (event.data.reward != null && event.data.reward.rewardProductType.equals(PRODUCT)) {\n    wallet.showEarnedReward(event.data.cardholderGroupId, event.data.reward);\n  }\n  if (event.data.spend != null) {\n    statements.creditOnce(event.data.source.percentsId, event.data.spend);\n  }\n});\n\n// 3. Send the actual purchase after settlement. Reuse this ID for retries.\n// Include optional fields only when available in your purchase data.\nvar purchase = object(\n  \"id\", \"issuer-txn-001\", \"amount\", 5000,\n  \"currency\", \"usd\", \"merchantDescriptor\", \"Example Coffee\",\n  \"merchantId\", \"processor-merchant-001\", \"mcc\", \"5814\",\n  \"createdAt\", \"2026-07-01T18:42:00.000Z\", \"authTimestamp\", \"2026-07-01T18:41:30.000Z\",\n  \"cardholderId\", \"issuer-cardholder-001\", \"cardId\", \"issuer-card-001\",\n  \"cardLast4\", \"4242\", \"cardBIN\", \"411111\",\n  \"physical\", true, \"billingZip\", \"10001\",\n  \"network\", \"visa\", \"authMethod\", \"contactless\",\n  \"externalCardholderGroupId\", \"issuer-group-001\",\n  \"externalAuthId\", \"issuer-auth-001\",\n  \"authCode\", \"123456\",\n  \"arn\", \"12345678901234567890123\",\n  \"merchantAddressStreet\", \"123 Main Street\",\n  \"merchantAddressCity\", \"New York\",\n  \"merchantAddressState\", \"NY\",\n  \"merchantAddressCountry\", \"US\",\n  \"merchantAddressZip\", \"10001\",\n  \"merchantLat\", \"40.7128\",\n  \"merchantLong\", \"-74.0060\",\n  \"state\", \"settled\"\n);\nvar result = api.post(\"/api/v2/incoming-txn\", purchase);\naccounts.saveCreated(optional(result, \"lazilyProvisionedAccounts\"));\n\n// 5. On wallet open or after a reward notification, use the saved Percents group ID.\nvar balances = api.get(\"/api/v2/chg/\" + cardholderGroupId + \"/balances\");\nwallet.showBalances(balances);\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"csharp","data-title":"C#","header":{"title":"C#","controls":{"copy":{}}},"source":"// Authentication: configure api on your server with the environment host and securely provided issuer credential.\nvar product = \"branded_balance\";\n\n// 1. Present a live CLICK offer. Stop if none is available.\nvar offer = await api.FindOffer(\"/api/v2/offers?page=1&pageSize=25\", product, \"CLICK\");\nwallet.ShowOffer(offer);\n\n// 2. Send this only after the cardholder really clicks the offer.\nvar activity = await api.Post(\"/api/v2/cardholder/external/issuer-cardholder-001/user-activity\",\n  new { externalCardholderGroupId = \"issuer-group-001\", events = new[] { new { eventId = \"issuer-activity-001\", offerId = offer.Id,\n    type = \"CLICK\", clickFlavor = \"ACTIVATE\", occurredAt = \"2026-07-01T18:41:00.000Z\" } } });\naccounts.SaveCreated(activity?.lazilyProvisionedAccounts);\n\n// 4. Use qualified settlement outcomes to update the customer wallet.\nwebhook.Listen(\"qualified_settlement\", evt => {\n  if (evt.Data.Reward?.RewardProductType == product) {\n    wallet.ShowEarnedReward(evt.Data.CardholderGroupId, evt.Data.Reward);\n  }\n  if (evt.Data.Spend != null) {\n    statements.CreditOnce(evt.Data.Source.PercentsId, evt.Data.Spend);\n  }\n});\n\n// 3. Send the actual purchase after settlement. Reuse this ID for retries.\n// Include optional fields only when available in your purchase data.\nvar purchase = JsonObject(\"\"\"\n{\n  \"id\": \"issuer-txn-001\", \"amount\": 5000,\n  \"currency\": \"usd\", \"merchantDescriptor\": \"Example Coffee\",\n  \"merchantId\": \"processor-merchant-001\", \"mcc\": \"5814\",\n  \"createdAt\": \"2026-07-01T18:42:00.000Z\", \"authTimestamp\": \"2026-07-01T18:41:30.000Z\",\n  \"cardholderId\": \"issuer-cardholder-001\", \"cardId\": \"issuer-card-001\",\n  \"cardLast4\": \"4242\", \"cardBIN\": \"411111\",\n  \"physical\": true, \"billingZip\": \"10001\",\n  \"network\": \"visa\", \"authMethod\": \"contactless\",\n  \"externalCardholderGroupId\": \"issuer-group-001\",\n  \"externalAuthId\": \"issuer-auth-001\",\n  \"authCode\": \"123456\",\n  \"arn\": \"12345678901234567890123\",\n  \"merchantAddressStreet\": \"123 Main Street\",\n  \"merchantAddressCity\": \"New York\",\n  \"merchantAddressState\": \"NY\",\n  \"merchantAddressCountry\": \"US\",\n  \"merchantAddressZip\": \"10001\",\n  \"merchantLat\": \"40.7128\",\n  \"merchantLong\": \"-74.0060\",\n  \"state\": \"settled\"\n}\n\"\"\");\nvar result = await api.Post(\"/api/v2/incoming-txn\", purchase);\naccounts.SaveCreated(result?.lazilyProvisionedAccounts);\n\n// 5. On wallet open or after a reward notification, use the saved Percents group ID.\nvar balances = await api.Get($\"/api/v2/chg/{cardholderGroupId}/balances\");\nwallet.ShowBalances(balances);\n","lang":"csharp"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","data-title":"Ruby","header":{"title":"Ruby","controls":{"copy":{}}},"source":"# Authentication: configure api on your server with the environment host and securely provided issuer credential.\nproduct = \"branded_balance\"\n\n# 1. Present a live CLICK offer. Stop if none is available.\noffer = api.find_offer(\"/api/v2/offers?page=1&pageSize=25\", product, \"CLICK\")\nwallet.show_offer(offer)\n\n# 2. Send this only after the cardholder really clicks the offer.\nactivity = api.post(\"/api/v2/cardholder/external/issuer-cardholder-001/user-activity\",\n  externalCardholderGroupId: \"issuer-group-001\", events: [{eventId: \"issuer-activity-001\", offerId: offer.id,\n    type: \"CLICK\", clickFlavor: \"ACTIVATE\", occurredAt: \"2026-07-01T18:41:00.000Z\"}])\naccounts.save_created(activity&.lazilyProvisionedAccounts)\n\n# 4. Use qualified settlement outcomes to update the customer wallet.\nwebhook.listen(\"qualified_settlement\") do |event|\n  if event.data.reward&.rewardProductType == product\n    wallet.show_earned_reward(event.data.cardholderGroupId, event.data.reward)\n  end\n  if event.data.spend\n    statements.credit_once(event.data.source.percentsId, event.data.spend)\n  end\nend\n\n# 3. Send the actual purchase after settlement. Reuse this ID for retries.\n# Include optional fields only when available in your purchase data.\npurchase = {\n  id: \"issuer-txn-001\", amount: 5000,\n  currency: \"usd\", merchantDescriptor: \"Example Coffee\",\n  merchantId: \"processor-merchant-001\", mcc: \"5814\",\n  createdAt: \"2026-07-01T18:42:00.000Z\", authTimestamp: \"2026-07-01T18:41:30.000Z\",\n  cardholderId: \"issuer-cardholder-001\", cardId: \"issuer-card-001\",\n  cardLast4: \"4242\", cardBIN: \"411111\",\n  physical: true, billingZip: \"10001\",\n  network: \"visa\", authMethod: \"contactless\",\n  externalCardholderGroupId: \"issuer-group-001\",\n  externalAuthId: \"issuer-auth-001\",\n  authCode: \"123456\",\n  arn: \"12345678901234567890123\",\n  merchantAddressStreet: \"123 Main Street\",\n  merchantAddressCity: \"New York\",\n  merchantAddressState: \"NY\",\n  merchantAddressCountry: \"US\",\n  merchantAddressZip: \"10001\",\n  merchantLat: \"40.7128\",\n  merchantLong: \"-74.0060\",\n  state: \"settled\"\n}\nresult = api.post(\"/api/v2/incoming-txn\", purchase)\naccounts.save_created(result&.lazilyProvisionedAccounts)\n\n# 5. On wallet open or after a reward notification, use the saved Percents group ID.\nbalances = api.get(\"/api/v2/chg/#{cardholder_group_id}/balances\")\nwallet.show_balances(balances)\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"rust","data-title":"Rust","header":{"title":"Rust","controls":{"copy":{}}},"source":"// Authentication: configure api on your server with the environment host and securely provided issuer credential.\nlet product = \"branded_balance\";\n\n// 1. Present a live CLICK offer. Stop if none is available.\nlet offer = api.find_offer(\"/api/v2/offers?page=1&pageSize=25\", product, \"CLICK\").await?;\nwallet.show_offer(&offer);\n\n// 2. Send this only after the cardholder really clicks the offer.\nlet activity = api.post(\"/api/v2/cardholder/external/issuer-cardholder-001/user-activity\", json!({\n  \"externalCardholderGroupId\": \"issuer-group-001\",\n  \"events\": [{\"eventId\": \"issuer-activity-001\", \"offerId\": offer.id,\n    \"type\": \"CLICK\", \"clickFlavor\": \"ACTIVATE\", \"occurredAt\": \"2026-07-01T18:41:00.000Z\"}]\n})).await?;\naccounts.save_created(activity.optional(\"lazilyProvisionedAccounts\"));\n\n// 4. Use qualified settlement outcomes to update the customer wallet.\nwebhook.listen(\"qualified_settlement\", |event| {\n  if let Some(reward) = &event.data.reward {\n    if reward.rewardProductType == product {\n      wallet.show_earned_reward(&event.data.cardholderGroupId, reward);\n    }\n  }\n  if let Some(spend) = &event.data.spend {\n    statements.credit_once(&event.data.source.percentsId, spend);\n  }\n});\n\n// 3. Send the actual purchase after settlement. Reuse this ID for retries.\n// Include optional fields only when available in your purchase data.\nlet purchase = json!({\n  \"id\": \"issuer-txn-001\", \"amount\": 5000,\n  \"currency\": \"usd\", \"merchantDescriptor\": \"Example Coffee\",\n  \"merchantId\": \"processor-merchant-001\", \"mcc\": \"5814\",\n  \"createdAt\": \"2026-07-01T18:42:00.000Z\", \"authTimestamp\": \"2026-07-01T18:41:30.000Z\",\n  \"cardholderId\": \"issuer-cardholder-001\", \"cardId\": \"issuer-card-001\",\n  \"cardLast4\": \"4242\", \"cardBIN\": \"411111\",\n  \"physical\": true, \"billingZip\": \"10001\",\n  \"network\": \"visa\", \"authMethod\": \"contactless\",\n  \"externalCardholderGroupId\": \"issuer-group-001\",\n  \"externalAuthId\": \"issuer-auth-001\",\n  \"authCode\": \"123456\",\n  \"arn\": \"12345678901234567890123\",\n  \"merchantAddressStreet\": \"123 Main Street\",\n  \"merchantAddressCity\": \"New York\",\n  \"merchantAddressState\": \"NY\",\n  \"merchantAddressCountry\": \"US\",\n  \"merchantAddressZip\": \"10001\",\n  \"merchantLat\": \"40.7128\",\n  \"merchantLong\": \"-74.0060\",\n  \"state\": \"settled\"\n});\nlet result = api.post(\"/api/v2/incoming-txn\", purchase).await?;\naccounts.save_created(result.optional(\"lazilyProvisionedAccounts\"));\n\n// 5. On wallet open or after a reward notification, use the saved Percents group ID.\nlet balances = api.get(format!(\"/api/v2/chg/{cardholder_group_id}/balances\")).await?;\nwallet.show_balances(balances);\n","lang":"rust"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"add-the-branded-sdk","__idx":9},"children":["Add the Branded SDK"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can use the optional branded SDK to display offers and wallet balances in your app. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/auth-security/sdk-auth"},"children":["session contract"]}," identifies the active cardholder for SDK activity reporting on your behalf. Follow the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/embedded-widget/quickstart"},"children":["Branded SDK Quickstart"]}," to create a server-side session and mount the components. Your backend still submits purchases and handles reward webhooks."]}]},"headings":[{"value":"Branded Rewards Quickstart","id":"branded-rewards-quickstart","depth":1},{"value":"Authentication","id":"authentication","depth":2},{"value":"Register Accounts When You Need Them","id":"register-accounts-when-you-need-them","depth":3},{"value":"1. Present an Offer","id":"1-present-an-offer","depth":2},{"value":"2. Record the Cardholder's Click","id":"2-record-the-cardholders-click","depth":2},{"value":"3. Submit the Settled Purchase","id":"3-submit-the-settled-purchase","depth":2},{"value":"4. Listen for Reward Webhooks","id":"4-listen-for-reward-webhooks","depth":2},{"value":"5. Show Wallet Balances and Usage","id":"5-show-wallet-balances-and-usage","depth":2},{"value":"Full Quickstart Script","id":"full-quickstart-script","depth":2},{"value":"Add the Branded SDK","id":"add-the-branded-sdk","depth":2}],"frontmatter":{"title":"Branded Rewards Quickstart","description":"Connect your wallet to Percents for branded rewards.","seo":{"title":"Branded Rewards Quickstart"}},"lastModified":"2026-11-10T20:25:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/percents-api/branded-rewards/quickstart","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}