Launch URLs
A hosted launch is a URL with authentication parameters. Your backend prepares them; your app or site opens the result.
TBD The canonical paths are not settled in the published material — more than one shape appears across documents, and the correct one depends on which experience your channel is provisioned for.
Treat the shapes below as the parameter contract, and get the exact base URL and path from Cheggout during onboarding. Do not copy a URL from another publisher's integration. This is a P0 item on Open items.
The handoff
The pattern is constant regardless of the shape: your backend mints a credential, the URL carries it, Cheggout validates it.
Token-based launch — recommended
A short-lived token is the strongest of the documented shapes, because the credential is scoped and expires.
https://<your-cheggout-host>/<path>?token={tokenvalue}
Replace {tokenvalue} with the token from the
token API. The token identifies the customer, so no
separate user parameter is needed.
Documented behaviour for the rewards experience: unscratched cards are displayed first, followed by scratched cards.
Session-based launch
Where a session has been minted with
GenerateSessionInfoV2:
https://<your-cheggout-host>/<path>?sessionId={sessionId}&virtualId={virtualId}&channelName={channelName}
| Parameter | Description |
|---|---|
sessionId | From GenerateSessionInfoV2 |
virtualId | The customer — must be the one the session was minted for |
channelName | Your channel identifier |
All three must be present and consistent. A sessionId minted for a different virtualId will not
authenticate.
Publisher-specific shapes
TBD Some integrations use a channel-and-user shape:
https://<your-cheggout-host>/?channelName={channelName}&vid={virtualId}
This form carries no credential — it identifies a customer without proving anything about them. Where it exists it is a publisher-specific arrangement rather than a general contract, and it should not be adopted for a new integration. If Cheggout offers you this shape, ask what authenticates it.
Which shape applies to you
| You have | Use |
|---|---|
| A user token | Token-based |
A session from GenerateSessionInfoV2 | Session-based |
| Neither | Mint one first — do not launch unauthenticated |
Building the URL safely
Mint per launch. Do not cache a launch URL — it embeds a credential.
URL-encode every parameter. Tokens and identifiers can contain characters that need encoding.
const url = new URL('https://your-cheggout-host/path');
url.searchParams.set('token', token);
open(url.toString());
Never log the full URL. It contains a credential. Log the destination without the query string.
Do not put it in a deep link you persist, in analytics, or in a push notification payload.
Anyone who obtains it can act as that customer until it expires. Treat it with the same care as a token — because it contains one.
Deep linking into a destination
Where you want the customer to land on something specific rather than the home screen, Cheggout provides deep links of the form:
https://click.cheggout.com?type=reward&scratchCardId=REPLACE_ID
These come back from APIs — for example the deepLink in a
GetScratchCardForBank response. Use the value
Cheggout returned rather than constructing one.
Verifying your launch works
- The customer lands with no login prompt
- The correct customer's data is shown
- An expired or tampered credential fails cleanly rather than hanging
- Back returns control to your app — see Return handshake
- The URL never appears in logs or analytics
- It works in your actual container: web view, custom tab or browser
If the experience opens but shows no data or hangs on a blank screen, the credential is almost
certainly not matching the customer — check that the virtualId you launched with is the one the
session or token was minted for.