{"templateId":"markdown","versions":[{"version":"2.0","label":"v2.0","link":"/percents-api/cashback/quickstart","default":true,"active":true,"folderId":"27d36c3a"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["code-group"]},"type":"markdown"},"seo":{"title":"Cashback Rewards Quickstart"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"cashback-rewards-quickstart","__idx":0},"children":["Cashback Rewards Quickstart"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cashback rewards give cardholders money back on qualifying card purchases. Follow this walkthrough to authenticate, present an offer, record activation, submit a settled purchase and use its reward notification in your wallet."]},{"$$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 offers and purchase data agreed with Percents. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/overview/sandbox"},"children":["sandbox guide"]},"."]},{"$$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/cashback/offers-and-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: cashback"]}," 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/cashback/offers-and-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."]},{"$$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-webhooks-with-earned-rewards-for-qualifying-events","__idx":6},"children":["4. Listen for Webhooks with Earned Rewards for Qualifying Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["qualified_settlement"]}," webhook reports the cashback actually earned. Use its reward amount, rate and cap for customer messaging. Connect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.cardholderGroupId"]}," to your customer through the saved group mapping."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The $50 purchase submitted as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["issuer-txn-001"]}," earns $2.50 at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}," basis points (5%), below the $4 cap. The settlement notification connects the awarded cashback to that purchase:"]},{"$$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/cashback/webhooks#settlement-reward"},"children":["full cashback 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\": \"cashback\",\n      \"currency\": \"usd\",\n      \"amountMinor\": 250,\n      \"cardholderEarnRate\": { \"kind\": \"basis_points\", \"basisPoints\": 500 },\n      \"maxEarnAmountMinor\": 400\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Show the customer “You earned $2.50 cashback” using the awarded amount. Follow your agreed cashback arrangements for customer crediting."]},{"$$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/cashback/reconciliation"},"children":["look up the purchase"]}," using your original purchase ID."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"full-quickstart-script","__idx":7},"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 offer terms or the reported earned reward in your own wallet."]}]}]}]}]},{"$$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":["Retry a lost or temporary failed request with its original event ID. Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/cashback/reconciliation"},"children":["purchase lookup"]}," to check its current result."]},{"$$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 = \"cashback\"\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})\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","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 = \"cashback\"\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\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","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 := \"cashback\"\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})\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","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 = \"cashback\";\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});\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","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 = \"cashback\";\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});\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","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 = \"cashback\"\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\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","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 = \"cashback\";\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});\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","lang":"rust"},"children":[]}]}]},"headings":[{"value":"Cashback Rewards Quickstart","id":"cashback-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 Webhooks with Earned Rewards for Qualifying Events","id":"4-listen-for-webhooks-with-earned-rewards-for-qualifying-events","depth":2},{"value":"Full Quickstart Script","id":"full-quickstart-script","depth":2}],"frontmatter":{"title":"Cashback Rewards Quickstart","description":"Connect your wallet to Percents for cashback rewards.","seo":{"title":"Cashback Rewards Quickstart"}},"lastModified":"2026-11-10T20:25:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/percents-api/cashback/quickstart","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}