Callbacks & Redirects

Learn how to receive the verification result after a user completes the AgeGO flow.

This guide explains how your site receives the verification result via redirect/callback and grants or denies access accordingly.

AgeGO always follows the same high-level principle:

1. A visitor requests a page on your site.
2. You trigger AgeGO (Overlay or S2S).
3. AgeGO performs the configured Checks (e.g. Selfie, Credit Card, SMS, etc).
4. Your site receives the result and handles access.

Overview

Depending on your integration method, the “callback” mechanism is different:

Modal (Overlay), callback events: With the Overlay integration, the verification flow runs in-page and your site can react through modal callback events (JavaScript events).

S2S, redirect back to your site: With S2S (server-to-server), your server redirects selected users to AgeGO for verification and then receives the result when AgeGO redirects the user back to your site.

Modal Callback Events

Use modal events to know what happened in the verification flow (for example, success, failure, underage selection, or returning verified users).

This is the recommended approach for handling “callbacks” in Modal integrations.

Typical uses:

1. Unlock content when verification succeeds.
2. Show an error state when verification fails.
3. Route underage users to an alternative page/experience.
4. Skip unnecessary prompting for returning verified users.

(Implementation details and the exact event names live in the Modal Integration guide)

S2S Callback via Redirect Back to Your Site

Where the User Returns

In S2S, your backend starts verification by redirecting the user to the AgeGO start endpoint.

After verification completes, AgeGO redirects the user back to:

1. The URL in returnto (if provided), or
2. The root of your Site’s Website URL (fallback behavior).

S2S Callback Endpoint

Your callback endpoint is simply the page/route on your domain that receives the redirect back from AgeGO (commonly the returnto URL).

Your backend should parse the returned parameters, validate them, and decide whether to grant or deny access.

Example payloads (what you receive)

• S2S return parameters (redirect back to your site)

After successful or failed verification, the returnto URL is modified with GET parameters containing the user status and verification state.

Common fields include:

1. ag_error: Error code, if any.
2. ag_expires: UNIX timestamp in milliseconds after which the request is expired.
3. ag_nonce: The original nonce value (or none).
4. ag_verified: yes If successfully verified, otherwise no.
5. ag_verified_site: Must match the site used in the initial request (asi).
6. ag_user_token: The unique token identifying the verified user.

Integrity fields:

1. ag_signature: Checksum of the returned values.
2. ag_signature_algo: The algorithm used (e.g. sha256).

(Full validation logic and code examples live in the S2S guide.)

When Callbacks Fire (Success, Cancel, Timeout)

At a high level, your site should expect a “result” whenever the flow ends in one of these ways:

• Success: the user completes verification successfully.
• Failure / not verified: the user fails verification or does not complete it.
• Underage selection: the user chooses the “I am not 18 years old” CTA (Modal).
• Technical error: network or system error (Modal message / S2S error parameter).
• Timeout / expired: the verification callback expires (S2S uses an expiry timestamp; modal can show an “expired” message).

(Exact event names and error strings are defined in your Modal “Prompt Messages / Error Messages” and S2S “Possible error codes” sections.)

How to Avoid Redirect Loops

Redirect loops usually happen when a user is sent to AgeGO again immediately after returning to your site.

Recommended safeguards:

1) Check verified state before triggering again: If the user is already verified, do not re-trigger the flow. For S2S, use the returned verification status (ag_verified) and your own session state.

2) Use a nonce (recommended): A nonce helps you correlate the return response to a specific session and reduce replay/sharing issues.

3) Respect expiration: If the response is expired (ag_expires), treat it as invalid and restart the flow only when needed.

4) Store “verification completed” in your session: Once a user returns verified, persist that state server-side (S2S) or client-side (Modal) so you don’t trigger again on every page load.

Related Guides

• Modal Integration Guide → Events, Prompt Messages, Error Messages.
• S2S Integration Guide → Return Parameters, Signature Verification, Error Codes, Code examples.