FAQs
How It Works
What is Actual Activation?
An SDK-based monetization solution that turns receipt scanning into a repeatable engagement and revenue loop. It extends the BlinkReceipt scanning SDK with offers, ads, rewards, and user engagement flows. Retailer-agnostic: any valid receipt can earn rewards.
How does the scan-to-reward flow work?
- User photographs receipt. SDK provides camera guidance.
- SDK sends scan data to Actual's backend.
- Loading screen appears with an ad while processing.
- SDK calls your
rewardCallbackwith aScanFinishedcontext. Your app returns the base scan reward amount. - Backend validates: duplicate check (14-day window, cross-client), fraud detection, promotion matching (PVP).
- Validation fail → error screen. Validation pass → receipt summary screen.
- Actual sends
ReceiptProcessedwebhook for every scan, regardless of outcome. - Once a promo reward is validated, Actual sends a
RewardUpdatedwebhook with the amount. - Your server receives the webhook and grants the reward.
Who determines each reward type?
| Reward Type | Who Decides | How It Reaches You |
|---|---|---|
| Base Scan Reward | Your app (rewardCallback) | SDK callback at scan time and RewardUpdated webhook |
| Promo/Offer Reward | Actual backend (PVP) | RewardUpdated webhook |
| Boost Reward | Actual backend (ad completion) | RewardUpdated webhook |
| UGC Reward | Actual backend (task completion) | RewardUpdated webhook |
| Missed Earnings | Actual backend (correction review) | RewardUpdated webhook (pending → accepted/rejected) |
Do NOT use ReceiptProcessed to calculate rewards. Use RewardUpdated exclusively.
Can a single receipt trigger multiple webhooks?
Yes. Separate webhooks are sent for promo, boost, UGC, and missed earnings rewards. There is no "all rewards complete" signal — design for open-ended reward accrual per receipt.
How long does validation take?
- Standard credits: instantaneous (seconds)
- Manual edits (missed earnings): up to 6 hours
- Blurry or suspicious receipts: up to 3 days
Is there a callback for when the user taps Done?
Not currently available.
SDK Integration
What SDKs are needed?
Both are required:
- BlinkReceipt SDK — camera and scanning
- BlinkEngage SDK — monetization (offers, ads, rewards)
Supported platforms: iOS 13.0+, Android. React Native is supported via a wrapper.
What credentials do I need?
A licenceKey and a ProdIntelKey. Contact your Actual account team to have Engage features enabled on your key.
What are the essential setup steps?
- Enable Monetization — Activate reward and ad features within the scanning system.
- Provide User Identity — Supply a hashed user identifier (SHA-256 lowercase hex of email or phone number) for personalization and fraud prevention.
- Define Reward Currency — Specify your in-app currency name (e.g., "points", "coins") and conversion rate to dollars (e.g., 100 points = $1).
After a scan, our didFinishScanning callback returns no results. Is that expected?
Yes. When BlinkEngage is enabled, no results are returned on-device in didFinishScanning. Results are delivered via webhook instead.
What format should hashed email or phone be in?
SHA-256, lowercase hex.
Rewards & Currency
How do users earn rewards?
- Base Scan Rewards — Awarded for any successfully scanned receipt. You control the amounts dynamically via
rewardCallback. - Promo/Offer Rewards — Automatically awarded when receipt items match active promotions in Actual's system.
- Boost Rewards — Optional bonus earned by watching a short rewarded video ad after the scan.
- UGC Rewards — Earned by completing barcode collection tasks.
- Missed Earnings — Correction-based rewards for receipts that were initially missed or under-awarded.
Who controls reward amounts?
You control base scan rewards via rewardCallback — the SDK requests a reward amount from your app in real-time, letting you implement dynamic logic (e.g., higher rewards for premium users or during promotional periods).
Actual handles validation and calculation for promo, boost, and UGC rewards, and notifies your server via RewardUpdated webhook when amounts should be credited.
What is the Missed Earnings feature?
Missed Earnings lets users correct receipt scanning errors and claim rewards they may have missed.
- Users access the Missed Earnings page from their Receipt Summary.
- They can correct merchant name, date, or product details.
- For unrecognized products, users can scan the item's barcode to identify it correctly.
- After submitting corrections, items show a "Pending Review" status.
- Once reviewed, Actual sends a
RewardUpdatedwebhook withupdateType: missed_earningsand statusacceptedorrejected.
Review takes up to 6 hours.
What does "Pending Review" mean?
When a user submits a correction, the item enters Actual's review queue. The product card shows "Pending Review" to confirm receipt. The system revalidates with the corrected information and updates rewards via webhook.
Can we use our own currency name?
Yes. Set rewardCurrencyName to configure the display name. Note that some hardcoded UI strings still say "points" and require a future SDK update.
What are the receipt submission caps per user?
- 10 receipt submissions on any given date
- 3 receipts at the same merchant per transaction date
- 7 receipts with the same purchase date (total)
- 20 receipts in a rolling 7-day window
When a cap is hit, an error is displayed and the user cannot submit until outside the relevant window. The offer wall remains usable during this time.
Is there a testing bypass for scan limits?
Yes, via Debug Mode (development builds only — do NOT enable in production):
TestOptions.Test— enables test mode and returns test promotions from the backendTestOptions.Ads— uses Google Ad Manager test ad units- Debug placements — force specific offer wall layouts (carousel, list, grid) to test UI variations
Note: duplicate detection cannot currently be bypassed. Each test scan requires a unique receipt.
Webhooks
How do we set up webhooks?
Provide the following to your Actual account team:
- HTTPS endpoint URL
- Event types to subscribe to (
ReceiptProcessed,RewardUpdated, or both) - Custom headers (optional)
- App bundle ID
What's the difference between ReceiptProcessed and RewardUpdated?
| Webhook | When It Fires | Use For |
|---|---|---|
ReceiptProcessed | Every scan, regardless of outcome (including failures) | Logging, support visibility, audit trails |
RewardUpdated | When a reward is confirmed | Granting rewards to your users |
Use RewardUpdated exclusively to grant rewards. Never use ReceiptProcessed for reward calculation.
When are RewardUpdated webhook events fired?
| Scenario | updateType | rewardType | status | Frequency |
|---|---|---|---|---|
| Promo reward | reward | promo | complete | Once per receipt (aggregated) |
| Rewarded ad (boost) | reward | boost | complete | Once per ad watched |
| UGC task | reward | ugc | complete | Once per task completed |
| Base Scan | reward | base_scan | complete | Once per receipt |
| Missed earnings (submitted) | missed_earnings | n/a | pending | Once on submission |
| Missed earnings (resolved) | missed_earnings | n/a | accepted/rejected | Once on resolution |
Is one webhook event sent per product or per receipt?
For redeemed offers and coupons: all qualified items are sent in one RewardUpdated webhook with details per promotion. For engagement events (boost, UGC): each is sent individually.
Can we add a unique constraint on blink_receipt_id?
Yes. A unique blink_receipt_id (BRID) is always returned for every scan.
Are reward_amount and reward_id always present for a complete promo?
Yes. Both fields will always be present for a complete promo reward.
Can we include our own user ID in webhook payloads?
Yes. Set clientUserId during SDK initialization. It is included on RewardUpdated payloads. You can also correlate events via blink_receipt_id or hashed email/phone.
Note: clientUserId is not currently included on ReceiptProcessed payloads. Until resolved, correlate ReceiptProcessed events using blink_receipt_id.
What SDK telemetry events are available?
Currently exposed via callbacks and/or webhooks:
- Offer clipped
- Scan started
- Scan finished
- Any reward completed
- Missed earnings completed
Additional events are being added. Contact your Actual account team to flag requests.
What are the possible fraud_reason values?
| Value | Meaning |
|---|---|
receipt_counterfeit_text | Fake text patterns detected |
receipt_manipulation | Receipt data appears altered |
duplicate_submission | Same receipt submitted before |
user_burst_activity | Unusual scan volume from user |
user_geo_inconsistency | User locations don't match |
device_multiple_users | Multiple users on same device |
no_match | No matching receipt pattern found |
What is the webhook retry behavior?
| Attempt | Wait Time | Timeout |
|---|---|---|
| 1 (initial) | — | 30 seconds |
| 2 (retry 1) | 5 seconds | 30 seconds |
| 3 (retry 2) | 15 seconds | 30 seconds |
| 4 (retry 3) | 45 seconds | 30 seconds |
After 3 failed retries, the webhook is moved to a dead letter queue for manual investigation.
Offers & Offer Wall
How does the offer wall work?
The SDK provides a ready-to-use Offer Wall displaying relevant coupons and deals. Actual handles sourcing offers, targeting based on location and shopping patterns, and keeping content fresh. Users can browse by category or filter by favorite merchants.
Can we control the offer wall header?
Yes. Use the offerWallHeaderTitle function to customize the header section. See "Presenting the Offer Wall" in the SDK docs.
How does My Stores get populated?
New users see merchants ranked by overall popularity. Once they interact, personalization kicks in based on recent clicks, store views, and receipt upload recency and frequency. Geo-relevant filtering uses zip code passthrough, IP lookup, and zip extraction from receipts.
How often are offers updated?
Daily, from both third-party and direct brand sources.
Can we change the scan button label?
Yes. Hide the default button via an SDK method and add your own button as a subview.
What percentage of offers require pre-clipping?
Approximately 60% require clipping before purchase; ~40% are automatic. Clippable offers are expected to grow over the next 6 months.
Can users unclip an offer after clipping?
Not currently. This is on the roadmap.
Can we place custom offers on the wall?
Yes. Provide UPCs, merchants, eligibility criteria, and reward details. This requires coordination with Actual — there is no self-service option today.
Can we change section headers like "New Offers" or "Last Chance"?
Yes. These are server-side controlled by Actual and can be updated quickly on request.
Ads & GAM
Do we need a Google Ad Manager account?
Yes, for production ads. Not a blocker for SDK testing. Note that identity verification for a new GAM account can take weeks — plan accordingly.
How does the GAM invite process work?
- Send Actual the email address of your GAM account admin.
- Actual sends an invite to that address.
- Open the email while logged into your existing GAM account and accept the invite.
This does not affect your existing account — it grants Actual the ability to create new ad placements within Actual's GAM network for your app. Actual then provides additional lines to add to your app-ads.txt file.
Do we need to serve all ad types?
No. The scan loading ad plays automatically during receipt processing. The boost/rewarded video is opt-in by the user.
Receipt Scanning & Fraud
What are the receipt validation rules?
| Check | Rule | Result |
|---|---|---|
| Duplicate | Same receipt in any Actual app within 14 days | Rejected |
| Receipt age | Purchase date more than 14 days old | Rejected |
| Non-receipt | Image is not a receipt | Rejected |
| Counterfeit text | Fake text patterns detected | Rejected |
| Burst activity | Unusual scan volume from user | Rejected |
| Geo inconsistency | User locations don't match | Rejected |
| Multiple users | Multiple users on same device | Rejected |
| Manipulation | Receipt data appears altered | Rejected |
How do we test scanning without test receipts?
Use any real receipt with a purchase date within the last 14 days. Actual does not currently provide test receipts.
Duplicate detection is enforced across all Actual apps, so each successful scan requires a different receipt — you cannot rescan the same one.
UI Customization
Can we customize colors, fonts, and icons?
Yes. Pass a custom theme to match your brand. The SDK supports customizing colors, fonts, and icons throughout the offer wall and receipt summary screens. Contact your Actual account team for the advanced styling guide.
Can we customize the icon/points display order?
Not currently. The display order on the offer wall and receipt summary is fixed.
Can we send push notifications for new deals?
Push notifications are not built into the SDK. Publishers handle this using webhook data.
UGC (Barcode Collection)
How are UGC submissions validated?
Two matching submissions of the same barcode from unique devices are required for validation.
How many UGC tasks can be completed per receipt?
A maximum of 3 UGC tasks per receipt.