1. Send the setup guide
Open your app’s Install Hyzl page and select Copy setup guide. Send it privately to your developer. The guide includes the endpoint, app details, consent rules, full event contract, and the app’s Ingest token. Never paste the secret-bearing guide into an AI conversation. The developer can store the token privately and use the redacted preview with an AI coding assistant. If you are implementing the server connection yourself, continue below or use the AI code assistant setup.2. Store the Ingest token
The Ingest token permits your server to send paywall events for one app. It is included in the private setup guide. Store the guide’s token directly in your server host’s secret manager asHYZL_INGEST_TOKEN.
Do not run a clipboard reader by itself if it prints the token.
Put the reader inside your host’s secret command.
Never put the Ingest token in these places:
- A browser or mobile app.
- An AI chat.
- A code file or
.env.examplefile. - A test, log, or screenshot.
401 unauthorized and this message:
3. Send the event
Send the event after a signed-in person sees your paywall and leaves without payment. This moment starts recovery.
If your app cannot detect the exit, send the event when the paywall appears.
Do not send it at signup.
Your first complete event needs these facts:
- A durable identity:
userIdorstripeCustomerId. - The real consent choice in
consent.attested. - A phone number in
phoneNumberbefore Hyzl can contact the person.
userId must equal the value passed to Purchases.logIn().
Any other value can make a paid person appear unpaid.
For Stripe, send stripeCustomerId when you know it.
It must start with cus_.
Also set client_reference_id or metadata.userId on the Checkout Session or Payment Link.
Use the same userId in the paywall event.
If you connected both Stripe and RevenueCat, send the Purchases.logIn() value as userId, and use that value on your Stripe Checkout too.
Use E.164 format for phoneNumber, such as +13105551212.
E.164 is the full number with its country code.
Send the person’s real choice in consent.attested.
Never set it to true for every person.
The examples also use these optional fields:
firstNameandemailadd known contact details.consent.textrecords the words that the person saw.consent.atrecords the consent time.eventIdmakes a retry safe.occurredAtrecords when the person left the paywall.stagedescribes the point that the person reached.recoveryUrlsupplies a separate link for that person when your link mode needs one.
POST request to this address:
- curl
- Node.js
- Swift server
200 and 202 as success.
A 5xx response means that Hyzl had a server error.
Retry only after a network problem or a 5xx response.
A 4xx response means that the request needs a correction.
Read the linked error code and fix the request.
If the phone number arrives later, send the facts in two steps.
Use the same linked userId in both requests.
4. Confirm that the event arrived
The Installation check proves that your server reached Hyzl with an event for this app. Any paywall event from your server counts, including an event withtest: true.
The dashboard test text does not count. It sends a text from Hyzl, so it tests your Hyzl number and Flow instead of your server code. A dashboard test text can arrive while your server integration still sends nothing.
Send one event for your own test account:
- Use your test account’s durable identity and a phone number that you control.
- Send the real consent state for that account.
- Set linked
testtotrueif you want the text to arrive without the Flow wait or payment check. Use only your own phone number for a test event. - Use a new linked
eventId. - Make sure that the response is
202with a linkedstatusvalue. - Open the Install page for the same app.
- Select Check installation.
- Make sure that the Installation check says Your paywall event is here.
test or set it to false, Hyzl does not send contact until the Flow wait ends and the app is Live. Do not use a real person’s account for this check.