FAQ
TBD This FAQ is assembled from the documented contracts, not yet from a history of real publisher support tickets. Mining past integrations for common issues is tracked on Open items. If your question isn't here, please ask — the answer belongs on this page.
Getting started
Which integration should we choose?
Work backwards from who builds the UI. If you want full control and have the engineering capacity, go headless. If you want it live quickly with minimal engineering, use the hosted experience. Between those, the native SDK gives you ready-made components that feel like part of your app. See Integration models.
How long does an integration take?
These are estimates, not commitments. A scratch-card integration is typically a few days on the SDK or widget, or around two weeks headless. The full marketplace is roughly 2–3 weeks. The long pole is usually onboarding — start key exchange and IP whitelisting before you write code.
Can we start building before credentials arrive?
Yes. Generate your key pair, implement and unit-test the
signed envelope against your own keys, decide your
virtualId scheme, and build your catalogue cache. Only live calls need credentials.
Do we have to take every module?
No. Each module is independent, and most publishers start with one.
Identity
What should virtualId be?
Any pseudonymous identifier that is unique per user, permanent, and contains no personal data. A hash of your internal user ID works well. It must never change for that user and must never be reassigned to someone else.
What if a user's virtualId changes?
Cheggout treats them as a new person: their reward history and coupons are orphaned. Treat a
virtualId as permanently burned once issued.
Does Cheggout see our customers' personal data?
Only what you send. The design intent is that just the pseudonymous virtualId and your channel
identifier cross the boundary.
Authentication
Why do we keep getting Signature Mismatch!?
Almost always because the signature was computed over the decoded JSON rather than the Base64
BDATA string. Compute BDATA once, sign that exact string, and transmit that exact string. See
common failures.
Which token goes where?
The reference token creates cards (GetReward). The user token reveals them and lists
history. They are not interchangeable — a 401 on reveal usually means the reference token was
sent. See Tokens.
How do we refresh a token?
There is no refresh endpoint — you re-mint by calling the same signed API. Refresh the reference
token hourly from a scheduled job; re-mint a user token when a call returns 401, then retry once.
Can the mobile app or website call Cheggout directly?
Only with a short-lived token your backend obtained. Private keys and API secrets must never reach a client, and the channel-scoped reference token must never be placed on one.
Why are there two authentication schemes?
They belong to different product lines. The Deals Store uses an AppKey header; the Rewards Center and Bank APIs use signed envelopes. Use whichever the endpoint's reference page specifies.
Scratch cards
Why is rewards empty?
The user is not eligible right now — a frequency cap, targeting rules, or an inactive campaign. It is a successful response. Render nothing; do not retry or alert.
What does BETTER LUCK NEXT TIME mean?
The reveal worked, and there was no reward behind that card. Also a normal outcome. Design that state into your UI early — with probability-based campaigns it will be common.
Can we reveal the same card twice?
No. Reveal is one-shot; a second attempt returns REWARD NOT FOUND. Persist the reward the moment
you receive it, and re-display it from your own store or from
reward history.
Our reveal timed out. Did the user get the reward?
Possibly. Do not blind-retry. Call
GetAllScratchCardsByUserId: if the card shows
isSeen: true, the reveal succeeded and the reward is in that response.
Why create a card without assigning the reward?
Two-phase issuance means inventory is only consumed by cards users actually open. It also lets targeting be applied at reveal, using context captured at creation.
Should we issue cards from the app or the backend?
The backend, after verifying the transaction. A client-initiated request cannot prove a payment
happened. Use
GetScratchCardForBank where it applies.
Deals and coupons
Do we have to burn coins before requesting a coupon?
Yes — burn, then deliver, then refund or retry on failure. Cheggout has no wallet API; the coin economy is entirely yours.
What if delivery fails after we've burned coins?
Retry with the same extTransactionId, or refund. Every failure path needs one of those two
outcomes. See coupon delivery.
How often should we refresh the catalogue?
Often enough to reflect your campaign velocity — hourly or nightly is typical. The catalogue is not user-specific, so cache it and serve your storefront from the cache. Only inventory needs to be fresh, and it carries its own 180-second TTL.
A user saw an offer but got NON_ELIGIBLE. Why?
Targeting is applied at delivery as well as through the tags you filter on. Handle the response
gracefully, refund the coins, and hide the offer for that user.
Tracking
Do we really have to fire impression and click URLs?
Yes. Attribution, reporting and settlement depend on them. An integration that renders correctly but never fires tracking is incomplete.
When exactly do we fire each one?
Impression when the item becomes visible; click when the user taps or scratches it. A plain GET on each URL is sufficient.
Operations
What are the rate limits?
TBD Not published. Cache the catalogue, pre-fetch tokens, back off on failures, and agree expected peak volumes with Cheggout before launch.
Is there a sandbox with test data?
There is a UAT environment, but seeded test data and test credentials are TBD. Ask Cheggout to configure a UAT campaign for your channel.
Is there an OpenAPI spec or Postman collection?
TBD Not yet. These reference pages are the contract.
How will we hear about breaking changes?
TBD There is no published versioning or release-notes policy. Agree a change notification path with your Cheggout contact. See Versioning.
Platforms
Is there a Flutter or React Native SDK?
Not today. Both are roadmap items with no published artifact. In the meantime the headless API and the hosted experience are platform-agnostic, and you can bridge to the native SDKs through platform channels. See Flutter & React Native.
Can we use the web widget in production?
Not yet — the only available artifact is served from a UAT host and built for UAT backends. A production build and URL are a P0 open item.
Is Refer & Earn available?
Not currently. The endpoints its lifecycle depends on are not confirmed available. See Refer & Earn.